docs(spec): publicSharing.enabled is a standing policy held at redemption; resolveToken names the switched-off block among its null causes

[huangyiirene]

Fixes #14703

What changed

TSDoc only — two sites, one fact: publicSharing.enabled is a standing policy held at every redemption, not a mint-time switch (the #14033 ruling, landed by PR #14580). No schema, shape or behaviour change; the .describe() string on publicSharing.enabled is untouched, and no generated tree moved (content/docs/references, json-schema, authorable-surface, api-surface: 0 files in the diff).

1. packages/spec/src/data/object.zod.ts — the comment above publicSharing.enabled read "no share links can be issued for this object". True, but the mint half only. It now states the redemption half too: with the switch off no link on the object resolves — links minted while it was on, and links minted through the system-context / permissive mint bypass alike; re-enabling the block serves them again, no row moves; off means nothing inside the block is evaluated. Written in the shape the sibling eligibility predicate's prose (sharing: publicSharing.eligibility is evaluated only at mint — a link keeps serving a record after it stops being eligible #13608) already uses.
2. packages/spec/src/contracts/share-link-service.ts — three hunks:
   • IShareLinkService.resolveToken's null-cause list gains the switched-off block, inserted where the gate runs in the implementation (after the audience/password gates, before the record probe 记录删除后 sys_share_link 能力令牌仍然有效 —— 与 #5103 同族，但因为是无身份令牌所以更糟 #5190 and the eligibility predicate sharing: publicSharing.eligibility is evaluated only at mint — a link keeps serving a record after it stops being eligible #13608); the existence-oracle sentence names "switched off" beside the other indistinguishable reasons.
   • A design note 7 beside note 6 (the sharing: publicSharing.eligibility is evaluated only at mint — a link keeps serving a record after it stops being eligible #13608 model): same shape, same "the refusal is the same undifferentiated null" ending.
   • The isSystem bypass sentence on the interface is marked mint-only, because the card's third point (bypass-minted links are governed at redemption) contradicts an unqualified "bypass".
3. .changeset/public-sharing-enabled-standing-policy-tsdoc.md — @objectstack/spec patch, "documentation only", following the shape of the docs-only spec changeset that landed at d5d8d50db. It states where the text reaches consumers, measured on the built package: every new line of the contract file ships in dist/contracts/index.d.ts (14033 ×3, design note 7 ×2, STANDING policy too ×1 in both .d.ts and .d.mts); the object.zod.ts property comment reaches no .d.ts (inferred type) and ships through the directly published src/**/*.zod.ts file and dist/data/index.js.map.

Route chosen (dispatch zone 3)

Restate in the resolveToken list as one clause (the enumeration entry, exactly as #5190 and #13608 have one), carry the mechanism in design note 7 beside note 6, and have the object.zod.ts comment point at IShareLinkService.resolveToken for the null. Reason: note 6 already set this convention for #13608 — header note carries the mechanism, the list carries one clause — and a pointer-only entry would be the odd one out in the list. Two statements of the fact remain (schema side, contract side), cross-linked, each in its file's existing convention.

Premise re-check against origin/main at d5d8d50db

• git show origin/main:packages/spec/src/data/object.zod.ts — the line drifted from :2237 to :2279; the READ is unchanged: /** Master switch. When false (default), no share links can be issued for this object. */.
• git grep -n "13608\|14033" origin/main -- packages/spec/src/contracts/share-link-service.ts — :41 and :236, both sharing: publicSharing.eligibility is evaluated only at mint — a link keeps serving a record after it stops being eligible #13608; no [Decision] What does turning publicSharing.enabled off mean for an ALREADY-MINTED share link? — the parent switch is mint-only while its own child predicate is now a standing policy #14033 line. Both sites still stale — premise holds.
• Behaviour still there: packages/plugins/plugin-sharing/src/share-link-service.ts resolveToken reads policy.enabled after the cheap gates and before the record probe and returns null with the SHARING_NOT_ENABLED log line; the permissive option's own doc says "Mint ONLY"; the [#14033] pins in share-link-service.test.ts and share-link-eligibility.test.ts are on main. Documented what is measured, not what the card asserts.

Verification (final head a1e1610ac; source commit 0b9aac129, the second commit touches the changeset only)

• Comment-only proof: ts.transpileModule with removeComments: true on BASE vs HEAD of both files — emit byte-identical (object.zod.ts 76755 = 76755 chars; share-link-service.ts 48 = 48 chars). No runtime or type reaches any consumer differently.
• pnpm --filter @objectstack/spec build — VERDICT command-exit 0; git status clean afterwards (no generated artifact moved).
• pnpm --filter @objectstack/spec typecheck — VERDICT command-exit 0 (tsc --noEmit, check:scripts-typecheck, check:test-typecheck OK).
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 — Test Files 482 passed (482) · Tests 13089 passed (13089), VERDICT command-exit 0.
• Gate union from node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (69 families): all 69 run at a1e1610ac, 68 green, 1 NOT-MEASURED (pnpm check:dual-build-cjs-loads, prerequisite unmet — below), 0 UNRUN; dispatch-gates.mjs --ran reconciliation ✓ (69 derived famil(ies) accounted for — 68 run, 1 NOT-MEASURED). The 17 @objectstack/spec gates include check:docs, check:authorable-surface and check:api-surface green after the rebuild — the mechanical proof that the .describe() string and the generated reference did not move. check:doc-formula-expressions refused on first run (formula/lint unbuilt); after turbo run build --filter=@objectstack/formula --filter=@objectstack/lint it measured green.
• Declared narrowing: turbo ls --affected lists 75 packages (spec and every dependent). Ran spec's own typecheck and test; the other 74 are declared to CI on the comment-only proof above — their emitted JS and their types are unchanged byte-for-byte, so only text-scanning gates can move, and those are in the union. pnpm check:dual-build-cjs-loads is NOT MEASURED locally: it refuses (exit 3, PREREQUISITE NOT MET) until all 86 unbuilt packages have a dist/, i.e. a whole-repo pnpm build, which is CI's run.
• Not applicable: ablation / reverse verification — no guard, type or behaviour was added; the diff is comments plus a changeset.

Out of scope, noted for the PM

• The block-level comment above publicSharing (same file, ~30 lines up) still describes the mint half only ("refuses to create share-link rows"). It is true as written and the corrected enabled comment sits inside that block, so it was left alone under the two-site ruling; not filed as an issue.
• spec: three sharing.zod.ts docblock sentences go false when #15072 lands — the field recipient stops being "not yet authorable" #15239 (sharing.zod.ts docblocks) is a different file and was not touched.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/permissions/system-context.mdx (via publicSharing (symbol, a field of const object ObjectSchemaBase, an authorable key of data/Object))
• content/docs/protocol/objectql/security.mdx (via publicSharing (symbol, a field of const object ObjectSchemaBase, an authorable key of data/Object))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via publicSharing (symbol, a field of const object ObjectSchemaBase, an authorable key of data/Object))

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.

What this run could not see

• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 130 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 9f3989771062ef660133b3432a32e03e0cd07f5a → packageMentionDocs.

Which tree this was computed on

This run read content/docs from bcb23e32750d5a58da998286ae0a0cc7918b1c71 — the merge of head a1e1610acab2d7a85e31db64d26c95eec4fa95b3 into base 9f3989771062ef660133b3432a32e03e0cd07f5a, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin bcb23e32750d5a58da998286ae0a0cc7918b1c71 && git checkout bcb23e32750d5a58da998286ae0a0cc7918b1c71
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9f3989771062ef660133b3432a32e03e0cd07f5a a1e1610acab2d7a85e31db64d26c95eec4fa95b3 && git checkout -B drift-repro 9f3989771062ef660133b3432a32e03e0cd07f5a && git merge --no-ff a1e1610acab2d7a85e31db64d26c95eec4fa95b3

node scripts/docs-audit/affected-docs.mjs --json 9f3989771062ef660133b3432a32e03e0cd07f5a

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 9f3989771062ef660133b3432a32e03e0cd07f5a → pass the list as
args.docs, on the commit named under Which tree this was computed on.