rollbackMetaItem / revertCommit always 409 on a package-bound overlay row — restoreVersion's put() scopes the parent lookup to `package_id IS NULL`

[baozhoutao]

Blocked-by: #4636

Found while implementing #4636 PR1 (write-path ownership key). Unassigned — nobody is on this. Recording only, per Prime Directive #10. Not fixed there: it is a SysMetadataRepository scoping defect, outside that PR's ruled scope, and it changes the repository write path — it deserves its own pin tests and review.

Evidence

SysMetadataRepository.restoreVersion (packages/metadata-protocol/src/sys-metadata-repository.ts, ~729) reads the current active row without a package predicate, then re-puts the historical body with no packageId option:

const currentActive = await this.get(ref, { state: 'active' });   // "match any package"
return this.put(ref, body, {
  parentVersion: currentActive?.hash ?? null,
  ...
});                                                                // no packageId

put then scopes its own existing-row lookup with:

where: this.whereFor(ref, state, opts.packageId ?? null)

and whereFor treats null as a predicate, not as "any package":

if (packageId !== undefined) where.package_id = packageId; // string -> eq; null -> IS NULL

undefined ?? null is null, so the lookup is always narrowed to package_id IS NULL. For a row bound to a real package (app.myapp, …) it therefore finds nothing:

• existingHash reads null;
• opts.parentVersion is the hash the unscoped read just returned;
• null !== hash -> ConflictError.

Observed, driving the real protocol + a sys_metadata / sys_metadata_history double (objectstack#4636 branch claude/issue-4636-writepath-real-package-id, packages/objectql/src/protocol-writepath-object-ownership.test.ts):

[metadata_conflict] object/myapp_invoice advanced during rollback.
Expected parent sha256:00ca6e72c421ecc68fa6a5153ef2b962ea307d6c9f78646425666a0c885927bc but current is null.

The same row rolls back fine when it has no package binding, which isolates the package dimension as the cause.

Why it matters

Every rollback of an overlay row authored inside a Studio package workspace fails, and fails with a message that blames a concurrent edit ("advanced during rollback") when nothing changed. Two callers, both user-facing:

• rollbackMetaItem — the per-item version-history revert;
• revertCommit (protocol.ts, ~9986) — the package-commit revert, same restoreVersion call.

ADR-0070 pushes authoring toward always resolving a writable base package, so the share of rows carrying a real package_id grows over time; the package-less rows that still work are the legacy shape.

Note the second face of the same bug: if the parent check ever did pass (no active row at all), put's existing would still be null and it would insert a duplicate global row rather than update the package-bound one.

Suggested fix

Thread the binding through, rather than making a consumer tolerant: restoreVersion already reads the row it is restoring, so it can pass that row's package_id into put (and into its own get), matching what saveMetaItem does. Alternatively give put an explicit "any package" spelling distinct from null — today undefined means that, and ?? null erases it at the one call site that needed it. Whichever route, the ?? null in put is the line that turns "unspecified" into "unbound".

Needs a pin test at both callers (rollbackMetaItem and revertCommit) with a package-bound row. #4636 PR1 leaves a tripwire test asserting the current 409 ([tripwire] a package-bound rollback still 409s) precisely so this fix trips it: whoever lands the fix should replace that test with the assertion one line above it, which already states what the registry write-through must then do with the package ownership key.

Related: #4636 (the write-through whose package-bound limb this defect makes unreachable), ADR-0048 (the per-package overlay row), ADR-0070.

---

Generated by Claude Code

[claude]

Triage: pm:blocked + Blocked-by: objectstack-ai/objectstack#4636 + domain:engine-core + target:v17.

Domain anchoring (landing site, not topic)

The fix lands in packages/metadata-protocol/src/sys-metadata-repository.ts (restoreVersion → put), and both callers named in the body — rollbackMetaItem and revertCommit — live in protocol.ts in the same package. packages/metadata* ⇒ domain:engine-core. Deliberately not routed by topic: "version history / package-commit revert" reads as a console or services concern, and neither is where the line is.

Stale-premise check — origin/main 72847c5, both halves re-read

• restoreVersion still reads const currentActive = await this.get(ref, { state: 'active' }) and calls this.put(ref, body, { parentVersion: currentActive?.hash ?? null, … }) with no packageId — verbatim as filed.
• put still narrows with where: this.whereFor(ref, state, opts.packageId ?? null) (:396).

One reading worth adding, because it makes the suggested fix cheaper and less debatable: the "any package" spelling the body asks for already exists one function away. The sibling read at :329 spells it explicitly —

where: this.whereFor(ref, state, opts && 'packageId' in opts ? (opts.packageId ?? null) : undefined),

— i.e. that call site distinguishes "caller said null" from "caller said nothing", and :396 is the single site that collapses the two with ?? null. So route B in the body ("give put an explicit any-package spelling distinct from null") is not a new concept to design; it is an existing idiom to apply. That does not pick the route — threading the row's own package_id through (route A) remains the body's preferred answer and matches saveMetaItem.

Why pm:blocked and not pm:queue

#4636 is pm:dispatched (in flight, claude/issue-4636-writepath-real-package-id) on the same write path, and this issue's stated acceptance depends on that PR's artifact existing: the tripwire test [tripwire] a package-bound rollback still 409s is what the fix is supposed to flip. Dispatching both now collides twice — on sys-metadata-repository.ts and on packages/objectql/src/protocol-writepath-object-ownership.test.ts. Blocked-by: added to the body; the unlock sweep returns it when #4636 closes.

Release board

target:v17 under criterion ① (published-surface defect a user hits today): every rollback of an overlay row authored in a package workspace fails, and fails with a message that blames a concurrent edit. ADR-0070 pushes authoring toward always resolving a writable base package, so the failing share grows rather than shrinks.

Dedup (three repos, open issues and PRs)

⚠️ The GitHub search API is not reachable from this seat (/search/issues answers "sessions are bound to their configured repositories", and returns a structurally empty result rather than an error). Dedup was therefore done by paginating all 442 open issues and PRs across the three repos and matching full text locally, on restoreVersion / rollbackMetaItem / revertCommit / package_id IS NULL.

No shadow. The only related open item is #4636 (handled above as a dependency, not a duplicate — its ruled scope is the write-path ownership key, and this defect makes its package-bound limb unreachable). objectui#3529 matched on revertCommit but is an unrelated commit-timeline error-message observation.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[hotlong]

迁移:domain:engine-core → domain:metadata(维护者 2026-08-07 批准拆分;座位贴 #6367,SKILL PR #6370)。落点证据:metadata-protocol/src/sys-metadata-repository.ts 的 restoreVersion put() 把父行查找锁死在 package_id IS NULL —— package-bound overlay 行回滚恒 409,元数据持久化层。pm:blocked 状态与正文 Blocked-by: 行随卡走。全量分类审计 49 卡三判,本卡 MOVE/high。分诊会话:session_01BickTBKm2JYSNnrtPT8ysa。

---

Generated by Claude Code