proactive-gate 0.1.2 → 0.2.0

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;
+};

package/dist/src/init.js

@@ -0,0 +1,115 @@
+/**
+ * `proactive-gate init` writes a policy you can read and edit, and prints the
+ * few lines that wire it into the framework you named. The goal is that the
+ * distance between "npm i" and a gate that actually runs is one command.
+ */
+import { presets } from "./presets.js";
+export const FRAMEWORKS = ["ai-sdk", "mastra", "langchain", "openai-agents", "none"];
+/** The order LILA runs, as a policy document. A preset is appended when one is named. */
+export function buildPolicy(preset) {
+    const checks = [
+        { id: "consent" },
+        { id: "enabled" },
+        { id: "mode", allow: ["normal"] },
+        { id: "snooze", defer: true },
+        { id: "mute" },
+        { id: "intensity" },
+        { id: "quietHours", priorityFloor: "critical" },
+        { id: "trustRamp", days: 7, minPriority: "high" },
+        { id: "dismissalCooldown", dismissals: 3, withinDays: 30, silenceDays: 7 },
+        { id: "dailyBudget", limit: 5, bypassPriority: "critical" },
+    ];
+    if (preset)
+        checks.splice(checks.length - 1, 0, { preset });
+    return { specVersion: "1.0.0", onStoreError: "open", checks };
+}
+const SNIPPETS = {
+    "ai-sdk": (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+import { gateToolApproval } from "proactive-gate/ai-sdk";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+const approve = gateToolApproval({ gate, toInput: (call) => call.input.gate });
+
+// Give the send tool needsApproval: true, then answer each request:
+const { approved, reason } = await approve(call);
+// addToolApprovalResponse({ id: call.approvalId, approved, reason })`,
+    mastra: (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+import { gateProcessor } from "proactive-gate/mastra";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+
+// In the agent definition:
+//   outputProcessors: [gateProcessor({ gate, toInput: ({ messages }) => ({ user, candidate }) })]
+// A rejection calls abort(reason) before the result reaches the user.`,
+    langchain: (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+import { gateMiddleware } from "proactive-gate/langchain";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+
+// createAgent({
+//   tools: [sendMessage],
+//   middleware: [gateMiddleware({ gate, tools: ["send_message"], toInput: (call) => call.args.gate })],
+// })
+// A rejection returns a tool message carrying the reason instead of running the tool.`,
+    "openai-agents": (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+import { gateToolInputGuardrail } from "proactive-gate/openai-agents";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+
+// tool({
+//   name: "send_message",
+//   inputGuardrails: [gateToolInputGuardrail({ gate, toInput: (input) => input.gate })],
+// })
+// A rejection trips the wire with the reason in outputInfo.`,
+    none: (file) => `import { readFile } from "node:fs/promises";
+import { createGate } from "proactive-gate";
+
+const gate = createGate({ policy: JSON.parse(await readFile("${file}", "utf8")) });
+
+const decision = await gate.evaluate({ user, candidate });
+if (decision.allowed && (await gate.commit(decision, { user, candidate }))) {
+  await send(candidate);
+} else {
+  log.info({ reason: decision.reason, rejectedBy: decision.rejectedBy }, "not sent");
+}`,
+};
+export function snippetFor(framework, file) {
+    return SNIPPETS[framework](file);
+}
+export function presetLines() {
+    return Object.entries(presets)
+        .map(([name, preset]) => `  ${name.padEnd(28)}${preset.sources[0] ?? ""}`)
+        .join("\n");
+}
+export function listText() {
+    return `presets (append one to the policy, or leave it out):\n${presetLines()}\n\nframeworks: ${FRAMEWORKS.join(", ")}`;
+}
+/** Everything init writes and prints, as data, so the test does not need a filesystem. */
+export function plan(options) {
+    if (options.preset && !presets[options.preset]) {
+        throw new Error(`unknown preset "${options.preset}"; known presets: ${Object.keys(presets).join(", ")}`);
+    }
+    const framework = options.framework ?? "none";
+    if (!FRAMEWORKS.includes(framework)) {
+        throw new Error(`unknown framework "${framework}"; known frameworks: ${FRAMEWORKS.join(", ")}`);
+    }
+    const preset = options.preset ? presets[options.preset] : undefined;
+    const lines = [
+        `wrote ${options.out}`,
+        "",
+        preset
+            ? `preset ${options.preset}: ${preset.note}\nsources:\n${preset.sources.map((s) => `  ${s}`).join("\n")}\n`
+            : "no preset: the ten checks above are the default order. `proactive-gate init --list` shows the platform and legal presets.\n",
+        `wire it in (${framework}):`,
+        "",
+        snippetFor(framework, options.out),
+        "",
+        `then replay a day against it before you ship:`,
+        `  npx proactive-gate replay day.jsonl --policy ${options.out} --commit`,
+    ];
+    return { policy: `${JSON.stringify(buildPolicy(options.preset), null, 2)}\n`, message: lines.join("\n") };
+}

package/dist/src/policy.d.ts

@@ -0,0 +1,8 @@
+import type { Check, GateOptions, Policy } from "./types.js";
+type Options = Record<string, unknown>;
+type Factory = (options: Options) => Check;
+/** Every check a JSON policy may name, with the options it reads. */
+export declare const KNOWN_CHECKS: Record<string, Factory>;
+/** Compile a JSON policy into gate options. Throws on unknown ids, unknown presets, or an unsupported specVersion. */
+export declare function compilePolicy(policy: Policy): GateOptions;
+export {};

package/dist/src/policy.js

@@ -0,0 +1,74 @@
+import * as checks from "./checks.js";
+import { presets } from "./presets.js";
+const num = (o, key) => (typeof o[key] === "number" ? o[key] : undefined);
+const str = (o, key) => (typeof o[key] === "string" ? o[key] : undefined);
+const bool = (o, key) => (typeof o[key] === "boolean" ? o[key] : undefined);
+const prio = (o, key) => str(o, key);
+const strs = (o, key) => (Array.isArray(o[key]) ? o[key] : undefined);
+const opt = (value, key) => (value === undefined ? {} : { [key]: value });
+const budgetOptions = (o) => ({ ...opt(num(o, "limit"), "limit"), ...opt(prio(o, "bypassPriority"), "bypassPriority"), ...opt(num(o, "nearLimit"), "nearLimit") });
+/** Every check a JSON policy may name, with the options it reads. */
+export const KNOWN_CHECKS = {
+    killSwitch: (o) => checks.killSwitch(() => bool(o, "on") === true),
+    consent: () => checks.consent(),
+    enabled: () => checks.enabled(),
+    mode: (o) => checks.mode({ allow: strs(o, "allow") ?? ["normal"] }),
+    snooze: (o) => checks.snooze({ ...opt(bool(o, "defer"), "defer") }),
+    mute: () => checks.mute(),
+    intensity: (o) => (o.floors ? checks.intensity(o.floors) : checks.intensity()),
+    quietHours: (o) => checks.quietHours({ ...opt(prio(o, "priorityFloor"), "priorityFloor") }),
+    trustRamp: (o) => checks.trustRamp({ ...opt(num(o, "days"), "days"), ...opt(prio(o, "minPriority"), "minPriority") }),
+    dismissalCooldown: (o) => checks.dismissalCooldown({ ...opt(num(o, "dismissals"), "dismissals"), ...opt(num(o, "withinDays"), "withinDays"), ...opt(num(o, "silenceDays"), "silenceDays") }),
+    adaptiveTiming: () => checks.adaptiveTiming(),
+    dailyBudget: (o) => checks.dailyBudget(budgetOptions(o)),
+    weeklyBudget: (o) => checks.weeklyBudget(budgetOptions(o)),
+    monthlyBudget: (o) => checks.monthlyBudget(budgetOptions(o)),
+    utilityFloor: (o) => checks.utilityFloor({ costFalseAlarm: num(o, "costFalseAlarm") ?? 1, costMissedHelp: num(o, "costMissedHelp") ?? 1 }),
+    boundedDeferral: (o) => checks.boundedDeferral({ ...opt(num(o, "lambda"), "lambda"), ...opt(num(o, "interruptCost"), "interruptCost"), ...opt(num(o, "staleness"), "staleness"), ...opt(num(o, "boundSeconds"), "boundSeconds") }),
+    allowedWindow: (o) => checks.allowedWindow({ start: str(o, "start") ?? "08:00", end: str(o, "end") ?? "21:00", timezone: str(o, "timezone") ?? "user", ...opt(prio(o, "priorityFloor"), "priorityFloor"), ...opt(str(o, "id"), "id") }),
+    requiresConsent: (o) => checks.requiresConsent({ name: str(o, "name") ?? "consent", ...(o.when ? { when: o.when } : {}), ...opt(str(o, "id"), "id") }),
+    rateLimit: (o) => checks.rateLimit({ limit: num(o, "limit") ?? 1, perSeconds: num(o, "perSeconds") ?? 1, ...opt(str(o, "keyBy"), "keyBy"), ...opt(str(o, "id"), "id") }),
+    recentInteraction: (o) => checks.recentInteraction({ withinHours: num(o, "withinHours") ?? 48 }),
+    windowBudget: (o) => checks.windowBudget({ limit: num(o, "limit") ?? 1, withinHours: num(o, "withinHours") ?? 48 }),
+};
+const SUPPORTED_MAJOR = 1;
+/** Compile a JSON policy into gate options. Throws on unknown ids, unknown presets, or an unsupported specVersion. */
+export function compilePolicy(policy) {
+    const major = Number(String(policy.specVersion).split(".")[0]);
+    if (!Number.isInteger(major) || major !== SUPPORTED_MAJOR) {
+        throw new Error(`policy specVersion ${policy.specVersion} is not supported; this package implements spec ${SUPPORTED_MAJOR}.x`);
+    }
+    if (!Array.isArray(policy.checks) || !policy.checks.length)
+        throw new Error("policy.checks must be a non-empty array");
+    const compiled = [];
+    for (const entry of policy.checks) {
+        const { shadow, ...rest } = entry;
+        let built;
+        if (typeof rest.preset === "string") {
+            const preset = presets[rest.preset];
+            if (!preset)
+                throw new Error(`unknown preset "${rest.preset}"; known presets: ${Object.keys(presets).join(", ")}`);
+            const { preset: _name, ...options } = rest;
+            built = preset(options);
+        }
+        else if (typeof rest.id === "string") {
+            const factory = KNOWN_CHECKS[rest.id];
+            if (!factory)
+                throw new Error(`unknown check "${rest.id}"; known checks: ${Object.keys(KNOWN_CHECKS).join(", ")}`);
+            const { id: _id, ...options } = rest;
+            built = [factory(options)];
+        }
+        else {
+            throw new Error("each policy entry needs an id or a preset");
+        }
+        if (shadow)
+            for (const c of built)
+                c.shadow = true;
+        compiled.push(...built);
+    }
+    return {
+        checks: compiled,
+        ...(policy.onStoreError ? { onStoreError: policy.onStoreError } : {}),
+        ...(policy.keyPrefix !== undefined ? { keyPrefix: policy.keyPrefix } : {}),
+    };
+}

package/dist/src/presets.d.ts

@@ -0,0 +1,9 @@
+import type { Check } from "./types.js";
+export interface Preset {
+    (options?: Record<string, unknown>): Check[];
+    /** Primary sources the numbers come from. */
+    sources: string[];
+    /** What the preset encodes and what it leaves out. */
+    note: string;
+}
+export declare const presets: Record<string, Preset>;

package/dist/src/presets.js

@@ -0,0 +1,45 @@
+/**
+ * Presets: the platform quotas and legal limits people ship against, as ordered
+ * check lists. Reviewable defaults, not legal advice. Every number sits next to
+ * its source; several official sources disagree with each other (the Kakao
+ * evening boundary is quoted as 20:00, 20:50 and 20:55), so read the note and
+ * decide for your own deployment.
+ */
+import * as c from "./checks.js";
+const define = (build, sources, note) => {
+    const preset = ((options = {}) => build(options));
+    preset.sources = sources;
+    preset.note = note;
+    return preset;
+};
+const LINE_PLANS = { communication: 200, light: 5000, standard: 30000 };
+export const presets = {
+    lineMessagingApi: define((o) => {
+        const plan = typeof o.plan === "string" ? o.plan : "communication";
+        const limit = LINE_PLANS[plan];
+        if (limit === undefined)
+            throw new Error(`lineMessagingApi: unknown plan "${plan}", known: ${Object.keys(LINE_PLANS).join(", ")}`);
+        return [c.consent(), c.monthlyBudget({ limit, nearLimit: 0.9 })];
+    }, ["https://developers.line.biz/en/docs/messaging-api/pricing/", "https://developers.line.biz/en/reference/messaging-api/"], "Monthly push messages per plan for Japan: communication 200, light 5,000, standard 30,000; replies are free and not counted. Multicast and broadcast request rates are not encoded."),
+    wechatSubscriptionMessage: define(() => [c.requiresConsent({ name: "subscription" }), c.windowBudget({ limit: 1, withinHours: 24 * 365 })], ["https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/subscribe-message-overview.html"], "One-time subscription: exactly one message per opt-in; set user.lastInboundAt to the opt-in instant. Long-term subscriptions for government, medical, transport, finance and education categories are not encoded."),
+    wechatCustomerService: define(() => [c.recentInteraction({ withinHours: 48 }), c.windowBudget({ limit: 5, withinHours: 48 })], ["https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/customer-message/send.html"], "Mini program customer-service messages: within 48 hours of the user's last message, at most 5 in that window."),
+    wechatTemplateMessage: define(() => [c.requiresConsent({ name: "templateTrigger" }), c.rateLimit({ limit: 3, perSeconds: 24 * 3600, keyBy: "user", id: "rate:template" })], ["https://developers.weixin.qq.com/doc/service/guide/product/template_message/Template_Message_Operation_Specifications.html"], "Template messages only after a user action (consents.templateTrigger) and no more than three repeated templates a day; marketing templates are not allowed at all."),
+    wecomAppMessage: define(() => [c.rateLimit({ limit: 30, perSeconds: 60, id: "rate:30/min" }), c.rateLimit({ limit: 1000, perSeconds: 3600, id: "rate:1000/h" })], ["https://developer.work.weixin.qq.com/document/path/96212"], "WeCom application messages per app per member: 30 a minute and 1,000 an hour; the platform drops the excess silently, this preset refuses it with a reason."),
+    kakaoAlimtalk: define(() => [c.consent()], ["https://kakaobusiness.gitbook.io/main/ad/infotalk"], "AlimTalk is informational and carries no time-of-day limit; consent is the only gate."),
+    kakaoBrandMessage: define(() => [c.requiresConsent({ name: "ad" }), c.allowedWindow({ start: "08:00", end: "20:50", timezone: "Asia/Seoul", id: "window:kakao" })], ["https://kakaobusiness.gitbook.io/main/ad/moment/messagead/channelmessage/new/send"], "Brand messages need advertising consent and go out 08:00 to 20:50 Korea time regardless of the recipient's location. Official sources also quote 20:00 and 20:55; 20:50 is the stricter documented value."),
+    krNetworkAct50: define(() => [c.requiresConsent({ name: "ad" }), c.requiresConsent({ name: "night", when: { start: "21:00", end: "08:00", timezone: "user" } })], ["https://www.law.go.kr", "https://developers.fingerpush.com/biz-message/console/ads-guide"], "Network Act article 50: prior consent for advertising, and a separate consent for 21:00 to 08:00 (email is exempt). The two-year re-confirmation is not encoded."),
+    jpAntiSpamLaw: define(() => [c.requiresConsent({ name: "optIn" })], ["https://www.soumu.go.jp/main_sosiki/cybersecurity/kokumin/basic/legal/08/"], "Opt-in since 2008 with sender identity and an opt-out route. There is no time-of-day rule in the law; a Japanese quiet-hours window would be etiquette, so none is encoded."),
+    cnMinorMode: define(() => {
+        const window = c.allowedWindow({ start: "06:00", end: "22:00", timezone: "Asia/Shanghai", id: "window:minor" });
+        const budget = c.dailyBudget({ limit: 1 });
+        const adult = () => ({ kind: "pass", reason: "not a minor" });
+        return [
+            { id: window.id, run: (ctx) => (ctx.user.minor ? window.run(ctx) : adult(ctx)) },
+            { id: budget.id, limit: budget.limit, run: (ctx) => (ctx.user.minor ? budget.run(ctx) : adult(ctx)), consume: (ctx) => (ctx.user.minor ? budget.consume(ctx) : Promise.resolve(true)) },
+        ];
+    }, ["https://www.cac.gov.cn/2024-11/15/c_1733364304749288.htm", "https://www.cac.gov.cn/2022-01/04/c_1642894606364259.htm"], "Minor mode: no service 22:00 to 06:00 China time and a daily budget of one when user.minor is true; adults pass both checks. Per-age daily durations are not encoded."),
+    usTcpa: define(() => [c.allowedWindow({ start: "08:00", end: "21:00", timezone: "user", id: "window:tcpa" })], ["https://www.law.cornell.edu/cfr/text/47/64.1200"], "47 CFR 64.1200: no solicitation before 8 a.m. or after 9 p.m. at the called party's local time."),
+    euEprivacy: define(() => [{ ...c.requiresConsent({ name: "marketing" }), run: (ctx) => (ctx.user.existingCustomer ? { kind: "pass", reason: "existing customer, soft opt-in" } : c.requiresConsent({ name: "marketing" }).run(ctx)) }], ["https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32002L0058"], "Directive 2002/58/EC article 13: prior consent for direct marketing, with the soft opt-in for existing customers (user.existingCustomer)."),
+    telegramBot: define(() => [c.rateLimit({ limit: 1, perSeconds: 1, keyBy: "channel", id: "rate:1/s" }), c.rateLimit({ limit: 20, perSeconds: 60, keyBy: "channel", id: "rate:20/min" })], ["https://core.telegram.org/bots/faq"], "One message a second per chat and twenty a minute per group, keyed by candidate.channel. The broadcast rate of roughly thirty a second is not encoded."),
+    slackApp: define(() => [c.rateLimit({ limit: 1, perSeconds: 1, keyBy: "channel", id: "rate:1/s" })], ["https://docs.slack.dev/apis/web-api/rate-limits/"], "chat.postMessage: one message a second per channel, keyed by candidate.channel."),
+};

package/dist/src/stores.js

@@ -1,5 +1,3 @@
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
 /** In-process store. Correct for one instance, wrong the moment you scale out. */
 export class MemoryStore {
     clock;
@@ -71,13 +69,12 @@ export class SqliteStore {
     database;
     clock;
     constructor(path, clock = () => Date.now()) {
-        let DatabaseSync;
-        try {
-            ({ DatabaseSync } = require("node:sqlite"));
-        }
-        catch {
+        // Resolved lazily so the module also loads where node:sqlite does not exist (older Node, a browser bundle).
+        const loader = globalThis.process?.getBuiltinModule;
+        const mod = loader ? loader("node:sqlite") : undefined;
+        const DatabaseSync = mod?.DatabaseSync;
+        if (!DatabaseSync)
             throw new Error("SqliteStore requires Node.js 22.5 or newer.");
-        }
         this.database = new DatabaseSync(path);
         this.clock = clock;
         this.database.exec("CREATE TABLE IF NOT EXISTS proactive_gate_store (key TEXT PRIMARY KEY NOT NULL, value TEXT NOT NULL, expires_at INTEGER)");