Extract rest-server.ts's error/fault-classification prologue — it is ADR-0112's concern, not the REST server's

[qq9340100]

Filed by the domain:cli seat on the 2026-08-15 maintainer ruling on #5949 (「接受你的建议」, recorded at #5949 comment 5301726968). Card 1 of the two extractions that ruling authorised.

⚠️ This is NOT the ADR-0076 D11 decomposition. That programme was ruled closed (option B — the second half is delineated, not split). This card stands on a different justification and would be worth doing even if the routes never move.

The justification — prism ① (coherence), not ③

packages/rest/src/rest-server.ts opens with ~1,980 lines before its first class declaration. That prologue (~732 code lines) is error and fault classification plus response shaping:

mapDataError · resolveErrorResponse · DATA_STORE_FAULT · UNCLASSIFIED_FAULT · isScriptFaultMessage · declaredHttpStatus · truncateClientMessage · sendError · sendFieldVisibilityFault · logWithheldServerFault · isExpectedDataStatus · isExpectedQueryRejection · isExpectedRouteError · logUnexpectedRouteError · handleRouteError · droppedFieldsHeaderValue · applyDroppedFieldsHeader · missingRelationIsObject

This is ADR-0112's domain — how a thrown thing becomes an HTTP answer — and it has zero coupling to the RestServer class: every one of these is a module-level function, declared before the class exists. It lives here for historical reasons, not structural ones.

Extracting it is a move, not a redesign.

Scope

• Move the prologue to its own module in packages/rest/src/, re-exporting whatever rest-server.ts and any external consumer already import.
• ⛔ No behaviour change. This is a file move plus imports. Any change to what a caller receives is out of scope and a stop-and-report.
• ⛔ Do not touch the RestServer class body, and ⛔ do not extract any registerXxxEndpoints method — that is the programme option B closed.
• export { zodIssuesToFields } at line ~188 is re-exported from here today; preserve the public surface exactly.

Premise to verify before moving

Measured on origin/main @ 04d03c3a0: first class declaration at line 1981, prologue is module-level functions only. Re-verify by symbol — this file has taken merges since, and this lane has been burned three times by trusting a stated line number.

⚠️ Also verify the zero-coupling claim rather than inheriting it: confirm no prologue function closes over class state or is referenced before its definition in a way that a module split would break. My reading was structural (declaration order), not a dependency trace.

Not claimed

• No user impact. Prism ② on [finding] ADR-0076 D11 的第二半从未落地:packages/rest/src/rest-server.ts 已 8593 行(ADR 记录约 5.1k),且无 issue 承接 #5949 found no measured business pull for anything in this file, and that finding stands. This card is justified on coherence alone, and it is cheap — not on urgency.
• Size is not the argument. [finding] ADR-0076 D11 的第二半从未落地:packages/rest/src/rest-server.ts 已 8593 行(ADR 记录约 5.1k),且无 issue 承接 #5949's line-count series was retired in the same ruling; ⛔ do not cite line counts as justification here.

Refs: #5949 (the ruling and the four-prism analysis), ADR-0112, ADR-0076 D11.

[qq9340100]

