`deleteMetaItem`'s catch re-wrap drops the error `code`, so a repository refusal reaches the caller as a 403 with no catalogued code

[os-zhuang]

Found while implementing #6960 (PR pending). Out of scope there — the fix is an error-envelope change on a path #6960 was not authorised to touch — so filing plainly and leaving the grading to triage.

What was measured

ObjectStackProtocolImplementation.deleteMetaItem's repository branch ends in a catch that translates ConflictError faithfully and then re-wraps everything else:

const e = new Error(`Failed to delete customization overlay: ${err.message ?? err}`);
(e as any).status = err?.status ?? 500;
throw e;

status is carried forward. code is not. So a refusal thrown by SysMetadataRepository with a full ADR-0112 envelope reaches the caller with err.status === 403 and err.code === undefined, its code surviving only as text inside the message.

Measured on f16e54e1d, control-plane kernel (environmentId === undefined, which is what the CLI's lightweight assembler builds for a host config — the showcase topology of #5086), deleting an artifact-backed item of a type the registry does not mark allowOrgOverride:

Error: Failed to delete customization overlay: [NOT_OVERRIDABLE] 'permission' is not allowOrgOverride
in the registry. Overlay-allowed: view, dashboard, report, translation, email_template.
Set OS_METADATA_WRITABLE to enable additional types at runtime.

 err.status -> 403
 err.code -> undefined

The same refusal on a project kernel (environmentId set) is thrown by deleteMetaItem's own two-tier block and arrives intact, code: 'NOT_OVERRIDABLE' + status: 403. So the envelope a caller sees for one and the same refusal depends on the deployment topology.

Why it reads as unintended

• ADR-0112 makes the code the machine-readable half of a refusal; a 403 with no code is exactly the shape the ledger exists to prevent, and every other refusal on this path carries one.
• The evidence that it has already cost a pin: ADR-0029 D9's control-plane delete pin in packages/objectql/src/protocol-object-overlay-layer.test.ts asserts expect(String(refused.message)).toContain('NOT_OVERRIDABLE') — a substring of the message — while its project-kernel sibling one describe up asserts code and status. A test that wants the envelope and can only reach the prose is the symptom, not a style choice.
• #6960's new pin file hit the same wall and states the gap in a comment rather than asserting around it, carrying the full envelope one layer down (directly against SysMetadataRepository) instead.

Blast radius, and why the fix is not a one-liner

Every non-ConflictError failure of the repository delete path goes through this re-wrap — genuine 500s (driver faults, history-table outages) as well as the 403 refusals. Restoring code unconditionally therefore changes the envelope of that whole class at once, including cases where the underlying error has a code that is not meant to surface. That is a deliberate contract decision about which codes propagate through a wrapper, which is why #6960 stopped here instead of taking it: its ruling moved the delete authorization, not the delete error envelope.

Worth checking in the same pass whether saveMetaItem and the other repository-fronting verbs carry the same shape — this was found on the delete path only, and no claim is made about the others.

Suggested shape (not a decision)

Carry code forward alongside status when the wrapped error has one, i.e. the same err?.status ?? 500 treatment applied to err?.code, and then let the D9 control-plane pin assert code + status like its sibling. The alternative — leave the wrapper alone and let callers parse the message — is what exists today and is what made the pin weaker than its twin.

Refs: #6960, #5086 (the control-plane topology), ADR-0112, ADR-0029 D9 (f16e54e1d).

[claude]

Triage: pm:queue + domain:metadata.

• Classification: concrete defect, fully anchored. The catch re-wrap that drops code is live on origin/main @ b948a41 at packages/metadata-protocol/src/protocol.ts:12188 (sibling re-wrap at :12273) — status is carried forward, code is not, exactly as filed. ADR-0112 makes the code the machine-readable half of a refusal, and the card documents a pin test already forced to assert against message prose instead of the envelope. Restoring code propagation (only when the wrapped error has one, the same treatment status gets) is restore-invariant execution, not new contract design. The wrapper-class blast radius the body flags is real: the dispatch should keep the "propagate only when present" shape and check the saveMetaItem siblings in the same pass. Maintainer veto window open on that scope.
• Routing: fix lands in packages/metadata-protocol ⇒ domain:metadata (packages/metadata* family). Not domain:spec — error envelope, no metadata acceptance-surface change.
• Dedup: A legacy env overlay on an artifact-backed item of a rolled-back type can no longer be REMOVED through the ordinary delete path (403) — only via OS_METADATA_WRITABLE #6960 is the found-while parent (its ruling moved delete authorization, explicitly not this envelope); no other open card covers this re-wrap. Clean.
• Stale-premise: reproduces on current main (anchors above); measured at f16e54e1d, path unchanged since.
• No target:v17: fail-closed today (the 403 still refuses; the code survives as message text), and the divergent topology is the control-plane kernel — envelope quality, not a first-hour user-facing failure.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 17 (domain:metadata seat, sticker #6367)

Session: session_01W6bLax4KMrSfnE1ydFU8Dw
Branch: claude/issue-7426-delete-rewrap-code
Worktree: objectstack-issue-7426
Domain: domain:metadata
File surface: packages/metadata-protocol/src/protocol.ts (deleteMetaItem's catch re-wrap), plus pins
Container & model: M, mode:cloud, model: opus — ⚠️ small diff, wide blast radius: it changes the error envelope of every non-conflict failure on that path, so it is sized by consequence rather than by line count.
Serial constraints cleared: no in-flight PR in this lane at claim time. Region-disjoint from the two siblings this round (#7134 = saveMetaItem, #7408 = a metadata-fs test); deleteMetaItem was last touched by #6960 → 30bed706d, already landed.

⚠️ Hard constraint carried into the dispatch: ADR-0029 D9's control-plane pin asserts a message substring precisely because of this defect. Tightening that pin is the natural follow-on but is not in this card — touching D9's pin file is a STOP.

---

Generated by Claude Code

[os-zhuang]

{
 "issue": 7426,
 "status": "draft_pr_open",
 "premise_still_valid": true,
 "premise_evidence": "Re-measured on origin/main @ 08363a09 (the issue measured f16e54e1d, and #6960 landed a delete carve-out in between). Control-plane kernel (environmentId === undefined), artifact-backed item of a supportsOverlay:false type: deleteMetaItem answers status 403 with code undefined, the code surviving only as prose in the message. Measured as 15 red in the new pin file against unmodified main; the first failing assertion on every refusal case is `expected undefined to be 'NOT_OVERRIDABLE'` while status is already 403 — the defect exactly as filed. The PM's mechanism hypothesis (the catch re-wrap carries status and drops code) is CONFIRMED, not falsified.",
 "branch": "claude/issue-7426-delete-rewrap-code",
 "base_sha": "08363a09f88457ee96db6dc1869d201122681928",
 "head_sha": "09fa628a2b33688c8703d110e7e9339df3afb79b",
 "pr": 7466,
 "pr_url": "https://github.com/objectstack-ai/objectstack/pull/7466",
 "pr_state": "draft",
 "changeset": ".changeset/delete-meta-item-rewrap-carries-code.md (@objectstack/metadata-protocol: patch)",
 "worktree": "objectstack-issue-7426",

 "file_surface": [
 {
 "file": "packages/metadata-protocol/src/protocol.ts",
 "change": "+1 module-scope helper `carryCatalogedErrorCode` next to `toRowApiError` (whose ADR-0112 predicate it reuses verbatim), and one added line in each of deleteMetaItem's two catches. No control flow, no status expression, no message text touched.",
 "lines_added": 64
 },
 {
 "file": "packages/metadata-protocol/src/protocol.delete-rewrap-envelope.test.ts",
 "change": "NEW. The affected-failure-kinds matrix, executable: 26 cases over the real write path against a stub engine injecting throws at named seams (probe read / transactional delete / history insert / audit insert / registry heal).",
 "lines_added": 564
 },
 {
 "file": "packages/metadata-protocol/src/protocol.legacy-overlay-delete.test.ts",
 "change": "#6960's own pin, TIGHTENED. Its `expectRefused` branched on topology and reached the code only as a message substring on the control-plane leg, with a comment naming #7426 as the reason. That comment becomes false after this change, so the branch is deleted and every leg asserts code + status.",
 "lines_changed": 42
 },
 {
 "file": ".changeset/delete-meta-item-rewrap-carries-code.md",
 "change": "NEW. patch changeset."
 }
 ],

 "affected_failure_kinds": [
 {
 "kind": "Repository authorization refusal, override-artifact (NOT_OVERRIDABLE) — control-plane kernel, whole supportsOverlay:false && allowRuntimeCreate tier: action datasource doc external_catalog field flow hook mapping object seed",
 "before": "403, code undefined",
 "after": "403 + code NOT_OVERRIDABLE",
 "pinned_before": "ADR-0029 D9's control-plane pin could only assert a MESSAGE SUBSTRING; #6960's pin stated the gap in a comment instead of asserting around it",
 "disposition": "FIXED — this is the card's own case"
 },
 {
 "kind": "Repository authorization refusal, runtime-only (NOT_CREATABLE)",
 "before": "n/a",
 "after": "n/a",
 "pinned_before": "none",
 "disposition": "UNREACHABLE THROUGH THIS CATCH, MEASURED. useRepoPath needs the protocol's isRuntimeCreateAllowed/isOverlayAllowed and the repository's assertAllowed reads the SAME registry, so it returns before it can throw. Recorded so its absence is not read as an omission."
 },
 {
 "kind": "Engine failure carrying a REGISTERED code (ERR_DATASOURCE_UNAVAILABLE, ERR_DRIVER_CONNECT) — probe read and inside the transaction",
 "before": "status only, no code",
 "after": "status + that code",
 "pinned_before": "none",
 "disposition": "FIXED — a code the engine did register is as machine-readable as this package's own"
 },
 {
 "kind": "Engine failure carrying an UNREGISTERED driver code (42P01, SQLITE_CONSTRAINT, ECONNREFUSED, ER_DUP_ENTRY)",
 "before": "500, no code",
 "after": "UNCHANGED — deliberately dropped",
 "pinned_before": "none",
 "disposition": "GUARDED. The predicate is the whole reason the fix is not `e.code = err.code`: an unconditional copy puts a driver dialect into the field ApiErrorSchema declares as a closed union (ADR-0112 D4). 4 new [GUARD] cases, load-bearing via the variant experiment."
 },
 {
 "kind": "Plain Error with no code (history-table outage, missing id column, closed repository)",
 "before": "500, no code",
 "after": "UNCHANGED",
 "pinned_before": "rest-5xx-message-sanitization.test.ts walks this live",
 "disposition": "UNCHANGED, pinned"
 },
 {
 "kind": "ConflictError (optimistic lock / row vanished)",
 "before": "409 + METADATA_CONFLICT",
 "after": "UNCHANGED",
 "pinned_before": "several",
 "disposition": "UNCHANGED — caught one branch ABOVE the re-wrap, never passes through it. Pinned anyway because the catch is shared: an edit moving the re-wrap above the conflict branch would silently relabel a 409 as a 500."
 },
 {
 "kind": "Post-persistence tail: registry heal, table drop, audit write, ADR-0094 projector, mutation listeners",
 "before": "never reaches the catch",
 "after": "UNCHANGED",
 "pinned_before": "none",
 "disposition": "CANNOT REACH THE RE-WRAP — each swallows its own failure by design. Measured, not read: one case makes three of them throw at once and asserts the receipt survives."
 },
 {
 "kind": "Legacy raw-engine exit (code-only types on a control-plane kernel) — the SECOND re-wrap in the same method",
 "before": "500, no code",
 "after": "500 + code under the SAME predicate; status stays the literal 500",
 "pinned_before": "none",
 "disposition": "FIXED for code, status untouched. Fixing only the repository catch would leave deleteMetaItem answering an envelope that varies by which path served the delete — the very thing the card forbids. Status stays literal because that path carries no authorization gate (deliberately, #5264), so every failure through it really is a fault; moving it is a separate contract decision."
 }
 ],

 "triage_question_answered": {
 "question": "check whether saveMetaItem and the other repository-fronting verbs carry the same shape",
 "answer": "They do NOT. protocol.ts contains exactly two re-wrap sites and both are in deleteMetaItem. Every sibling verb (saveMetaItem, publishMetaItem, revertCommit, rollbackMetaItem) translates ConflictError and then `throw err`s the original untouched, so code survives there already. saveMetaItem's re-wrap was deleted with its legacy raw-engine branch in #5264."
 },

 "reverse_verification": {
 "base": "08363a09 (own base SHA, never a moving origin/main)",
 "dist_rebuilt_before_reading_results": true,
 "predicted_red_measured_red": {
 "predicted": 17,
 "measured": 17,
 "detail": "Reverting ONLY protocol.ts to base while keeping both test files: 15 red in protocol.delete-rewrap-envelope.test.ts (10-type refusal sweep, plural spelling, cross-topology equality, 2 catalogued-engine cases, legacy catalogued case) — each failing on code === undefined while status is already correct; plus 2 red in protocol.legacy-overlay-delete.test.ts (the two control-plane legs of expectRefused). NOTE: those two carry a [GUARD] label that is #6960's, scoped to #6960's change; they are genuine red-in-reverse evidence for THIS one and were left unrenamed rather than misreport what they guard."
 },
 "green_in_both_directions_GUARDS": {
 "count": 9,
 "cases": [
 "[GUARD] Postgres undefined_table (42P01) does not become an ADR-0112 code",
 "[GUARD] SQLite constraint (SQLITE_CONSTRAINT) does not become an ADR-0112 code",
 "[GUARD] Node socket (ECONNREFUSED) does not become an ADR-0112 code",
 "[GUARD] MySQL duplicate (ER_DUP_ENTRY) does not become an ADR-0112 code",
 "[GUARD] a plain Error with no code at all is unchanged — 500, no code",
 "[GUARD] an uncatalogued driver code stays out of the legacy envelope",
 "[GUARD] ConflictError keeps its own translation (METADATA_CONFLICT / 409)",
 "[GUARD] the post-persistence tail cannot reach the catch",
 "[GUARD] the project kernel answered the full envelope already, and still does"
 ],
 "labelled_in_test_file": true,
 "what_makes_them_load_bearing": "VARIANT EXPERIMENT, direction declared before running: replace the predicate with an unconditional `if (typeof code === 'string')` copy — the over-broad shape the issue names. PREDICTED: exactly the 5 uncatalogued-code guards turn red, nothing else. MEASURED: exactly 5 red, exactly those. Variant reverted."
 },
 "missed_predictions": [
 {
 "prediction": "Promoting expectRefused's message-substring check from the control-plane leg to EVERY leg would be green in both directions",
 "measured": "RED on the project kernel, 2 cases",
 "cause": "The two producers spell the marker inside their PROSE differently: deleteMetaItem's own two-tier block writes `[not_overridable]`, SysMetadataRepository writes `[NOT_OVERRIDABLE]`. Only the `code` FIELD is uniform — which is ADR-0112's own point (the catalog governs error.code; message prose is a different surface) and precisely why the field is the assertion that belongs there.",
 "resolution": "Check made case-insensitive; the correction is written into the test file rather than tidied away. The prose divergence is pre-existing and outside this card — listed as follow-up 2."
 }
 ],
 "unmeasured": "none — every assertion in the new file was run in both directions; the ones that cannot go red on this change say so in their own names and are covered by the variant experiment"
 },

 "gates": [
 { "gate": "check:error-code-casing", "status": "pass", "detail": "17 self-test cases; 3443 files scanned; no lowercase codes" },
 { "gate": "check:route-envelope", "status": "pass", "detail": "8 route modules + 16 dispatcher domains; 0 ratcheted" },
 { "gate": "check:engine-double-contract", "status": "pass", "detail": "138 pinned, 133 DEBT, 2 exempt — ledger unchanged" },
 { "gate": "check:nul-bytes", "status": "pass", "detail": "6840 text files" },
 { "gate": "metadata-protocol suite", "status": "pass", "detail": "70 files / 1035 tests" },
 { "gate": "objectql suite", "status": "pass", "detail": "176 files / 3127 tests — ADR-0029 D9's pin file untouched and green" },
 { "gate": "rest-5xx-message-sanitization.test.ts", "status": "pass", "detail": "13/13 — affected downstream surface; its live-protocol section walks this exact catch with a failing driver" },
 { "gate": "CI (full lint farm + queue build)", "status": "in_progress", "detail": "left to CI by instruction; not enumerated locally" }
 ],

 "stop_conditions": [
 { "condition": "touch ADR-0029 D9's pin file (packages/objectql/src/protocol-object-overlay-layer.test.ts)", "triggered": false, "detail": "byte-identical; read only. This PR makes that pin TIGHTENABLE and does not tighten it." },
 { "condition": "change packages/spec's acceptance surface", "triggered": false, "detail": "read only — ErrorCode / ERROR_CODE_LEDGER consulted, nothing declared or altered. No route to #6017 needed." },
 { "condition": "change packages/rest's behaviour", "triggered": false, "detail": "not touched. rest already forwards a declared code when the producer sets one (resolveErrorResponse, both 5xx and 4xx limbs), so the improvement reaches the wire with no change there." }
 ],

 "open_questions": [
 "Tightening ADR-0029 D9's control-plane pin (packages/objectql/src/protocol-object-overlay-layer.test.ts) to assert code + status like its project-kernel sibling is now possible. Explicitly out of scope by dispatch constraint — needs its own card.",
 "The [not_overridable] vs [NOT_OVERRIDABLE] prose divergence between deleteMetaItem's own block and SysMetadataRepository. Cosmetic for machines (both set code correctly), confusing for a human grepping logs. Not an error.code defect, so not filed as one; recorded here for the PM to decide whether it is worth a card.",
 "The legacy raw-engine exit's status stays a literal 500 even when it now carries a code whose natural status differs (e.g. ERR_DATASOURCE_UNAVAILABLE → 503). Judged deliberately: that path has no authorization gate, so every failure through it really is a fault, and pass-through status there has no known beneficiary. Flagged rather than taken."
 ],

 "notes": "Worktree: the container's primary checkout was pre-created ON the designated branch and `git checkout main` was refused by the permission classifier, so the dedicated worktree was created with `git worktree add --force` onto the same branch. All edits were made in /home/user/objectstack-issue-7426, never in the primary checkout. No git stash was used at any point."
}

---

Generated by Claude Code