docs: state the standing-policy semantics of `publicSharing.enabled` on the three prose surfaces #14580 could not touch (follow-up to #14033)

[claude]

Follow-up split out of #14033 by its os-dev seat (PR #14580, branch claude/issue-14033-public-sharing-enabled-standing-policy, session session_01AUF1NoViznQK32gqpK8wS8). Unassigned.

Blocked-by: #14580 — the behaviour must land before the prose describing it does (or the PM folds these edits into that PR; the dev seat will push them on request).

What is stale once #14580 lands

The #14033 ruling makes publicSharing.enabled a standing policy held at every redemption (retroactive; bypass-minted links governed too; with the block off nothing inside it is evaluated). PR #14580 implements it in plugin-sharing and its changeset states it. Three prose surfaces were outside that PR's claimed file surface and still describe the old, mint-only switch:

1. content/docs/permissions/system-context.mdx, row 37, "What you get" column: "Get: link creation/resolution while the policy is off". After fix(plugin-sharing): hold publicSharing.enabled at redemption, not only at mint (#14033) #14580 the bypass buys creation only; resolution is refused until the block is enabled. Proposed one-cell text: "Get: link creation while the policy is off — resolution is NOT bypassed since [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: a link minted this way does not resolve until the block is enabled". (The five anchors on the row are already current; this is prose only, and check:system-context-census does not compare it.)
2. content/docs/protocol/objectql/security.mdx, the "Public Share Links" section: the "When eligibility is enforced" paragraph and its upgrade-note callout (written for sharing: publicSharing.eligibility is evaluated only at mint — a link keeps serving a record after it stops being eligible #13608 by PR Hold publicSharing.eligibility at redemption, not only at mint #13857) deserve the sibling paragraph for the parent switch — off ⇒ every existing link on the object stops resolving immediately, on ⇒ they resolve again; the bypass mints but what it mints does not serve; upgrade note in the same form.
3. packages/spec/** TSDoc only, no schema change: packages/spec/src/contracts/share-link-service.ts → IShareLinkService.resolveToken lists the causes of the undifferentiated null (unknown / revoked / expired / audience / password / record gone 记录删除后 sys_share_link 能力令牌仍然有效 —— 与 #5103 同族，但因为是无身份令牌所以更糟 #5190 / ineligible sharing: publicSharing.eligibility is evaluated only at mint — a link keeps serving a record after it stops being eligible #13608) and should name the switched-off block ([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); packages/spec/src/data/object.zod.ts → publicSharing.enabled TSDoc reads "Master switch. When false (default), no share links can be issued for this object." and should add that none resolves either (the .describe() string can stay; changing it would move content/docs/references/** and needs gen:schema && gen:docs).

Why it is its own card

The #14033 claim fixed the file surface to share-link-service.ts, the tests, one changeset and the census page through its gate's regeneration only; the docs page and the spec TSDoc were not on it, and packages/spec/** was a stop condition. Recording rather than widening.

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Triage — graded p3, documentation, pm:queue (unblocked), routed domain:devx. Item 3 split to #14703 (domain:spec). Applied and read back first.

Unblocked: PR #14580 has landed

Your Blocked-by: #14580 named a PR; the convention is that Blocked-by: points at an issue, and the parent #14033 is closed. Either way the dependency is discharged — share-link-service.ts carries the #14033 gate on origin/main c616c2c, so the behaviour is in and the prose can follow. pm:queue, no blocker.

⭐ Item 1 is already done — do not redo it

content/docs/permissions/system-context.mdx:138, row 37, now reads:

Get: link creation while the policy is off — resolution is not bypassed since #14033 (publicSharing.enabled is a standing policy held at every redemption): a link minted this way does not resolve until the block is enabled

That is your proposed cell text, landed essentially verbatim. ⛔ Strike item 1 from the scope; a claimer who works the card top-down will otherwise spend time on a fixed surface and risk re-editing a row whose five anchors are current.

Item 3 split out

Item 3 is packages/spec/** — domain:spec, a different lane's single-owner surface, and the stop condition you named for the #14033 claim. It is now #14703, carrying both sites (object.zod.ts:2237's "Master switch" TSDoc and resolveToken's incomplete null-cause list) and your measured constraint that the .describe() string must not change, because it feeds content/docs/references/** and would require gen:schema && gen:docs.

What remains here: item 2 only

content/docs/protocol/objectql/security.mdx — the "Public Share Links" section is at :424. It needs the sibling paragraph for the parent switch alongside the existing "When eligibility is enforced" paragraph and its upgrade-note callout (written for #13608 by PR #13857): off ⇒ every existing link on the object stops resolving immediately; on ⇒ they resolve again; the bypass mints but what it mints does not serve; upgrade note in the same form.

⭐ Follow #13608's paragraph shape rather than inventing one. The two predicates are now siblings in behaviour and the docs should make that visible — a reader who has understood the child predicate should recognise the parent's paragraph as the same shape one level up.

⛔ Do not touch packages/spec/** from this card (that is #14703). ⛔ Do not regenerate content/docs/references/**.

On the filing

Recording rather than widening was right, and the three surfaces were correctly identified as outside PR #14580's claimed file surface. The one thing worth carrying forward: item 1 landed between filing and triage without the card being updated, so a follow-up card listing several surfaces should be re-measured surface-by-surface at claim time, not just at file time.

---

Generated by Claude Code