@sema-agent/core 5.21.0 → 5.22.0

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

@@ -28,7 +28,7 @@
  * defended against: for a file backend, host = user, no more and no less.
  */
 import { type RuleScope, type RuleDot } from "./permission-rule-model.js";
-import type { PermissionRuleStoreProvider } from "./permission-rule-store.js";
+import type { PermissionRuleStoreProvider, RuleOwner } from "./permission-rule-store.js";
 /** One candidate rule inside an approval record: the exact text and where it would apply. */
 export interface RuleCandidate {
     rule: string;
@@ -36,10 +36,18 @@ export interface RuleCandidate {
 }
 /** What the approval record is for — it decides the provenance the minted adds carry. */
 export type RuleApprovalKind = "card" | "import" | "starter";
-/** A durable record of one pending/settled human decision about minting rules. */
+/** A durable record of one pending/settled human decision about minting rules.
+ *
+ * Identity (design/182 §4.5, additive): a v1 record carries `principal` and nothing else — it stays
+ * valid forever and projects at runtime to a principal-kind {@link RuleOwner} (zero migration; pending
+ * and redeemed-but-unlanded records redeem across the upgrade unchanged). Only the local-owner path
+ * mints records with the `owner` field and NO principal. A record carrying both, disagreeing, is
+ * contradictory and unredeemable. */
 export interface RuleApprovalRecord {
     id: string;
-    principal: string;
+    principal?: string;
+    /** Structural owner (additive). Absent on every record a v1 tree minted. */
+    owner?: RuleOwner;
     kind: RuleApprovalKind;
     state: "pending" | "approved" | "redeemed";
     candidates: RuleCandidate[];
@@ -118,7 +126,9 @@ export declare function mintRuleTicket(recordId: string, candidateIndex: number)
  * engine at all.
  */
 export declare function prepareCardApproval(opts: {
-    principal: string;
+    principal?: string;
+    /** design/182 §4.5 (additive): the structural owner — only the local-owner path needs it. */
+    owner?: RuleOwner;
     /** The tool whose ask this card belongs to. Only the shell tool the rule lane speaks for is accepted. */
     toolName: string;
     /** The command as adjudicated — the same bytes the ask carried. */
@@ -143,7 +153,9 @@ export declare function prepareCardApproval(opts: {
  */
 export declare function confirmRuleApproval(opts: {
     approvalId: string;
-    principal: string;
+    principal?: string;
+    /** design/182 §4.5 (additive): the structural owner — only the local-owner path needs it. */
+    owner?: RuleOwner;
     /**
      * REQUIRED for a card record: the index of the option the person chose. A card presents alternatives of
      * different breadth, so "they said yes" is not an answer on its own — "they said yes to THIS one" is.
@@ -182,7 +194,8 @@ export type RedeemResult = {
  */
 export declare function redeemRuleTicket(opts: {
     ticket: RuleTicket;
-    principal: string;
+    principal?: string;
+    owner?: RuleOwner;
     deps: RuleConsentDeps;
 }): Promise<RedeemResult>;
 /** The three user-editable settings layers this version reads. */
@@ -238,7 +251,8 @@ export interface ImportResult {
  */
 export declare function prepareCcImport(opts: {
     layers: CcImportLayer[];
-    principal: string;
+    principal?: string;
+    owner?: RuleOwner;
     deps: RuleConsentDeps;
 }): Promise<{
     preview: ImportPreview;
@@ -256,7 +270,8 @@ export declare const STARTER_RULES: readonly string[];
 /** Prepare the starter batch as a pending approval record. Nothing takes effect without confirmation;
  *  an unconfirmed deployment simply starts with an empty rule set. */
 export declare function prepareStarterBatch(opts: {
-    principal: string;
+    principal?: string;
+    owner?: RuleOwner;
     deps: RuleConsentDeps;
 }): Promise<{
     preview: RuleCandidate[];
@@ -268,7 +283,8 @@ export declare function prepareStarterBatch(opts: {
  */
 export declare function redeemRuleBatch(opts: {
     approvalId: string;
-    principal: string;
+    principal?: string;
+    owner?: RuleOwner;
     deps: RuleConsentDeps;
 }): Promise<ImportResult | {
     status: "refused";

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

@@ -1,5 +1,5 @@
 import { parseAllowRuleText, suggestRulesForCommand } from "./permission-rule-model.js";
-import { errText, sameScope, writerOf } from "./permission-rule-store.js";
+import { errText, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
     async get(id) {
@@ -36,6 +36,49 @@ function requirePrincipal(principal, entry) {
     }
     return principal;
 }
+function resolveCallerOwner(principal, owner, entry) {
+    if (owner !== undefined) {
+        if (owner.kind === "principal") {
+            const p = requirePrincipal(owner.principal, entry);
+            if (typeof principal === "string" && principal !== "" && principal !== p) {
+                throw new Error(`${entry}: contradictory identity — principal "${principal}" and owner principal "${p}" disagree`);
+            }
+            return { kind: "principal", principal: p };
+        }
+        if (typeof principal === "string" && principal !== "") {
+            throw new Error(`${entry}: contradictory identity — a principal and a local-owner were both given; a bucket has one owner`);
+        }
+        return { kind: "local-owner" };
+    }
+    return { kind: "principal", principal: requirePrincipal(principal, entry) };
+}
+function ownerOfRecord(rec) {
+    if (rec.owner !== undefined) {
+        if (rec.owner.kind === "principal") {
+            if (typeof rec.owner.principal !== "string" || rec.owner.principal === "")
+                return undefined;
+            if (typeof rec.principal === "string" && rec.principal !== "" && rec.principal !== rec.owner.principal)
+                return undefined;
+            return rec.owner;
+        }
+        if (typeof rec.principal === "string" && rec.principal !== "")
+            return undefined;
+        return { kind: "local-owner" };
+    }
+    return typeof rec.principal === "string" && rec.principal !== "" ? { kind: "principal", principal: rec.principal } : undefined;
+}
+function recordIdentityOf(owner) {
+    return owner.kind === "principal" ? { principal: owner.principal } : { owner: { kind: "local-owner" } };
+}
+function storeForOwner(provider, owner) {
+    if (owner.kind === "principal")
+        return provider.forPrincipal(owner.principal);
+    const store = provider.forLocalOwner?.();
+    if (store === undefined) {
+        throw new Error("this deployment's permission-rule provider has no local-owner bucket (forLocalOwner is not implemented)");
+    }
+    return store;
+}
 export function mintRuleTicket(recordId, candidateIndex) {
     return `rt.${candidateIndex}.${recordId}`;
 }
@@ -46,7 +89,7 @@ function parseRuleTicket(ticket) {
     return { index: Number(m[1]), recordId: m[2] };
 }
 export async function prepareCardApproval(opts) {
-    const principal = requirePrincipal(opts.principal, "prepareCardApproval");
+    const owner = resolveCallerOwner(opts.principal, opts.owner, "prepareCardApproval");
     if ("candidates" in opts) {
         const e = new Error("prepareCardApproval does not accept caller candidates — card options are minted by the engine from the adjudicated command");
         e.code = "config.invalid_argument";
@@ -60,7 +103,7 @@ export async function prepareCardApproval(opts) {
         return undefined;
     const record = {
         id: mintId(opts.deps, "rar"),
-        principal,
+        ...recordIdentityOf(owner),
         kind: "card",
         state: "pending",
         rev: 0,
@@ -74,10 +117,11 @@ export async function prepareCardApproval(opts) {
 }
 const CARD_RULE_TOOL = "Bash";
 export async function confirmRuleApproval(opts) {
-    const principal = requirePrincipal(opts.principal, "confirmRuleApproval");
+    const caller = resolveCallerOwner(opts.principal, opts.owner, "confirmRuleApproval");
     const no = (reason) => ({ ok: false, reason });
     const rec = await opts.deps.approvals.get(opts.approvalId);
-    if (rec === undefined || rec.principal !== principal)
+    const recOwner = rec === undefined ? undefined : ownerOfRecord(rec);
+    if (rec === undefined || recOwner === undefined || !sameRuleOwner(recOwner, caller))
         return no("record_not_found");
     if (rec.kind === "card") {
         const chosen = opts.selectedCandidate;
@@ -101,14 +145,15 @@ export async function confirmRuleApproval(opts) {
     return won ? { ok: true } : no("conflict");
 }
 export async function redeemRuleTicket(opts) {
-    const principal = requirePrincipal(opts.principal, "redeemRuleTicket");
+    const caller = resolveCallerOwner(opts.principal, opts.owner, "redeemRuleTicket");
     const parsed = parseRuleTicket(opts.ticket);
     if (parsed === undefined)
         return { status: "refused", reason: "malformed ticket" };
     const rec = await opts.deps.approvals.get(parsed.recordId);
     if (rec === undefined)
         return { status: "refused", reason: "no such approval record" };
-    if (rec.principal !== principal)
+    const recOwner = ownerOfRecord(rec);
+    if (recOwner === undefined || !sameRuleOwner(recOwner, caller))
         return { status: "refused", reason: "the ticket belongs to a different principal" };
     if (rec.state === "pending")
         return { status: "refused", reason: "the approval record has not been confirmed" };
@@ -121,7 +166,13 @@ export async function redeemRuleTicket(opts) {
     const parsedRule = parseAllowRuleText(candidate.rule);
     if ("reject" in parsedRule)
         return { status: "refused", reason: `${parsedRule.reject.code}: ${parsedRule.reject.message}` };
-    const store = opts.deps.provider.forPrincipal(principal);
+    let store;
+    try {
+        store = storeForOwner(opts.deps.provider, caller);
+    }
+    catch (err) {
+        return { status: "refused", reason: errText(err) };
+    }
     const writer = writerOf(store);
     if (writer === undefined)
         return { status: "refused", reason: "the resolved permission-rule store has no write face" };
@@ -140,14 +191,20 @@ export async function redeemRuleTicket(opts) {
             const theirs = again?.redeemedDots?.[parsed.index];
             if (theirs === undefined)
                 return { status: "refused", reason: "the approval record changed state concurrently" };
-            return await applyRedemption({ ...opts, principal, candidate, parsedRule: parsedRule.rule, dot: theirs, recordId: rec.id, kind: rec.kind, replay: true });
+            return await applyRedemption({ deps: opts.deps, owner: caller, candidate, parsedRule: parsedRule.rule, dot: theirs, recordId: rec.id, kind: rec.kind, replay: true });
         }
     }
-    return await applyRedemption({ ...opts, principal, candidate, parsedRule: parsedRule.rule, dot, recordId: rec.id, kind: rec.kind, replay: known !== undefined });
+    return await applyRedemption({ deps: opts.deps, owner: caller, candidate, parsedRule: parsedRule.rule, dot, recordId: rec.id, kind: rec.kind, replay: known !== undefined });
 }
 const REDEEM_MAX_ATTEMPTS = 8;
 async function applyRedemption(args) {
-    const store = args.deps.provider.forPrincipal(args.principal);
+    let store;
+    try {
+        store = storeForOwner(args.deps.provider, args.owner);
+    }
+    catch (err) {
+        return { status: "refused", reason: errText(err) };
+    }
     const writer = writerOf(store);
     if (writer === undefined)
         return { status: "refused", reason: "the resolved permission-rule store has no write face" };
@@ -170,7 +227,10 @@ async function applyRedemption(args) {
                 match: args.parsedRule.match,
                 command: args.parsedRule.command,
                 add: { dot: args.dot, origin, createdAt: nowIso(args.deps) },
-                redemption: { recordId: args.recordId, principal: args.principal },
+                redemption: {
+                    recordId: args.recordId,
+                    ...(args.owner.kind === "principal" ? { principal: args.owner.principal } : { owner: args.owner }),
+                },
             }, { expectedRev: rev });
         }
         catch (err) {
@@ -187,7 +247,7 @@ function originOfRecordKind(kind) {
 }
 const IMPORT_UNCOVERED = { flagSettings: "not-imported-v1", policySettings: "not-imported-v1" };
 export async function prepareCcImport(opts) {
-    const principal = requirePrincipal(opts.principal, "prepareCcImport");
+    const owner = resolveCallerOwner(opts.principal, opts.owner, "prepareCcImport");
     const candidates = [];
     const skipped = [];
     const layers = [];
@@ -234,7 +294,7 @@ export async function prepareCcImport(opts) {
     }
     const record = {
         id: mintId(opts.deps, "rar"),
-        principal,
+        ...recordIdentityOf(owner),
         kind: "import",
         state: "pending",
         rev: 0,
@@ -256,7 +316,7 @@ export const STARTER_RULES = [
     "Bash(npm --version)",
 ];
 export async function prepareStarterBatch(opts) {
-    const principal = requirePrincipal(opts.principal, "prepareStarterBatch");
+    const owner = resolveCallerOwner(opts.principal, opts.owner, "prepareStarterBatch");
     const candidates = [];
     for (const text of STARTER_RULES) {
         const parsed = parseAllowRuleText(text);
@@ -266,7 +326,7 @@ export async function prepareStarterBatch(opts) {
     }
     const record = {
         id: mintId(opts.deps, "rar"),
-        principal,
+        ...recordIdentityOf(owner),
         kind: "starter",
         state: "pending",
         rev: 0,
@@ -277,11 +337,12 @@ export async function prepareStarterBatch(opts) {
     return { preview: candidates, approvalId: record.id };
 }
 export async function redeemRuleBatch(opts) {
-    const principal = requirePrincipal(opts.principal, "redeemRuleBatch");
+    const caller = resolveCallerOwner(opts.principal, opts.owner, "redeemRuleBatch");
     const rec = await opts.deps.approvals.get(opts.approvalId);
     if (rec === undefined)
         return { status: "refused", reason: "no such approval record" };
-    if (rec.principal !== principal)
+    const recOwner = ownerOfRecord(rec);
+    if (recOwner === undefined || !sameRuleOwner(recOwner, caller))
         return { status: "refused", reason: "the record belongs to a different principal" };
     if (rec.kind === "card")
         return { status: "refused", reason: "a card record is redeemed by its chosen ticket, not as a batch" };
@@ -291,7 +352,13 @@ export async function redeemRuleBatch(opts) {
     const deduped = [];
     const skippedAtRedeem = [];
     let rev = 0;
-    const store = opts.deps.provider.forPrincipal(principal);
+    let store;
+    try {
+        store = storeForOwner(opts.deps.provider, caller);
+    }
+    catch (err) {
+        return { status: "refused", reason: errText(err) };
+    }
     for (let i = 0; i < rec.candidates.length; i++) {
         const candidate = rec.candidates[i];
         let alreadyThere = false;
@@ -303,7 +370,11 @@ export async function redeemRuleBatch(opts) {
         catch (err) {
             return { status: "refused", reason: `could not read the permission-rule store: ${errText(err)}` };
         }
-        const res = await redeemRuleTicket({ ticket: mintRuleTicket(rec.id, i), principal, deps: opts.deps });
+        const res = await redeemRuleTicket({
+            ticket: mintRuleTicket(rec.id, i),
+            ...(caller.kind === "principal" ? { principal: caller.principal } : { owner: caller }),
+            deps: opts.deps,
+        });
         if (res.status === "refused") {
             skippedAtRedeem.push({ rule: candidate.rule, reason: res.reason });
             continue;

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

@@ -126,8 +126,16 @@ export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
  * This is the ONE validator every entry point shares — minting a suggestion, importing another
  * product's settings, reloading a store file, and any future backend. A shape refused here cannot enter
  * the store through any door.
+ *
+ * `direction` (design/182 §7, additive): the bare-interpreter-prefix refusal is an ALLOW-side argument
+ * — one approval click cannot be read as authorizing arbitrary programs. An org deny/ask rule has the
+ * opposite polarity: `Bash(node:*)` as a DENY is a legitimately wide tightening, and refusing it would
+ * silently disarm exactly the policy an administrator most wants. `"tighten"` therefore admits the
+ * interpreter-headed prefix form and changes nothing else; the default stays the allow-side floor.
  */
-export declare function parseAllowRuleText(text: string): {
+export declare function parseAllowRuleText(text: string, opts?: {
+    direction?: "allow" | "tighten";
+}): {
     rule: ParsedAllowRule;
 } | {
     reject: RuleReject;

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

@@ -43,7 +43,7 @@ function foldSpacing(s) {
 function reject(code, message) {
     return { reject: { code, message } };
 }
-export function parseAllowRuleText(text) {
+export function parseAllowRuleText(text, opts) {
     if (text.length > MAX_RULE_TEXT_CHARS) {
         return reject("invalid.too_long", `rule text exceeds ${MAX_RULE_TEXT_CHARS} characters`);
     }
@@ -67,7 +67,7 @@ export function parseAllowRuleText(text) {
             ? reject("invalid.empty_command", `rule "${text}" names no command`)
             : reject("invalid.not_simple_command", `rule "${text}" is not a single simple command (${floor.reject})`);
     }
-    if (match === "prefix" && BARE_INTERPRETER_NAMES.has(floor.name)) {
+    if (match === "prefix" && BARE_INTERPRETER_NAMES.has(floor.name) && opts?.direction !== "tighten") {
         return reject("invalid.bare_interpreter_prefix", `prefix rule "${text}" is headed by the interpreter "${floor.name}" — such a rule authorizes running arbitrary programs, which one approval click cannot be read as having granted (an exact rule naming the whole command line is accepted)`);
     }
     const command = foldSpacing(body);

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

@@ -0,0 +1,161 @@
+/**
+ * design/182 §7 — the ORGANIZATION rule layer: 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
+ * convergent merge). So the org layer has NO CRDT, no tombstones and no join: the server is the single
+ * authority, a client holds a read-only versioned snapshot, an update is a whole replacement (revision
+ * strictly ordered), and a rollback is a NEW revision carrying old content. Cross-layer tombstones are
+ * structurally impossible — an org rule never enters `PersistedAllowRule`, and an org snapshot replace
+ * never touches a personal store's bytes. The two layers meet only at the CONSUMPTION site, where org
+ * deny/ask folds strict-side: **org deny > org ask (non-dismissable) > personal allow rule > bare ask**.
+ *
+ * ## 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:
+ *  - 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
+ *    the CONSUMING gate must fail the ENTIRE decision boundary closed: every terminal allow — policy
+ *    allow and default allow included — tightens to an ask carrying `decisionReason: "org_unavailable"`
+ *    AND `requiresRealApproval: true` (the same non-dismissable bit an org ask itself carries; without
+ *    it a blanket `onAsk: "allow"` deployment would clear the synthetic ask — a third fail-open path),
+ *    with the personal-rule lane and the auto-mode classifier both disarmed. That obligation lives at
+ *    the gate integration; THIS module's contract is to report `unavailable` honestly and never lapse
+ *    into an empty-rules answer that reads as "not governed".
+ *
+ * ## Anti-rollback
+ *
+ * `revision` is an orderable server-monotone number, and the installed high-water mark persists with
+ * the snapshot in ONE atomic write: a replayed older snapshot (fresh `fetchedAtMs`, old content) is
+ * refused and disclosed — identity comparison alone cannot catch it, and an in-memory-only mark would
+ * 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 RuleScope } from "./permission-rule-model.js";
+import { type PermissionRuleStore, type PermissionRuleStoreProvider, type RuleOwner } from "./permission-rule-store.js";
+/** One org rule. There is structurally no allow bucket (design/179 §9: the org layer only tightens). */
+export interface OrgPermissionRule {
+    rule: string;
+    behavior: "deny" | "ask";
+}
+/** The read-only versioned snapshot a client holds. */
+export interface OrgRuleSnapshot {
+    /** Server-monotone orderable revision. A snapshot below the persisted high-water mark is refused. */
+    revision: number;
+    rules: OrgPermissionRule[];
+    /** Reserved for the privilege-separation ticket's signed-snapshot contract. Carried, not verified here. */
+    signature?: string;
+    /** Observation timestamp (epoch ms) — staleness input only, never adjudication input. */
+    fetchedAtMs: number;
+}
+/** Where the deployment fetches the current snapshot. `undefined` = the provider has none to give. */
+export interface OrgRuleSnapshotProvider {
+    current(): Promise<OrgRuleSnapshot | undefined>;
+}
+/**
+ * The durable org state: last-known-good snapshot + the anti-rollback high-water mark, installed in one
+ * atomic write. SQL twin note (server/org ticket): `revision_high_water` and `installed_at_ms` are
+ * structured columns (`_ms` suffix for epoch milliseconds); the snapshot itself is a JSON blob — it is
+ * installed and read whole, never row-queried.
+ */
+export interface PersistedOrgRuleState {
+    revisionHighWater: number;
+    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.
+ *
+ *  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
+ *  durable home can interleave read-then-write, and the backend's atomic write is the one place the
+ *  lowering can be caught. The file backend enforces this under its write serialization. */
+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. */
+export declare const ORG_UNAVAILABLE_DECISION_REASON = "org_unavailable";
+/** How far into the future a snapshot's `fetchedAtMs` may sit before it is refused — ordinary NTP-level
+ *  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;
+    rules: OrgPermissionRule[];
+    revision?: number;
+    /** Honest-disclosure lines: provider failures, refused snapshots, rollback refusals. */
+    disclosures: string[];
+}
+export interface OrgRuleOverlay {
+    resolve(): Promise<OrgOverlayResolution>;
+}
+/**
+ * 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;
+    /** 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;
+/**
+ * design/182 §7.2 — which org rule speaks for this command, if any. Deny outranks ask; within a
+ * behavior the first textual match wins (reporting order only — all denies are the same one answer).
+ * Matching uses the SAME parser and matcher the personal lane uses (tighten direction: an
+ * interpreter-headed prefix deny like `Bash(node:*)` is a legitimately wide tightening and matches).
+ * A rule text the validator refuses never gets here — snapshot validation refuses the whole snapshot,
+ * so an unenforceable deny cannot install as policy; the skip below is a defensive floor only.
+ */
+export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: {
+    tool: string;
+    command: string;
+}): {
+    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 forge 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).
+ *
+ * The shadow predicate: an org DENY rule admits 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). org ASK rules do not shadow: the personal lane never consumes a `requiresRealApproval`
+ * ask, so the two never actually meet on one call.
+ */
+export declare function effectivePermissionRules(opts: {
+    provider: PermissionRuleStoreProvider;
+    principal?: string;
+    owner?: RuleOwner;
+    orgSnapshot?: OrgRuleSnapshot;
+}): Promise<EffectivePermissionRule[]>;
+/** 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;