diff --git a/docs/report/merge-request-schema-generation-skew-00001KZYAEWJT.md b/docs/report/merge-request-schema-generation-skew-00001KZYAEWJT.md new file mode 100644 index 00000000..ae950c26 --- /dev/null +++ b/docs/report/merge-request-schema-generation-skew-00001KZYAEWJT.md @@ -0,0 +1,44 @@ +# Merge Request schema generation skew blocks Coder review handoff + +Ticket: `00001KZYAEWJT` + +## Summary + +The Ticket implementation committed a new immutable Merge Request schema revision that removes caller-supplied `head_tree`, adds target authority, and adds immutable `MergeResult` evidence. All intended source changes were committed on a clean Workdir before opening the MR revision. + +`MergeRequestOpen` then failed with HTTP 409: + +```text +merge request error: merge request database error: schema drift: table merge_request_revisions is missing required column head_tree +``` + +The authoritative database has already lost the legacy `head_tree` column, while the live Server generation serving Worker tools still verifies the previous schema and requires that column. The Coder cannot repair this through the Workdir or typed MR tools, and restarting the live dogfood Server/Runtime would violate the active Worker safety boundary. + +## Impact + +- The exact committed source revision cannot be opened as an immutable MR revision. +- The required trusted `builtin:reviewer` handoff cannot be created because it requires a current MR revision id. +- The Ticket cannot proceed to review or `MergeRequestComplete` even though source validation passed. +- Retrying the same typed tool cannot converge while the live binary and database schema remain on different generations. + +## Evidence + +Attempted MR evidence before the report-only follow-up commit: + +- base: `11e4d536c50eef45801ea755cd8ef83add933749` +- head: `040ec49087b940803062425590b00ab3b3a78b7c` +- tree: `202df4a6e30bf437e451b8677b555f438108c5e7` +- diff digest: `sha256:45a0a0b1b916572d6804aece3f6db555d9748602131b17dd3727afb727fa8791` +- requested revision: `00001KZYAEWJT-r1-040ec490` + +The current final source evidence must be recomputed after this report commit before retrying MR creation. + +## Improvement + +Schema authority changes used by live typed tools need generation fencing: + +1. Server startup should verify the database schema before accepting MR tool traffic and report its executable/schema generation. +2. A schema-migrating generation must not share the authority database with an older running generation that still enforces the previous shape. +3. MR tool failures should report the running Server generation and observed schema version/columns in bounded diagnostics. +4. Deployment should atomically sequence migration and executable activation, or preserve a deliberate compatibility reader during the transition; a stale binary must never continue serving writes after the incompatible migration commits. +5. Coder review handoff should remain fail-closed, as it did here; it must not bypass immutable MR authority or fabricate review evidence when MR creation is unavailable.