fix(plugin-sharing): per-grant catch in both reconcile loops so one refused grant no longer aborts the pass (#14754) (#14930)

* fix(plugin-sharing): per-grant catch in both reconcile loops so a refused grant no longer aborts the pass

After #14484 `sys_record_share` is tenant-scoped in the #13491 ledger, so an
organization-less system insert on it is refused loudly with
`ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED` on a walled install. A platform-global
sharing rule materialising a grant onto an organization-less record resolves no
organization and meets that refusal; with no per-grant catch it propagated and
that rule's reconcile pass aborted mid-loop, taking the pass's stale-row
revocations with it. Those revocations are the security-relevant half: a stale
over-grant persisted across every later pass, which met the same record and
died in the same place.

Both loops now attempt each grant individually. A refusal is logged with the
rule, object, record, recipient and the engine's code, counted in the pass
result, and the pass continues.

The catch is narrow — only `ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED` is
absorbed. `record-share-organization-stamp.test.ts` deliberately pins the abort
on the other error a pass can meet here (the scoped update half answering
`RECORD_NOT_FOUND`), a shape the 2026-09-02 contract review left standing; a
catch-all would retire that decision as a side effect.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

* docs(permissions): re-anchor the system-context census to the two shifted elevation reads

`check:check-system-context-census` failed with pure line rot: the per-grant
catch added 37 lines above `sharing-rule-service.ts`'s two `context?.isSystem`
elevation reads, so the census page's anchors pointed at :157/:382 while the
reads now sit at :194/:419. Re-anchored with the gate's own `--fix`; no prose
and no behaviour changed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

* docs(permissions): re-derive the row-39 census anchors on the merged tree

The merge with origin/main moved `sharing-rule-service.ts` — main added the
`warnOnEmptyUnitExpansion` limb above both elevation reads — so the anchors
this branch re-anchored before the merge point at the pre-merge lines. Machine
re-derived with `pnpm gen:system-context-census`; nothing hand-edited.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

* docs(permissions): re-derive the system-context census anchors on the merged tree

The os-regen merge driver does not text-merge this file. Regenerated with
`pnpm gen:system-context-census` on the committed merge, as its own commit:
main's line rot (rows 21, 56, 63 and the misconception table) is re-anchored,
and row 39's branch anchors are re-derived unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WXyGTWPbbreqXow7Z2pZCk

* chore(spec): record the plugin-sharing organization-refusal MATCH as a provenance waiver (#14937)

`check:error-code-provenance` scans for `constdef` stamp sites and cannot tell
a package that RECOGNISES a registered code from one that EMITS it. The
per-grant catch added for #14754 spells the engine's refusal code once, as
`ENGINE_ORGANIZATION_REFUSAL_CODE`, and compares an incoming `err.code`
against it — the gate reads that as an unlisted stamp site under
`@objectstack/plugin-sharing`.

Adjudicated on #14937 (maintainer ruling A, 2026-09-04): record it as a
`PROVENANCE_WAIVERS` row naming `@objectstack/objectql` — the real emitter,
whose owner key already carries the code (#8844) — rather than widening the
gate or evading it with a bare inline literal. The row comes out together with
the stamp site when #14936 lands and objectql publishes a recognizer.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WXyGTWPbbreqXow7Z2pZCk

* docs(changeset): declare the wire surface `grantsRefused` reaches, and the client-type lag

The evaluate route is a ledgered SDK route whose handler passes the service
return value through unfiltered, so the seventh key is on the response body
every caller already receives. The SDK method's declared resolved type is the
spec's six-field `SharingRuleEvaluationResult`, which cannot name it — a
client-type lag, additive on the wire, tracked as #14969. Declared here rather
than lifted, because the spec type is a `domain:spec` single-owner file.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WXyGTWPbbreqXow7Z2pZCk

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/sharing-reconcile-per-grant-organization-refusal.md

@@ -0,0 +1,79 @@
+---
+"@objectstack/plugin-sharing": minor
+---
+
+fix(plugin-sharing): one refused grant no longer aborts a sharing rule's reconcile pass — its stale-row revocations still run (#14754)
+
+After #14484 `sys_record_share` is `tenant-scoped` in the #13491 ledger, so on a
+walled install an organization-less system insert on it is refused loudly with
+`ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED` (#8844). `SharingService.grant`
+resolves the organization on every path that can; a platform-global sharing
+rule (`organization_id = null`, its sweep unscoped) materialising a grant onto
+an organization-LESS record resolves none, and meets that refusal.
+
+`SharingRuleService.reconcile` / `reconcileForRecord` had no per-grant catch, so
+the refusal propagated and **that rule's pass aborted mid-loop**. Two things
+were lost, and they are not equally serious:
+
+- the remaining grants — recoverable, the next pass writes them;
+- **the stale-row revocations of that pass** — not recoverable by waiting,
+  because every subsequent pass meets the same organization-less record and
+  dies in the same place. A stale over-grant of that rule therefore persisted
+  indefinitely, and the record kept aborting the pass until it was repaired by
+  hand. That is the security-relevant half.
+
+Measured while pinning this, and it sharpens the point: the engine returns
+organization-less rows **last** in a rule's criteria sweep (the driver's
+NULL-org compatibility arm is appended to the scoped arm). So a refused grant
+is nearly always one of the final attempts of a pass, and what an abort
+destroyed was hardly ever "the remaining grants" — it was almost entirely the
+revoke loop that runs after the whole upsert loop.
+
+Both loops now attempt each grant individually. A refusal is logged with the
+rule, object, record, recipient and the engine's own code, counted, and the
+pass **continues** — the remaining grants and, above all, the stale-row
+revocations still run.
+
+**The catch is deliberately narrow.** Only
+`ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED` is absorbed; every other error
+rethrows unchanged. A catch-all would swallow real defects and report a pass
+that "completed" having written nothing. It would also silently retire a
+reviewed decision: `record-share-organization-stamp.test.ts` deliberately pins
+the abort on the OTHER error a reconcile pass can meet here — the scoped update
+half answering `RECORD_NOT_FOUND` for a row stamped with a different
+organization — which the 2026-09-02 contract review left standing on "loud
+beats a wrong count". Those three pins are unchanged and still green.
+
+**Why `minor` rather than `patch`.** The repair is a bug fix, but it reports
+through a new key. `reconcile` / `reconcileForRecord` / `evaluateRule` /
+`evaluateAllForRecord` now return `SharingRuleReconcilePassResult` — the spec's
+`SharingRuleEvaluationResult` plus `grantsRefused: number` — and that type is
+newly exported from the package index. Purely additive: the contract in
+`@objectstack/spec` is untouched, its six declared fields are unchanged, and a
+consumer typed against `ISharingRuleService` keeps compiling as it did. Same
+shape as `fix(runtime): tell an action handler when its caller-scope record load
+was refused` (#14143), which shipped `minor` for the same reason.
+
+`grantsRefused > 0` does **not** mean the pass failed. It means the pass met a
+record it cannot grant on and carried on — which is the whole point.
+
+**Wire surface — declared, not lifted.** `grantsRefused` reaches the wire.
+`POST /api/v1/sharing/rules/:idOrName/evaluate` is a ledgered **SDK** route —
+`packages/rest/src/rest-route-ledger.ts:390`, the row carrying
+`disposition: 'sdk'` and `client: 'shares.rules.evaluate'` — and its REST handler
+passes the service return value through **unfiltered**
+(`packages/rest/src/rest-server.ts:11108`–`:11109`:
+`const result = await svc.evaluateRule(req.params.idOrName, context ?? {})`
+followed by `res.json(result)`). So the seventh key is on the response body every
+caller of that route already receives. The SDK method declares
+`SharingRuleEvaluationResult` as its resolved type
+(`packages/client/src/index.ts:4766`, unwrapped at `:4771` through
+`unwrapResponse` parameterised on that same type), and that type is the spec's
+six-field contract — so the **declared client type cannot name the seventh key**.
+That is a client-type **lag**, not a contract break: the key is additive on the
+wire, every declared field is unchanged, and a consumer typed against
+`SharingRuleEvaluationResult` keeps compiling exactly as before. Lifting the type
+is not this PR's to do — `SharingRuleEvaluationResult` lives in
+`@objectstack/spec`, a `domain:spec` single-owner file — so the lag is declared
+here and tracked as the follow-up #14969, which lifts `grantsRefused?: number`
+(optional) into `SharingRuleEvaluationResult`.

content/docs/permissions/system-context.mdx

@@ -137,7 +137,7 @@ The largest single consumer — **17 of the 106 sites**.
 | 36 | `sys_record_share` reads are **not** self-scoped | Get: tenant-wide share listing without `manage_sharing` | `sharing-plugin.ts:1088` |
 | 37 | Share-link policy `enabled` check bypassed; system callers re-enter under a system context | Get: link **creation** while the policy is off — resolution is **not** bypassed since #14033 (`publicSharing.enabled` is a standing policy held at every redemption): a link minted this way does not resolve until the block is enabled | `plugin-sharing/src/share-link-service.ts:469`, `:523`, `:527`, `:600`, `:630` |
 | 38 | Sharing-rule provenance stamp skipped | Lose: the row is not marked as an admin customization — seeder / `defineRule` / boot reconcilers are "the package door" | `sharing-rule-provenance.ts:47` |
-| 39 | Sharing-rule service write + delete paths return early | Lose: the manage-rules gate on the service surface, and the platform-global-rule delete guard | `sharing-rule-service.ts:165`, `:390` |
+| 39 | Sharing-rule service write + delete paths return early | Lose: the manage-rules gate on the service surface, and the platform-global-rule delete guard | `sharing-rule-service.ts:202`, `:427` |
 
 ### 4. Approvals, reports, attachments, comments, knowledge
 

packages/plugins/plugin-sharing/src/index.ts

@@ -23,6 +23,10 @@ export {
 export {
   SharingRuleService,
   type SharingRuleServiceOptions,
+  // [#14754] The spec's `SharingRuleEvaluationResult` plus the pass's
+  // `grantsRefused` count. Additive: the six declared fields are unchanged, and
+  // a consumer typed against the spec contract keeps compiling untouched.
+  type SharingRuleReconcilePassResult,
 } from './sharing-rule-service.js';
 export {
   ShareLinkService,