Claim: PM loop round 14
Session: session_01NaS1PAHJcPfAA2acnV53Tn
Branch: claude/issue-8850-rest-error-prologue-extract
Worktree: objectstack-issue-8850
Domain: domain:cli
File surface: packages/rest/src/** — region-level: the module-level prologue before the first class declaration, plus the new module and import updates (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Serial constraints cleared:

1. No open PR touches packages/rest — checked against the full open-PR set at claim time.
2. ⚠️ Characterize registerMetadataEndpointsInner (2,328 lines, 20% of rest-server.ts) — read and propose, do not split blind #8851 is dispatched in the same batch and reads the same file — deliberately, and here is why it is not a serial violation. Characterize registerMetadataEndpointsInner (2,328 lines, 20% of rest-server.ts) — read and propose, do not split blind #8851's scope is read and propose, with pr: null as its expected complete delivery; it produces no diff, so there is no collision for the merge queue to arbitrate. The two also do not overlap in region: this card moves the prologue (before the class), Characterize registerMetadataEndpointsInner (2,328 lines, 20% of rest-server.ts) — read and propose, do not split blind #8851 characterises registerMetadataEndpointsInner (inside it). The only real interaction is that line numbers shift under Characterize registerMetadataEndpointsInner (2,328 lines, 20% of rest-server.ts) — read and propose, do not split blind #8851 mid-analysis — which is why both dispatches require anchoring on symbols, and why this note exists on both cards rather than in my head.

Dispatched under the maintainer's direct channel and the 2026-08-15 ruling on #5949 (「接受你的建议」 ⇒ option B), which authorised exactly these two extractions and closed the ADR-0076 D11 programme.

⛔ Do not cite line counts as justification. #5949's line-count series was retired by the same ruling. This card stands on prism ① coherence alone: the prologue is ADR-0112's concern (how a thrown thing becomes an HTTP answer), it is module-level with zero coupling to the RestServer class, and it lives in this file for historical rather than structural reasons.

⛔ No behaviour change. A file move plus imports. Anything a caller receives differently is a stop-and-report, not a fix.

---

Generated by Claude Code

[qq9340100]

{
 "issue": 8850,
 "status": "done",
 "branch": "claude/issue-8850-rest-error-prologue-extract",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8887",
 "premise_still_valid": true,
 "summary": "Both dispatch premises hold, re-derived by symbol rather than inherited. First class is still `export class RestServer` at line 1981 on cc5c07b80; everything above it is module-level. Zero-coupling confirmed by dependency trace, not by declaration order: no moved function reads class state, and the arrow runs strictly class -> prologue (the class calls 7 of the 18; the other 11 had zero call sites there and stay module-private, exactly as before). Moved the card's 18 symbols plus their module constants to packages/rest/src/error-response.ts as one contiguous block, byte-identical (1289 lines, 0 diffs vs HEAD~1); the console shim both files need went to packages/rest/src/log.ts rather than being duplicated. Two deviations worth the PM's eye, both flagged in the PR body: (1) `log.ts` is a SECOND new module, chosen over copying a two-line shim or inverting the dependency; (2) mapDataError's docblock, stranded ~300 lines above its function since #8124 moved zodIssuesToFields to spec, is reattached — the only non-byte-identical edit besides six `export` prefixes. The sibling docblock drift (missingRelationIsObject's block above declaredHttpStatus) was deliberately left alone. Public surface preserved exactly: AST-compared, rest-server.ts exports the same 13 names before and after, none added or removed, `zodIssuesToFields` re-export and `mapDataError` included; index.ts byte-identical. One correction to the card, immaterial to the verdict since line counts are barred as justification: the extracted region is 404 non-comment code lines, not ~732.",
 "tests": "All at final head 24ee1df61 (clean tree, nothing unpushed). Gate union re-derived AFTER the final commit via `node scripts/pm/dispatch-gates.mjs packages/rest/src/error-response.ts packages/rest/src/log.ts packages/rest/src/rest-server.ts`, which surfaced check:authz-resolver, check:cross-package-test-inputs and check:route-envelope; check:nul-bytes added as the any-edit convention gate. Results, all exit 0, output redirected to files never piped: `pnpm --filter '@objectstack/rest^...' build` (closure, built first in the fresh worktree); `pnpm --filter '@objectstack/rest' typecheck`; `pnpm --filter '@objectstack/rest' test` = 118 files / 1948 tests, all passed; `pnpm --filter '@objectstack/rest' build` incl. DTS; check:route-envelope; check:authz-resolver; check:cross-package-test-inputs; check:nul-bytes (5894 files). check:route-envelope is the one the dispatch flagged: its counts did NOT move — rest-server.ts stays at stringError 44 / siblingCode 69 — because all 113 dialect sites are inside the class body and the moved prologue contained none. Measured with the checker's own scanSource BEFORE editing anything, so this is a measurement rather than a post-hoc reading. No ledger line was edited. REVERSE VERIFICATION, direction predicted before running: for a pure move the meaningful question is whether the suites exercise the NEW module rather than a stale copy, so I ablated UNCLASSIFIED_FAULT's status 500 -> 599 in error-response.ts and predicted RED. Observed RED across five suites (rest-5xx-status-passthrough, rest-expected-error-logging, rest-hook-refusal-status-passthrough, rest-hook-script-fault-envelope, rest-unclassified-fault-status). Restored with `git restore --source=HEAD --staged --worktree`, then proved identity by `git hash-object` == `git rev-parse HEAD:<path>` with a clean `git status --porcelain` — not by eyeballing a --stat. No dist ablation involved: these suites run from src via vitest, so no rebuild applies; the package build was run separately and is green. COVERAGE, including the gap: 19 rest suites cover the moved code (rest-unclassified-fault-status, rest-unknown-object-heuristic, rest-5xx-status-passthrough, rest-5xx-message-sanitization, rest-4xx-message-truncation, rest-hook-refusal-status-passthrough, rest-hook-script-fault-envelope, rest-expected-error-logging, rest-meta-outage-vs-miss, rest-unique-violation-dialects, external-write-forbidden-envelope, package-door-5xx-message-sanitization, rest-dropped-fields, rest-update-path-id-not-a-dropped-field, zod-union-fields, rest.test.ts + 3 more). HONEST GAP: `sendFieldVisibilityFault` — the ADR-0106 D6 tier-3 refusal — has NO test anywhere in the repo; a repo-wide search for FIELD_VISIBILITY_UNRESOLVED outside dist/ returns only the emitter and a docs page that advertises it to operators. Filed as #8885. CI gate conclusions on the PR are in_progress and are the PM's to read per the 2026-08-10 ruling; I did not wait on them.",
 "open_questions": [
 {
 "question": "The move creates packages/rest/src/error-response.ts, which emits 2 REST response bodies (sendError, handleRouteError) but is invisible to check:route-envelope's discover() — it is neither *-routes.ts nor in OFF_CONVENTION_MODULES. Nothing is red and rest-server.ts's ratchet is intact, but a new non-conforming dialect literal written in the new module would now be counted by nothing, whereas the same literal next to sendError in rest-server.ts was counted before. The remedy is ~4 lines in scripts/check-route-envelope.mjs, which is OUTSIDE this card's declared file surface (packages/rest/src/**), and the dispatch said to stop on breach and explain rather than widen. Fold it into PR #8887, or leave it to #8884?",
 "options": [
 "A — leave as filed (#8884), PR #8887 lands as a strict packages/rest/src/** change. Honours the stated file surface; the gap stays open until #8884 is dispatched.",
 "B — fold the 4 lines into #8887 now: add 'error-response.ts' to OFF_CONVENTION_MODULES and { responses: 2, ok: 0, err: 0 } to MODULES, so the move lands with its own audit coverage intact and #8884 closes with it.",
 "C — leave both the gap and #8884 open indefinitely on the grounds that the counts are 0/0 today."
 ],
 "recommendation": "B, if you are willing to widen the surface by those 4 lines — otherwise A. B is right on all three axes and is the gate's own documented onboarding path ('Adding a name here is cheap; the module then has to appear in MODULES or the audit fails, which is the point'). Real business need: measured, not speculative — the coverage reduction is created by THIS PR, and 0/0 is precisely the moment a ratchet is worth pinning, since it can then only ever tick up into a failure. Long-term soundness: a response-emitting module nobody audits is the exact shape the checker's header records paying for once already with rest-server.ts. Hard-to-get-wrong: it makes a future AI-written dialect literal in the new module a loud CI failure instead of silent drift — structural prevention at authoring time rather than reviewer vigilance. I did NOT take it unilaterally because the file surface was stated explicitly and a 4-line gate edit is exactly the kind of 'while I was in there' that the surface constraint exists to stop. One thing to verify while doing B: every conformant entry in that table is 0/0/0, so a responses: 2 entry would be the first of its shape — read auditModule before assuming it is legal. C is wrong: it treats a green count as a blessing rather than as the cheapest possible moment to pin it."
 }
 ],
 "out_of_scope_findings": [
 "filed as #8884 (finding): check:route-envelope's discover() cannot see packages/rest/src/error-response.ts — a response-emitting module (responses: 2, all dialects 0) outside both the *-routes.ts convention and OFF_CONVENTION_MODULES; latent coverage reduction created by this PR, remedy is ~4 lines outside the card's file surface",
 "filed as #8885 (unlabeled, concrete defect, Blocked-by #8846): rest puts FIELD_VISIBILITY_UNRESOLVED (503, ADR-0106 D6 tier 3) and RECORD_NOT_ACCESSIBLE (403) on the wire, and neither is in StandardErrorCode or ERROR_CODE_LEDGER — while UNIQUE_VIOLATION / FEEDS_DISABLED / ERR_DATASOURCE_UNAVAILABLE / PROJECT_PROVISIONING all are, so the absence is real and not an artifact of the search. FIELD_VISIBILITY_UNRESOLVED additionally has zero test coverage repo-wide while being documented to operators in production-readiness.mdx. RECORD_NOT_ACCESSIBLE's own source comment claims it uses 'the STANDARD catalog code rather than a bespoke one' and it is not in the catalog. Likely a population larger than two — flagged as needing a sweep, not a two-line fix."
 ]
}

---

Generated by Claude Code

[qq9340100]

Supersedes the report at 5302650141. Option B taken as ruled; the CI failure on check-durability-degradation-log-level diagnosed and fixed first, per the PM's sequence. Final head 294788317.

{
 "issue": 8850,
 "status": "done",
 "branch": "claude/issue-8850-rest-error-prologue-extract",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8887",
 "premise_still_valid": true,
 "summary": "Both dispatch premises hold, re-derived by symbol. Moved the card's 18 symbols plus module constants to packages/rest/src/error-response.ts, byte-identical (1289 lines, 0 diffs); console shim to packages/rest/src/log.ts rather than duplicated; mapDataError's stranded docblock reattached (the only non-byte-identical edit besides six `export` prefixes). Public surface preserved exactly: same 13 exported names, index.ts byte-identical. TWO GATE DECLARATIONS added in a second commit, both consequences of the move, neither changing what any gate enforces — no baseline touched, no ratchet raised, no threshold moved. (1) check-route-envelope.mjs: error-response.ts named in OFF_CONVENTION_MODULES + a { responses: 2, ok: 0, err: 0, ratchet: '#7035' } entry, closing #8884 in this PR per the ruling. (2) check-durability-degradation-log-level.mjs: handleRouteError declared in FAILURE_PROPAGATION_CALLEES as via:'effect', repairing a visibility regression the move caused.",
 "tests": "STOP CONDITION ON OPTION B: NOT triggered. `auditModule` does not exist as a named function — the ordinary-module audit is inline in `audit()` at lines 704-719. Read before editing: `want = { privateOk: 0, stringError: 0, siblingCode: 0, ...declared }` and each of the six keys is compared by strict equality `got[key] !== want[key]`. `responses`/`ok`/`err` carry NO default, so they must be declared, and a non-zero `responses` is legal — the `got > want` branch at line 710 only appends extra advice text to an ALREADY-failing comparison, it is not a legality constraint. `{ responses: 2, ok: 0, err: 0 }` therefore audits by equality like any other entry. I added a `ratchet` alongside it (allowed: `ratchet` is spread into `want` but is not in the iterated key list, and NON_DIALECT_KEYS exclusivity applies only to dialectOnly entries) because `responses: 2` IS outstanding drift by the table's own definition — the conformant state is 0, with #7035 option 1 as the end state, exactly as rest-server.ts's entry names. Result: check:route-envelope exit 0, 10 modules audited (was 9), and rest-server.ts UNMOVED at stringError 44 / siblingCode 69 — the PM's stop condition on that number did not fire. CI FAILURE, diagnosed in the ordered sequence before any fix: (1) Is main green? YES — clean origin/main worktree at cc5c07b80, `pnpm check:durability-log-level` exit 0, 25 seams. So this PR caused it. (2) HOW — measured, not assumed, and the PM's hypothesis was directionally right but named the wrong table. It is NOT FAILURE_PROPAGATION_CALLEES that lost resolution. The gate's own `--list` on main reports both seams as `loud (error@120 via handleRouteError())`: line 120 was `logError`, and `collectLoggedLevels()` reached it by following handleRouteError as a SAME-FILE helper through a per-file `functionBodies` map (depth-capped at 3). The regressed path is loudness-via-same-file-helper, not delivery. Moving handleRouteError to its own module made that inference unavailable; helper resolution is file-scoped by construction. Behaviour did not move a line. FIX = the declaration the gate's own failure message prescribes, not a log: handleRouteError in FAILURE_PROPAGATION_CALLEES, via:'effect' (it is a bare ExpressionStatement in both catches; `via` semantics read at catchDeliversFailure lines 835-904). Justified: it resolves once then ALWAYS writes res.status().json(), no branch returns without answering; and it is the ONLY definition of that name in the repo (measured), so a callee-scoped declaration is unambiguous. NOT a weakening, and stricter than what it replaces: handleRouteError logs only when isExpectedRouteError() is false, so 'unconditionally loud' was always slightly generous — what is unconditional is the answer to the caller. catchDeliversFailure() still proves every path reaches it. Seam count 25 on main and 25 on the branch — nothing left the gate's view (3 propagating -> 5, matching the two reclassified sites). FINAL UNION at head 294788317, re-derived over all five changed paths, output redirected to files never piped: check:route-envelope 0, check:durability-log-level 0, check:authz-resolver 0, check:cross-package-test-inputs 0, check:nul-bytes 0 (5894 files); `pnpm --filter '@objectstack/rest^...' build` 0; typecheck 0; test 118 files / 1948 tests all passed; package build 0 incl. DTS. NOTE the derivation now DOES name check:durability-log-level — it matches on the script path literal, which is why the first derivation could not see it while the gate still applied to packages/rest source. One false red worth recording so it is not mistaken for a real one: my first post-fix typecheck failed with ~25 TS2307 'cannot find module' errors, which was the missing build closure in the RE-CREATED worktree (I had torn the first one down after the initial PR, taking every dependency dist with it), not a code fault — rebuilt the closure and it went green. Reverse verification unchanged from the first report: 500->599 ablation of UNCLASSIFIED_FAULT predicted RED, observed RED across five suites, restored and proved byte-identical via git hash-object.",
 "open_questions": [],
 "out_of_scope_findings": [
 "#8884 — CLOSED BY THIS PR per the PM ruling, not left open: check:route-envelope could not discover packages/rest/src/error-response.ts. Both table entries added, `Fixes #8884` added to the PR body alongside `Fixes #8850`.",
 "#8885 remains open and is NOT addressed here (no closing keyword anywhere near it in the PR body — verified by regex read-back of the stored body: the only closing keywords are `Fixes #8850` and `Fixes #8884`). rest puts FIELD_VISIBILITY_UNRESOLVED (503, ADR-0106 D6 tier 3) and RECORD_NOT_ACCESSIBLE (403) on the wire and neither is in StandardErrorCode or ERROR_CODE_LEDGER; FIELD_VISIBILITY_UNRESOLVED additionally has zero test coverage repo-wide while documented to operators in production-readiness.mdx. Blocked-by #8846.",
 "NOT filed, reported here as a PM judgment call: check:durability-log-level's lint.yml path filter lists only its own script, so it does not fire on packages/rest/src/** changes — which is exactly why dispatch-gates.mjs could not name it for the first commit even though the gate applied. This is the known repo-wide-family gap rather than a new defect, and widening a workflow path filter is a devx decision, so I did not file it unilaterally. Say the word and I will."
 ]
}

---

Generated by Claude Code

[qq9340100]

ACCEPT — PR #8887, including both gate declarations and the option-B widening I authorised. Pending gates, this lands.

The CI failure was diagnosed correctly, and my hypothesis was wrong

I guessed the regression was FAILURE_PROPAGATION_CALLEES losing delivery resolution. Measured, it was not. The gate's own --list on main reported both seams as loud (error@120 via handleRouteError()): collectLoggedLevels() was reaching logError two frames down by following handleRouteError as a same-file helper, through a per-file functionBodies map. Moving the function to its own module made that inference unavailable, because helper resolution is file-scoped by construction.

So what regressed was loudness-via-same-file-helper, not delivery — a different table and a different mechanism than I named. Correct diagnosis of a gate you did not write, reached by reading it rather than by pattern-matching my guess.

The order was right and it is the part that mattered most: main was checked first (clean worktree at cc5c07b80, gate exit 0, 25 seams) before anything was fixed. Had main been red, none of this was ours. That question decides whether "make my PR green" is even the correct goal.

Why the fix is not a weakening — and is in fact stricter

The declaration says handleRouteError delivers via: 'effect', and the argument for it is sharper than the thing it replaces: handleRouteError logs only when isExpectedRouteError() is false, so the old "unconditionally loud" inference was always slightly generous. What is unconditional is the answer to the caller — res.status(...).json(...) with no branch returning without answering. catchDeliversFailure() still proves every path reaches it, and it is the only definition of that name repo-wide, so a callee-scoped declaration is unambiguous.

⭐ The check that makes this trustworthy rather than plausible: seam count is 25 on main and 25 on the branch, with propagating sites going 3 → 5 — exactly the two reclassified seams. Nothing left the gate's field of view. That is the measurement that distinguishes "restored visibility" from "hid two problems", and it is the one I would have asked for.

And no logger.error was bolted on, which was the trap the gate's own message warns about.

Option B: the stop condition did not fire, and it was actually checked

auditModule does not exist as a named function — the ordinary-module audit is inline in audit() (704–719). Read before editing: responses/ok/err carry no default so they must be declared, comparison is strict equality per key, and the got > want branch only appends advice to an already-failing comparison rather than constraining legality. So { responses: 2, ok: 0, err: 0 } audits like any other entry.

Adding ratchet: '#7035' alongside it is the right call and slightly better than what I authorised: responses: 2 is outstanding drift by the table's own definition, with 0 as the conformant state — so it is recorded as drift-with-an-owner rather than as a blessed shape. check:route-envelope exit 0, 10 modules audited (was 9), and rest-server.ts unmoved at stringError 44 / siblingCode 69 — the stop condition I set on that number did not fire. #8884 closes with this PR.

One judgment call I am ruling on, and one thing I want filed

File it. The report flags — correctly, without filing unilaterally — that check:durability-log-level's lint.yml path filter lists only its own script, so dispatch-gates.mjs could not name it for a packages/rest/src/** change even though the gate applies there. That is the concrete mechanism behind the "repo-wide / undetermined" bucket that has cost this lane a red CI round tonight, and it is worth a card in the devx lane rather than folklore. I am filing it; ⛔ not fixing it here, since widening a workflow path filter is a devx decision.

The false red (≈25 TS2307 from a missing build closure in a re-created worktree) is correctly identified as environment rather than code, and recording it is the right instinct — that failure mode reads exactly like a broken diff.

#8885 stays open and carries no closing keyword — verified by read-back of the stored PR body, which contains only Fixes #8850 and Fixes #8884. Good: it is a real defect with a wider population than two, and it should not ride out on this card.

---

Generated by Claude Code