fix(plugin-sharing)!: the share-link routes emit the declared envelope, and the last ratchet retires (#3983)

[os-zhuang]

Closes #3983. The fifth and final drifting route module — guard goes 6 / 1 / 1 → 7 / 0 / 1.

Merge order is satisfied inside this PR. objectui#2980 is merged (96ee72e) and the .objectui-sha bump is a commit here, so the coupling is atomic — see Merge order.

This wasn't envelope cosmetics — two SDK methods were broken

Worth leading with, because #3983 framed this as "no body carries the success flag" and that undersells it.

Three of these routes are disposition: 'sdk' in runtime/src/route-ledger.ts, and ObjectStackClient.unwrapResponse decides a body is an envelope by finding a boolean success. With no flag it hands back the body verbatim:

method	documented / typed as	actually returned
shareLinks.create()	"Returns the link row (incl. token)"	{ link: … } — so .token was undefined
shareLinks.list()	Promise<any[]>	{ links: [] } — so .map() threw

And packages/client/src/admin-surfaces.test.ts mocks all three as { success: true, data: <payload> }. The SDK was written and tested against the dispatcher's shape, and only ever worked there.

So the target shape wasn't a design decision

runtime/src/domains/share-links.ts serves these same five paths, and for cloud's per-environment kernels it is the designed primary surface (registerShareLinkRoutes: false). It has always answered in the declared envelope with data carrying the payload directly. Same routes, two shapes, decided by which surface happened to mount them — the asymmetry #3636 fixed for /i18n, one domain over. This module converges onto the twin:

route	was	now
POST /share-links	{ link }	{ success: true, data: link }
GET /share-links	{ links }	{ success: true, data: link[] }
DELETE /share-links/:idOrToken	{ ok: true }	{ success: true, data: { ok: true } }
GET /:token/resolve	{ record, link, redactFields }	{ success: true, data: { … } }
GET /:token/messages	{ data: rows }	{ success: true, data: rows }
errors	{ error: { code, message } }	{ success: false, error: { … } }

data carries each payload bare — data: links, not data: { links }. That is what makes unwrapResponse return the same value on both surfaces.

Two details worth calling out:

• { ok: true } survives on revoke, but as the data rather than as the body. At the top level it was a second word for success (service-storage success bodies are three shapes, none carrying success: true — the other half of #3675 #3689 retired that from storage); under data it is the payload, and it is the payload the dispatcher and admin-surfaces.test.ts both already use. Dropping it would have re-introduced a divergence.
• The error half was already right — nested { code, message }, which is why service-i18n error responses are bare { error }, not the declared { success: false, error: {...} } envelope #3675's changeset cited this module as the good example. Only the flag is new, and all eleven codes were already SCREAMING_SNAKE and registered, so ADR-0112 needs nothing here.

Consumer sweep

#3983 said this "needs its own consumer sweep". Done, and the blast radius is smaller than assumed — the framework has zero consumers of these routes (no dogfood proof drives them either).

In objectui, ShareDialog was already dual-shape tolerant on all three routes it calls — body.links ?? body.data, created.link ?? created.data, and revoke never reads the body. It needs no change, and the reason it was already tolerant is the point: both shapes genuinely exist in the fleet.

SharedRecordPage did need one fix, and it is exactly the kind a shape-swap would have missed. It renamed the wire's redactFields to the redactedFields its render reads — but only on the bare branch. The enveloped branch handed body.data through verbatim, so on the dispatcher path the "Some fields are hidden by the owner" notice never rendered, on exactly the pages where fields were being stripped. Converting this surface would have spread that to every share page. Fixed in objectui#2980 (merged).

Merge order

1. ✅ objectui#2980 → merged as 96ee72e
2. ✅ .objectui-sha bump + console rebuild → commit 3a67ab4 in this PR
3. this PR → ready to merge

Step 2 lives here rather than in its own PR so the coupling is atomic: merging the conversion against a dist built from the old pin would ship enveloped resolve bodies to a page that skips the rename, i.e. it would cause the vanished-notice regression for one release window. check:console-sha confirms the rebuilt dist matches the new pin (packages/console/dist is gitignored, so only .objectui-sha and the generated changeset are committed).

I'm stating the order explicitly because I got the analogous claim wrong on #3972 ("the two repos are not coupled by merge order") — packages/console/dist is built from .objectui-sha, so they are.

Bonus fix: bump-objectui.sh rejected the mandated workflow

Doing step 2 surfaced a defect in the tool for it. The script guarded on -d "$OBJECTUI_ROOT/.git", but in a git worktree .git is a regular file holding a gitdir: pointer — so it rejected every linked worktree and only ever ran from a primary clone, while the Prime Directives require a per-task worktree in each repo a task spans. -e accepts both. Its error message also claimed the default sibling path even when OBJECTUI_ROOT was set explicitly, pointing the reader at the wrong thing; it now names the path it actually rejected.

Tests

The module had no test file at all — only share-link-service.test.ts beside it. It gains a driven conformance suite: 26 cases over all five routes and thirteen error branches, every body parsed against the real spec schemas rather than restatements of them, plus the unwrapResponse decision restated so the two broken SDK methods are pinned as working, and a sameShapeAsDispatcher block so the two surfaces cannot drift apart again (#3833's failure mode, one domain over).

I checked the suite isn't vacuous: reverting the two emitters to their pre-#3983 form fails 22 of the 26.

Guard

privateOk is narrowed to what its own doc comment always claimed — a literal ok at the top of a response body, where it competes with success. The same literal inside data is payload, which is what a conformant revoke returns; counting it was an over-broad approximation that was harmless only while no conformant module had one. Four self-test assertions pin both readings, and the narrowing can only lower counts, so the six already-conformant modules stay at privateOk: 0.

The ratchet section is now empty but the mechanism stays — it is how the next drifting module gets recorded honestly instead of being either fixed on the spot or quietly skipped.

Verification

gate	result
pnpm check:route-envelope + --self-test	7 conformant / 0 ratcheted / 1 exempt
pnpm check:console-sha	dist matches pin objectui@96ee72e85439
@objectstack/plugin-sharing	224 passed (11 files)
@objectstack/runtime	904 passed (65 files)
@objectstack/client	200 passed (14 files)
spec tsc --noEmit · check:docs · check:skill-refs · check:react-blocks	all clean
check:error-code-casing · check:nul-bytes · check:role-word · check:org-identifier	all clean
eslint --no-inline-config on changed files	clean

Method note. The runtime suite first showed 1 failure in datasource-autoconnect.test.ts (expected ['first','second'], got each row 6×). It is not mine and not a product bug: a gitignored packages/runtime/.objectstack/data/memory-driver.json persists rows across local runs. I confirmed it by stashing my changes and reproducing on the pristine tree, then cleared the file and got 904/904 both with and without my diff. CI checks out fresh, so it never sees it. Recording the method because I misdiagnosed a stale-artifact failure as "reproduces on main" during #3972.

Deferred finding. #4038 — the dispatcher domain emits data and a legacy link/links beside it on create/list. That producer-side shim loses its last reader once this PR lands, but deleting it needs a cloud sweep, so it is filed rather than done here (Prime Directive #10).

[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:39am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-sharing.

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

• content/docs/permissions/authorization.mdx (via packages/plugins/plugin-sharing)
• content/docs/permissions/permissions-matrix.mdx (via packages/plugins/plugin-sharing)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-sharing)
• content/docs/protocol/objectql/security.mdx (via packages/plugins/plugin-sharing)

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.