Commit-revert fails with `VERSION_NOT_FOUND: No history row at version 2` while `/history` shows exactly that row — the revert's lookup key disagrees with the history writer (and the package-level revert route 500s)

[huangyiirene]

Symptom

Commit history itself is correct: commits grow by one per publish, and a failed publish adds none. What cannot be done is undoing one.

• Commit-revert answers success: false with:

  VERSION_NOT_FOUND: No history row at version 2
  

• …while GET …/history at that same moment lists exactly that version-2 publish row.

• The package-level revert route answers 500.

Expected: reverting to a version the history endpoint lists restores that version; a revert route that cannot serve the request answers a declared 4xx, not a 500.

Root cause

The report locates it to this much and no further: the revert's lookup key disagrees with what the history writer stores. The row exists — the reader asks for it under a key the writer did not use (or under a different scope). The report does not open the code, so the specific key (version numbering base, package/overlay scoping, or the parent id) is unidentified; measure the write and the read side of the same row before choosing a fix. The 500 on the package-level route is a separate, unexamined failure on the same feature.

Relationship to the closed revert family — a distinct key mismatch, not a regression

revertCommit / rollbackMetaItem had four cards closed on 2026-08-08, all before this run's framework commit (a86db175, cut 2026-08-10) — so their fixes are in this build:

