proactive-gate 0.1.2 → 0.2.1

package/dist/src/cli.js

@@ -1,31 +1,65 @@
 #!/usr/bin/env node
 /**
- * proactive-gate replay <events.jsonl> [--policy <module>] [--json]
+ * proactive-gate replay <events.jsonl> [--policy <file>] [--json] [--commit]
+ * proactive-gate replay --fixtures <dir>
+ * proactive-gate hook --policy <file> [--tool <name>]
  *
- * Replays candidate messages through a gate and prints why each one was or
+ * replay feeds candidate messages through a gate and prints why each one was or
  * was not allowed. Each JSONL line is an EvaluateInput: { user, candidate, now? }.
- * The policy module must export `gate` (a Gate) or default-export one; without
- * --policy the default check order runs against an in-memory store.
+ * A policy is a JSON document (spec/schema/policy.schema.json) or an ES module
+ * that exports `gate`; without --policy the default check order runs against an
+ * in-memory store. --fixtures runs the conformance suite instead.
+ *
+ * hook reads a Claude Code PreToolUse event on stdin and prints a permission
+ * decision for the matching tool.
  */
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
+import { createRequire } from "node:module";
 import { createGate } from "./gate.js";
 import { defaultChecks } from "./checks.js";
-const HELP = `usage: proactive-gate replay <events.jsonl> [--policy <module.js>] [--json] [--commit]
+import { loadFixtures, readSkips, runFixture } from "./conformance.js";
+import { FRAMEWORKS, listText, plan } from "./init.js";
+const HELP = `usage: proactive-gate init [--preset <name>] [--framework <name>] [--out <file>]
+       proactive-gate replay <events.jsonl> [--policy <file>] [--json] [--commit]
+       proactive-gate replay --fixtures <dir> [--skip <file>]
+       proactive-gate hook --policy <file> [--tool <name>]
+
+init writes a policy you can read and edit, and prints the lines that wire it in.
 
-Replays candidates through a gate and reports what was allowed and why not.
+  --preset <name>    a platform or legal preset to append (see --list)
+  --framework <name> ${FRAMEWORKS.join(", ")} (default none)
+  --out <file>       where to write (default proactive-gate.policy.json)
+  --force            overwrite an existing file
+  --list             print the presets and frameworks and exit
 
