docs(sharing): say why getPolicy's disabled-branch redactFields read is kept

[claude]

Fixes #14581

Comment-only. getPolicy()'s enabled !== true branch keeps its raw.redactFields read; the comment beside it now describes why, instead of describing a case that can no longer arise.

⚠️ This takes the card's route 2, and my dispatch asked for route 1

Flagging it up front, because it is a disposition disagreement and not a judgement call I should bury. The dispatch that sent me here selected route 1 (collapse the branch to redactFields: []). The triage comment on the card, posted five hours earlier by a different seat, had already ruled route 2 explicitly — "leave the read, rewrite the comment", "⛔ Comment only. No behaviour change, no test change." The dispatch does not mention that ruling.

I took route 2. It is what the prior ruling of record says, and my dispatch left the door open for it ("you may better it, with reasons"; "if you conclude route 2 is right anyway, argue it from what you measured"). The measurement below is the argument, and it points the same way. A maintainer who wants route 1 after all should say so — nothing here is hard to revisit.

Premise checks, run before editing, at origin/main 7a17f3bf1

1 · Is the read actually dead? Yes, exactly as the card claims.

• policy.redactFields has one reader in the file — the union at :772 in resolveToken.
• The [#14033] gate if (!policy.enabled) sits at :697 and return nulls, 75 lines above that reader.
• createLink (:442) reads enabled (:449) and at :545 writes input.redactFields — the caller's list, never policy.redactFields.
• getPolicy has exactly two callers repo-wide, both in this file (:442, :650). Every other hit of the name is a comment, changelog, or docs reference.
• share-link-routes.ts reads resolved.redactFields, which is resolveToken's return — only ever non-null on the enabled path.

2 · Does removing it red anything? No — and that is the finding. See below.

3 · Is getPolicy exported? No. It is a module-private function getPolicy(schema: any) at :89. The package entry exports ShareLinkService and its options type, not this helper. Clause ② stays no.

The measurement that decided the route

I applied route 1's exact collapse as an ablation, proved it reached disk (blob 726dace8 to b017e772; injected marker count 1, removed-text count 0, via a globalThis write rather than a comment), and ran the suite:

route-1 collapse applied:  Test Files 30 passed (30)   Tests 726 passed (726)

Byte-identical to baseline. Nothing reds. Restore proven afterwards by blob equality against HEAD plus an empty git diff HEAD.

A green ablation is ambiguous on its own — it can also mean the mutated line never executed. So the branch was proven live with a second, deliberately-fatal mutation in the same spot (throw new Error('ABLATION_PROBE_14581'), also proven on disk):

disabled branch throws:  Test Files 2 failed | 28 passed (30)   Tests 18 failed | 708 passed (726)

The branch runs 18 times across the suite, and not one of those 18 assertions cares which value it returns. That is what makes the green above a measurement rather than an artefact. Restored again, blob equality plus empty git diff HEAD.

That result cuts both ways, and the second way is the load-bearing one:

• it confirms the read is unreachable today, so route 1 would have been safe now;
• it also proves no pin distinguishes the two shapes. The four #14171 pins that used to read the set with the switch off are all reversed to toBeNull(), so they pass under either version. If the :697 gate ever regresses, route 1 restores #13856's fail-open widening with zero test coverage to catch it; route 2 still fails closed.

Deleting a free, fail-closed read whose absence no test would notice, in a file where #14637 currently measures a stated security property being defeated one layer up, is the trade that looks clean in the diff and bad in the incident. The read stays; the comment now says exactly that, so it is documented defence in depth rather than dead code wearing a confident wrong comment.

Why the comment is dense: line-count parity is deliberate

First pass wrote this over 32 lines. That rotted check-system-context-census, which anchors this file's context.isSystem sites by absolute line number — measured, all three legs:

tree	census
base, unmodified	OK — ... 145 anchors resolve (exit 0)
base + 32-line comment	10 problem(s) over 145 anchors (exit 1)
--fix	rewrites 5 anchors, all on content/docs/permissions/system-context.mdx:138

One line of churn — but that page is one of the two hottest generated files in the repo and is contended by two other open PRs on this branchline (#14528, #14726). A comment-only change carrying no behaviour should not need a census regenerated to land, so the replacement says the same five things in exactly the 11 lines it replaced. File is 1006 lines before and after; no anchor moves; the census stays green without being touched.

Clause ② — no, derived from the diff

$ git diff -U0 origin/main...HEAD | grep -E '^\+\s*export '
(no matches)

That grep cannot see a changed signature on an already-exported symbol, so that half is checked separately and mechanically: stripping // comment lines from the base file and from this one yields byte-identical content (sha 12e7b2f64695a3a3 both sides). No declaration, signature, or statement moved — a comment-only diff cannot alter an export surface.

Tests

before:  Test Files 30 passed (30)   Tests 726 passed (726)
after:   Test Files 30 passed (30)   Tests 726 passed (726)

pnpm --filter @objectstack/plugin-sharing test plus typecheck (check:test-typecheck: OK), both on d2b749a92, tree clean. The named control pin — control — the enabled:true path serves exactly declared ∪ per-link, as before — passes untouched; it reads the enabled branch at :122, which this diff does not go near.

Gates

24 commands (23 derived by dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, plus the always-owed check:nul-bytes), every exit code captured before any pipe. 21 exit 0. Zero real findings. Three non-zero, all NOT MEASURED on their own words:

• check-test-completeness (exit 3) — "PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named ... ⛔ It is not a red"
• check:dual-build-cjs-loads (exit 3) — "PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/ ... ⛔ This is NOT a pass: nothing was measured"
• check:i18n (exit 1, and its verdict is why the code is not the classifier) — "Nothing was checked: no bundle was compared and no config was parsed"

All three want a full workspace build that a comment-only diff cannot influence; CI builds and runs them properly.

Changeset

None, deliberately. Comment-only, no behaviour change, and the compiled output is unchanged — this releases nothing from any package, so skip-changeset is applied rather than an empty changeset, which check-empty-changeset.mjs rejects outright.

Left alone on purpose

• The #14033 reversal register in share-link-service.test.ts:459-491, including its line saying the read is "deliberately left as sharing: turning publicSharing off leaves already-minted links serving — and silently drops the object's redactFields #13856 landed it" — route 2 keeps that statement true, so it needed no edit.
• #14637 (open, p2, needs-user-decision) — cited as evidence, not touched. Its fix spans share-link-routes.ts and the runtime twin, both out of fence.
• The pre-existing sharing_deal cross-field-filter ERROR logs in the suite output — expected fixture noise from a passing test, unrelated.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 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 — 8 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 7a17f3bf1e48e1e88f8e833a794e37bd40230f17 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from a1d6677a8e466a8b54b16313f99bc19207db731a — the merge of head d2b749a92d72ec0e0ff72b33edab7feb60166a03 into base 7a17f3bf1e48e1e88f8e833a794e37bd40230f17, 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 a1d6677a8e466a8b54b16313f99bc19207db731a && git checkout a1d6677a8e466a8b54b16313f99bc19207db731a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7a17f3bf1e48e1e88f8e833a794e37bd40230f17 d2b749a92d72ec0e0ff72b33edab7feb60166a03 && git checkout -B drift-repro 7a17f3bf1e48e1e88f8e833a794e37bd40230f17 && git merge --no-ff d2b749a92d72ec0e0ff72b33edab7feb60166a03

node scripts/docs-audit/affected-docs.mjs --json 7a17f3bf1e48e1e88f8e833a794e37bd40230f17

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