• rollbackMetaItem / revertCommit always 409 on a package-bound overlay row — restoreVersion's put() scopes the parent lookup to package_id IS NULL #6215 — rollbackMetaItem / revertCommit always 409 on a package-bound overlay row; restoreVersion's put() scoped the parent lookup to package_id IS NULL.
• revertCommit cannot restore an object overlay at all — it passes no write intent, so restoreVersion defaults to override-artifact and the repository answers NOT_OVERRIDABLE #6563 — revertCommit passed no write intent, so restoreVersion defaulted to override-artifact → NOT_OVERRIDABLE.
• revertCommit's soft-remove limb hard-codes intent: 'override-artifact', so a commit that CREATED an object cannot be reverted either #6620 — the soft-remove limb hard-coded intent:'override-artifact'.
• A successful revertCommit never refreshes the SchemaRegistry — the runtime keeps dispatching the reverted-away body until restart (the #4521 rule, missing on the batch path) #6621 — a successful revertCommit never refreshed the SchemaRegistry.

Reading against #6215 specifically, as asked: this looks like a distinct key mismatch, not a regression of #6215. #6215 failed after the version row was located, at restoreVersion's put() parent lookup, and its signature was a 409; here the failure is earlier and different in class — the version row is not found at all, VERSION_NOT_FOUND, on a lookup the history endpoint satisfies. Same family (the revert path's row addressing disagreeing with the writer's), different key and different stage. Caveat: that judgement is made from symptoms only, since the report did not inspect the code — confirm by comparing #6215's fixed package_id scoping against whatever scope the version lookup uses.

Reproduction

1. Publish a package twice so history holds ≥ 2 versions (confirm a failed publish adds no commit — it correctly does not).
2. GET …/history — the version-2 publish row is listed.
3. Revert that commit → success:false, VERSION_NOT_FOUND: No history row at version 2.
4. Call the package-level revert route → 500.

Source

Extracted from the QA run #7514 (framework a86db17, console 09987b68).

[os-zhuang]

Claimed — domain:metadata seat.

• Session: session_0155v8vapVCt98zb9eWVhbLq
• Branch: claude/issue-7559-revert-version-key-mismatch
• Worktree: ../objectstack-7559 (dedicated; the shared primary checkout is not edited)
• File surface: packages/metadata-protocol/src/sys-metadata-repository.ts, with tests in packages/objectql/src/ (sys-metadata-repository.test.ts, protocol-publish-rollback.test.ts).

The first deliverable is a measurement, not a patch. The card localises this to "the revert's lookup key disagrees with what the history writer stores" and deliberately stops there — the reporter did not open the code, so the specific key (version numbering base, package_id / overlay scope, or parent id) is unidentified. The dispatch requires reading both sides of the same row — what the writer persists and what the revert's lookup asks for — and putting both in the PR body. ⛔ Guessing which of the three it is and patching that is explicitly out.

The #6215 relationship must be confirmed, not assumed. All four revert-family cards closed 2026-08-08 (#6215 / #6563 / #6620 / #6621) are in this build. #6215 failed later and differently — after the version row was located, at restoreVersion's put() parent lookup, signature 409; here the row is not found at all, VERSION_NOT_FOUND, earlier and a different class. The dev compares #6215's fixed package_id scoping against the version lookup's scope and reports either way. If it turns out this IS a regression of #6215, the dev stops and reports — that changes the card's character.

Both halves are in scope. The package-level revert route's 500 is a declared-envelope violation (ADR-0112: a route that cannot serve answers a declared 4xx). It may or may not share the root cause; if it proves to be a separate defect outside this card's reach, it gets its own unassigned finding issue carrying the measurement rather than going unreported.

Standard clause for a refusal-shaped card: "should be refused" cases assert code and status, never a bare rejects.toThrow() — that is green against an implementation that throws a naked Error. Positive identity (a revert that succeeds and restores the expected version) is pinned first, so the suite cannot pass by refusing everything.

---

Generated by Claude Code

[claude]

{
  "issue": 7559,
  "status": "done",
  "branch": "claude/issue-7559-revert-version-key-mismatch",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/7619",
  "premise_still_valid": true,
  "summary": "Measured both sides of the same row against a real ObjectQL engine and the real SysMetadataRepository, driving a package publish twice: the writer stores sys_metadata_history at organization_id=NULL (publish routes each draft to the draft's OWN scope, the #3115 rule) while the revert's lookup asks under the REQUEST's active org, so it missed a row GET /history lists and answered VERSION_NOT_FOUND at version 2 \u2014 the card's symptom verbatim. The other two candidate keys AGREE: the version numbering base is the same per-(org,type,name) lineage counter on both sides (drafts consume numbers, so prevVersion is 2), and package_id is not involved at all because sys_metadata_history has no such column. NOT a regression of #6215, confirmed against the code rather than symptoms: #6215's package_id scoping of restoreVersion's put() parent lookup is present, intact and structurally uninvolved \u2014 this fails one step earlier, on a different key, with a 404 rather than its 409. Fixed with one shared resolver used by both revert callers (revertCommit per item, rollbackMetaItem per call) that resolves the scope an item's lineage actually lives in, caller's own overlay first and env-wide second; rollbackMetaItem had the identical defect, measured and not previously reported. Second half: the package-level revert 500 is a separate defect on the same feature and is fixed here rather than filed \u2014 but NOT where it looked. The route already reaches errorFromThrown through one enclosing catch, so the per-route catch this card implies is inert (I wrote it, reverse verification showed it changed nothing, and it is not in the PR \u2014 the route file is byte-identical to main); the whole cause was MetadataManager.revertPackage throwing bare Errors with no code/status, now RESOURCE_NOT_FOUND/404 and RESOURCE_CONFLICT/409 from the ADR-0112 standard catalog. UPDATE (head aa17597, after PM review): TypeScript Type Check was RED and it was mine \u2014 the new test file added raw tsc errors to objectql's shrink-only TEST_DEBT ledger (355 recorded, 356 measured). Fixed the errors, not the ledger: registerObject's required `packageId` argument omitted (TS2554 x3), a `Record(string, unknown)` spread in the field helper putting an index signature on every field so the object was not assignable to ServiceObject (TS2345 x3), and `longtext` for a FieldType that is spelled `textarea` (TS2322 x5) \u2014 the latter two only surfaced as each preceding one was cleared, so the count went 356 to 358 to 353 rather than straight down. objectql now measures 353 against a recorded 355; the ledger is deliberately UNCHANGED and I lowered no entry, mine or anyone's.",
  "tests": "New packages/objectql/src/protocol-revert-org-scope.test.ts (7 cases, real engine + real repository, full publish-to-revert round trip; the existing ADR-0067 suite stubs repo.restoreVersion and so cannot see whether the plan's version resolves to a row \u2014 the gap #7559 lived in). Positive identity pinned FIRST and asserting the restored BODY, not just the absence of an error; every refusal asserts code AND status. Also strengthened the two revertPackage cases in metadata-service.test.ts from rejects.toThrow(message) to code+status+message, and added a dispatcher case pinning that a declared refusal reaches the wire as its own status AND code rather than flattening to 500. REVERSE VERIFICATION, direction predicted before running \u2014 half 1 (protocol.ts reverted to main): predicted 2 red / 5 green, got exactly that, both reds VERSION_NOT_FOUND; the writer-measurement case, the org-scoped control and the three refusals stay green by design, which is what stops the suite passing by refusing everything. Half 2 (manager reverted to main): 2 red (the envelope cases); the route case stayed GREEN \u2014 the unpredicted direction that found the inert route change, reported rather than papered over. LOCAL RUNS, all green: @objectstack/metadata 30 files/593 tests; @objectstack/metadata-protocol 72/1062; @objectstack/objectql 180/3194; @objectstack/runtime 124/1992. typecheck: objectql Done, runtime Done \u2014 metadata and metadata-protocol declare no typecheck script (ledger DEBT), so that is the full available coverage for the four packages, not a subset I chose. Gates: check:nul-bytes, check:error-code-casing, check:engine-double-contract, check:durability-log-level all OK. Consumer-sweep direction not applicable \u2014 no exported type or signature changed (the new resolver is private). CI on PR #7619: in_progress at the time of this report; the convergence read is the PM's. UPDATE (head aa17597): my earlier 'typecheck objectql Done' was true but not evidence about a test file \u2014 the package's own typecheck config excludes *.test.ts while the ratchet measures with them put back, which is exactly the gap the PM named. Re-measured the way the gate does (sibling tsconfig extending the package's own with the test globs dropped from `exclude`) and reproduced CI's 356 exactly; the same command over an UNBUILT closure reports 654, the TS2307-plus-implicit-any cascade the script itself refuses to record, so the full `pnpm build` came first. After the fix: `pnpm check:type-check-debt` exits 0 \u2014 '33 ledger entries re-measured, 1785 raw tsc errors total, none above its recorded number'. Re-ran reverse verification UNDER THE NEW FIXTURES to confirm the tests are still armed rather than quietly disarmed by the fixture edit: reverting protocol.ts still turns exactly the two positive-identity cases red with VERSION_NOT_FOUND, 2 red / 5 green as before. objectql 180 files / 3194 tests still green. CI on aa17597 is now FULLY GREEN: 25 checks, none failing, none pending \u2014 TypeScript Type Check, ESLint, Test Core 1-3/3 and Check Changeset all success.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #7620: 16 test doubles across objectql/runtime/plugin-security/plugin-sharing short-circuit $or in their WHERE matcher, dropping sibling equality keys, so the suite stays green while exercising a different query than written \u2014 hit while measuring this card (it made a probe's second publish record no commit at all); unassigned, finding label, no pm:queue"
  ]
}

