@sema-agent/core 7.4.0 → 7.5.1

package/dist/core/permission-rule-org.d.ts

@@ -1,5 +1,5 @@
 /**
- * design/182 §7 — the ORGANIZATION rule layer: core's half of the contract.
+ * design/182 §7 / design/389 — the ORG partition of the permission-rule store: core's half of the contract.
  *
  * Org rules and personal rules are opposite in polarity (deny/ask vs allow), authority (a server-side
  * administrator publish vs one human click per add) and evolution (whole-snapshot replacement vs
@@ -12,9 +12,10 @@
  *
  * ## Availability semantics (the fail-closed shape, ruled through three review rounds)
  *
- * A deployment DECLARES governance (`governed: true`) — governance is never inferred from wiring, so a
- * forgotten provider is a loud boot contradiction instead of a silently ungoverned deployment. Under
- * that declaration the org adjudication surface must ALWAYS be effective:
+ * A deployment DECLARES governance by handing `createPermissionRuleStoreProvider` an `org` partition
+ * config — governance is never inferred from a provider happening to be wired somewhere, and a config
+ * naming no snapshot source is a loud boot contradiction instead of a silently ungoverned deployment.
+ * Under that declaration the org adjudication surface must ALWAYS be effective:
  *  - the last successfully installed snapshot persists durably (`PersistedOrgRuleState`) and keeps
  *    adjudicating while the provider is unreachable, up to a deployment-configured staleness bound;
  *  - beyond the bound (or before any snapshot was ever installed) the resolution is `unavailable`, and
@@ -34,8 +35,8 @@
  * accept revision N−1 after a restart. Signature / predecessor chaining belongs to the privilege-
  * separation ticket; the high-water mark is the floor that needs no key distribution.
  */
