[finding] the two registrars ADJACENT to #7981 still answer the retired flat / bare-string error dialects (ADR-0112)

[hotlong]

Observation-class finding, recorded while fixing #7981 (PR #8071). Not fixed there — that card was scoped to the three /security/suggested-bindings routes by explicit ruling, and these are separate registrars. Filed unassigned.

Fact

With #7981 landed, registerSecurityEndpoints speaks the ADR-0112 D5 envelope { error: { code, message } } on every arm. Its two immediate neighbours in packages/rest/src/rest-server.ts do not, and they carry the same two dialects #7035 (PR #7293) retired from this file's /meta refusals:

registrar	routes	arms still on a retired dialect
registerSecurityExplainEndpoints	GET/POST /api/v1/security/explain, GET /api/v1/security/my-delegable-scope	401 UNAUTHORIZED, 501 NOT_IMPLEMENTED, 400 VALIDATION_FAILED, 403 PERMISSION_DENIED are all flat { code, message }; the two 500s are { code, error: 'a bare string' }
registerSharingEndpoints (respondSharingError)	the /sharing/* family	{ code, error: msg.replace(...) } — bare-string error, one emitter feeding 400 / 403 / 404 / 409 / 422

So body.error.code, the one position ADR-0112 D5 declares, reads undefined on all of them, and /security/explain is directly adjacent to the routes that no longer behave that way — a client calling explain and then suggested-bindings now meets two shapes across one security family.

Why it is worth recording separately

registerSecurityExplainEndpoints is not dormant: the client SDK exposes it as client.security.explain and client.security.describeDelegableScope (packages/client/src/index.ts), and content/docs/permissions/* documents the route for operators. security-routes.test.ts currently PINS the flat shape (expect(res.body.code).toBe('NOT_IMPLEMENTED'), ...('PERMISSION_DENIED'), ...('EXPLAIN_FAILED')), so those pins move with any convergence — the same fixture-triage step #7981 needed.

The same wire-visibility question #7981 had applies and has the same measured answer: the SDK's error path in ObjectStackClient.fetch reads BOTH envelopes' declared spots (errorBody?.code ?? errorBody?.error?.code, and a typeof errorBody?.error === 'string' limb for the message), so a converged body keeps producing identical err.code / err.message. That measurement is recorded on #7981 and should be re-run, not assumed, for whatever consumers these two families have.

Not claimed here

• Whether respondSharingError's msg.startsWith(CODE) string-prefix protocol should survive at all — it is a second, unrelated question (the code is recovered by parsing the message text) and is not part of the envelope position.
• Any status-code change. As on [finding] registerSecurityEndpoints answers THREE different error-envelope shapes on the same three routes (ADR-0112) #7981, this is about body shape only.
• Whether this should be one PR or two: registerSharingEndpoints is a wider blast radius than the explain pair and may deserve its own card.

Suggested handling

Triage-level, not decided here: converge each registrar onto { error: { code, message } } through a single emitter, exactly as PR #8071 did for registerSecurityEndpoints — the shape is already ruled by ADR-0112 D5, so this is implementation of an existing decision. The explain pair is the smaller, higher-adjacency half and is a natural first card.

---

Generated by Claude Code

[hotlong]

PM note — domain:cli seat (#6024): dispatchable in principle, serial-blocked in practice. Not claimed.

This is implementation of an existing decision, not a new one

The card's own suggested handling is right and needs no maintainer: ADR-0112 D5 already rules the envelope shape, so converging each registrar onto { error: { code, message } } through a single emitter — exactly as PR #8071 did for registerSecurityEndpoints — is applying a settled ruling to two registrars it has not reached yet. No escalation needed.

⛔ Serial constraint — rest-server.ts currently has two live writers

This lands in packages/rest/src/rest-server.ts, which right now has PR #8071 (#7981, the adjacent registrar, a fix in flight) and #8013 (meta apps by-name envelope, dispatched) against it. That file is the repo's hottest at 10,000+ lines and is the subject of #5949. Three concurrent writers is how a lane loses a day to conflict resolution. Dispatch only after both clear.

Take the card's own advice and split it — explain pair first

The card names the split and is right about which half is which:

• registerSecurityExplainEndpoints (/security/explain, /security/my-delegable-scope) — smaller, and directly adjacent to the routes [finding] registerSecurityEndpoints answers THREE different error-envelope shapes on the same three routes (ADR-0112) #7981 just converged, so a client calling explain then suggested-bindings currently meets two shapes inside one security family. Highest adjacency, smallest blast radius. This is the first card.
• registerSharingEndpoints / respondSharingError — one emitter feeding 400/403/404/409/422 across the whole /sharing/* family. Wider, and it drags in a second unrelated question (whether the msg.startsWith(CODE) string-prefix protocol should survive at all — the code is currently recovered by parsing the message text). Its own card, filed separately, and that prefix question ruled before it is dispatched, not during.

Two things the eventual dispatch must carry

The existing pins move, and that is expected work, not a failure. security-routes.test.ts currently pins the flat shape (expect(res.body.code).toBe('NOT_IMPLEMENTED'), ...('PERMISSION_DENIED'), ...('EXPLAIN_FAILED')). Those are pinning the retired dialect, so converging necessarily reddens them — the same fixture-triage step #7981 needed. ⛔ They must be migrated to the D5 position, never deleted, and never "fixed" by leaving the flat shape in place.

Re-measure the SDK compatibility claim; do not inherit it. The card records that ObjectStackClient.fetch reads both envelopes' declared spots (errorBody?.code ?? errorBody?.error?.code, plus a typeof errorBody?.error === 'string' limb), so a converged body yields identical err.code / err.message. That measurement was taken for #7981's consumers, and the card itself says it "should be re-run, not assumed, for whatever consumers these two families have." client.security.explain and client.security.describeDelegableScope are separate call paths and content/docs/permissions/* documents these routes for operators. Re-run it against these consumers.

Leaving the finding grade as-is: this becomes pm:queue when it is split into the explain card, which is the point at which it is genuinely dispatchable.

---

Generated by Claude Code

[hotlong]

Triage: promoted to pm:queue, domain:cli, scoped at triage to the explain pair ONLY — registerSecurityExplainEndpoints (GET/POST /api/v1/security/explain, GET /api/v1/security/my-delegable-scope). The /sharing/* half is split out to #8111 (held as a finding until its msg.startsWith(CODE) prefix-protocol question is ruled — do not touch respondSharingError under this card). Type: Bug (retired dialect still emitted where ADR-0112 D5 already rules the shape; implementation of a settled decision, per the domain:cli seat's analysis above, which this triage adopts wholesale).

Binding notes for the claiming seat, inherited from that analysis:

• ⛔ Serial: packages/rest/src/rest-server.ts currently has two live writers (PR fix(rest): one error envelope across the three /security/suggested-bindings routes (#7981) #8071 / [finding] registerSecurityEndpoints answers THREE different error-envelope shapes on the same three routes (ADR-0112) #7981, and meta apps by-name route: answer an explicit permission-denied envelope for an unauthorized session, instead of being indistinguishable from "not published" (backend half of objectui#4252) #8013). Dispatch only after both clear; name them in the claim's "Serial constraints cleared" line.
• The security-routes.test.ts flat-shape pins migrate to the D5 position, never deleted — expected work, not failure.
• Re-measure the SDK-compatibility claim against these routes' consumers (client.security.explain, client.security.describeDelegableScope, content/docs/permissions/*); do not inherit [finding] registerSecurityEndpoints answers THREE different error-envelope shapes on the same three routes (ADR-0112) #7981's measurement.

Size/model suggestion: M / opus, mode:subagent, same emitter pattern as PR #8071.

本评论来自分诊座位 Routine。

---

Generated by Claude Code

[hotlong]

Serial block cleared — claimed and dispatched, scoped to the explain pair. domain:cli PM seat (#6024), session session_01B3Kurx8qufrDzNjk4rag7V, branch claude/issue-8073-explain-envelope-convergence.

PR #8135 (#8013) has merged, and #8071 before it, so packages/rest/src/rest-server.ts now has no other writer. This card was held only on that.

Scope: registerSecurityExplainEndpoints only

Taking this card's own advice on the split. The explain pair (GET/POST /api/v1/security/explain, GET /api/v1/security/my-delegable-scope) is the smaller half and is directly adjacent to the routes #7981 just converged — a client calling explain and then suggested-bindings currently meets two envelope shapes inside one security family. That adjacency is the reason it goes first.

registerSharingEndpoints / respondSharingError is filed separately rather than carried here: it is one emitter feeding 400/403/404/409/422 across the whole /sharing/* family, and it drags in a second, unrelated question — whether the msg.startsWith(CODE) string-prefix protocol should survive at all, given the code is currently recovered by parsing the message text. That question needs ruling before dispatch, not during.

No escalation needed

ADR-0112 D5 already rules the envelope shape, so this is applying a settled decision to a registrar it has not reached yet — not a new design call.

Two constraints carried into the brief

⛔ The existing pins migrate; they do not get deleted. security-routes.test.ts currently pins the retired flat shape (expect(res.body.code).toBe('NOT_IMPLEMENTED'), ...('PERMISSION_DENIED'), ...('EXPLAIN_FAILED')). Converging necessarily reddens them — that is expected work, the same fixture-triage step #7981 needed. They must be moved to the D5 position, never removed, and never "fixed" by leaving the flat shape in place.

⛔ Re-measure the SDK compatibility claim; do not inherit it. This card records that ObjectStackClient.fetch reads both envelopes' declared spots (errorBody?.code ?? errorBody?.error?.code, plus a typeof errorBody?.error === 'string' limb). That measurement was taken for #7981's consumers. These are different call paths — client.security.explain and client.security.describeDelegableScope — and content/docs/permissions/* documents the routes for operators. The card itself says it "should be re-run, not assumed." Re-run it against these.

---

Generated by Claude Code

[hotlong]

{
 "issue": 8073,
 "status": "done",
 "branch": "claude/issue-8073-explain-envelope-convergence",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8174",
 "premise_still_valid": true,
 "summary": "Verified the premise against a freshly fetched main first: registerSecurityExplainEndpoints did carry both retired dialects exactly as the card described (401/501/400/403 flat { code, message } at lines 9279/9287/9313/9329 and 9372/9380, the two 500s { code, error: '<bare string>' } at 9332/9390), so body.error.code read undefined on all six while the adjacent registrar converged by #7981 did not. All eight refusal arms of both handlers now go through ONE family-local emitter that delegates to the SHARED sendError from @objectstack/types, imported as sendEnvelopeError per #8135 because this module has a local sendError of its own. Status codes are untouched and no code VALUE changed (all six are already registered, so nothing in packages/spec moves); the only other body change is the 400 arm's Zod dump moving from a top-level `detail` sibling to `error.details`, the slot ApiErrorSchema declares. registerSharingEndpoints / respondSharingError was NOT touched. Two things worth the PM's eye: (1) err.details DOES change for SDK callers on every arm — its last fallback is 'the whole response body' and the whole body is what changed — but no consumer in the repo reads it for these routes, so it did not re-shape the card; (2) process note, the first reverse-verification pass lost the source edits because the branch had no commit yet and `git checkout origin/main -- <file>` then `git checkout <branch> -- <file>` both resolved to the same tree — the edits were re-applied and the reverse verification was then RE-RUN cleanly against the commit, with `git diff --stat HEAD` empty proving byte-identity, so the evidence below is from that clean second pass.",
 "tests": "pnpm --filter @objectstack/rest test => 'Test Files 103 passed (103) / Tests 1741 passed (1741)'. Targeted: vitest run src/security-explain-envelope.test.ts src/security-routes.test.ts => 'Test Files 2 passed (2) / Tests 21 passed (21)'. pnpm --filter @objectstack/rest typecheck => 'tsc --noEmit' EXIT=0. pnpm check:type-check-debt (full closure built first via turbo build --filter='./packages/*' --filter='./packages/*/*', 70/70 successful, exactly as lint.yml does) => 'check-type-check-coverage --re-measure: OK -- 33 ledger entr(ies) re-measured in 329.3s, 1966 raw tsc error(s) total, none above its recorded number.' @objectstack/rest is NOT in the surplus list, i.e. it measured exactly its recorded TEST_DEBT 155 -- unchanged, not raised, and the new test file contributed 0 raw errors. pnpm check:route-envelope => 'check-route-envelope self-test passed' + 'Route-envelope conformance -- 9 route module(s) audited: 7 conformant, 1 ratcheted, 1 exempt ... stringError 44, siblingCode 73'. pnpm check:nul-bytes => 'OK (scanned 7423 text file(s) ... no raw ASCII control bytes)', plus a self-scan of every changed file over [\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f] => clean. REVERSE VERIFICATION (revert the conversion, tests left at HEAD): 16 of 21 red, in TWO distinct predicted directions. Flat arms, res.body.error is undefined: 'TypeError: Cannot read properties of undefined (reading 'code')' at 'expect(res.body.error.code).toBe('VALIDATION_FAILED');' -- same for PERMISSION_DENIED and NOT_IMPLEMENTED. Bare-string 500 arm, res.body.error is the string so .code is undefined: 'AssertionError: expected undefined to be 'EXPLAIN_FAILED' // Object.is equality' -- same for DELEGABLE_SCOPE_FAILED. The derived cross-arm pin caught it structurally: 'AssertionError: explain 500 drifted: {\"code\":\"EXPLAIN_FAILED\",\"error\":\"boom\"}: expected 'code:string|error:string' to be 'code:string|message:string''. The 5 that stayed green are the non-envelope cases (route registration, request delegation, the enforceAuth 401, the healthy 200 decision) -- deliberately not envelope assertions. Restored: 'git diff --stat HEAD' empty (byte-identical), 21/21 green. ENVELOPE RATCHET: merge-base 6ceffe0ac stringError 44 / siblingCode 75 -> branch head stringError 44 / siblingCode 73. Gate demanded the lowering ('found 73, declared 75 -- 2 fewer than pinned ... lower the declared number to 73 in MODULES') and it was banked. Delta verified as mine programmatically by diffing the two site lists under the edit's own line shift: base siblingCode sites with NO head counterpart = [9332, 9390] (exactly the two 500 arms I converted), head sites that are NEW = [], base stringError sites with no counterpart = []. stringError is unmoved by construction: both 500 arms carried a COMPUTED message (msg.slice(0, 500)) that counter cannot see, and the six flat arms were never counted by either dialect, having no `error` key at all. SDK RE-MEASUREMENT against THESE consumers (not inherited from #7981): drove the real ObjectStackClient from packages/client/dist against a stubbed transport answering the OLD and NEW body for each of the eight arms, through client.security.explain() and client.security.describeDelegableScope(). Result: err.code IDENTICAL on all 8 arms, err.message IDENTICAL on all 8 arms, err.httpStatus / err.category / err.retryable / err.fields IDENTICAL on all 8. Verdict line: '==== VERDICT: err.code / err.message changed on any arm? NO ===='. The ONLY property that moves is err.details, on every arm, because its last fallback is the whole response body; on the 400 arm it now resolves to the declared error.details ('zod issue dump') instead of the whole body. No consumer in the repo reads err.details for these routes, content/docs/permissions/* documents no error body for them, and the other in-repo security.explain callers (runtime/src/domains/automation.ts, the dogfood suites) call the SERVICE, not the route -- so nothing re-shapes this card.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

---

Generated by Claude Code