fix(service-package): classify a publish driver fault as 5xx and stop returning driver text as caller data (#8131)

[os-zhuang]

Part of #8131

⚠️Deliberately Part of and not Fixes. This closes the card's §1 (POST /packages/publish) only. Its §2 — the DELETE partial-failure array, whose raw text rides in details.failed[].error — is produced by protocol.deletePackage in packages/metadata-protocol, which is out of this card's declared file surface and is the surface of the in-flight #8136. Merging this must not auto-close a card with that half unaddressed; the PM should close#8131 deliberately once #8136 lands. Details in "What is NOT in this PR" below.

The premise, verified before anything was changed

The card filed its publish path as read from source, not reproduced, and asked whoever took it to force a real failure first. Done: a real SQLite database behind objectql.execute, running the real INSERT INTO sys_packages … statement, driven through the real handler. Two forced failures on origin/main:

400 {"success":false,"error":{"code":"PACKAGE_PUBLISH_FAILED",
"message":"no such table: sys_packages"}}
400 {"success":false,"error":{"code":"PACKAGE_PUBLISH_FAILED",
"message":"NOT NULL constraint failed: sys_packages.tenant_ref"}}

The card's claim is exactly right, and both defects are real: raw driver text as caller-visible data, on a 400.

The load-bearing assumption was FALSE — and it stays false after #8132

The dispatch assumed that reclassifying this path to 5xx would put it inside the existing 5xx withhold "with no new rule".

The structural reason it is false, which is the whole argument. The withhold lives in sendThrownError. A failure that is returned reaches sendError directly, and sendError consults no predicate at any status. Classification alone turns a 400 into a 500 and leaves the driver line exactly where it was.

Measured as a counterfactual — main's producer with only the status corrected (400 → 500, producer untouched):

500 {"success":false,"error":{"code":"PACKAGE_PUBLISH_FAILED",
"message":"no such table: sys_packages"}}

Re-measured after #8132 landed, and the result is unchanged.#8132 (f598aa8) taught looksLikeInternalErrorLeak the bare-SQLite and Postgres phrasings, so no such table: sys_packages is now recognised as a leak. The counterfactual above still produces the same body — a driver line on the wire while a predicate that recognises it perfectly is never asked. #8132 does not make this fix redundant, and a new case pins exactly that so nobody concludes otherwise.

An earlier revision of this PR also argued a semantic half — that the phrasing tripped none of the heuristic's keywords, so even reaching the withhold would not have helped. #8132 retired that half. It is called out here rather than quietly dropped, because it was load-bearing in the original reasoning and is no longer true.

What changed

Producer — packages/services/service-package/src/index.ts

• The driver's text goes to the log and nowhere else. It was already logged, so nothing an operator sees changes; what changes is that this is now the only place it goes.
• A throw that declares its own status is a refusal, not this method's to swallow — it is re-thrown, so the door's existing mapping answers it with the producer's own status and code. Previously publish caught everything, so every coded refusal reachable from this call path was flattened into one 400 PACKAGE_PUBLISH_FAILED, losing both.
• Everything else is a driver fault and returns a discriminated driverFault carrying a constant sentence with no interpolation at all.

Door — packages/rest/src/package-routes.ts, the two lines of status/message mapping and nothing else: 400 → 500, and result.error → result.driverFault?.message.

The discriminant is the STATUS channel, and that is a measured decision

An earlier draft accepted any non-empty string code as a declaration. It reads as reasonable and is wrong: every SQL driver populates that field — node:sqlite throws ERR_SQLITE_ERROR, better-sqlite3 SQLITE_ERROR, Postgres the SQLSTATE 42P01, MySQL ER_NO_SUCH_TABLE. The real-driver cases went red at once: every genuine driver fault was re-thrown as if it were a refusal and resolved to 500 INTERNAL_ERROR with the driver's own message. Pinned per dialect so it cannot come back.

Caller-facing 4xx is untouched — the binding scope guard

Held and pinned. Missing manifest, invalid manifest, and any coded refusal thrown from below publish all keep their status, code and self-correcting message; a 409 DESTRUCTIVE_CHANGE is still a 409. The refusal pins assert the service was never called, not merely the status.

Reverse verification — direction predicted before each run

Lap	Reverted	Predicted	Observed
A	producer only	producer pins RED, door pins GREEN (stub-driven, producer-independent)	14 RED, door GREEN — as predicted
B	door only	classification pins RED with a clean 500→400 diff	5 RED, all expected 400 to be 500 plus the message diff
B	door only	§3/§4 stay GREEN — measurements about sendError, not pins on this diff	GREEN (58 passed) — as predicted
C	producer only, status forced to 500	driver line still on the wire	confirmed, quoted above
C′	same, re-run against #8132's widened predicate	still on the wire — nothing on that path asks	confirmed, quoted above
type	reinstate the removed field	RED	error TS2339: Property 'error' does not exist on type 'PackagePublishResult'

Restoration after every lap was verified byte-identical to the commit.

The CI red, and what it was

Test Core (3/3) failed on three cases in this PR's own new suite, all reading expected true to be false — the leak-predicate pins, turned red by #8132 landing after this branch point. Those cases were written with an explicit instruction for this exact event ("delete or invert it; do not repair it to green"), and they are inverted, not flipped: the prose claiming a gap is rewritten because the gap is closed, and the surviving argument is re-proved without them (lap C′). Not a flake, not environmental, and not a re-run candidate.

Verification

• @objectstack/service-package — 21/21, @objectstack/rest — 1800/1800, on main merged in.
• Typecheck green on the producer and all three downstream consumers of the changed contract — @objectstack/rest, @objectstack/runtime, @objectstack/cli (downstream direction, i.e. the packages that depend onservice-package).
• Gates re-run on the merged tree: check:route-envelope, check:cross-package-test-inputs, check:test-source-alias, check:type-source-resolution, check:nul-bytes, check:error-code-casing, check:authz-resolver, check:filter-alias-parity, check:meta-type-normalized, check:docs-audit-scope, check:adr-0087-registration — all pass.

What is NOT in this PR

• The DELETE partial-failure array. Its producer is protocol.deletePackage in packages/metadata-protocol — outside this card's file surface, and the subject of [finding] metadata-protocol interpolates raw driver text into client-facing messages — three downstream sanitizers each have a hole because of it (option C of #8086) #8136, which reasons about this exact array as part of its own case.
• packageService.delete's PACKAGE_DELETE_FAILED, which answers 400 for a driver fault in the identical shape. It carries no message, so there is no disclosure — only the mislabelling. Filed as [finding] packageService.delete's driver fault is answered as 400 PACKAGE_DELETE_FAILED — the same mislabelling #8131 fixed for publish, on the sibling route #8275 rather than swept in.

---

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 13, 2026 2:38am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/rest, @objectstack/service-package.

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

• content/docs/ai/connect-mcp.mdx(via @objectstack/rest)
• content/docs/api/error-handling-server.mdx(via @objectstack/rest)
• content/docs/api/index.mdx(via @objectstack/rest)
• content/docs/permissions/authentication.mdx(via @objectstack/rest)
• content/docs/permissions/system-context.mdx(via packages/rest)
• content/docs/plugins/index.mdx(via @objectstack/rest)
• content/docs/plugins/packages.mdx(via @objectstack/rest, @objectstack/service-package)
• content/docs/protocol/kernel/http-protocol.mdx(via @objectstack/rest)
• content/docs/protocol/kernel/i18n-standard.mdx(via packages/rest)

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

• content/docs/releases/implementation-status.mdx(via @objectstack/rest)
• content/docs/releases/v12.mdx(via @objectstack/rest)
• content/docs/releases/v17.mdx(via @objectstack/rest)

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.