-import { type RuleRejectCode, type RuleScope } from "./permission-rule-model.js";
-import { type PermissionRuleStore, type PermissionRuleStoreProvider, type RuleOwner } from "./permission-rule-store.js";
+import { type PersistedAllowRule, type RuleRejectCode } from "./permission-rule-model.js";
+import type { PermissionRuleStore } from "./permission-rule-provider.js";
 /** One org rule. There is structurally no allow bucket (design/179 §9: the org layer only tightens). */
 export interface OrgPermissionRule {
     rule: string;
@@ -66,8 +67,9 @@ export interface PersistedOrgRuleState {
     snapshot: OrgRuleSnapshot;
     installedAtMs: number;
 }
-/** The durable home of {@link PersistedOrgRuleState}. The file rule-store backend implements it over an
- *  org block published with the same O_EXCL/fsync/rename discipline as the rule file itself.
+/** The durable home of {@link PersistedOrgRuleState}. The file backend implements it over a
+ *  deployment-level `org.json` published with the same O_EXCL/fsync/rename discipline as the rule files
+ *  (`FileDurableRulePartitionProvider.orgStatePersistence()`); a SQL twin keeps one blob row.
  *
  *  CONTRACT: `installOrgState` must REFUSE (throw) an install that would LOWER the persisted
  *  `revisionHighWater` — the overlay serializes its own resolves, but two overlay instances over one
@@ -77,8 +79,6 @@ export interface OrgRuleStatePersistence {
     readOrgState(): Promise<PersistedOrgRuleState | undefined>;
     installOrgState(state: PersistedOrgRuleState): Promise<void>;
 }
-/** Duck-typed discovery of the persistence face on a store backend, `writerOf` style. */
-export declare function orgRuleStatePersistenceOf(store: PermissionRuleStore): OrgRuleStatePersistence | undefined;
 /** The `decisionReason` the consuming gate stamps on the synthetic asks it mints while org adjudication
  *  is unavailable. Exported so the gate integration and its tests share one spelling — and TYPED as the
  *  member of {@link import("./tool-policy.js").DecisionReason} it must equal, so the constant and the
@@ -129,37 +129,48 @@ export declare const ORG_RULE_DECISION_REASON: Extract<import("./tool-policy.js"
  *  clock skew passes; a far-future timestamp (which would satisfy the staleness bound INDEFINITELY,
  *  turning fail-closed into evergreen freshness) does not. */
 export declare const ORG_FETCHED_AT_SKEW_ALLOWANCE_MS: number;
-export type OrgOverlayStatus = "fresh" | "last-known-good" | "unavailable";
-/** What one resolution reports. `rules` is empty ⟺ status `unavailable` or the snapshot is empty —
- *  the two are distinguished by `status`, never by the emptiness of the list. */
-export interface OrgOverlayResolution {
-    status: OrgOverlayStatus;
+/** The org partition's resolution word. `ungoverned` is the store's answer on a deployment that
+ *  configured no org partition — a fourth member so "no org layer here" is never spelled as an
+ *  empty `fresh` snapshot. */
+export type OrgRuleStatus = "fresh" | "last-known-good" | "unavailable" | "ungoverned";
+/** What one resolution reports. `rules` is empty ⟺ status `unavailable`/`ungoverned` or the snapshot
+ *  is empty — the cases are distinguished by `status`, never by the emptiness of the list. */
+export interface OrgRuleResolution {
+    source: "org";
+    status: OrgRuleStatus;
     rules: OrgPermissionRule[];
     revision?: number;
-    /** Honest-disclosure lines: provider failures, refused snapshots, rollback refusals. */
+    /** Honest-disclosure lines: source failures, refused snapshots, rollback refusals. */
     disclosures: string[];
 }
-export interface OrgRuleOverlay {
-    resolve(): Promise<OrgOverlayResolution>;
+/** The org partition engine the unified store composes (design/389): fetch → validate → install-if-newer
+ *  → judge freshness, one serialized chain per deployment. */
+export interface OrgRulePartition {
+    resolve(): Promise<OrgRuleResolution>;
 }
-/**
- * Construct the org overlay for a GOVERNED deployment. This constructor IS the boot gate:
- *  - `governed` must be literally `true` — the overlay does not exist for ungoverned deployments
- *    (their decision path stays byte-identical to a build without this module);
- *  - a governed declaration WITHOUT a provider is a configuration contradiction and refuses to boot —
- *    a silently ungoverned "governed" deployment is precisely the failure this bit exists to prevent;
- *  - `stalenessBoundMs` follows the knob discipline: a non-number, NaN, non-finite or non-positive
- *    bound is refused loudly, never coerced.
- */
-export declare function createOrgRuleOverlay(cfg: {
-    governed: true;
-    provider?: OrgRuleSnapshotProvider;
+/** The partition config a deployment hands to `createPermissionRuleStoreProvider({ org })`. Its
+ *  PRESENCE is the governance declaration. */
+export interface OrgRulePartitionConfig {
+    /** Where the deployment fetches the current snapshot. Required — a governed declaration without a
+     *  source is a configuration contradiction and refuses to boot. */
+    source: OrgRuleSnapshotProvider;
     /** Durable LKG + high-water home. Omitted ⇒ process-local only, DISCLOSED on every resolution: a
      *  restart then forgets both the last-known-good snapshot and the anti-rollback mark. */
     persistence?: OrgRuleStatePersistence;
     stalenessBoundMs: number;
     now?: () => number;
-}): OrgRuleOverlay;
+}
+/** The ungoverned resolution — what a store with no org partition answers. */
+export declare const UNGOVERNED_ORG_RESOLUTION: Readonly<OrgRuleResolution>;
+/**
+ * Construct the org partition engine for a GOVERNED deployment. This constructor IS the boot gate:
+ *  - a declaration WITHOUT a snapshot source is a configuration contradiction and refuses to boot —
+ *    a silently ungoverned "governed" deployment is precisely the failure this bit exists to prevent
+ *    (the type requires `source`; the check is executed for a JavaScript caller);
+ *  - `stalenessBoundMs` follows the knob discipline: a non-number, NaN, non-finite or non-positive
+ *    bound is refused loudly, never coerced.
+ */
+export declare function createOrgRulePartition(cfg: OrgRulePartitionConfig): OrgRulePartition;
 /**
  * Which entries of an org snapshot the CURRENT rule validator refuses — the published deny/ask rules
  * that can match nothing on this build. Empty ⟺ every rule is enforceable.
@@ -180,7 +191,7 @@ export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[
  * interpreter-headed prefix deny like `Bash(node:*)` is a legitimately wide tightening and matches).
  *
  * The skip below is a defensive floor, and what stands behind it is worth stating precisely: rules that
- * arrive from {@link OrgRuleOverlay.resolve} have passed {@link validateOrgSnapshot} on BOTH the install
+ * arrive from the org partition's `resolve` ({@link createOrgRulePartition}) have passed {@link validateOrgSnapshot} on BOTH the install
  * and the serving path (backlog #177), so an unenforceable entry cannot reach here through the overlay
  * — the whole snapshot is refused, or the resolution reports `unavailable`, and either way it is
  * disclosed. A caller that hands this function a snapshot it obtained ELSEWHERE gets no such guarantee:
@@ -194,31 +205,36 @@ export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], c
     behavior: "deny" | "ask";
     rule: string;
 } | undefined;
-/** The effective status of one personal rule under the current org overlay — computed, never stored. */
-export interface EffectivePermissionRule {
-    rule: string;
-    scope: RuleScope;
-    status: "live" | "shadowed-by-org" | "removed";
-}
 /**
- * design/182 §7.3 — the introspection face: every personal rule with its effective status under the org
- * overlay. An org deny does not delete a personal rule — the personal rule is the user's approval
- * record, and the org's power is to OVERRIDE it, not to self-declare its removal — so a shadowed rule reports
- * `shadowed-by-org` and comes back by itself when the org deny is withdrawn. A rule whose every add is
- * tombstoned reports `removed` (its tombstone identity is still visible in the store).
+ * design/182 §7.3 / design/389 — the SHADOW predicate the unified store's read face applies to every
+ * personal allow row: does an org DENY reach this rule's own command pattern? An org deny does not
+ * delete a personal rule — the personal rule is the user's approval record, and the org's power is to
+ * OVERRIDE it, not to self-declare its removal — so a shadowed rule reports `shadowed-by-org` and comes
+ * back by itself when the org deny is withdrawn.
+ *
+ * The SAME reach the gate uses (`orgRuleReaches`), so the view and the decision cannot disagree about
+ * whether a deny touches this rule at all. A personal rule may name a connector chain, and a deny on one
+ * of its segments shadows it exactly as a deny on the whole does.
+ *
+ * WHAT `shadowed-by-org` DOES AND DOES NOT CLAIM: the predicate asks whether the deny reaches the
+ * personal rule's own command PATTERN — one exemplar — not whether it covers every call that pattern
+ * admits. The two differ for a PREFIX personal rule under a narrower deny: `Bash(git status:*)` with an
+ * org deny of exactly `Bash(git status)` reports shadowed, yet `git status --short` is still admitted at
+ * the gate. The inverse partial overlap (personal `Bash(git:*)`, org deny `Bash(git status:*)`) reports
+ * live while part of its reach is denied. A truthful answer needs pattern CONTAINMENT and a third status
+ * for partial overlap, which is an API change with its own design; what the two-value view is honest
+ * about today is "this rule is touched by a deny" / "no deny mentions it". The gate is the authority
+ * either way. org ASK rules do not shadow: the personal lane never consumes a `requiresRealApproval`
+ * ask, so the two never actually meet on one call.
  *
- * The shadow predicate: an org DENY rule REACHES the personal rule's command pattern (for a prefix
- * personal rule, the org deny admits its prefix body — a wider org deny shadows every narrower allow
- * under it; for a personal rule naming a connector chain, a deny on any one segment shadows it, which
- * is the same reach the gate decides with — see `orgRuleReaches`). org ASK rules do not shadow: the
- * personal lane never consumes a `requiresRealApproval` ask, so the two never actually meet on one call.
+ * design/382 §2.6 — a Read directory rule is never org-shadowed in this version: the org layer has no
+ * Read grammar (a snapshot carrying one refuses whole at the validator), so there is no deny that could
+ * reach it, and its `command` is a PATH that must not be fed to the shell lane's segment reader as
+ * though it were a command line.
  */
-export declare function effectivePermissionRules(opts: {
-    provider: PermissionRuleStoreProvider;
-    principal?: string;
-    owner?: RuleOwner;
-    orgSnapshot?: OrgRuleSnapshot;
-}): Promise<EffectivePermissionRule[]>;
+export declare function orgRuleShadows(orgRules: readonly OrgPermissionRule[], rule: Pick<PersistedAllowRule, "tool" | "command">): boolean;
+/** The shadow predicate with the org denies parsed ONCE — what a read over many rows uses. */
+export declare function compileOrgShadowPredicate(orgRules: readonly OrgPermissionRule[]): (rule: Pick<PersistedAllowRule, "tool" | "command">) => boolean;
 /** Does this store carry a write face? Re-exported convenience for org-ticket integrations that need to
  *  distinguish a read-only projection from a writable personal bucket without importing the writer seam. */
 export declare function isWritablePermissionRuleStore(store: PermissionRuleStore): boolean;

package/dist/core/permission-rule-org.js

@@ -1,11 +1,5 @@
 import { escapeForDisclosure, parseAllowRuleText, ruleAdmitsProgramRun, ruleLaneSegmentsOf } from "./permission-rule-model.js";
-import { sameScope, writerOf } from "./permission-rule-store.js";
-export function orgRuleStatePersistenceOf(store) {
-    const s = store;
-    return typeof s.readOrgState === "function" && typeof s.installOrgState === "function"
-        ? { readOrgState: s.readOrgState.bind(store), installOrgState: s.installOrgState.bind(store) }
-        : undefined;
-}
+import { writerOf } from "./permission-rule-store.js";
 export const ORG_UNAVAILABLE_DECISION_REASON = "org_unavailable";
 export const ORG_ADJUDICATION_TIMEOUT_MS = 15_000;
 export function settleOrgVerdictWithin(p, fallback, opts) {
@@ -38,17 +32,18 @@ export function settleOrgVerdictWithin(p, fallback, opts) {
 }
 export const ORG_RULE_DECISION_REASON = "org_rule";
 export const ORG_FETCHED_AT_SKEW_ALLOWANCE_MS = 5 * 60_000;
-export function createOrgRuleOverlay(cfg) {
-    if (cfg.governed !== true) {
-        throw new Error("createOrgRuleOverlay is only for org-governed deployments — pass `governed: true` or do not construct one");
+export const UNGOVERNED_ORG_RESOLUTION = Object.freeze({ source: "org", status: "ungoverned", rules: [], disclosures: [] });
+export function createOrgRulePartition(cfg) {
+    if (cfg === null || typeof cfg !== "object") {
+        throw new Error("the org partition config must be an object naming a snapshot source and a staleness bound");
     }
-    if (cfg.provider === undefined) {
-        throw new Error("org-governed is declared but no OrgRuleSnapshotProvider is wired — a governed deployment without an org source is a configuration contradiction; refusing to boot rather than running silently ungoverned");
+    if (cfg.source === undefined || typeof cfg.source.current !== "function") {
+        throw new Error("org-governed is declared but no OrgRuleSnapshotProvider is wired as `org.source` — a governed deployment without an org source is a configuration contradiction; refusing to boot rather than running silently ungoverned");
     }
     if (typeof cfg.stalenessBoundMs !== "number" || !Number.isFinite(cfg.stalenessBoundMs) || cfg.stalenessBoundMs <= 0) {
         throw new Error(`org stalenessBoundMs must be a finite positive number of milliseconds (got ${escapeForDisclosure(cfg.stalenessBoundMs)})`);
     }
-    const provider = cfg.provider;
+    const provider = cfg.source;
     const now = cfg.now ?? Date.now;
     let memoryState;
     const readState = async () => {
@@ -74,14 +69,19 @@ export function createOrgRuleOverlay(cfg) {
         }
         let fetched;
         let fetchFailed = false;
+        const settled = await settleOrgVerdictWithin(provider.current().then((v) => ({ v }), (e) => ({ e })), { timedOut: true }, { timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
         try {
-            fetched = structuredClone(await provider.current());
+            if ("timedOut" in settled)
+                throw new Error(`the org snapshot source did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms`);
+            if ("e" in settled)
+                throw settled.e;
+            fetched = structuredClone(settled.v);
         }
         catch (err) {
             fetchFailed = true;
-            disclosures.push(`org snapshot provider failed: ${escapeForDisclosure(err instanceof Error ? err.message : err)}`);
+            disclosures.push(`org snapshot source failed: ${escapeForDisclosure(err instanceof Error ? err.message : err)}`);
         }
-        return await serialize(async () => {
+        return await settleOrgVerdictWithin(serialize(async () => {
             const nowMs = now();
             const guardedRead = async (context) => {
                 try {
@@ -109,6 +109,9 @@ export function createOrgRuleOverlay(cfg) {
                     disclosures.push(`org snapshot revision ${fetched.revision} is below the installed high-water mark ${escapeForDisclosure(persistedFloor)} — refusing the rollback; the current deny set is unchanged`);
                     return persisted;
                 }
+                if (persisted !== undefined && fetched.revision === persisted.snapshot.revision && sameOrgPolicyContent(fetched, persisted.snapshot) && fetched.fetchedAtMs <= persisted.snapshot.fetchedAtMs) {
+                    return persisted;
+                }
                 if (persisted !== undefined && fetched.revision === persisted.snapshot.revision && !sameOrgPolicyContent(fetched, persisted.snapshot)) {
                     disclosures.push(`org snapshot revision ${fetched.revision} equals the installed revision but carries DIFFERENT policy content — refusing the swap; the current deny set is unchanged`);
                     return persisted;
@@ -137,19 +140,20 @@ export function createOrgRuleOverlay(cfg) {
             if (installed !== undefined) {
                 if (installed.snapshot.fetchedAtMs > decisionMs + ORG_FETCHED_AT_SKEW_ALLOWANCE_MS) {
                     disclosures.push(`the installed org snapshot claims a FUTURE observation time (${escapeForDisclosure(installed.snapshot.fetchedAtMs)} vs now ${decisionMs}) — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask`);
-                    return { status: "unavailable", rules: [], disclosures };
+                    return { source: "org", status: "unavailable", rules: [], disclosures };
                 }
                 const servingRefusal = validateOrgSnapshot(installed.snapshot, decisionMs);
                 if (servingRefusal !== undefined) {
                     disclosures.push(`the installed org snapshot (revision ${escapeForDisclosure(installed.snapshot.revision)}) does not meet this version's validator: ${servingRefusal} — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask`);
-                    return { status: "unavailable", rules: [], disclosures };
+                    return { source: "org", status: "unavailable", rules: [], disclosures };
                 }
                 if (withinBound(installed.snapshot)) {
                     const freshlyInstalled = fetched !== undefined && installed.snapshot === fetched;
                     if (!freshlyInstalled && !fetchFailed && fetched === undefined) {
-                        disclosures.push("org snapshot provider returned no snapshot — continuing on the last-known-good");
+                        disclosures.push("org snapshot source returned no snapshot — continuing on the last-known-good");
                     }
                     return {
+                        source: "org",
                         status: freshlyInstalled ? "fresh" : "last-known-good",
                         rules: structuredClone(installed.snapshot.rules),
                         revision: installed.snapshot.revision,
@@ -157,11 +161,16 @@ export function createOrgRuleOverlay(cfg) {
                     };
                 }
                 disclosures.push(`the newest org snapshot was observed ${decisionMs - installed.snapshot.fetchedAtMs}ms ago (bound ${cfg.stalenessBoundMs}ms) — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask`);
-                return { status: "unavailable", rules: [], disclosures };
+                return { source: "org", status: "unavailable", rules: [], disclosures };
             }
             disclosures.push("no org snapshot has ever been installed — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask");
-            return { status: "unavailable", rules: [], disclosures };
-        });
+            return { source: "org", status: "unavailable", rules: [], disclosures };
+        }), {
+            source: "org",
+            status: "unavailable",
+            rules: [],
+            disclosures: [...disclosures, `org state persistence did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask`],
+        }, { timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
     };
     return { resolve };
 }
@@ -257,47 +266,24 @@ function orgRuleReaches(rule, command, segments) {
         return false;
     return segments.some((segment) => ruleAdmitsProgramRun(rule, segment));
 }
-export async function effectivePermissionRules(opts) {
-    const store = resolveIntrospectionStore(opts);
-    const listed = await store.list();
-    const orgDenies = (opts.orgSnapshot?.rules ?? []).filter((r) => r.behavior === "deny");
-    const out = [];
-    for (const r of listed.rules) {
-        const shadowed = r.tool === "Bash" &&
-            (() => {
-                const segments = ruleLaneSegmentsOf(r.command);
-                return orgDenies.some((d) => {
-                    const parsed = parseAllowRuleText(d.rule, { direction: "tighten" });
-                    return !("reject" in parsed) && parsed.rule.tool === r.tool && orgRuleReaches(parsed.rule, r.command, segments);
-                });
-            })();
-        out.push({ rule: r.rule, scope: r.scope, status: shadowed ? "shadowed-by-org" : "live" });
-    }
-    for (const t of listed.tombstones) {
-        if (listed.rules.some((r) => r.rule === t.rule && sameScope(r.scope, t.scope)))
-            continue;
-        if (out.some((e) => e.rule === t.rule && sameScope(e.scope, t.scope)))
-            continue;
-        out.push({ rule: t.rule, scope: t.scope, status: "removed" });
-    }
-    return out;
+export function orgRuleShadows(orgRules, rule) {
+    return compileOrgShadowPredicate(orgRules)(rule);
 }
-function resolveIntrospectionStore(opts) {
-    if (opts.owner !== undefined && opts.owner.kind === "local-owner") {
-        if (opts.principal !== undefined) {
-            throw new Error("pass either a principal or a local-owner, not both — a bucket has one owner");
-        }
-        const store = opts.provider.forLocalOwner?.();
-        if (store === undefined) {
-            throw new Error("this provider has no local-owner bucket (forLocalOwner is not implemented)");
-        }
-        return store;
-    }
-    if (opts.owner !== undefined && opts.owner.kind === "principal" && opts.principal !== undefined && opts.owner.principal !== opts.principal) {
-        throw new Error(`contradictory identity: principal "${escapeForDisclosure(opts.principal)}" and owner principal "${escapeForDisclosure(opts.owner.principal)}" disagree`);
+export function compileOrgShadowPredicate(orgRules) {
+    const denies = [];
+    for (const d of orgRules) {
+        if (d.behavior !== "deny")
+            continue;
+        const parsed = parseAllowRuleText(d.rule, { direction: "tighten" });
+        if (!("reject" in parsed))
+            denies.push(parsed.rule);
     }
-    const principal = opts.owner?.kind === "principal" ? opts.owner.principal : opts.principal;
-    return opts.provider.forPrincipal(principal);
+    return (rule) => {
+        if (rule.tool !== "Bash" || denies.length === 0)
+            return false;
+        const segments = ruleLaneSegmentsOf(rule.command);
+        return denies.some((d) => d.tool === rule.tool && orgRuleReaches(d, rule.command, segments));
+    };
 }
 export function isWritablePermissionRuleStore(store) {
     return writerOf(store) !== undefined;

package/dist/core/permission-rule-provider.d.ts

@@ -0,0 +1,162 @@
+/**
+ * design/389 — ONE permission-rule store, partitioned by SOURCE.
+ *
+ * A rule comes from one of four sources — `org | user | project | session` — and the four differ in
+ * polarity, authority and evolution (an org snapshot is replaced whole by a server administrator; a
+ * user/project rule is one human click folded into an OR-Set CRDT; a session grant lives exactly as long
+ * as its session). Those differences are WRITE LAWS, and each partition keeps its own. What is one is the
+ * READ: "which rules stand for this owner, in this session, and what does each one's standing look like"
+ * is a single question, so it has a single answer — {@link PermissionRuleStore.effective}, a query the
+ * store answers across every partition with each row's `source` and `status`, the org shadow predicate
+ * applied inside the store rather than at each caller.
+ *
+ * ## Composition, not inheritance
+ *
+ * {@link createPermissionRuleStoreProvider} is the ONE way to build the store. A deployment hands it
+ * partition backends — the durable CRDT partition (`DurableRulePartitionProvider`: file, in-memory, an
+ * out-of-repo SQL twin), an org partition config (its snapshot source and staleness bound), a session
+ * partition — and the engine composes them. The org and session partition LAWS are engine code the
+ * backend cannot weaken; the durable partition's law is the exported pure fold every backend runs.
+ * A partition a deployment does not configure does not exist: its source answers nothing, and the
+ * provider's `partitions` face says so, so a manifest reads a declaration rather than inferring one.
+ *
+ * ## Source is a projection of the row's address
+ *
+ * `user` ⟺ scope `global`, `project` ⟺ scope `project`, `session` ⟺ scope `session`. A row never carries
+ * a second source byte that could drift from its scope — {@link ruleSourceOf} is the whole mapping.
+ *
+ * ## One write path, routed by scope
+ *
+ * `writerOf(store)` hands back a writer whose `apply` routes a `redemption-add` by the delta's scope: a
+ * session scope lands in the session partition (idempotent by dot, refused `session_ended` past the
+ * session's epoch seal), the two durable scopes take the CRDT partition's compare-and-set. The consent
+ * protocol therefore has ONE write path with ONE result vocabulary ({@link RuleWriteOutcome}); the
+ * durable backend keeps refusing a session row loudly should one ever reach it — the route is the
+ * store's, the fence stays the partition's.
+ */
+import type { PersistedAllowRule, RuleScope } from "./permission-rule-model.js";
+import { type DurableRulePartitionProvider, type QuarantinedRuleAdd, type RuleOwner } from "./permission-rule-store.js";
+import { type OrgRulePartitionConfig, type OrgRuleResolution } from "./permission-rule-org.js";
+import type { SessionRulePartition } from "./permission-rule-session.js";
+import type { StoreDurability, StoreFidelity } from "./checkpoint-store.js";
+/** The four sources a rule can come from — CC's settings-layer vocabulary folded onto sema's four. */
+export type RuleSource = "org" | "user" | "project" | "session";
+/** The source of a row is a projection of its scope — `global` is the `user` source. */
+export declare function ruleSourceOf(scope: RuleScope): Exclude<RuleSource, "org">;
+/** One live personal rule in the effective view: the row itself, its source, and its standing under the
+ *  org partition (`shadowed-by-org` = an org deny reaches its command pattern; see `orgRuleShadows`). */
+export interface EffectivePermissionRule extends PersistedAllowRule {
+    source: Exclude<RuleSource, "org">;
+    status: "live" | "shadowed-by-org";
+}
+/** A durable rule identity every add of which is tombstoned — the rule no longer stands, and its
+ *  tombstone identity is still visible in the partition. Session rows never appear here (they die
+ *  with their session and leave no tombstone). */
+export interface RemovedPermissionRule {
+    rule: string;
+    scope: RuleScope;
+    source: "user" | "project";
+    status: "removed";
+}
+/** THE answer of the store's one read query. */
+export interface EffectivePermissionRules {
+    /** Live personal rows, in reporting order: this session's rows first (the narrowest standing yes), then
+     *  the durable partition in its own table order — byte-equivalent to the pre-389 splice. */
+    rules: EffectivePermissionRule[];
+    /** Tombstoned durable identities (introspection). */
+    removed: RemovedPermissionRule[];
+    /** The org partition's resolution. `ungoverned` on a deployment with no org partition. */
+    org: OrgRuleResolution;
+    /** The durable partition's revision — the optimistic-concurrency anchor for its writes. */
+    rev: number;
+    /** Present iff the DURABLE partition could not be read: `rules`/`removed` are then empty and `rev` is 0,
+     *  while the org partition's resolution beside it still stands (a flaky personal store must not become
+     *  an org governance outage). A consumer that needs the durable rows treats this as a read failure —
+     *  {@link effectiveOrThrow} is that reading; the gate's personal lane reads it as "unreadable"
+     *  (zero rules + a disclosure, fail toward asking). */
+    unreadable?: string;
+    /** Disclosure lines from the personal partitions (a session partition that could not be read, rows it
+     *  served that are not canonical session rows of this session). The org partition's lines ride
+     *  `org.disclosures`. */
+    disclosures: string[];
+}
+/**
+ * The host-visible store, already anchored to one owner. One read verb, which never throws: each
+ * partition reports its own failure in the view — the DURABLE partition's read failure as `unreadable`
+ * (zero rows; the caller maps it to "unreadable": a loud disclosure, fail toward asking, exactly as the
+ * old `list()` throw did), the SESSION partition's as zero session rows plus a `disclosures` line, the
+ * ORG partition's as its `status`. The three are independent on purpose: the org verdict must stand
+ * while a personal store is down, and the personal rows must stand while an org source is down.
+ */
+export interface PermissionRuleStore {
+    effective(query?: {
+        sessionId?: string;
+    }): Promise<EffectivePermissionRules>;
+    /** design/182 §5.2 — the durable partition's quarantine area, for introspection. */
+    quarantined?(): Promise<QuarantinedRuleAdd[]>;
+    /** The durable partition's declared durability; an undeclared backend reads fail-closed as `"process-local"`. */
+    readonly durability?: StoreDurability;
+    readonly fidelity?: StoreFidelity;
+}
+/**
+ * The unified provider — the ONE `RunnerDeps.permissionRuleStore` seam. `partitions` is the declaration
+ * face: the wiring manifest's cells and the ask evidence's `not_wired` words read it verbatim instead of
+ * inferring from three separate seams.
+ */
+export interface PermissionRuleStoreProvider {
+    /** The store for one verified principal. `undefined` ⇒ zero personal rules — but the org partition
+     *  still adjudicates: governance applies to everyone, an anonymous task included. */
+    forPrincipal(principal: string | undefined): PermissionRuleStore;
+    /** design/182 §4.5 — the identity-less local bucket. Present iff the durable backend has one. */
+    forLocalOwner?(): PermissionRuleStore;
+    readonly partitions: Readonly<{
+        durable: boolean;
+        org: boolean;
+        session: boolean;
+    }>;
+}
+/** What {@link createPermissionRuleStoreProvider} composes. */
+export interface PermissionRuleStoreConfig {
+    /** The durable CRDT partition (user + project sources). Absent ⇒ no personal rules exist on this
+     *  deployment (the rule lane does not arm), and no session grant can land either (the redemption
+     *  dot is minted by the durable replica). */
+    durable?: DurableRulePartitionProvider;
+    /** The org partition. Its PRESENCE is the governance declaration (design/182 §7.4 D3): under it the
+     *  org adjudication surface must always be effective, and an unreadable snapshot fails the whole
+     *  decision boundary closed. */
+    org?: OrgRulePartitionConfig;
+    /** The session partition. Absent ⇒ the session source does not exist: a session-scope redemption is
+     *  refused loudly (nowhere to land), and `effective()` carries no session rows. */
+    session?: SessionRulePartition;
+}
+/**
+ * Compose the unified store over its partition backends. This is the boot gate of the org declaration
+ * (`createOrgRulePartition` refuses a config naming no source) and the ONLY constructor of the store.
+ */
+export declare function createPermissionRuleStoreProvider(cfg: PermissionRuleStoreConfig): PermissionRuleStoreProvider;
+/**
+ * The one read query for a consumer that NEEDS the durable rows (a write's optimistic-concurrency anchor,
+ * a coverage judgment, a removal): an `unreadable` durable partition is a thrown read failure here, so
+ * the caller's existing "could not read the permission-rule store" arm fires — the gate lane is the one
+ * consumer that reads the word itself.
+ */
+export declare function effectiveOrThrow(store: PermissionRuleStore, query?: {
+    sessionId?: string;
+}): Promise<EffectivePermissionRules>;
+/**
+ * The one read query, addressed by owner (design/182 §7.3 introspection, design/389 form): resolve the
+ * owner's store and ask it. Nothing is assembled here — a consumer that needs the effective view with
+ * `source`/`status` per row and the org resolution beside it gets the store's own answer.
+ */
+export declare function effectivePermissionRules(opts: {
+    provider: PermissionRuleStoreProvider;
+    principal?: string;
+    owner?: RuleOwner;
+    sessionId?: string;
+}): Promise<EffectivePermissionRules>;
+/** Owner routing shared by the introspection entry: either a principal or the local owner, never both. */
+export declare function resolveOwnerStore(opts: {
+    provider: PermissionRuleStoreProvider;
+    principal?: string;
+    owner?: RuleOwner;
+}): PermissionRuleStore;