plugin-security, plugin-sharing: at boot, the administrator is told when an upgrade renamed, removed or collided with an access choice (#24446 U1) - #25311

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-security, @objectstack/plugin-sharing, touching 77 documentable anchor(s).

37 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 9dc1f42d50b2ee0c0afe8b6b7d7922b7c912f83a.

⛔ 10 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d0f22d3740a5c4d14580cc95ddaeda3475bcb5a6 && git checkout d0f22d3740a5c4d14580cc95ddaeda3475bcb5a6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9dc1f42d50b2ee0c0afe8b6b7d7922b7c912f83a 4aa031c97c228fa7aa8b8a61c5e333cc051416f6 && git checkout -B drift-repro 9dc1f42d50b2ee0c0afe8b6b7d7922b7c912f83a && git merge --no-ff 4aa031c97c228fa7aa8b8a61c5e333cc051416f6

node scripts/docs-audit/affected-docs.mjs --json 9dc1f42d50b2ee0c0afe8b6b7d7922b7c912f83a

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 9dc1f42d50b2ee0c0afe8b6b7d7922b7c912f83a → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 4aa031c97c228fa7aa8b8a61c5e333cc051416f6
Local-runs: none

Seat read on the declaration face. The PR declares Clause-②: yes (widening), which is the face this tier serves, with no narrowing, no published schema and no governed path. The read covers the net diff against main (6 files, +1,567 / −0), the measurement 6353200007, the seat's GO 6353222762 and option A 6353787407, the os-dev-report 6354303990, and the check-runs on this head.

① Derived judgments

1. It refuses nothing and writes no row of its own: right. reportAccessUpgrade runs at kernel:bootstrapped, beside catalog-reference-report.ts. The only write is the single notification through messaging.emit(). security-plugin.ts wraps the call, so a failed report logs a warning and never fails the boot.
2. Fail-closed reads: right.
   • scanAll (the activation ledger, sys_sharing_rule) throws ReportStop on any read fault, and so does the catalog list or listDeclaredRules. A stopped report says what it could not read and delivers nothing.
   • An object the composition does not register is listed under absent, not guessed.
3. Findings match the GO: right.
   • orphans;
   • suspected re-enablements: a ledger row's package_id against the entry's packageId, with candidates and, for a permission set, the positions binding it;
   • sharing-rule collisions per organization;
   • broken references in customer items;
   • field denies a same-object customer set lacks.
     The two accepted limits are stated: candidates, and "same object" rather than "copied from".
4. Delivery: right.
   • single: the Default Organization's admin_full_access holders plus OS_PLATFORM_OWNER_EMAIL, stamped with the Default Organization.
   • Walled: no emit, and one error line addressed to the operator (option A).
   • dedupKey is the finding set's digest, so an unchanged set notifies once; the dev measured this across two single boots.
   • Each non-delivery (no messaging service, no recipient, an unreadable audience, a refused emit) is logged with its own cause and fix.
5. New public surface: one member. SharingRuleService.listDeclaredRules() on plugin-sharing's exported class. It reads only, and returns null when the service reads no declarations. The report's own exports are not re-exported from plugin-security's index.
6. Observations, not blocking:
   • the report runs at every boot, not only after a package change, because no version is recorded to detect one; the digest makes the repeat silent;
   • both tables are read whole, which is bounded by the customer's ledger and rule counts;
   • the walled line echoes the configured operator address or addresses into the server log.

② Semver level

• Changeset: @objectstack/plugin-security and @objectstack/plugin-sharing at patch, Clause-②: yes (widening), Metadata-protocol: none.
• yes (widening) is right, and it is the value both carriers now read: the changeset at this head, and the PR body as amended by the seat. The widening is the new public listDeclaredRules(). The notification topic is a free-form string on an existing ingress, not a published key.
• patch is right under the house rule: Metadata-protocol: none takes patch, and no authorable key moves.
• Check Changeset is success on this head.

③ Boundary flags

• The walled channel is ruled A (6353787407). Option C, an organization-less operator notification, is put to the maintainer as a card of its own and does not block this PR.
• Mandatory topic: not set. A recipient's mute can hide it, and the changeset names the existing mandatoryTopics operator option that makes it mute-proof. Accepted.
• Out-of-scope observation: no example app declares @objectstack/organizations, so a walled os serve of a shipped example refuses at boot. Carried by the seat; not this PR's.
• R1–R4 were measured by the dev on the final head (see the ACCEPT).

Implemented-by: claude/issue-24446-u1-access-upgrade-comparison
Reviewed-by: session_01Y5583bs2RDd53MH6kM1ca3

VERDICT: PASS

Seat ACCEPT · epic PM session_01Y5583bs2RDd53MH6kM1ca3 (os-steve) · 2026-10-23T01:00Z. PR #25311 at 4aa031c97c228fa7aa8b8a61c5e333cc051416f6 (#24446 U1; claim 6353092498; measurement 6353200007; GO 6353222762; walled option A 6353787407; report 6354303990). ACCEPT.

Seat check

• Shape: 6 files, +1,567 / −0:
  • plugin-security's new access-upgrade-report.ts, its unit and wiring pins, and the boot wiring in security-plugin.ts;
  • plugin-sharing's new public SharingRuleService.listDeclaredRules();
  • one changeset.
    check-governed-merges --pr 25311: not governed, so this is an ordinary queue landing. It touches no ceremony, plan, harness or tenancy read, so no needs:upgrade-harness; the dev ran the harness locally.
• Review tier: Clause-②: yes (widening), so the declaration face at TIER_DEFAULT. Seat record 6354822120 on this head: PASS.
  • The value was first declared no. The seat corrected it, because the widening is the new public member on an exported class: the dev fixed the changeset in c945716b7, and the seat amended the PR body.
• What it does (ruling 6259332195 items 1–2, the access class; ADR-0126 §6 wall 3): at kernel:bootstrapped, it compares the customer's access state with the registry this boot holds. It covers the activation ledger for positions, permission sets and sharing rules; customer-authored permission sets; and sys_sharing_rule rows. It reports:
  • orphans;
  • suspected re-enablements;
  • sharing-rule collisions;
  • broken references;
  • uncovered field denies.
    It writes and refuses nothing.
• Delivery:
  • single: one deduplicated messaging.emit() notification to the Default Organization's administrators and the configured operator.
  • Walled: one error line addressed to the operator (option A), with no emit.
  • Every non-delivery is logged with its cause.
• CI on the head: 41 check-runs, every one success or skipped, including Test Core, Build Core, TypeScript Type Check, Lint & Repo Gates, Governed Surface Queue Guard and Check Changeset. The unlabelled harness lane is skipped. Mergeable clean.
• R1–R4, measured by the dev on this head, after the main merge:
  • Build, plugin-security (4,442 passed) and plugin-sharing (1,201 passed); typecheck 0.
  • R1: a fresh boot logs a clean report, with nothing absent.
  • R4: a production os serve on a persistent database, clean boot, then CONTROL, then a vendor rename.
    • isolated and group: the CONTROL reports nothing. After the rename: 1 re-enablement and 1 operator line, 0 refused writes, 0 "reached no administrator", 0 sys_notification rows.
    • single: 1 re-enablement, and exactly 1 notification, which is deduplicated on the next boot.
  • R2 and R3: the harness passed 16/16, both fixture legs, measured on 68e1310b7, which carries the same source.
• Changeset: @objectstack/plugin-security and @objectstack/plugin-sharing at patch, Clause-②: yes (widening), Metadata-protocol: none. Right under the house rule. The two accepted limits (ADR-0126 §9) and the mandatoryTopics option are stated.
• Carried, not this PR's:
  • option C (an in-app operator notification under a wall) is with the maintainer;
  • no example app declares @objectstack/organizations, so a walled R4 needs a temporary edit. That is with the maintainer as a possible p3 card.
• Landing: the seat flips the PR ready and enables auto-merge. Part of #24446: the card stays open for U2 and the ADR-0126 note.