docs(plugin-sharing): state the grantsRefused narrowing, not a spec lag

[claude]

Fixes #15712

Clause-②: no

Prose-only. Since #14969 (delivered by PR #15714) @objectstack/spec declares grantsRefused?: number on SharingRuleEvaluationResult itself, which falsified two comments in @objectstack/plugin-sharing that described a spec/plugin lag. The code is not wrong and is not touched: SharingRuleReconcilePassResult extends SharingRuleEvaluationResult { grantsRefused: number } remains a legal covariant narrowing.

Session: https://claude.ai/code/session_01URLHobLUJB9K1ABV6ofdjj

What changed

Line numbers re-derived on this branch's base cb648cb1b (the card read them on 22a006b26):

file	lines on cb648cb1b	the sentence #14969 falsified
packages/plugins/plugin-sharing/src/index.ts	26-28	"Additive: the six declared fields are unchanged, and a consumer typed against the spec contract keeps compiling untouched."
packages/plugins/plugin-sharing/src/sharing-rule-service.ts	145-149	"the contract lives in @objectstack/spec and is another lane's to move, and every declared consumer keeps compiling against the six fields it always had. The seventh is additive…"

Both now state the NARROWING rather than the lag: the spec declares the key OPTIONAL on purpose (an implementation that does not count refusals leaves it ABSENT, and absent is not 0), this implementation always counts them, so the subtype REQUIRES it — which is the reason a caller holding the subtype never has to decide whether an unset key means "no grant was refused" or "this implementation does not report refusals".

The load-bearing paragraph is kept verbatim, as the card and the triage comment both demanded:

⛔ grantsRefused > 0 is NOT "the pass failed". It is the pass reporting that it met a record it cannot grant on … and CONTINUED.

The card named two instances — the sweep that makes "no others" a measurement

Three greps over packages/plugins/plugin-sharing/src (every file, tests included), each with the two known-stale blocks as its positive control:

sweep	pattern family	hits	both known-stale blocks hit?
A	SharingRuleEvaluationResult|SharingRuleReconcilePassResult|grantsRefused, comment lines only	5	yes — index.ts:26, sharing-rule-service.ts:145
B	keeps compiling|rides along|additive|declared fields|declared consumer	10	yes — index.ts:27-28, sharing-rule-service.ts:147-148
C	@objectstack/spec named in a comment	8	yes — sharing-rule-service.ts:146

