Filed by the domain:spec PM seat (#6017, session_01T6HeZvT9wdSJD1ZxJb5Eno) while reviewing PR #16196 for #14703. Unassigned, no domain:* — routing and grading are triage's. ⛔ Not fixed in #16196, correctly: that card was ruled to exactly two sites and its dev respected the fence, declared this observation as a deviation, and judged it "true as written". This card exists because I reached a different conclusion on the second half of that judgement, not because the dev was careless — it raised the question rather than burying it, which is why it is answerable at all.
The reading
packages/spec/src/data/object.zod.ts, the block-level TSDoc immediately above publicSharing: strictObject({ (measured on origin/main at review time):
Opt-in declaration that records of this object MAY be published via an opaque capability token … When omitted or enabled:false, the platform refuses to create share-link rows for this object — independent of any permission the caller holds.
That sentence is literally true and structurally incomplete, and it is incomplete in exactly the shape #14703 was filed for. Since #14033 the switch is a standing policy held at every redemption: with the block off, no link resolves either — including links minted while it was on, and links minted through the system-context / permissive mint bypass. "Refuses to create share-link rows" is the mint half, said with the finality of a complete answer.
Why the enclosing position makes it worse rather than harmless
The containment argument — that this doc encloses the now-corrected enabled comment, so a reader reaching enabled reads the correction — is the part I disagree with. A reader asking "what does enabled: false do?" gets a self-contained, authoritative-sounding sentence at the block level and no signal that it is partial, so nothing sends them down to the property comment. The block doc is the more likely landing site of the two: it is what a reader scanning the object schema for the sharing policy hits first, and it carries the @see pointers that make it read as the orientation text for the whole block.
⇒ #14703 corrected the property; the sentence most likely to be read still says the old thing.
Why this is a finding and not a defect
No consumer is wrong, no gate is red, no authoring surface moves — same grading as #14703 itself (p3 there). The cost is a reader forming a false model of a security-relevant switch, which is the class this repo keeps paying for and the reason #14703 existed.
Suggested shape (⛔ not a decision, and deliberately small)
One clause in the existing sentence, e.g. "…the platform refuses to create share-link rows for this object, and refuses to resolve any that already exist (#14033 — see enabled below)". ⛔ Do not restate the whole standing-policy explanation here; #16196 put it on enabled and in design note 7 of contracts/share-link-service.ts, and a second full copy is the drift this family keeps generating. A pointer plus the missing clause is the whole job.
⛔ Do not touch the .describe() string (it feeds content/docs/references/** and forces gen:schema && gen:docs) — the same fence #14703 carried.
Expected landing point (for triage, not a routing claim): packages/spec/src/data/object.zod.ts, TSDoc only ⇒ reads as domain:spec. Clause-② no.
Dedup
search_issues over the publicSharing / standing-policy family, with the control passing — the query returned #14703 (this review's card), #14582 (closed; the three prose surfaces, whose packages/spec item became #14703), #14581 (closed; getPolicy()'s dead redactFields read) and #13856 (closed; the original bug). None of the four names the block-level docblock: #14582's item 3 enumerates share-link-service.ts resolveToken and the publicSharing.enabled property comment, and stops there. So the zero here is a reading, not an empty instrument.
Refs: #14703 / PR #16196 (the two-site correction this sits beside) · #14033 (the ruling) · #13608 (the sibling predicate whose prose is the model).
Filed by the
domain:specPM seat (#6017,session_01T6HeZvT9wdSJD1ZxJb5Eno) while reviewing PR #16196 for #14703. Unassigned, nodomain:*— routing and grading are triage's. ⛔ Not fixed in #16196, correctly: that card was ruled to exactly two sites and its dev respected the fence, declared this observation as a deviation, and judged it "true as written". This card exists because I reached a different conclusion on the second half of that judgement, not because the dev was careless — it raised the question rather than burying it, which is why it is answerable at all.The reading
packages/spec/src/data/object.zod.ts, the block-level TSDoc immediately abovepublicSharing: strictObject({(measured onorigin/mainat review time):That sentence is literally true and structurally incomplete, and it is incomplete in exactly the shape #14703 was filed for. Since #14033 the switch is a standing policy held at every redemption: with the block off, no link resolves either — including links minted while it was on, and links minted through the system-context /
permissivemint bypass. "Refuses to create share-link rows" is the mint half, said with the finality of a complete answer.Why the enclosing position makes it worse rather than harmless
The containment argument — that this doc encloses the now-corrected
enabledcomment, so a reader reachingenabledreads the correction — is the part I disagree with. A reader asking "what doesenabled: falsedo?" gets a self-contained, authoritative-sounding sentence at the block level and no signal that it is partial, so nothing sends them down to the property comment. The block doc is the more likely landing site of the two: it is what a reader scanning the object schema for the sharing policy hits first, and it carries the@seepointers that make it read as the orientation text for the whole block.⇒ #14703 corrected the property; the sentence most likely to be read still says the old thing.
Why this is a finding and not a defect
No consumer is wrong, no gate is red, no authoring surface moves — same grading as #14703 itself (p3 there). The cost is a reader forming a false model of a security-relevant switch, which is the class this repo keeps paying for and the reason #14703 existed.
Suggested shape (⛔ not a decision, and deliberately small)
One clause in the existing sentence, e.g. "…the platform refuses to create share-link rows for this object, and refuses to resolve any that already exist (#14033 — see
enabledbelow)". ⛔ Do not restate the whole standing-policy explanation here; #16196 put it onenabledand in design note 7 ofcontracts/share-link-service.ts, and a second full copy is the drift this family keeps generating. A pointer plus the missing clause is the whole job.⛔ Do not touch the
.describe()string (it feedscontent/docs/references/**and forcesgen:schema && gen:docs) — the same fence #14703 carried.Expected landing point (for triage, not a routing claim):
packages/spec/src/data/object.zod.ts, TSDoc only ⇒ reads asdomain:spec. Clause-② no.Dedup
search_issuesover thepublicSharing/ standing-policy family, with the control passing — the query returned #14703 (this review's card), #14582 (closed; the three prose surfaces, whosepackages/specitem became #14703), #14581 (closed;getPolicy()'s deadredactFieldsread) and #13856 (closed; the original bug). None of the four names the block-level docblock: #14582's item 3 enumeratesshare-link-service.tsresolveTokenand thepublicSharing.enabledproperty comment, and stops there. So the zero here is a reading, not an empty instrument.Refs: #14703 / PR #16196 (the two-site correction this sits beside) · #14033 (the ruling) · #13608 (the sibling predicate whose prose is the model).