@sema-agent/core 5.21.1 → 5.23.0

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

@@ -0,0 +1,195 @@
+/**
+ * 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 — and TYPED as the
+ *  member of {@link import("./tool-policy.js").DecisionReason} it must equal, so the constant and the
+ *  vocabulary cannot drift into two spellings of one word. */
+export declare const ORG_UNAVAILABLE_DECISION_REASON: Extract<import("./tool-policy.js").DecisionReason, "org_unavailable">;
+/**
+ * How long a single org adjudication may take before the consuming gate stops waiting and reads the
+ * answer as UNAVAILABLE (its fail-closed word).
+ *
+ * A bound is MANDATORY rather than optional because of where this call sits: on the hot path of every
+ * governed tool call, and — on the durable resume leg — after the checkpoint has been consumed and the
+ * start frame emitted. A provider that never settles would otherwise wedge the call past any task
+ * deadline (tasks carry no walltime by default), leaving the frame unpaired and the approval spent with
+ * nothing retryable. A hang is the one outcome worse than either verdict.
+ *
+ * The value matches the auto-mode classifier's per-round-trip cap — the other model/network call the
+ * permission path makes — because the reasoning is the same: a governance lookup that takes longer than
+ * this is indistinguishable from an outage, and an outage is exactly what the unavailable arm is for.
+ * The task's own abort signal still applies in parallel; whichever fires first ends the wait.
+ */
+export declare const ORG_ADJUDICATION_TIMEOUT_MS = 15000;
+/**
+ * Await `p`, but settle with `fallback` if the deadline elapses or the signal fires first.
+ *
+ * Shared by both org consumption sites so one bound cannot drift into two. Deliberately NOT `.unref()`
+ * on the timer: this is a foreground rescue timer, and the caller is awaiting it inside the control
+ * flow — an unref'd timer stops firing in exactly the situation it exists for (an otherwise idle loop).
+ * A rejecting `p` also lands on the fallback: the callers' fail-closed word is the same either way, and
+ * an escaping rejection here would turn a dependency failure into a task crash.
+ */
+export declare function settleOrgVerdictWithin<T>(p: Promise<T>, fallback: T, opts: {
+    signal?: AbortSignal;
+    timeoutMs: number;
+}): Promise<T>;
+/** The `decisionReason` of a decision an ORG RULE produced (a deny, or a non-dismissable ask). Same
+ *  single-spelling contract as {@link ORG_UNAVAILABLE_DECISION_REASON}. */
+export declare const ORG_RULE_DECISION_REASON: Extract<import("./tool-policy.js").DecisionReason, "org_rule">;
+/** 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;

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

@@ -0,0 +1,234 @@
+import { parseAllowRuleText, ruleAdmitsCommand } 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;
+}
+export const ORG_UNAVAILABLE_DECISION_REASON = "org_unavailable";
+export const ORG_ADJUDICATION_TIMEOUT_MS = 15_000;
+export function settleOrgVerdictWithin(p, fallback, opts) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            resolve(v);
+        };
+        const onAbort = () => finish(fallback);
+        const timer = setTimeout(() => finish(fallback), opts.timeoutMs);
+        if (opts.signal?.aborted === true) {
+            finish(fallback);
+            return;
+        }
+        opts.signal?.addEventListener("abort", onAbort);
+        p.then(finish, () => finish(fallback));
+    });
+}
+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");
+    }
+    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 (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 ${String(cfg.stalenessBoundMs)})`);
+    }
+    const provider = cfg.provider;
+    const now = cfg.now ?? Date.now;
+    let memoryState;
+    const readState = async () => {
+        const state = cfg.persistence !== undefined ? await cfg.persistence.readOrgState() : memoryState;
+        return state === undefined ? undefined : structuredClone(state);
+    };
+    const writeState = async (state) => {
+        if (cfg.persistence !== undefined)
+            await cfg.persistence.installOrgState(structuredClone(state));
+        else
+            memoryState = structuredClone(state);
+    };
+    let chain = Promise.resolve();
+    const serialize = (fn) => {
+        const run = chain.then(fn, fn);
+        chain = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const resolve = async () => {
+        const disclosures = [];
+        if (cfg.persistence === undefined) {
+            disclosures.push("org rule state has no durable persistence wired — the last-known-good snapshot and the anti-rollback mark do not survive a restart");
+        }
+        let fetched;
+        let fetchFailed = false;
+        try {
+            fetched = await provider.current();
+        }
+        catch (err) {
+            fetchFailed = true;
+            disclosures.push(`org snapshot provider failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return await serialize(async () => {
+            const nowMs = now();
+            const guardedRead = async (context) => {
+                try {
+                    return await readState();
+                }
+                catch (err) {
+                    disclosures.push(`org state ${context} read failed: ${err instanceof Error ? err.message : String(err)}`);
+                    return undefined;
+                }
+            };
+            const installed = await (async () => {
+                const persisted = await guardedRead("persistence");
+                if (fetched === undefined)
+                    return persisted;
+                const invalid = validateOrgSnapshot(fetched, nowMs);
+                if (invalid !== undefined) {
+                    disclosures.push(`org snapshot refused: ${invalid}; the previously installed snapshot (if any) remains in force`);
+                    return persisted;
+                }
+                if (persisted !== undefined && fetched.revision < persisted.revisionHighWater) {
+                    disclosures.push(`org snapshot revision ${fetched.revision} is below the installed high-water mark ${persisted.revisionHighWater} — refusing the rollback; the current deny set is unchanged`);
+                    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;
+                }
+                const state = {
+                    revisionHighWater: Math.max(persisted?.revisionHighWater ?? 0, fetched.revision),
+                    snapshot: fetched,
+                    installedAtMs: nowMs,
+                };
+                try {
+                    await writeState(state);
+                }
+                catch (err) {
+                    const reread = await guardedRead("reconciliation");
+                    if (reread !== undefined && reread.revisionHighWater >= state.revisionHighWater) {
+                        disclosures.push(`org snapshot install was superseded by a concurrent install at revision ${reread.snapshot.revision} — continuing on the newer installed state`);
+                        return reread;
+                    }
+                    disclosures.push(`org snapshot install failed (${err instanceof Error ? err.message : String(err)}) and no superseding installed state exists — org adjudication is UNAVAILABLE`);
+                    return undefined;
+                }
+                return state;
+            })();
+            const decisionMs = now();
+            const withinBound = (snap) => decisionMs - snap.fetchedAtMs <= cfg.stalenessBoundMs && snap.fetchedAtMs <= decisionMs + ORG_FETCHED_AT_SKEW_ALLOWANCE_MS;
+            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 (${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 };
+                }
+                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");
+                    }
+                    return {
+                        status: freshlyInstalled ? "fresh" : "last-known-good",
+                        rules: structuredClone(installed.snapshot.rules),
+                        revision: installed.snapshot.revision,
+                        disclosures,
+                    };
+                }
+                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 };
+            }
+            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 { resolve };
+}
+function sameOrgPolicyContent(a, b) {
+    if (a.rules.length !== b.rules.length)
+        return false;
+    return a.rules.every((r, i) => b.rules[i]?.rule === r.rule && b.rules[i]?.behavior === r.behavior);
+}
+function validateOrgSnapshot(s, nowMs) {
+    if (typeof s.revision !== "number" || !Number.isFinite(s.revision))
+        return `revision is not a finite number (${String(s.revision)})`;
+    if (typeof s.fetchedAtMs !== "number" || !Number.isFinite(s.fetchedAtMs))
+        return `fetchedAtMs is not a finite number (${String(s.fetchedAtMs)})`;
+    if (s.fetchedAtMs > nowMs + ORG_FETCHED_AT_SKEW_ALLOWANCE_MS) {
+        return `fetchedAtMs is ${s.fetchedAtMs - nowMs}ms in the future (allowance ${ORG_FETCHED_AT_SKEW_ALLOWANCE_MS}ms) — a future-dated observation would satisfy the staleness bound indefinitely`;
+    }
+    if (!Array.isArray(s.rules))
+        return "rules is not an array";
+    for (const r of s.rules) {
+        if (typeof r?.rule !== "string" || r.rule === "")
+            return "a rule entry carries no rule text";
+        if (r.behavior !== "deny" && r.behavior !== "ask")
+            return `rule "${r.rule}" carries behavior "${String(r.behavior)}" — the org layer has no allow bucket`;
+        const parsed = parseAllowRuleText(r.rule, { direction: "tighten" });
+        if ("reject" in parsed)
+            return `rule "${r.rule}" does not parse (${parsed.reject.code}) — an unenforceable ${r.behavior} must not install as policy`;
+    }
+    return undefined;
+}
+export function orgRuleVerdictFor(rules, call) {
+    let ask;
+    for (const r of rules) {
+        const parsed = parseAllowRuleText(r.rule, { direction: "tighten" });
+        if ("reject" in parsed)
+            continue;
+        if (parsed.rule.tool !== call.tool)
+            continue;
+        if (!ruleAdmitsCommand(parsed.rule, call.command))
+            continue;
+        if (r.behavior === "deny")
+            return { behavior: "deny", rule: r.rule };
+        ask ??= { behavior: "ask", rule: r.rule };
+    }
+    return ask;
+}
+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 = orgDenies.some((d) => {
+            const parsed = parseAllowRuleText(d.rule, { direction: "tighten" });
+            return !("reject" in parsed) && parsed.rule.tool === r.tool && ruleAdmitsCommand(parsed.rule, r.command);
+        });
+        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;
+}
+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 "${opts.principal}" and owner principal "${opts.owner.principal}" disagree`);
+    }
+    const principal = opts.owner?.kind === "principal" ? opts.owner.principal : opts.principal;
+    return opts.provider.forPrincipal(principal);
+}
+export function isWritablePermissionRuleStore(store) {
+    return writerOf(store) !== undefined;
+}