docs(driver-sql): uncompilableAggregateFunctionError's 501 now survives to the wire (#7407)

[claude]

Fixes #7407

Comment-only. One paragraph of one docblock in packages/drivers/driver-sql/src/sql-driver.ts. No behaviour, no tests, no changeset — skip-changeset route (per the card; not creating an empty changeset).

What was stale

uncompilableAggregateFunctionError's closing "measured consequence" paragraph said:

on the /data routes mapDataError's generic status passthrough is 4xx-ONLY, so this declared 501 does not survive to the wire — it falls to UNCLASSIFIED_FAULT's 500 INTERNAL_ERROR.

True when written (#5907). PR #7402 closed #5582 and inverted it.

Verification (read, not taken on trust)

Against merged main @ 36237a1:

• packages/rest/src/rest-server.ts:846 — if (typeof error?.status === 'number' && error.status >= 400 && error.status < 600). The passthrough is 400-599, not 4xx-only.
• packages/rest/src/rest-server.ts:872-880 — the >= 500 arm returns { status: error.status, body: { error: INTERNAL_ERROR_MESSAGE, ...(declaresServerFault(error) ? { code: error.code } : {}) } }.
• packages/types/src/error-leak.ts:113-117 — declaresServerFault is status >= 500 && typeof code === 'string' && code.length > 0. The driver throws status: 501 + code: 'NOT_IMPLEMENTED', so both halves hold.
• Nothing above :846 intercepts it: every earlier branch keys on DELETE_RESTRICTED / CONCURRENT_UPDATE / ERR_DATASOURCE_UNAVAILABLE / VALIDATION_FAILED / the capability + access gates / PERMISSION_DENIED / innerMessage / OBJECT_NOT_FOUND / INVALID_FIELD.
• Pinned end-to-end, not just as a unit: packages/rest/src/rest-5xx-status-passthrough.test.ts:406-415 — "an aggregate the backend cannot compile answers 501 NOT_IMPLEMENTED on the wire", asserting res.statusCode === 501 and res.body === { error: INTERNAL_ERROR_MESSAGE, code: 'NOT_IMPLEMENTED' }.

So: the status and the ADR-0112 code now reach the caller. The prose does not — the 5xx arm drops the message unconditionally and substitutes 'Internal server error'. The card and the dispatch both described only the first half; the new paragraph records both, because the message-drop is the next thing a reader measuring this endpoint will notice, and it is what the paragraph's existing closing ADR-0112 sentence ("what reaches every in-process caller and the operator log") was always about.

The edit

Before:

 * Measured consequence, recorded so it is not rediscovered as a bug: on the
 * `/data` routes `mapDataError`'s generic status passthrough is 4xx-ONLY, so
 * this declared 501 does not survive to the wire — it falls to
 * `UNCLASSIFIED_FAULT`'s `500 INTERNAL_ERROR`. That is a gap in the REST
 * boundary — #5582, which this is the first live producer for — not a reason
 * for the driver to misdescribe the fault as the caller's. The driver's job is
 * to state the condition truthfully at the throw site (ADR-0112), which is also
 * what reaches every in-process caller and the operator log.

After:

 * Measured consequence, recorded so it is not rediscovered as a bug: on the
 * `/data` routes `mapDataError`'s generic status passthrough spans 400-599, so
 * this declared 501 DOES survive to the wire as `501` / `NOT_IMPLEMENTED` —
 * pinned end-to-end by `rest-5xx-status-passthrough.test.ts`. This paragraph
 * read the opposite until #7402 closed #5582: the passthrough was 4xx-ONLY,
 * this was its first live producer, and the status fell to
 * `UNCLASSIFIED_FAULT`'s `500 INTERNAL_ERROR`. What that band does drop is the
 * PROSE — a 5xx body is the generic `Internal server error` — so the driver's
 * job at the throw site is unchanged: state the condition truthfully
 * (ADR-0112), which is what reaches every in-process caller and the operator
 * log.

The ADR-0112 class-2 argument, the #6188/ADR-0049 history, the "class is now EMPTY, kept deliberately" warning, and the catalog-choice rationale are all untouched. The issue pointers (#5582, plus #7402) are kept, now as the history that explains why the paragraph once said the opposite — so a reader measuring a real 501 learns it is correct-by-design instead of having to work out which of the two statements is stale.

Companion grep (positive control, re-run)

$ grep -rn "survive to the wire" . | grep -v '^./.git/'
./packages/drivers/driver-sql/src/sql-driver.ts:713: * this declared 501 does not survive to the wire — it falls to

One hit, this file. No driver-turso companion edit needed — matches triage's finding.

Comment-only self-check

$ git diff -U0 | grep -E '^[+-]' | grep -v '^[+-][+-]'

Emits 17 lines, every one of them * … docblock content. git diff --stat: 1 file, +10 −7.

Gates run locally

Gate	Result
eslint packages/drivers/driver-sql/src/sql-driver.ts --no-inline-config	pass (exit 0, no output)
pnpm --filter @objectstack/driver-sql typecheck	pass (exit 0) — needed turbo run build --filter=@objectstack/driver-sql^... first, since a fresh worktree has no built workspace dist/ type declarations

Per the card, the rest of the gate farm is CI's; it is in_progress at the time of writing.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YcMB8dGrg4WFmpH8JuSRmo

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 5:40pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via @objectstack/driver-sql)
• content/docs/getting-started/glossary.mdx (via @objectstack/driver-sql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/driver-sql)
• content/docs/plugins/anatomy.mdx (via @objectstack/driver-sql)
• content/docs/plugins/packages.mdx (via @objectstack/driver-sql)
• content/docs/protocol/kernel/index.mdx (via @objectstack/driver-sql)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/driver-sql)
• content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/driver-sql)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/driver-sql)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.