refactor(service-i18n): collapse the four inline success builders behind a sendOk, retire the ratchet (#3973)

[os-zhuang]

#3973 option 1. No wire shape changes — this is about the guard, not the bodies.

What was actually wrong

#3636 put the declared { success: true, data } envelope on all three i18n read routes, but built it inline in each — four call sites for one envelope half, while the error half had already been consolidated behind sendError (#3675).

Those bodies were never wrong. That is precisely why this needed stating rather than being left alone: scripts/check-route-envelope.mjs counts response write sites per module, so a consolidated module sits at a fixed two however many routes it grows. This one sat at five with a declared ratchet, because a fifth read route could have hand-rolled a fourth-dialect body and only a driven test would have caught it — and a driven test only covers the routes that existed when it was written.

Four builders → one sendOk. The module now declares the same 2 / 1 / 1 as the other five.

guard: 5 conformant / 2 ratcheted / 1 exempt   →   6 / 1 / 1

The one remaining ratchet is share-link-routes.ts (#3983), which needs its own consumer sweep and is not touched here.

A claim #3843 got wrong, fixed in the same pass

Six suite headers (and the guard's own header) said the repo-wide scan "found two immediately (#3973, #3983)". #3973 was not one of them — i18n's unconsolidated builder was already known from #3843's own survey. The two the scan actually surfaced were share-link-routes.ts and the dev-only hmr-routes.ts. That conflation was mine, in #3843; corrected in all seven places.

Why "no wire change" is a checkable claim, not an assertion

packages/runtime/src/i18n-success-envelope.conformance.test.ts drives those exact three routes and parses the bodies against the real spec schemas. It passes unchanged — 901 tests in @objectstack/runtime — which is what makes the refactor provably shape-preserving rather than merely intended to be.

Verification

gate	result
pnpm check:route-envelope + --self-test	6 conformant / 1 ratcheted / 1 exempt
pnpm lint	clean
spec tsc --noEmit	clean
check:docs	251 generated files in sync
check:skill-docs · check-console-sha · changeset gates	clean
@objectstack/runtime	901 passed (65 files)
@objectstack/rest	491 passed (34 files)
@objectstack/service-i18n	62 passed (5 files)
@objectstack/service-storage	220 passed (18 files)
@objectstack/service-settings	189 passed (13 files)
@objectstack/service-datasource	154 passed (10 files)

I ran the typecheck job's gates explicitly this time — check:docs lives there, not in the test job, and missing it cost a red CI round on #3972.

Empty changeset: this releases nothing. Branch restarted from main per branch hygiene.

---

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 4:45am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/rest, packages/services.

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

• content/docs/api/error-handling-server.mdx (via @objectstack/rest)
• content/docs/api/index.mdx (via @objectstack/rest)
• content/docs/automation/webhooks.mdx (via packages/services)
• content/docs/kernel/runtime-services/audit-service.mdx (via packages/services)
• content/docs/kernel/runtime-services/index.mdx (via packages/services)
• content/docs/kernel/runtime-services/settings-service.mdx (via packages/services)
• content/docs/plugins/index.mdx (via @objectstack/rest)
• content/docs/plugins/packages.mdx (via @objectstack/rest, packages/services)
• content/docs/protocol/kernel/i18n-standard.mdx (via packages/rest, packages/services)
• content/docs/releases/implementation-status.mdx (via @objectstack/rest)
• content/docs/releases/v12.mdx (via @objectstack/rest)

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.