feat(plugin-sharing): one INFO line when isSystem writes materialise zero sharing grants (#6783)

[os-zhuang]

Fixes #6783

Demand 3 of #4707, maintainer-ruled 2026-08-06 (诉求 3(做)). Execution, not a decision.

The defect: silence, not behaviour

plugin-sharing's record-write hooks return early on (ctx?.session as any)?.isSystem. So a seed run — or any internal write batch — lands rows on an object an active sharing rule covers and materialises zero sys_record_share rows.

That skip is correct. The kernel:bootstrapped backfill (backfillRuleGrants in sharing-plugin.ts) reconciles every rule and evaluateRule is idempotent, so the state heals. What was wrong is that nothing said so. hotcrm#640: a fresh install, 9 active rules, 9 accounts matching their criteria, users holding the right positions — and sys_record_share empty. Every visible layer said "configured"; the only way to learn otherwise was to query the table, find it empty, and read this package's source.

Mechanism

packages/plugins/plugin-sharing/src/rule-hooks.ts:

• A new exported constant SYSTEM_WRITE_SKIP_NOTICE carries the ruling's wording verbatim, behind the package tag every other line in the file uses:

  [sharing-rule] sharing materialisation skipped for isSystem writes; re-evaluate rules or restart to backfill
  

• The two skips that drop grant materialisation — afterInsert and afterUpdate — call a noteSystemWriteSkipped(objectName) helper before returning. The early-return itself is byte-for-byte the same decision it was.

• The helper is latched by a per-object set built inside bindRuleHooks, and logs { object, rules: [active rule names] } as metadata. It claims the latch before logging and swallows a throwing logger, so a log sink that is down cannot turn an observability line into a failed seed row, nor into one throw per row.

One line per batch, not per row. That boundary is the shape of the fix, not an optimisation: the defect is silence, and a per-row flood is the same defect with a different symptom. A seed batch of N rows on one object produces exactly one line; an insert batch plus an update batch on the same object still produces one. The latch re-arms with the binding generation — bindRuleRebindTriggers unbinds and re-binds this package on every sys_sharing_rule write — so a changed rule set gets its own notice instead of inheriting the previous generation's silence.

Conclusion per authority face

Face	Verdict
Active rule	Structural, not re-checked. bindRuleHooks skips active === false rules when building its object set, so an object whose only rule is inactive gets no hooks bound at all — silence is guaranteed upstream of the notice. Pinned by asserting the bound-hook list is empty, then that the write is silent.
Zero grants materialised	Structural. The notice sits inside the early return, ahead of every materialisation call. The positive tests assert sys_record_share is empty alongside the line, so the assertion is about the outcome and not only about the logger.
Level	INFO. The behaviour is correct and self-healing; warning about a subsystem working as designed is how operators learn to ignore it. A test asserts warn and error never carry this text.
Wording	Contract. Asserted as an exact string, plus a separate case that both remedies ("re-evaluate rules", "restart to backfill") survive any future rewording.
Active rule that legitimately matches nothing	Reported honestly rather than claimed. See below.

The one face that is worded around rather than detected

The card asks that an active rule which legitimately matches nothing stay silent. Whether a given seeded row satisfies a rule's criteria is answerable only by running recordMatches — the engine.find per row that the skip exists to avoid. Detecting it here would cost the skip its entire reason to exist, and re-implementing criteria matching in memory would fork the engine's filter semantics inside a plugin.

So the line is worded as a statement about the write path ("materialisation did not run, here is where the answer comes from"), never as a claim that grants were owed. It is therefore true in both cases and is not a false alarm when the rule genuinely matched nothing.

The observable half of that face is pinned: a rule that is active, a row that is written, and zero grants materialised because the row is outside the criteria produces no line — because the defect only exists on the isSystem path.

Deliberately NOT done

• The skip itself is unchanged. No write materialises grants that did not before; no sys_record_share row is created, updated or revoked by this PR.
• No new switch, flag or option. Demand 2 of isSystem: true has at least three distinct, undocumented side effects across three packages — each one has cost an app-side bug #4707 is decided — the isSystem concept is not being split — and this card introduces nothing that could reopen it.
• Not promoted to warn/error. The ruling asked for INFO.
• afterDelete stays silent, and this is a decision, not an omission. A delete skips revocation, not materialisation, and the remedy the line names would be false there: evaluateRule iterates records that still exist, so neither re-evaluating a rule nor restarting can reach a grant whose record is gone (the orphan named at the tail of 共享规则 hook 对谓词式(multi)写入不重算:if (!id) return 让 sys_record_share 授权在批量更新后变陈旧 #4779). That class belongs to record-share-cascade.ts — which stashes for system writes on its own account (记录删除后 source: 'manual' 的 sys_record_share 仍是孤儿 —— #4779 的 afterDelete 只覆盖规则共享,且只覆盖有规则的对象 #5103) — and to the boot orphan sweep. A line here would point an operator at a repair that cannot run. Pinned by a test, and by mutation C below.
• beforeUpdate/beforeDelete stash skips stay silent. They are row-set plumbing, not materialisation; noticing there would double-count with afterUpdate.
• Scope held to packages/plugins/plugin-sharing plus one changeset. No content/docs/releases/ edit.

Reverse verification

Direction predicted and written down before each run. All three matched exactly — no unpredicted movement in either direction. 14 tests in the new file.

Mutation	Predicted	Measured
A — delete both noteSystemWriteSkipped(objectName) call sites, keep the constant and helper	7 red / 7 green; red = the 6 positive cases + the logger-throws case	7 failed, 7 passed — exactly the named set
B — remove the latch, log on every skip	4 red / 10 green: one-line-per-batch, insert+update-is-one-line, per-object-latch, logger-throws	4 failed, 10 passed — exactly the named set
C — add the notice to the afterDelete skip	1 red: the isSystem-DELETE-stays-silent case	1 failed, 13 passed

Two readings worth stating plainly rather than rounding off:

• Guards that correctly stayed green are a result. Under mutation A all five negative-face cases and both wording cases stay green, because they assert absence and the mutation removes the thing that could be present. That is the expected direction for a silence-shaped guard, not a coverage gap.
• One green pass under mutation B is green for the wrong reason, and was predicted as such. re-arms on rebind expects 2 notices from 1 insert + rebind + 1 insert; with no latch at all it also gets 2. It cannot distinguish "the latch re-armed" from "there is no latch", which is why the per-object and per-batch cases carry that half of the contract. Recorded here rather than counted as a pass.

Taken out with git diff to a patch file plus git checkout --, never git stash — the stash stack lives in the common .git and is shared by every worktree.

Gates

Gate	Result
pnpm --filter @objectstack/plugin-sharing test	16 files, 410 passed (was 15 files / 396 before this PR's 14)
pnpm --filter @objectstack/plugin-sharing typecheck	clean (tsc --noEmit, no output)
eslint on both touched files, --no-inline-config	exit 0
check:engine-double-contract	OK — 120 pinned, 133 DEBT, 2 exempt. The new fake engine enters pinned on both verbs (assertEngineDeleteDispatch, assertEngineUpdateDispatch); the shrink-only baseline is untouched and gains no row
check:nul-bytes	OK (6442 files) + a manual grep -naP self-scan of all three changed files, clean
check:empty-changeset	OK — 1 declaring changeset added
check:error-code-casing, check:route-envelope, check:durability-log-level, check:kernel-hook-pairs, check:wildcard-fallthrough	OK
check:i18n	prerequisite not met in a fresh worktree — the gate needs the built CLI (packages/cli/dist/commands/i18n/extract.js) and reports "Nothing was checked". Pre-existing environment state, not this change: no translation bundle, authoring key or locale file is touched here

Premise

Re-measured against origin/main @ 68feaadd6, which includes #6909 (merged into this package 2026-08-09T04:08:21Z). Premise stands. Measured, not assumed:

• The four isSystem early returns in rule-hooks.ts are still at :157, :165, :180, :194 — fix(sharing): defer to an app-authored RLS widener before hard-refusing a by-id write (#5493) #6909 touched the by-id write gate in sharing-plugin.ts, not this file, so the card's anchors did not drift after all.
• The boot-backfill anchor did drift by 14 lines: the comment documenting that seed rows are written with isSystem and the hooks skip them deliberately is at sharing-plugin.ts:61, not :47 as the card records. Same comment, same meaning; only the address moved.
• The behaviour the card describes is real and current: bindRuleHooks binds only for rules with active !== false, and all four hooks return before any materialisation when the session is isSystem.

---

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 9, 2026 6:26am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-sharing.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/kernel/runtime-services/examples.mdx (via @objectstack/plugin-sharing)
• content/docs/kernel/runtime-services/sharing-service.mdx (via @objectstack/plugin-sharing)
• content/docs/kernel/services-checklist.mdx (via @objectstack/plugin-sharing)
• content/docs/permissions/authorization.mdx (via packages/plugins/plugin-sharing)
• content/docs/permissions/permissions-matrix.mdx (via packages/plugins/plugin-sharing)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-sharing)
• content/docs/protocol/objectql/security.mdx (via packages/plugins/plugin-sharing)
• content/docs/releases/implementation-status.mdx (via @objectstack/plugin-sharing)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.