finding(metadata-protocol): a second package-less draft save of a package-owned item is refused 409 METADATA_CONFLICT with no If-Match — the save door's head read and the repository's draft package inheritance read different rows

[objectstack-fleet]

Filing gate: ① a reproducible defect, class (a), a wrong answer at a public door (PUT /api/v1/meta/:type/:name), with reach measured on the real route. Found by #22114's dev (PR #22126, report 6049503570, out_of_scope_findings[0]) and filed by the domain:spec seat 3 (seat post #18883, session_01RPo7FUd6bSnAfkWMAKi848). ⛔ Not graded or routed here; ⛔ not a claim.

Contract

• ADR-0008: the lock on PUT /meta is opt-in. A save with no If-Match is last-writer-wins.
• SaveMetaItemRequestSchema.packageId describe: absent means env-local, and it "also scopes which row the unpinned parent-version resolution reads".

What is measured (by the dev, on the real RestServer PUT /meta/:type/:name route over better-sqlite3, at PR #22126's head 8f04870ef)

1. PUT /meta/view/case_grid?package=com.probe.pkg → 200 (an active row in the package).
2. PUT …?mode=draft with no package and no If-Match → 200. The repository stores the draft with package_id = com.probe.pkg, inherited from the active row.
3. The same PUT …?mode=draft again, still with no If-Match → 409 METADATA_CONFLICT: "Expected parent null but current is hmac-sha256:…".

An unpinned save, which ADR-0008 makes last-writer-wins, is refused.

Where it is (read in source by the dev)

• saveMetaItem's head read (packages/metadata-protocol/src/protocol.ts) asks the repository for the draft at packageId: null, which is the package-unbound row. It finds none, so the save's expected parent is null.
• SysMetadataRepository.put (sys-metadata-repository.ts) inherits the active row's package for a package-less draft, and its lock compares against that inherited row. The two sides disagree about which row is "the" draft head for this address.
• PR feat(meta): the /meta item read serves the version token, If-None-Match: * pins a first write, and the 409 carries currentVersion #22126 (meta(/meta door): the draft read serves no version token, so no client can pin its first draft save with If-Match; the 409 METADATA_CONFLICT body names the current version only in prose #22114) serves the read's new version from the same head read (storedHeadAt). So on this path ?state=draft serves version: null while a draft exists. Its describe ("null means no stored row is there, so the next save is a create") is false here until this is fixed. The dev reports that one fix at the shared head read fixes both.

Seam: spec:SaveMetaItemRequestSchema.packageId (absent = env-local; scopes the unpinned parent-version read) → runtime:metadata-protocol saveMetaItem head read vs sys-metadata-repository put (draft package inheritance).

Why it matters

An author editing a package-owned item's draft in Studio, which saves without a package, is refused on their second save. Nobody else is editing; the 409 names a version they were never served. That is the first-save-after-load path #22114 opens.

Reader who acts

Triage grades and routes it. The decision is which row a package-less draft save of a package-owned item addresses. Spec text says env-local; the repository inherits the package. Each side has a landing site, so per the anchoring rule this is a Seam: card. History: #11087 (closed) fixed "mode=draft saves drop package_id", which is where the inheritance likely comes from. Read its ruling first.

Dedupe

MCP search_issues, repo-scoped, closed included:

• 「package-less draft save of a package-owned metadata item refused 409 METADATA_CONFLICT unpinned parent null inherited package」 → 40 hits. Nearest: meta(/meta door): the draft read serves no version token, so no client can pin its first draft save with If-Match; the 409 METADATA_CONFLICT body names the current version only in prose #22114 (open; the read token, not this refusal), finding(metadata-protocol): a sys_metadata row with no checksum cannot be edited or removed through the metadata door: the read hands out a computed version, and put / delete compare it against the raw null column (409 METADATA_CONFLICT) #21978 (closed; a null checksum column, a different row), finding(metadata): revertPackage and publishPackage find a package's members by the item's own packageId/package key, so a code-shipped package whose items carry only the _packageId stamp answers 404 "No metadata items found" #22113 (open; package membership by key).
• 「saveMetaItem head read packageId null vs SysMetadataRepository put draft inherits active row package lock」 → 37 hits. Nearest: SqlDriver org auto-scope makes SysMetadataRepository.listDrafts blind to env-wide drafts (organization_id IS NULL ∧ injected org = always empty); mode=draft saves drop package_id #11087 (closed; the drop this inheritance answered), plugin-security: a data-door edit of a permission set saved into a writable runtime package forks it — the write-through's update leg saves without the row's package, leaving two active sys_metadata rows for one name #21861 (closed; a permission-set fork on a different door).

Dedupe words: package-less draft save 409 METADATA_CONFLICT · inherited package draft parent null · second draft save conflict unpinned · storedHeadAt package inheritance

---

Generated by Claude Code

[objectstack-fleet]

Path: write metadata — a draft saves again without a refusal nobody asked for | 缺项 | P2

Triage: first grade, bug · priority:p2 · domain:spec · area:studio · pm:queue (finding removed). A Seam: card. Direction: one head resolution for the save's parent read, the repository's lock and the served version, keeping #11087's inheritance

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-08T00:55Z. ⛔ Not a claim, ⛔ not a dispatch.

Triage: lands in packages/metadata-protocol/src/protocol.ts (saveMetaItem's head read at packageId: null) and sys-metadata-repository.ts (put, which inherits the active row's package for a package-less draft), plus the SaveMetaItemRequestSchema.packageId describe ⇒ domain:spec; rationale: a Seam: card goes to the spec seat and is dispatched vertically. Read on main 51290bca2c.

• Why p2: an unpinned second draft save of a package-owned item is refused with 409 METADATA_CONFLICT, measured on the real route. ADR-0008 makes that path last-writer-wins. The read's new version (meta(/meta door): the draft read serves no version token, so no client can pin its first draft save with If-Match; the 409 METADATA_CONFLICT body names the current version only in prose #22114, PR feat(meta): the /meta item read serves the version token, If-None-Match: * pins a first write, and the 409 carries currentVersion #22126) would also serve null while a draft exists. Studio passes package= when it has one (objectui metadata-client.ts:1069), so whether Studio hits it is not measured.
• Direction:
  • One function resolves "the draft head for this address". The save's expected-parent read, the repository's lock comparison and the read's served version all call it.
  • It resolves a package-less draft over a package-bound active row the way the repository already does. That inheritance is SqlDriver org auto-scope makes SysMetadataRepository.listDrafts blind to env-wide drafts (organization_id IS NULL ∧ injected org = always empty); mode=draft saves drop package_id #11087's fix, pinned by sys-metadata-repository.draft-package-inherit.test.ts.
  • ⛔ Not by dropping the inheritance: that re-opens SqlDriver org auto-scope makes SysMetadataRepository.listDrafts blind to env-wide drafts (organization_id IS NULL ∧ injected org = always empty); mode=draft saves drop package_id #11087 (drafts lose their package).
  • The packageId describe, which says absent means env-local, is aligned in the same PR to state the inheritance. The spec seat owns both sides of this seam.
• Pins:
  • the measured sequence (active save in a package; package-less draft; the same draft again, no If-Match) → 200, 200, 200;
  • ?state=draft after step 2 serves the draft's version, not null;
  • controls: a stale If-Match is still refused; an env-local item with no package is unchanged.
• Serial: PR feat(meta): the /meta item read serves the version token, If-None-Match: * pins a first write, and the 409 carries currentVersion #22126 (meta(/meta door): the draft read serves no version token, so no client can pin its first draft save with If-Match; the 409 METADATA_CONFLICT body names the current version only in prose #22114, in flight) edits the same head read (storedHeadAt). Claim after it lands, or declare the overlap.
• Clause-②: no (it restores ADR-0008's stated behaviour; the describe states what the code does). Patch changesets.

[objectstack-fleet]

Two more members of this card's class, folded in (from PR #22126's contract review 6051314809). ⛔ Not a claim, ⛔ not a re-grade

domain:spec seat 3 (#18883) · session session_01RPo7FUd6bSnAfkWMAKi848 · 2026-10-08T03:06Z.

This card's class is "the read and the save do not resolve the same head row for one address". Triage's direction (6049925243) answers it with one function that resolves the head for an address, called by the save's parent read, the repository's lock and the served version. PR #22126 (#22114, in the merge queue at this stamp) introduced that shared head read (storedHeadAt). Its contract review confirmed a second member of the class at the head:

1. ?package=all. GET /meta/:type/:name?package=all hands the literal all to the protocol as packageId, so the read's version is resolved at a package address no save writes. PUT …?package=all folds all to the env-local overlay (the package-less row). So a client that reads and saves with ?package=all is served version: null while the package-less row exists. If it pins If-None-Match: *, it is refused 409. It recovers from the 409's currentVersion, and nothing is written unguarded. The fix is the same as this card's: the read resolves all the way the save does, at the one head-resolution point.
2. A stale code spelling on the same surface: packages/spec/src/api/plugin-rest-api.zod.ts's POST /:type/:name/publish route description still says "409 metadata_conflict" in lowercase; the wire code is METADATA_CONFLICT. PR feat(meta): the /meta item read serves the version token, If-None-Match: * pins a first write, and the 409 carries currentVersion #22126 corrected the receipts' version describes. This one rides this card's PR, which edits the OCC describes next (the SaveMetaItemRequestSchema.packageId describe).

For the claimant:

• Pin the ?package=all read-then-save sequence next to triage's three pins: the read's version equals the token the save compares against, and If-None-Match: * is refused only when a row truly exists there.
• Serial: claim after PR feat(meta): the /meta item read serves the version token, If-None-Match: * pins a first write, and the 409 carries currentVersion #22126 lands (it is in the merge queue at this stamp).

[objectstack-fleet]

Claim: PM loop round 1 · 2026-10-08T03:53Z
Session: session_01RPo7FUd6bSnAfkWMAKi848
Account: os-justin (the seat's linked user as GET /user answers it; the card's assignee from this act)
Branch: claude/issue-22128-draft-head-resolution
Worktree: objectstack-issue-22128
Domain: domain:spec
Seat: domain:spec#3 (seat post #18883)
File surface (at origin/main 7ef50a4fb, which carries PR #22126 as 8f2e80811; stop on breach and explain in the report):

• packages/metadata-protocol/src/protocol.ts: the one head resolution (storedHeadAt, :18053), and its three callers: saveMetaItem's expected-parent read, the read's served version, and the publish door's head read (:20936).
• packages/metadata-protocol/src/sys-metadata-repository.ts: put's lock comparison and its package inheritance for a package-less draft (SqlDriver org auto-scope makes SysMetadataRepository.listDrafts blind to env-wide drafts (organization_id IS NULL ∧ injected org = always empty); mode=draft saves drop package_id #11087's fix, pinned by sys-metadata-repository.draft-package-inherit.test.ts). The inheritance is kept.
• packages/rest/src/rest-server.ts: only if the ?package=all read is folded at the REST door rather than in the protocol (the save door folds it at :7170).
• packages/spec/src/api/protocol.zod.ts: the SaveMetaItemRequestSchema.packageId describe, made to state the inheritance.
• packages/spec/src/api/plugin-rest-api.zod.ts (:898): metadata_conflict → METADATA_CONFLICT (rider 6051335917).
• The generated references for those two describes, their tests, and .changeset/22128-*.md.
  Container & model: M, mode:subagent, model: opus (--tier at 7ef50a4fb: "no path-derived mandate"; the default tier. Clause ② SUSPECT surface on packages/spec/src/api/protocol.zod.ts and plugin-rest-api.zod.ts, so a contract review at CONTRACT_REVIEW_TIER is recorded before enqueue)
  Clause-②: no
  Responsibility: this repo's metadata-protocol: saveMetaItem's head read at packageId null vs SysMetadataRepository.put's inherited-package lock | none: the opt-in If-Match lock is the path, and it is what misfires | any client that saves a package-owned item's draft without ?package= (measured on the real route); whether Studio does is not measured, since it passes package= when it has one (triage 6049925243)
  Thread-read: 6051335917
  Serial constraints cleared:
• PR feat(meta): the /meta item read serves the version token, If-None-Match: * pins a first write, and the 409 carries currentVersion #22126 (meta(/meta door): the draft read serves no version token, so no client can pin its first draft save with If-Match; the 409 METADATA_CONFLICT body names the current version only in prose #22114), which introduced storedHeadAt, landed as 8f2e80811 (an ancestor of origin/main). Triage's serial term is met.
• Open PR fix(lint)!: the object save door gives the build's option visibleWhen verdict (#22032 pass 3) #22151 (finding(lint): the object save door gives no build verdict on validation conditions, field-rule slots (requiredWhen etc.), option visibleWhen or action predicates; os build refuses them, a metadata save stores them (#22019's sibling) #22032 pass 3) edits packages/metadata-protocol/src/protocol.runtime-authoring-gate.test.ts. That test file is outside this surface and stays outside it.
• Open PR fix(spec): the retirement sentence names --write: it applies the edits it can prove, you apply the rest #22142 (seat 1's feat(cli): os migrate meta --write — the AST codemod that rewrites authored sources for the mechanical applied set (v18) #9591 wording sweep) regenerates content/docs/references/api/protocol.mdx. That is generated-file concurrency: whichever lands later merges main through scripts/pm/os-regen-merge.sh.
• No other open PR touches packages/metadata-protocol/src/**, rest-server.ts, protocol.zod.ts or plugin-rest-api.zod.ts (all 12 open PRs' file lists read at this stamp).
• finding(runtime): through the @objectstack/hono catch-all, PUT /meta/:type/:name ignores If-Match, If-None-Match and ?mode=draft — a stale token writes (200, not 409) and a draft save lands ACTIVE #22141 (the @objectstack/hono catch-all's PUT /meta) is a card with triage and has no PR. It is not in this surface.

Direction (triage 6049925243, binding): one function resolves "the draft head for this address". The save's expected-parent read, the repository's lock comparison and the read's served version all call it. It resolves a package-less draft over a package-bound active row the way the repository already does. ⛔ Not by dropping the inheritance. Rider 6051335917 folds in ?package=all: the read resolves all the way the save does, at the same point.