-  --policy <module>  ES module exporting \`gate\` (or default) built with createGate()
+replay reports what was allowed and why not.
+
+  --policy <file>    policy.json (spec/schema/policy.schema.json) or an ES module
+                     exporting \`gate\` (or default) built with createGate()
   --json             one Decision per line instead of the summary table
-  --commit           also call gate.commit() for allowed decisions, so the daily
-                     budget is consumed in order, as it would be in production
+  --commit           also call gate.commit() for allowed decisions, so budgets are
+                     consumed in order, as they would be in production
+  --fixtures <dir>   run the conformance fixtures under <dir> and report failures
+  --skip <file>      fixture names to skip, one per line (default spec/skip/ts.txt)
+
+hook reads a PreToolUse event (JSON) on stdin; when tool_name matches --tool
+(default send_message) it evaluates tool_input.gate = { user, candidate, now? }
+and prints a permissionDecision. Other tools print nothing.
+
   -h, --help         this text
+  --version          print the version
 
-Each line of the file is {"user": {...}, "candidate": {...}, "now": "ISO date"}.`;
+Each line of an events file is {"user": {...}, "candidate": {...}, "now": "ISO date"}.`;
 export async function loadPolicy(path) {
     if (!path)
         return createGate({ checks: defaultChecks() });
+    if (path.endsWith(".json")) {
+        const policy = JSON.parse(await readFile(path, "utf8"));
+        return createGate({ policy });
+    }
     const mod = await import(pathToFileURL(resolve(path)).href);
     const gate = mod.gate ?? mod.default;
     if (!gate || typeof gate.evaluate !== "function")
@@ -50,8 +84,8 @@ export async function replay(lines, gate, commit) {
             const ok = await gate.commit(decision, input);
             if (!ok) {
                 decision.allowed = false;
-                decision.rejectedBy = "dailyBudget";
-                decision.reason = "daily budget exhausted at commit";
+                decision.rejectedBy = "commit";
+                decision.reason = "a budget was exhausted at commit";
             }
         }
         decisions.push(decision);
@@ -60,23 +94,26 @@ export async function replay(lines, gate, commit) {
 }
 export function summarize(decisions) {
     const allowed = decisions.filter((d) => d.allowed).length;
+    const deferred = decisions.filter((d) => d.deferredBy).length;
     const byCheck = new Map();
     const sample = new Map();
     for (const d of decisions) {
-        if (d.allowed || !d.rejectedBy)
+        const by = d.rejectedBy ?? d.deferredBy;
+        if (d.allowed || !by)
             continue;
-        byCheck.set(d.rejectedBy, (byCheck.get(d.rejectedBy) ?? 0) + 1);
-        if (!sample.has(d.rejectedBy) && d.reason)
-            sample.set(d.rejectedBy, d.reason);
+        byCheck.set(by, (byCheck.get(by) ?? 0) + 1);
+        if (!sample.has(by) && d.reason)
+            sample.set(by, d.reason);
     }
-    const deferred = decisions.filter((d) => d.allowed && d.deliverAt).length;
+    const later = decisions.filter((d) => d.allowed && d.deliverAt).length;
+    const shadowed = decisions.reduce((n, d) => n + d.shadowed.length, 0);
     const lines = [
-        `${decisions.length} candidates  ·  ${allowed} allowed (${pct(allowed, decisions.length)})  ·  ${decisions.length - allowed} rejected${deferred ? `  ·  ${deferred} deferred to a later moment` : ""}`,
+        `${decisions.length} candidates  ·  ${allowed} allowed (${pct(allowed, decisions.length)})  ·  ${decisions.length - allowed - deferred} rejected${deferred ? `  ·  ${deferred} deferred` : ""}${later ? `  ·  ${later} moved to a later moment` : ""}${shadowed ? `  ·  ${shadowed} shadow rejections` : ""}`,
         "",
     ];
     if (byCheck.size) {
         const w = Math.max(...[...byCheck.keys()].map((k) => k.length), 5);
-        lines.push(`${"check".padEnd(w)}  ${"rejected".padStart(8)}  example`);
+        lines.push(`${"check".padEnd(w)}  ${"stopped".padStart(8)}  example`);
         lines.push("-".repeat(w + 2 + 8 + 2 + 40));
         for (const [id, n] of [...byCheck.entries()].sort((a, b) => b[1] - a[1])) {
             lines.push(`${id.padEnd(w)}  ${String(n).padStart(8)}  ${sample.get(id) ?? ""}`);
@@ -88,19 +125,112 @@ export function summarize(decisions) {
     return lines.join("\n");
 }
 const pct = (n, total) => (total ? `${((100 * n) / total).toFixed(1)}%` : "0%");
+const argValue = (argv, flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : undefined;
+};
+async function runFixtures(dir, skipFile) {
+    const fixtures = await loadFixtures(dir);
+    const skips = await readSkips(skipFile ?? resolve(dir, "..", "skip", "ts.txt"));
+    let failed = 0;
+    let skipped = 0;
+    for (const fixture of fixtures) {
+        const reason = skips.get(fixture.name);
+        if (reason !== undefined) {
+            skipped++;
+            console.log(`skip  ${fixture.name}  (${reason})`);
+            continue;
+        }
+        const failures = await runFixture(fixture);
+        if (failures.length) {
+            failed++;
+            console.log(`FAIL  ${fixture.name}`);
+            for (const f of failures)
+                console.log(`      ${f}`);
+        }
+        else {
+            console.log(`ok    ${fixture.name}`);
+        }
+    }
+    console.log(`${fixtures.length - failed - skipped} passed, ${failed} failed, ${skipped} skipped`);
+    return failed ? 1 : 0;
+}
+/** Turns a PreToolUse event into the hook output Claude Code expects, or null when the tool does not match. */
+export async function hookDecision(event, gate, tool) {
+    if (event.tool_name !== tool)
+        return null;
+    const payload = event.tool_input?.gate;
+    const out = (permissionDecision, permissionDecisionReason) => JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason } });
+    if (!payload?.user || !payload.candidate)
+        return out("deny", "tool_input.gate must carry { user, candidate } for proactive-gate to decide");
+    const decision = await gate.evaluate({ user: payload.user, candidate: payload.candidate, ...(payload.now ? { now: new Date(payload.now) } : {}) });
+    if (decision.allowed) {
+        const ok = await gate.commit(decision, { user: payload.user, candidate: payload.candidate, ...(decision.evaluatedAt ? { now: decision.evaluatedAt } : {}) });
+        return ok ? out("allow", `proactive-gate: allowed on ${decision.surfaces.join(",")}${decision.deliverAt ? `, deliver at ${decision.deliverAt.toISOString()}` : ""}`) : out("deny", "proactive-gate: a budget was exhausted at commit");
+    }
+    if (decision.deferredBy)
+        return out("deny", `proactive-gate: deferred by ${decision.deferredBy} until ${decision.retryAt?.toISOString()} (${decision.reason})`);
+    return out("deny", `proactive-gate: rejected by ${decision.rejectedBy} (${decision.reason})`);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+const VERSION = createRequire(import.meta.url)("../../package.json").version;
 async function main(argv) {
+    if (argv.includes("--version")) {
+        console.log(VERSION);
+        return;
+    }
     if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
         console.log(HELP);
         return;
     }
     const [command, file] = argv;
-    if (command !== "replay" || !file) {
+    if (command === "init") {
+        if (argv.includes("--list")) {
+            console.log(listText());
+            return;
+        }
+        const out = argValue(argv, "--out") ?? "proactive-gate.policy.json";
+        const presetName = argValue(argv, "--preset");
+        const frameworkName = argValue(argv, "--framework");
+        const { policy, message } = plan({
+            ...(presetName === undefined ? {} : { preset: presetName }),
+            ...(frameworkName === undefined ? {} : { framework: frameworkName }),
+            out,
+        });
+        if (!argv.includes("--force") && existsSync(out)) {
+            console.error(`${out} already exists; pass --force to overwrite it`);
+            process.exit(1);
+        }
+        await writeFile(out, policy);
+        console.log(message);
+        return;
+    }
+    if (command === "hook") {
+        const gate = await loadPolicy(argValue(argv, "--policy"));
+        const event = JSON.parse((await readStdin()) || "{}");
+        const output = await hookDecision(event, gate, argValue(argv, "--tool") ?? "send_message");
+        if (output)
+            console.log(output);
+        return;
+    }
+    if (command !== "replay") {
+        console.error(HELP);
+        process.exit(2);
+    }
+    const fixtures = argValue(argv, "--fixtures");
+    if (fixtures) {
+        process.exit(await runFixtures(fixtures, argValue(argv, "--skip")));
+    }
+    if (!file || file.startsWith("--")) {
         console.error(HELP);
         process.exit(2);
     }
-    const policyIndex = argv.indexOf("--policy");
-    const policy = policyIndex >= 0 ? argv[policyIndex + 1] : undefined;
-    const gate = await loadPolicy(policy);
+    const gate = await loadPolicy(argValue(argv, "--policy"));
     const text = await readFile(file, "utf8");
     const decisions = await replay(text.split("\n"), gate, argv.includes("--commit"));
     if (argv.includes("--json")) {

package/dist/src/conformance.d.ts

@@ -0,0 +1,42 @@
+import type { Candidate, Policy, UserState } from "./types.js";
+export interface FixtureExpect {
+    allowed: boolean;
+    rejectedBy?: string;
+    deferredBy?: string;
+    retryAt?: string;
+    surfaces?: string[];
+    deliverAt?: string;
+    trace: string[];
+    shadowed?: string[];
+    nearLimit?: Array<{
+        check: string;
+        used: number;
+        limit: number;
+    }>;
+    reason_pattern?: string;
+    commit?: boolean;
+    store_after?: Record<string, string>;
+}
+export interface FixtureTest {
+    description: string;
+    input: {
+        user: UserState;
+        candidate: Candidate;
+        now: string;
+    };
+    commit?: boolean;
+    expect: FixtureExpect;
+}
+export interface Fixture {
+    spec_version: string;
+    since: string;
+    name: string;
+    description: string;
+    policy: Policy;
+    store_seed?: Record<string, string>;
+    tests: FixtureTest[];
+}
+export declare function loadFixtures(dir: string): Promise<Fixture[]>;
+export declare function readSkips(file: string): Promise<Map<string, string>>;
+/** Runs one fixture and returns the list of mismatches, empty when it conforms. */
+export declare function runFixture(fixture: Fixture): Promise<string[]>;

package/dist/src/conformance.js

@@ -0,0 +1,83 @@
+/**
+ * Runs the language-neutral fixtures under spec/fixtures against a gate. The
+ * TypeScript test suite and `proactive-gate replay --fixtures` both use it.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGate } from "./gate.js";
+import { MemoryStore } from "./stores.js";
+export async function loadFixtures(dir) {
+    const files = [];
+    const walk = async (d) => {
+        for (const entry of await readdir(d, { withFileTypes: true })) {
+            const path = join(d, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (entry.name.endsWith(".json"))
+                files.push(path);
+        }
+    };
+    await walk(dir);
+    files.sort();
+    return Promise.all(files.map(async (f) => JSON.parse(await readFile(f, "utf8"))));
+}
+export async function readSkips(file) {
+    const skips = new Map();
+    let text = "";
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        return skips;
+    }
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const [name, ...reason] = trimmed.split("#");
+        skips.set(name.trim(), reason.join("#").trim());
+    }
+    return skips;
+}
+const iso = (d) => (d ? d.toISOString() : undefined);
+/** Runs one fixture and returns the list of mismatches, empty when it conforms. */
+export async function runFixture(fixture) {
+    const failures = [];
+    const store = new MemoryStore();
+    const prefix = fixture.policy.keyPrefix ?? "pg:";
+    for (const [key, value] of Object.entries(fixture.store_seed ?? {}))
+        await store.set(prefix + key, value);
+    const gate = createGate({ policy: fixture.policy, store });
+    for (const [i, t] of fixture.tests.entries()) {
+        const at = `${fixture.name} [${i}] ${t.description}`;
+        const input = { user: t.input.user, candidate: t.input.candidate, now: new Date(t.input.now) };
+        const decision = await gate.evaluate(input);
+        const e = t.expect;
+        const check = (field, actual, expected) => {
+            if (JSON.stringify(actual) !== JSON.stringify(expected))
+                failures.push(`${at}: ${field} expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+        };
+        check("allowed", decision.allowed, e.allowed);
+        check("trace", decision.trace.map((x) => x.id), e.trace);
+        check("rejectedBy", decision.rejectedBy, e.rejectedBy);
+        check("deferredBy", decision.deferredBy, e.deferredBy);
+        check("retryAt", iso(decision.retryAt), e.retryAt);
+        if (e.surfaces)
+            check("surfaces", decision.surfaces, e.surfaces);
+        check("deliverAt", iso(decision.deliverAt), e.deliverAt);
+        if (e.shadowed)
+            check("shadowed", decision.shadowed, e.shadowed);
+        if (e.nearLimit)
+            check("nearLimit", decision.nearLimit, e.nearLimit);
+        if (e.reason_pattern && !(decision.reason && new RegExp(e.reason_pattern).test(decision.reason)))
+            failures.push(`${at}: reason ${JSON.stringify(decision.reason)} does not match /${e.reason_pattern}/`);
+        if (t.commit) {
+            const committed = await gate.commit(decision, input);
+            if (e.commit !== undefined)
+                check("commit", committed, e.commit);
+        }
+        for (const [key, value] of Object.entries(e.store_after ?? {}))
+            check(`store ${key}`, await store.get(prefix + key), value);
+    }
+    return failures;
+}