---

Generated by Claude Code

[os-zhuang]

ACCEPT — PR #7619, marked ready and armed into the merge queue. 25/25 green after one patch round.

The card's first deliverable was a measurement, and it was delivered — including what was ruled out. The writer stores sys_metadata_history at organization_id = NULL (publish routes each draft to the draft's own scope, the #3115 rule) while the revert's lookup asks under the request's active org, so it missed a row GET /history lists. The other two candidate keys agree: the version numbering base is the same per-(org, type, name) lineage counter on both sides, and package_id is not involved at all because that table has no such column. The card named three possible keys and told the dev not to guess which; naming the two that were eliminated is what makes the diagnosis checkable rather than merely plausible.

The #6215 question was answered against the code, not against symptoms. That fix is present, intact, and structurally uninvolved — this fails one step earlier, on a different key, with a 404 rather than its 409. The card asked for that comparison specifically because a wrong answer there would have made this a regression card, i.e. a different piece of work.

Two findings beyond the card, both handled correctly:

• rollbackMetaItem carried the identical defect and had never been reported. Fixed through one shared resolver used by both callers rather than a second copy of the scope logic — which is the lesson fix(metadata-protocol): deleteManyData has the same fake-atomic as batchData, updateManyData ignores atomic entirely #4620 left about how these paths drift apart in the first place.
• The 500 was fixed, but not where the card pointed — and this is the part of the run I'd single out. The dev wrote the per-route catch the card implies, their own reverse verification showed it changed nothing (the route already reaches errorFromThrown through an enclosing catch), and they removed it and said so. I verified the claim rather than taking it: there is no packages/rest/ file in the diff at all, before or after the patch push. The real cause was MetadataManager.revertPackage throwing bare Errors with no code/status, now RESOURCE_NOT_FOUND/404 and RESOURCE_CONFLICT/409 from the ADR-0112 catalog. Shipping an inert change that looks like diligence is the easy path, and refusing it — then reporting that you had written it — is the harder and better one.

The reverse verification earned its keep in the unpredicted direction. Half 1 predicted 2 red / 5 green and got exactly that. Half 2 predicted the envelope cases red — but the route case stayed green, which is what exposed the inert change. A prediction that comes out wrong and is followed rather than explained away is worth more than a table of confirmations.

It also diagnosed why the defect survived, which is the part that stops it recurring: the existing ADR-0067 suite stubs repo.restoreVersion, so it structurally cannot see whether the plan's version resolves to a row. The new suite drives a real engine and a real repository through a full publish-to-revert round trip, pins positive identity first by asserting the restored body rather than the absence of an error, and asserts code and status on every refusal. Two existing rejects.toThrow(message) cases were strengthened to code + status + message in the same pass.

On the patch round — the ratchet was respected. @objectstack/objectql TEST_DEBT had drifted 355 → 356 from the new test file. Verified from the diff: scripts/check-type-check-coverage.mjs is absent, so the error was fixed rather than the ledger raised, and the commit says so in as many words. Worth recording for the next author who hits this: the dev's local turbo typecheck genuinely passed, because a package's own typecheck config excludes its tests (the gate itself reports 19 packages in that state) while the ratchet measures raw tsc --noEmit including them. A green package typecheck is therefore not evidence about a new test file — that is a real gap between the local and CI reads, not a dev oversight.

Verified independently: six files, no docs/adr/**, no content/docs/releases/, changeset present, and closed_by_pull_requests confirms this PR closes the card — Fixes is right, since both halves are addressed and nothing is left pending. Gate jobs' own conclusions read personally: ESLint success, TypeScript Type Check success.

Out-of-scope finding filed as #7620: 16 test doubles across objectql / runtime / plugin-security / plugin-sharing short-circuit $or in their WHERE matcher and drop sibling equality keys, so those suites stay green while exercising a different query than the one written. It was hit while measuring this card — it made a probe's second publish record no commit at all. That is a test-infrastructure defect that silently weakens whatever it touches, and filing it separately rather than folding it in was right.

---

Generated by Claude Code