refactor(service-settings)!: settings error bodies use the declared details slot (#4224)

[os-zhuang]

Closes #4224.

The finding, confirmed

Four /api/settings/* error branches spread ad-hoc context as siblings of code and message inside error. ApiErrorSchema declares code, message, category?, httpStatus?, details?, requestId? — and none of namespace, key, reason, fields.

The bodies passed every gate anyway, for two independent reasons that happened to line up: ApiErrorSchema is a plain z.object, so unknown keys are stripped rather than rejected, and envelopeViolations inspects only the body's top level. Conformant by stripping, not by declaration. The same module already used error.details correctly one branch over (SETTINGS_ACTION_FAILED), so this was one file speaking two dialects rather than a missing capability — as the issue says.

A survey of the sibling route modules confirms settings was the outlier: i18n, storage and share-link take no extra parameter at all, and package-routes.ts already names its one details.

FROM → TO

Values unchanged in every case; only the position moves.

Code	HTTP	FROM	TO
SETTINGS_FORBIDDEN	403	error.namespace	error.details.namespace
UNKNOWN_KEY	400	error.namespace, error.key	error.details.{namespace,key}
SETTINGS_LOCKED	409	error.namespace, error.key, error.reason	error.details.{namespace,key,reason}
SETTINGS_VALIDATION	400	error.namespace, error.fields	error.details.{namespace,fields}

The decision the issue asked for

error.details is the home, and SETTINGS_VALIDATION.fields joins the field-level vocabulary properly rather than dodging it.

ADR-0114 (#3977) landed the vocabulary D6 deferred: fields now means FieldError[] — { field, code, message, label?, constraint? } with code from a closed 27-member catalog. That makes the middle option the worst one: putting the existing Record<key, message> under the name fields inside details would leave one spelling meaning two shapes, which is the exact drift these ADRs exist to prevent. So the map becomes the declared array:

• required — an empty required specifier
• invalid_format — a value that misses its declared pattern, which travels as constraint.pattern

It stays details.fields rather than a top-level error.fields because fields is declared on EnhancedApiErrorSchema, not on the base ApiErrorSchema these routes emit. validation-failure.ts puts the dispatcher's array in the same place for the same reason, and objectui's extractFieldErrors already reads details.fields — so settings validation failures become renderable per-field in the console with no per-surface special case.

The constraint kind is knowable at the throw site and nowhere after it (the route only ever saw prose), so the exported SettingsValidationError.fields changes with the wire rather than being reconstructed from message text.

What keeps it fixed

sendError's last parameter is tightened from extra?: Record<string, unknown> to Pick<ApiError, 'category' | 'httpStatus' | 'details' | 'requestId'> — the loose edge the issue names — and code from string to the closed ADR-0112 ErrorCode union (all seven codes this module emits are already in the standard catalog or the ledger). An undeclared sibling is now a compile error at the call site instead of a key that quietly evaporates at the schema boundary.

The conformance suite gains the assertion neither existing gate could make: every key of body.error must be one ApiErrorSchema.shape declares. It is derived from the schema rather than restated, so a field added to the contract is allowed the moment it is declared and one removed stops being allowed — a hand-written list's failure mode is that it silently keeps blessing a retired key.

On not generalising this into envelopeViolations

Tempting, since that is where the check structurally belongs — but wrong here. DispatcherErrorResponseSchema is a declared superset of ApiErrorSchema that legitimately carries route / hint / service as siblings, and buildApiError has an extra parameter for exactly that. A blanket "no undeclared key inside error" rule in the shared checker would fail those conformant bodies. The generalisation needs a per-module notion of which error schema applies; that is a larger change than this issue, so the assertion stays local and honest — settings emits the base ApiError and nothing more.

Breaking, and the cross-repo half

The issue's "write-only today" note is right for three of the four keys but not the fourth. Its grep covered packages/ and examples/ in this repo; error.key has a live reader one repo over — objectui's SettingsView save handler renders the locked key in a toast.

So this ships tolerant-read-first (the objectui#2869 pattern ADR-0112 records):

1. fix(console): read the SETTINGS_LOCKED key from error.details, tolerating both shapes (objectstack#4224) objectui#3079 — console reads error.details?.key ?? error.key
2. this PR — server moves the keys

Landing this one first shows Locked by environment: undefined to anyone on a console built before it. The changeset carries the full FROM → TO mapping and the one-line consumer fix, per AGENTS.md.

Verification

• pnpm --filter @objectstack/service-settings test — 13 files, 194 tests, green
• pnpm --filter @objectstack/spec test — 276 files, 7174 tests, green
• pnpm check:route-envelope — 7 conformant, 0 ratcheted
• pnpm check:error-code-casing — clean across 2492 files
• Both new pins verified to fail against the pre-settings error bodies carry four keys ApiErrorSchema does not declare, conformant only because z.object strips them #4224 shape — reintroducing the sibling spread on one branch turns the suite red with error carries keys ApiErrorSchema does not declare: ['namespace','key'], so these are pins rather than assertions that cannot fail
• No packages/spec exports added or removed, so gen:api-surface is untouched
• @objectstack/verify has one pre-existing failure in this environment (Failed to resolve entry for package "@objectstack/runtime", an unbuilt sibling) — reproduced with these changes stashed, unrelated

🤖 Generated with Claude Code

---

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		Jul 30, 2026 5:01pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-settings.

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

• content/docs/kernel/runtime-services/audit-service.mdx (via packages/services/service-settings)
• content/docs/kernel/runtime-services/index.mdx (via packages/services/service-settings)
• content/docs/kernel/runtime-services/settings-service.mdx (via packages/services/service-settings)
• content/docs/plugins/packages.mdx (via @objectstack/service-settings)
• content/docs/releases/v9.mdx (via @objectstack/service-settings)

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.