package/dist/src/gate.d.ts

@@ -1,11 +1,12 @@
-import type { Candidate, Check, Decision, EvaluateInput, GateOptions, OutcomeEvent, UserState } from "./types.js";
+import type { Candidate, Check, Decision, EvaluateInput, GateHooks, GateOptions, OutcomeEvent, Policy, Store, UserState } from "./types.js";
 export interface Gate {
     /** Run every check in order. Never throws for a check failure; see the trace. */
     evaluate(input: EvaluateInput): Promise<Decision>;
     /**
-     * Call right before you actually send. Atomically consumes one unit of the
-     * user's daily budget when a dailyBudget check is configured, and returns
-     * false if the budget was exhausted by a concurrent delivery in the meantime.
+     * Call right before you actually send. Consumes one unit of every budget-like
+     * check, in order, and returns false if a unit was taken by a concurrent
+     * delivery in the meantime. Idempotent on decision.id: a second call returns
+     * the first result without consuming again.
      */
     commit(decision: Decision, input: EvaluateInput): Promise<boolean>;
     /** Tell the gate what happened after delivery, so cooldowns can learn. */
@@ -17,4 +18,11 @@ export interface Gate {
     }>;
     readonly checks: readonly Check[];
 }
-export declare function createGate(options: GateOptions): Gate;
+/** createGate accepts explicit checks or a JSON policy (see spec/schema/policy.schema.json). */
+export interface PolicyGateOptions {
+    policy: Policy;
+    store?: Store;
+    onDecision?: (decision: Decision) => void;
+    hooks?: GateHooks;
+}
+export declare function createGate(options: GateOptions | PolicyGateOptions): Gate;

