docs: accept metadata-generated module SDK design - #460
Conversation
|
Preserved final targeted verification for the unchanged commit from #412. The user authorized this terminal documentation check after three full panel rounds and arbitration. This record honestly lists only Codex for the final targeted check; historical full panels remain at their original commits in the linked effort evidence. It is not a new full panel and does not claim one ran. |
Review — ARN-477: FAILPanel: codex, greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| - `-2` when the raw request exceeds the module's request-byte budget; | ||
| - `-3` when the response-handle slot or response-byte budget cannot be | ||
| reserved before dispatch; and | ||
| - `-4` for a host trap or exhausted invocation deadline before dispatch. |
There was a problem hiding this comment.
A genuine WebAssembly host trap cannot produce the documented -4 return value. Traps unwind the invocation and surface to the host as an invocation error while the guest is no longer running, so generated clients cannot observe -4 in this situation. Reserve this code for recoverable pre-dispatch failures such as deadline exhaustion, or document actual traps as out-of-band invocation failures.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/adrs/0176-metadata-generated-typed-module-data-sdk.md
Line: 370
Comment:
**Trap Return Is Unreachable**
A genuine WebAssembly host trap cannot produce the documented `-4` return value. Traps unwind the invocation and surface to the host as an invocation error while the guest is no longer running, so generated clients cannot observe `-4` in this situation. Reserve this code for recoverable pre-dispatch failures such as deadline exhaustion, or document actual traps as out-of-band invocation failures.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| A write is durable only after `FileWriteCommit`, which atomically changes one | ||
| open write entry to consumed before dispatching the commit and cannot be called | ||
| twice. `FileStreamAbort` atomically consumes an open read or write entry and |
There was a problem hiding this comment.
FileWriteCommit consumes the stream before commit dispatch, but authorization, conflict, persistence, or action dispatch can still fail afterward. Because a consumed handle cannot be retried or aborted and retains neither the payload nor a terminal result, a retryable failure forces the module to upload the entire file again and may leave persisted content unreferenced. Preserve the upload until the durable outcome is known, or define an in-progress and terminal state that can replay the result safely.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/adrs/0176-metadata-generated-typed-module-data-sdk.md
Line: 438-440
Comment:
**Failed Commit Consumes Upload**
`FileWriteCommit` consumes the stream before commit dispatch, but authorization, conflict, persistence, or action dispatch can still fail afterward. Because a consumed handle cannot be retried or aborted and retains neither the payload nor a terminal result, a retryable failure forces the module to upload the entire file again and may leave persisted content unreferenced. Preserve the upload until the durable outcome is known, or define an in-progress and terminal state that can replay the result safely.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.| The response maximum plus a fixed compact acknowledgement/error allowance is | ||
| reserved from the invocation budget before dispatch. Encoding uses a bounded | ||
| writer, charges actual bytes, and releases unused reservation. If a read result |
There was a problem hiding this comment.
The contract calls max_response_bytes a per-operation budget but also reserves it from an unspecified invocation budget. It does not say whether released capacity becomes available to later calls or whether bytes remain reserved until response_close. Implementations can therefore disagree on whether sequential small calls or several open response handles exhaust capacity and return -3. Define the invocation-wide byte budget and the exact reservation, charging, release, and re-credit lifecycle.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/adrs/0176-metadata-generated-typed-module-data-sdk.md
Line: 402-404
Comment:
**Response Accounting Is Ambiguous**
The contract calls `max_response_bytes` a per-operation budget but also reserves it from an unspecified invocation budget. It does not say whether released capacity becomes available to later calls or whether bytes remain reserved until `response_close`. Implementations can therefore disagree on whether sequential small calls or several open response handles exhaust capacity and return `-3`. Define the invocation-wide byte budget and the exact reservation, charging, release, and re-credit lifecycle.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.
|
Superseded by the restored original contributor PR #412 at the same commit. The repository owner requested fixing the fork-compatible gate workflow rather than rehosting the contribution. No source changes were made. |
2 participants
Maintainer-hosted successor to #412. Preserves the exact reviewed head and existing effort; the original PR retains contributor discussion and all historical review context. Hosting the branch in this repository allows the existing required workflows to access their repository secrets.
Accept ADR-0176 as a design, with coherent commit tokens, bounded response semantics, scalar JSON encoding, root generation-input hashing, and explicit File entity identity. Documentation only; no SDK implementation or migration work.
Merge authorization
Final documentation corrections are published. On 2026-09-10 the user explicitly authorized merging documentation-only PRs despite unrelated workspace-test blockers. The pre-push hook was skipped for this documentation-only publication after formatting, clippy, and readability checks passed; full workspace tests failed on Postgres container startup (
WaitContainer(StartupTimeout)). No runtime changes or infrastructure fixes were added. Temper proof ingestion remains denied withno matching permit policy; no successful proof registration is claimed.Verification
Three full panel rounds and arbitration are preserved. User authorized the prepared terminal patch and targeted verification on 2026-09-10. Independent targeted verification matched the approved patch byte-for-byte and passed with no findings; historical panels retain their original reviewed commits.
Preserved verification evidence. This report distinguishes targeted checks from pending full-workspace completion.
Decisions & Tradeoffs
Decision
Keep the existing host path documented as the current implementation until migration completes.
Came up because the PR marked ADR-0099 Superseded while ADR-0157 remained Proposed.
Options: retain contradictory statuses; declare the runtime migrated; distinguish accepted replacement design from current implementation.
Chose explicit design and implementation status because approval does not implement the SDK.
Where: PR #412, docs/adrs/0099-local-wasm-tdata-host-path.md and docs/adrs/0176-metadata-generated-typed-module-data-sdk.md (originally numbered 0157).
Full-panel corrections
Decision: carry complete read tokens over the ABI, reserve acknowledgement capacity before dispatch, state the existing result-omission rule consistently, and renumber this design ADR-0176.
Came up because round one identified contradictions between the exact ABI and its guarantees, and ADR-0157 collisions on current main.
Options: weaken entity-token validation and acknowledgement guarantees; leave conflicting prose; align the concrete request, capacity reservation, and result promises.
Chose to align the concrete contract because the existing intended guarantees require those fields and reservations. No runtime implementation is added. ADR-0176 was verified unused on main aa22bf1. Interrupted execution is explicitly an unknown outcome, not a failed-write acknowledgement.
Where: PR #412, docs/adrs/0176-metadata-generated-typed-module-data-sdk.md, Sub-Decisions 4 and 8; ADR-0099 supersession link.
ABI wording completion
Decision: Use the existing pre-dispatch capacity error for response-byte exhaustion and state the scalar JSON payload shape explicitly.
Came up because round two found an undefined return for failed byte reservation and a mismatch between the named tagging mode and wire examples.
Options: add another ABI mechanism; leave the cases undefined; clarify the existing error code and object shape.
Chose the existing
-3capacity error and a namedvaluefield for scalar payloads because these complete the already-proposed contract without new capabilities or runtime code.Where: PR #412, ADR-0176 Sub-Decision 4.
Scope constraint: This PR accepts a design. Review rounds may correct contradictions in that design; they do not authorize SDK implementation, migration tooling, broader architecture changes, or unrelated improvements.
Human-authorized terminal pass
Decision: Clarify root generation-input hashing and File-operation identity, then end the full-panel loop with targeted verification.
Came up because arbitration after three rounds identified these remaining contract inconsistencies without a need for new capabilities.
Options: continue the full-panel loop; leave the ambiguities; apply the prepared documentation patch with targeted verification.
Chose the prepared patch because the user authorized it on 2026-09-10 and reiterated no scope creep. Root compilation inputs exclude their generated outputs; File open calls identify the entity type. No runtime implementation or architecture expansion is included. Original panel records retain their reviewed commits.
Where: PR #412, ADR-0176 Sub-Decisions 1 and 4; Temper Ask en-01a08869-9373-7063-a217-271bb8a34531.
Original contributor work retained. Merge preparation: GPT-6 in Codex; terminal verification: independent Codex reviewer.
Greptile Summary
This documentation-only PR accepts ADR-0176 as the target design for a metadata-generated module SDK and marks ADR-0099 as superseded at the design level while retaining its implementation during migration.
Confidence Score: 3/5
The PR should not merge until the accepted ABI design resolves its unreachable trap return and irreversible failed File-commit lifecycle.
A genuine trap cannot return the specified guest-visible code, and consuming File streams before a potentially failing commit leaves no retry or abort path; response-budget reservation semantics are also underspecified.
Files Needing Attention: docs/adrs/0176-metadata-generated-typed-module-data-sdk.md
Important Files Changed
Sequence Diagram
sequenceDiagram participant Build as Build Pipeline participant Lock as Dependency Lock participant SDK as Generated SDK/WASM participant Host as Data Host ABI participant Service as Governed Data Service participant Store as Persistence/Projection Build->>Lock: Resolve immutable metadata closure Build->>SDK: Generate SDK and artifact binding Host->>Lock: Recompute and verify binding at activation SDK->>Host: DataRequestV1 Host->>Host: Validate grant, schema, and budgets Host->>Service: Typed operation + host authority Service->>Service: Capability and Cedar checks Service->>Store: Dispatch and acknowledge Store-->>Service: Result + sequence Service-->>Host: Domain result or structured error Host-->>SDK: DataResponseV1 handlePrompt To Fix All With AI
Reviews (1): Last reviewed commit: "docs: finalize SDK digest and File ident..." | Re-trigger Greptile