Plus a count/ownership sweep (\b(six\|sixth\|seven\|seventh)\b, another lane\|lane's\|to move\|contract lives\|not ours). Everything the sweeps returned beyond the two blocks was read and is unaffected by #14969:

• sharing-rule-service.ts:151 and :1723 — the two surviving grantsRefused sentences; both describe the pass's behaviour, not the spec's shape. Kept.
• sharing-plugin.ts:1163 — "six suites in plugin-security" is about buildSharingMiddleware's messageTranslator callers, a different six.
• exec-context-annotation.pin.ts, bu-tree-recompute.ts, objects/sys-sharing-rule.object.ts, field-recipient.test.ts, logger-shapes.ts — unrelated counts (a retired six-field exec-context shape, six hooks, six access levels, a seven-point executor contract, seven module-local logger interfaces).

Repo-wide, outside the package: packages/client/src/index.ts types shares.rules.evaluate as SharingRuleEvaluationResult and carries no prose about its shape; docs/qa/platform-checklist/areas/access-security.json names the body, not the field count. The only other text describing the lag is in packages/plugins/plugin-sharing/CHANGELOG.md (entries 563-592), which is a historical release record and correct as of the release it describes — ⛔ not edited.

Acceptance notes

• The replaced sentence also claimed the extra key "rides along for the callers that want it — the boot backfill's aggregate and this package's own pins". backfillRuleGrants (sharing-plugin.ts) never reads grantsRefused; it counts reconciled rules and returns a number. That half was already inaccurate before spec: lift grantsRefused?: number (optional) into SharingRuleEvaluationResult so the SDK type stops lagging the wire by one key #14969. Since the whole sentence was being replaced anyway, the rewrite simply does not carry the claim forward, and names the consumers that are real: this package's own pins, and POST /api/v1/sharing/rules/:idOrName/evaluate, which answers svc.evaluateRule(…) unfiltered (rest-server.ts, res.json(result)).
• Whether SharingRuleReconcilePassResult is still worth keeping as a named export is the same lane's judgment and is ⛔ not decided here. [finding] plugin-sharing comments still describe SharingRuleEvaluationResult as six-key / "another lane's to move" once #14969 lifts grantsRefused? into the spec #15712 asks for prose only.

Verification

All readings below are from branch tip bd8f35bb8 — this branch's merge of origin/main at fd1247142, plus the prose commit and the changeset commit.

Gate denominator. node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 59 families from the change set. (The first derivation, taken before the merge, printed STALE TREE because scripts/pm/check-clause2-carriers.mjs had moved on main; it was discarded and re-derived on the merged tree, which prints no staleness line.) All 59 were run with the exit code captured before any pipe, then reconciled back through --ran with the codes attached:

Run reconciliation — 59 derived, 59 run, 0 NOT-MEASURED, 0 UNRUN.
  EXIT CODES — all 59 accounted famil(ies) carry one, so the NOT-MEASURED count above is DERIVED from them.
✓ dispatch-gates --ran: 59 derived famil(ies) accounted for — 59 run, 0 NOT-MEASURED
  (a DERIVED zero — all 59 recorded an exit code and none of them is 3).

derived 59 / run 59 / NOT MEASURED 0 / UNRUN 0. Every family exited 0. No family exited 3 (PREREQUISITE NOT MET), so nothing here is a prerequisite miss being read as a pass. Slowest four: check:slot-lookup 106s, check-comment-mask-corpus 78s, check:dual-build-cjs-loads 37s, check:i18n 32s.

Package lap (through scripts/pm/os-verify-lock.sh, verdict lines quoted, never a bare exit code):

command	verdict
pnpm turbo run build --filter='!@objectstack/docs' --concurrency=2	VERDICT command-exit 0 — 73 successful, 73 total
pnpm --filter @objectstack/plugin-sharing exec vitest run --maxWorkers=2	VERDICT command-exit 0 — 37 files, 910 tests passed
pnpm --filter @objectstack/plugin-sharing typecheck	VERDICT command-exit 0 — includes check:test-typecheck, which reports the test layer compiles and the debt ledger is unchanged (2 files / 3 errors / 3 pinned signatures)

Import-side packages are not owed tests: the published surface does not change by a byte (measured below).

Repo-wide lint — run, not narrowed. pnpm lint (eslint . --no-inline-config) exited 0 on bd8f35bb8. It fit inside the foreground cap, so no narrowing had to be declared.

Published-artifact measurement — the changeset decision, not an assumption. The prose commit was built, the two sources were restored to their base blobs with git checkout HEAD~1 --, rebuilt, and the resulting dist/index.d.ts captured; then restored with git checkout HEAD -- and rebuilt. The restore leg is proved by a whole-tree git status --porcelain (empty) and by blob identity — disk git hash-object equals git rev-parse HEAD:path for both files, non-empty on both sides.

marker in published dist/index.d.ts	before	after
"another lane's to move"	1	0
"The NARROWING is the point"	0	1
"grantsRefused is greater than 0" paragraph	1	1
"six declared fields"	0	0

• The .d.ts is 705,069 bytes before and 705,528 after — published bytes move, so skip-changeset is not available and .changeset/15712-sharing-grants-refused-narrowing-prose.md declares a patch on @objectstack/plugin-sharing.
• The declaration-only projection of that file — the same bytes with every comment stripped — is byte-identical before and after. No exported symbol added or removed, no key changed.
• dist/index.js and dist/index.mjs contain neither the old nor the new prose: the compiler strips comments from the JavaScript outputs, so only the two .d.ts / .d.mts files move.
• Worth recording: the index.ts half of this diff is a // comment inside an export list, and it does not reach the published payload at all (both markers read 0 in both builds). The sharing-rule-service.ts JSDoc is the half that ships.

Clause-② — re-derived from the delivered diff, by reachability from the published entry.

leg	reading
positive control	interface SharingRuleReconcilePassResult is declared at dist/index.d.ts:11920 — the touched symbol IS reachable from the published entry, so the instrument can see it
negative control	declare const ENGINE_ORGANIZATION_REFUSAL_CODE reads 0 in the same file — a module-local const in the same edited source is NOT reachable, so the instrument is not answering "yes" to everything
the reading itself	reachable, but what changed inside the reachable text is comment bytes only: declaration-only projection byte-identical, so no new exported symbol and no new key on a published payload

⇒ Clause-②: no, and node scripts/pm/check-clause2-carriers.mjs --pair 18260 agrees independently: exit 0 — "the clause-② declaration is readable in the fixed spelling and both carriers agree, and its diff carries no widening tell".

Control characters. grep -naP over the edited files and the changeset for the C0 set plus DEL: no hits. pnpm check:nul-bytes is one of the 59 green families.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 2 changed file(s) yielded no anchor (packages/plugins/plugin-sharing/src/index.ts, packages/plugins/plugin-sharing/src/sharing-rule-service.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 2 changed file(s) yielded no anchor (packages/plugins/plugin-sharing/src/index.ts, packages/plugins/plugin-sharing/src/sharing-rule-service.ts) — pages documenting those are invisible to this run
• 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 — 9 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 fd1247142a4beac65f9016de78f70caf7bb976b3 → packageMentionDocs.