package/dist/src/gate.js

@@ -1,4 +1,5 @@
-import { budgetKey, dismissalKey, weeklyBudgetKey, DAY_SECONDS } from "./checks.js";
+import { budgetKey, dismissalKey, DAY_SECONDS } from "./checks.js";
+import { compilePolicy } from "./policy.js";
 import { MemoryStore } from "./stores.js";
 class PrefixedStore {
     inner;
@@ -12,32 +13,59 @@ class PrefixedStore {
     incr(key, ttl) { return this.inner.incr(this.prefix + key, ttl); }
     del(key) { return this.inner.del(this.prefix + key); }
 }
+const COMMIT_TTL = 2 * DAY_SECONDS;
 export function createGate(options) {
-    const store = new PrefixedStore(options.store ?? new MemoryStore(), options.keyPrefix ?? "pg:");
-    const onStoreError = options.onStoreError ?? "open";
-    const checks = [...options.checks];
-    const budgetChecks = checks.filter((c) => c.id === "dailyBudget" || c.id === "weeklyBudget");
+    if ("policy" in options && "checks" in options)
+        throw new Error("createGate takes either checks or policy, not both");
+    const resolved = "policy" in options
+        ? { ...compilePolicy(options.policy), ...(options.store ? { store: options.store } : {}), ...(options.onDecision ? { onDecision: options.onDecision } : {}), ...(options.hooks ? { hooks: options.hooks } : {}) }
+        : options;
+    const store = new PrefixedStore(resolved.store ?? new MemoryStore(), resolved.keyPrefix ?? "pg:");
+    const onStoreError = resolved.onStoreError ?? "open";
+    const hooks = resolved.hooks ?? {};
+    const checks = [...resolved.checks];
+    let sequence = 0;
+    const consumers = checks.filter((c) => typeof c.consume === "function");
+    const callHook = async (name, ctx, check, ...rest) => {
+        const hook = hooks[name];
+        if (!hook)
+            return;
+        try {
+            await hook(...(ctx ? [ctx, check, ...rest] : rest));
+        }
+        catch (error) {
+            if (name !== "error" && ctx && check)
+                await callHook("error", ctx, check, error);
+        }
+    };
     const evaluate = async (input) => {
         const now = input.now ?? new Date();
         const priority = input.candidate.priority ?? "normal";
         const trace = [];
+        const shadowed = [];
+        const nearLimit = [];
         let surfaces = pickSurfaces(input.user, input.candidate);
         let deliverAt;
-        const finish = (partial) => {
+        const finish = async (partial) => {
             const decision = {
+                id: `${input.user.id}:${input.candidate.id}:${now.toISOString()}#${++sequence}`,
                 allowed: false,
                 userId: input.user.id,
                 candidateId: input.candidate.id,
                 surfaces: [],
+                shadowed,
+                nearLimit,
                 trace,
                 evaluatedAt: now,
                 ...partial,
             };
-            options.onDecision?.(decision);
+            resolved.onDecision?.(decision);
+            await callHook("finally", null, null, decision);
             return decision;
         };
         for (const check of checks) {
             const ctx = { user: input.user, candidate: input.candidate, now, priority, store, surfaces };
+            await callHook("before", ctx, check);
             const started = performance.now();
             let outcome;
             try {
@@ -45,6 +73,7 @@ export function createGate(options) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                await callHook("error", ctx, check, error);
                 if (onStoreError === "closed") {
                     trace.push({ id: check.id, outcome: "reject", reason: `check threw (${message}); failing closed`, ms: elapsed(started) });
                     return finish({ rejectedBy: check.id, reason: `check "${check.id}" failed and the gate fails closed: ${message}` });
@@ -52,15 +81,30 @@ export function createGate(options) {
                 trace.push({ id: check.id, outcome: "skip", reason: `check threw (${message}); failing open`, ms: elapsed(started) });
                 continue;
             }
-            if (check.nonRejecting && outcome.kind === "reject") {
-                // A non-rejecting check that tries to reject is a bug in the check, not a decision about the user.
-                trace.push({ id: check.id, outcome: "skip", reason: `non-rejecting check returned reject (${outcome.reason}); ignored`, ms: elapsed(started) });
+            const ms = elapsed(started);
+            await callHook("after", ctx, check, outcome, ms);
+            if (check.nonRejecting && (outcome.kind === "reject" || outcome.kind === "defer")) {
+                // A non-rejecting check that tries to stop evaluation is a bug in the check, not a decision about the user.
+                trace.push({ id: check.id, outcome: "skip", reason: `non-rejecting check returned ${outcome.kind} (${outcome.reason}); ignored`, ms });
                 continue;
             }
-            trace.push({ id: check.id, outcome: outcome.kind, ...(("reason" in outcome && outcome.reason) ? { reason: outcome.reason } : {}), ms: elapsed(started) });
-            if (outcome.kind === "reject") {
-                return finish({ rejectedBy: check.id, reason: outcome.reason });
+            const stops = outcome.kind === "reject" || outcome.kind === "defer";
+            const entry = { id: check.id, outcome: outcome.kind, ms };
+            if ("reason" in outcome && outcome.reason)
+                entry.reason = outcome.reason;
+            if (stops && check.shadow)
+                entry.shadow = true;
+            trace.push(entry);
+            if (outcome.kind === "pass" && outcome.nearLimit)
+                nearLimit.push({ check: check.id, ...outcome.nearLimit });
+            if (stops && check.shadow) {
+                shadowed.push(check.id);
+                continue;
             }
+            if (outcome.kind === "reject")
+                return finish({ rejectedBy: check.id, reason: outcome.reason });
+            if (outcome.kind === "defer")
+                return finish({ deferredBy: check.id, retryAt: outcome.retryAt, reason: outcome.reason });
             if (outcome.kind === "adjust") {
                 if (outcome.deliverAt)
                     deliverAt = outcome.deliverAt;
@@ -73,20 +117,25 @@ export function createGate(options) {
     const commit = async (decision, input) => {
         if (!decision.allowed)
             return false;
-        if (!budgetChecks.length)
+        if (!consumers.length)
             return true;
-        const now = input.now ?? new Date();
+        const now = input.now ?? decision.evaluatedAt;
+        const priority = input.candidate.priority ?? "normal";
+        const marker = `commit:${decision.id}`;
         try {
-            for (const check of budgetChecks) {
-                const key = check.id === "weeklyBudget"
-                    ? weeklyBudgetKey(input.user.id, now, input.user.timezone)
-                    : budgetKey(input.user.id, now, input.user.timezone);
-                const used = await store.incr(key, check.id === "weeklyBudget" ? 8 * DAY_SECONDS : 2 * DAY_SECONDS);
-                const limit = readLimit(check);
-                if (limit !== undefined && used > limit)
-                    return false;
+            const seen = await store.get(marker);
+            if (seen !== null)
+                return seen === "1";
+            let ok = true;
+            for (const check of consumers) {
+                const ctx = { user: input.user, candidate: input.candidate, now, priority, store, surfaces: decision.surfaces };
+                if (!(await check.consume(ctx))) {
+                    ok = false;
+                    break;
+                }
             }
-            return true;
+            await store.set(marker, ok ? "1" : "0", COMMIT_TTL);
+            return ok;
         }
         catch {
             return onStoreError === "open";
@@ -121,7 +170,3 @@ function pickSurfaces(user, candidate) {
     return wanted.filter((s) => allowed.has(s));
 }
 const elapsed = (started) => Math.round((performance.now() - started) * 1000) / 1000;
-/** dailyBudget() closes over its limit; expose it through a well-known property for commit(). */
-function readLimit(check) {
-    return typeof check.limit === "number" ? check.limit : undefined;
-}

package/dist/src/index.d.ts

@@ -1,8 +1,11 @@
 export { createGate } from "./gate.js";
-export type { Gate } from "./gate.js";
+export type { Gate, PolicyGateOptions } from "./gate.js";
+export { compilePolicy, KNOWN_CHECKS } from "./policy.js";
+export { presets } from "./presets.js";
+export type { Preset } from "./presets.js";
 export { MemoryStore, RedisStore, SqliteStore } from "./stores.js";
 export type { RedisLike } from "./stores.js";
 export * as checks from "./checks.js";
-export { defaultChecks, localClock, inWindow, budgetKey, weeklyBudgetKey, dismissalKey } from "./checks.js";
+export { defaultChecks, localClock, inWindow, budgetKey, weeklyBudgetKey, monthlyBudgetKey, dismissalKey } from "./checks.js";
 export { PRIORITY_RANK } from "./types.js";
-export type { Candidate, Check, CheckContext, CheckOutcome, Decision, EvaluateInput, GateOptions, OutcomeEvent, Priority, Store, Surface, TraceEntry, UserState, } from "./types.js";
+export type { Candidate, Check, CheckContext, CheckOutcome, Decision, EvaluateInput, GateHooks, GateOptions, OutcomeEvent, Policy, PolicyEntry, Priority, Store, Surface, TraceEntry, UserState, } from "./types.js";

package/dist/src/index.js

@@ -1,5 +1,7 @@
 export { createGate } from "./gate.js";
+export { compilePolicy, KNOWN_CHECKS } from "./policy.js";
+export { presets } from "./presets.js";
 export { MemoryStore, RedisStore, SqliteStore } from "./stores.js";
 export * as checks from "./checks.js";
-export { defaultChecks, localClock, inWindow, budgetKey, weeklyBudgetKey, dismissalKey } from "./checks.js";
+export { defaultChecks, localClock, inWindow, budgetKey, weeklyBudgetKey, monthlyBudgetKey, dismissalKey } from "./checks.js";
 export { PRIORITY_RANK } from "./types.js";

package/dist/src/init.d.ts

@@ -0,0 +1,16 @@
+export declare const FRAMEWORKS: readonly ["ai-sdk", "mastra", "langchain", "openai-agents", "none"];
+export type Framework = (typeof FRAMEWORKS)[number];
+/** The order LILA runs, as a policy document. A preset is appended when one is named. */
+export declare function buildPolicy(preset?: string): Record<string, unknown>;
+export declare function snippetFor(framework: Framework, file: string): string;
+export declare function presetLines(): string;
+export declare function listText(): string;
+/** Everything init writes and prints, as data, so the test does not need a filesystem. */
+export declare function plan(options: {
+    preset?: string;
+    framework?: Framework;
+    out: string;
+}): {
+    policy: string;
+    message: string;
+};