proactive-gate 0.1.1 → 0.1.2

package/README.md

@@ -2,6 +2,15 @@
 
 English | [Türkçe](README.tr.md)
 
+<p>
+  <img src="https://img.shields.io/npm/v/proactive-gate?style=flat-square&color=111111&label=npm" alt="npm">
+  <img src="https://img.shields.io/npm/dm/proactive-gate?style=flat-square&color=111111" alt="npm downloads">
+  <img src="https://img.shields.io/github/actions/workflow/status/Bubblegunn/proactive-gate/ci.yml?style=flat-square&color=111111&label=ci" alt="ci">
+  <img src="https://img.shields.io/bundlephobia/minzip/proactive-gate?style=flat-square&color=111111" alt="minzipped size">
+  <img src="https://img.shields.io/github/stars/Bubblegunn/proactive-gate?style=flat-square&color=111111" alt="stars">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT">
+</p>
+
 Decide whether a proactive AI agent may reach a user right now, and log why not.
 
 A proactive assistant has two halves. The generating half decides what is worth
@@ -31,8 +40,8 @@ if (decision.allowed && (await gate.commit(decision, { user, candidate }))) {
 Zero dependencies. TypeScript. Node 20 or newer. Framework-agnostic: the gate sits
 between "the model produced something" and "the user's phone buzzed", whichever
 model or framework produced it. Examples: [`examples/vercel-ai-sdk.ts`](examples/vercel-ai-sdk.ts),
-[`examples/mastra.ts`](examples/mastra.ts), and a replayable policy in
-[`examples/policy.js`](examples/policy.js).
+[`examples/mastra.ts`](examples/mastra.ts), [`examples/langgraph.ts`](examples/langgraph.ts), and a
+replayable policy in [`examples/policy.js`](examples/policy.js). API reference: [`docs/api`](docs/api/README.md).
 
 ## What a decision looks like
 
@@ -81,6 +90,12 @@ something returned false".
 | 11 | `adaptiveTiming({ nextGoodMoment, surfacesFor })` | never | non-rejecting: moves `deliverAt` or narrows surfaces; a check marked `nonRejecting` cannot reject even if it tries |
 | 12 | `dailyBudget({ limit, bypassPriority })` | the user's local-day counter is at the limit | `evaluate` reads, `commit` increments atomically and can still refuse |
 
+`weeklyBudget({ limit, bypassPriority })` is the same shape keyed on the user's local ISO
+week; `defaultChecks({ weeklyLimit })` places it just before the daily one. Budgets are
+consumed in check order at commit, so when a weekly check passes and the daily one then
+refuses, that weekly unit is spent without a delivery. It only happens when two commits
+race after a shared evaluate.
+
 Order is a design decision and it should be visible. Consent has to come before
 everything. Quiet hours have to come before the budget, or a rejected candidate
 consumes a delivery it never made. Reorder freely; the trace will show what you did.
@@ -140,6 +155,13 @@ if (decision.allowed && await gate.commit(decision, input)) {   // INCR, returns
 counter is keyed on the user's local day, so a budget resets at the user's midnight,
 not at UTC.
 
+## Stores
+
+`MemoryStore` keeps values in process memory and is useful for a single instance. `RedisStore`
+shares values across instances. `SqliteStore` persists values in a SQLite database without
+adding a package dependency. `SqliteStore` requires Node.js 22.5 or newer; the SQLite module
+is loaded only when the store is constructed so the package can still be used on Node.js 20. On Node 22 the module prints an ExperimentalWarning on first use; it is stable from Node 24.
+
 ## Fail open, on purpose
 
 When a store-backed check throws (Redis is down), the default lets the candidate
@@ -173,6 +195,50 @@ dailyBudget         1  daily budget of 5 used (5)
 per line for a notebook. Replay a week of real candidates against a proposed policy
 and you know its allow rate and its silence reasons before a single user does.
 
+## Compared with hand-rolled checks and feature flags
+
+Most products start with a few `if` statements next to the send call and grow from there.
+The difference is not the checks, which anyone can write, but four properties that are hard
+to keep once the checks are scattered:
+
+- The order is one list in one place, so "consent before everything" is a fact you can read
+  rather than a convention you hope each caller followed.
+- Every rejection names the check and the reason, so "why was the user not told" has an
+  answer in the log instead of "something returned false somewhere".
+- The budget is consumed by an atomic increment at send time, so two instances cannot both
+  send the sixth message; scattered checks read a counter and race.
+- A policy can be replayed over a day of real candidates before it ships, and a non-rejecting
+  check cannot reject even if a bug makes it try.
+
+A feature-flag system does a different job better: rolling a behaviour out to a percentage
+of users, per-tenant overrides, and an audit trail of who flipped what. Use flags to decide
+whether the gate runs at all, and the gate to decide whether this message reaches this
+person now.
+
+## Integrations
+
+| framework | example | where the gate sits |
+|---|---|---|
+| Vercel AI SDK | [`examples/vercel-ai-sdk.ts`](examples/vercel-ai-sdk.ts) | after `generateText`, before the push |
+| Mastra | [`examples/mastra.ts`](examples/mastra.ts) | after `agent.generate`, before the send |
+| LangGraph | [`examples/langgraph.ts`](examples/langgraph.ts) | inside the `notify` node, before the tool call |
+
+The pattern is the same everywhere: the model decides whether there is something to say,
+`gate.evaluate` decides whether it may be said now, and `gate.commit` runs right before the
+message leaves.
+
+## Performance
+
+`npm run bench` runs `gate.evaluate()` ten thousand times with the default twelve checks and
+`MemoryStore`. On 5 September 2026:
+
+```
+evaluate() x 10,000, twelve checks, MemoryStore: median 48.7 µs, p95 91.1 µs (v24.13.0, Apple M4 Max)
+```
+
+With `RedisStore` the two store-backed checks add one round trip each; the gate itself is
+not where the time goes.
+
 ## Learning from what happened
 
 ```ts

package/dist/src/checks.d.ts

@@ -72,10 +72,16 @@ export declare function dailyBudget(options?: {
     bypassPriority?: Priority;
 }): BudgetCheck;
 export declare const budgetKey: (userId: string, now: Date, timezone?: string) => string;
+export declare const weeklyBudgetKey: (userId: string, now: Date, timezone?: string) => string;
+export declare function weeklyBudget(options?: {
+    limit?: number;
+    bypassPriority?: Priority;
+}): BudgetCheck;
 /** The LILA order, as a starting point. Replace, reorder, or drop checks freely. */
 export declare function defaultChecks(options?: {
     killSwitch?: () => boolean | Promise<boolean>;
     modes?: string[];
     dailyLimit?: number;
+    weeklyLimit?: number;
     quietHoursFloor?: Priority;
 }): Check[];

package/dist/src/checks.js

@@ -211,6 +211,32 @@ export function dailyBudget(options = {}) {
     };
 }
 export const budgetKey = (userId, now, timezone) => `budget:${userId}:${timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10)}`;
+const isoWeekKey = (day) => {
+    const date = new Date(`${day}T00:00:00Z`);
+    const weekday = date.getUTCDay() || 7;
+    date.setUTCDate(date.getUTCDate() + 4 - weekday);
+    const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
+    const week = Math.ceil((((date.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
+    return `${date.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+};
+export const weeklyBudgetKey = (userId, now, timezone) => {
+    const day = timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10);
+    return `weeklyBudget:${userId}:${isoWeekKey(day)}`;
+};
+export function weeklyBudget(options = {}) {
+    const limit = options.limit ?? 20;
+    return {
+        id: "weeklyBudget",
+        limit,
+        async run({ user, now, store, priority }) {
+            if (options.bypassPriority && atLeast(priority, options.bypassPriority))
+                return pass;
+            const key = weeklyBudgetKey(user.id, now, user.timezone);
+            const used = Number((await store.get(key)) ?? 0);
+            return used < limit ? pass : reject(`weekly budget of ${limit} used (${used})`);
+        },
+    };
+}
 /** The LILA order, as a starting point. Replace, reorder, or drop checks freely. */
 export function defaultChecks(options = {}) {
     return [
@@ -225,6 +251,7 @@ export function defaultChecks(options = {}) {
         trustRamp(),
         dismissalCooldown(),
         adaptiveTiming(),
+        ...(options.weeklyLimit === undefined ? [] : [weeklyBudget({ limit: options.weeklyLimit })]),
         dailyBudget({ limit: options.dailyLimit ?? 5 }),
     ];
 }

package/dist/src/gate.js

@@ -1,4 +1,4 @@
-import { budgetKey, dismissalKey, DAY_SECONDS } from "./checks.js";
+import { budgetKey, dismissalKey, weeklyBudgetKey, DAY_SECONDS } from "./checks.js";
 import { MemoryStore } from "./stores.js";
 class PrefixedStore {
     inner;
@@ -16,7 +16,7 @@ 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 budgetCheck = checks.find((c) => c.id === "dailyBudget");
+    const budgetChecks = checks.filter((c) => c.id === "dailyBudget" || c.id === "weeklyBudget");
     const evaluate = async (input) => {
         const now = input.now ?? new Date();
         const priority = input.candidate.priority ?? "normal";
@@ -73,13 +73,20 @@ export function createGate(options) {
     const commit = async (decision, input) => {
         if (!decision.allowed)
             return false;
-        if (!budgetCheck)
+        if (!budgetChecks.length)
             return true;
         const now = input.now ?? new Date();
-        const limit = readLimit(budgetCheck);
         try {
-            const used = await store.incr(budgetKey(input.user.id, now, input.user.timezone), 2 * DAY_SECONDS);
-            return limit === undefined || used <= limit;
+            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;
+            }
+            return true;
         }
         catch {
             return onStoreError === "open";

package/dist/src/index.d.ts

@@ -1,8 +1,8 @@
 export { createGate } from "./gate.js";
 export type { Gate } from "./gate.js";
-export { MemoryStore, RedisStore } from "./stores.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, dismissalKey } from "./checks.js";
+export { defaultChecks, localClock, inWindow, budgetKey, weeklyBudgetKey, 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";

package/dist/src/index.js

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

package/dist/src/stores.d.ts

@@ -36,3 +36,14 @@ export declare class RedisStore implements Store {
     incr(key: string, ttlSeconds?: number): Promise<number>;
     del(key: string): Promise<void>;
 }
+export declare class SqliteStore implements Store {
+    private readonly database;
+    private readonly clock;
+    constructor(path: string, clock?: () => number);
+    private live;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    incr(key: string, ttlSeconds?: number): Promise<number>;
+    del(key: string): Promise<void>;
+    close(): void;
+}

package/dist/src/stores.js

@@ -1,3 +1,5 @@
+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;
@@ -65,3 +67,52 @@ export class RedisStore {
         await this.client.del(key);
     }
 }
+export class SqliteStore {
+    database;
+    clock;
+    constructor(path, clock = () => Date.now()) {
+        let DatabaseSync;
+        try {
+            ({ DatabaseSync } = require("node:sqlite"));
+        }
+        catch {
+            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)");
+    }
+    live(key) {
+        const row = this.database.prepare("SELECT value, expires_at FROM proactive_gate_store WHERE key = ?").get(key);
+        if (!row)
+            return undefined;
+        if (row.expires_at !== null && row.expires_at <= this.clock()) {
+            this.database.prepare("DELETE FROM proactive_gate_store WHERE key = ?").run(key);
+            return undefined;
+        }
+        return { value: row.value, expiresAt: row.expires_at };
+    }
+    async get(key) {
+        return this.live(key)?.value ?? null;
+    }
+    async set(key, value, ttlSeconds) {
+        const expiresAt = ttlSeconds ? this.clock() + ttlSeconds * 1000 : null;
+        this.database
+            .prepare("INSERT INTO proactive_gate_store (key, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at")
+            .run(key, value, expiresAt);
+    }
+    async incr(key, ttlSeconds) {
+        const now = this.clock();
+        const expiresAt = ttlSeconds ? now + ttlSeconds * 1000 : null;
+        const row = this.database
+            .prepare("INSERT INTO proactive_gate_store (key, value, expires_at) VALUES (?, '1', ?) ON CONFLICT(key) DO UPDATE SET value = CASE WHEN proactive_gate_store.expires_at IS NOT NULL AND proactive_gate_store.expires_at <= ? THEN '1' ELSE CAST(CAST(proactive_gate_store.value AS INTEGER) + 1 AS TEXT) END, expires_at = CASE WHEN proactive_gate_store.expires_at IS NOT NULL AND proactive_gate_store.expires_at <= ? THEN excluded.expires_at ELSE proactive_gate_store.expires_at END RETURNING value")
+            .get(key, expiresAt, now, now);
+        return Number(row.value);
+    }
+    async del(key) {
+        this.database.prepare("DELETE FROM proactive_gate_store WHERE key = ?").run(key);
+    }
+    close() {
+        this.database.close();
+    }
+}

package/dist/test/gate.test.js

@@ -1,6 +1,9 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { createGate, MemoryStore, defaultChecks, checks, localClock, inWindow } from "../src/index.js";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createGate, MemoryStore, SqliteStore, defaultChecks, checks, localClock, inWindow } from "../src/index.js";
 import { replay, summarize } from "../src/cli.js";
 const user = (overrides = {}) => ({
     id: "u1",
@@ -134,6 +137,53 @@ test("daily budget: evaluate reads, commit consumes atomically and refuses the s
     assert.equal((await gate.evaluate({ ...input, now: nextLocalDay })).allowed, true);
     assert.equal((await gate.inspect(user(), noon)).budgetUsed, 5);
 });
+test("weekly budget: resets on the user's local ISO week and commits atomically", async () => {
+    const store = new MemoryStore();
+    const gate = createGate({ store, checks: [checks.weeklyBudget({ limit: 2 })] });
+    const input = { user: user(), candidate: candidate(), now: new Date("2026-09-04T09:00:00Z") };
+    const first = await gate.evaluate(input);
+    const second = await gate.evaluate(input);
+    assert.equal(await gate.commit(first, input), true);
+    assert.equal(await gate.commit(second, input), true);
+    assert.equal((await gate.evaluate(input)).rejectedBy, "weeklyBudget");
+    const nextWeek = await gate.evaluate({ ...input, now: new Date("2026-09-07T09:00:00Z") });
+    assert.equal(nextWeek.allowed, true);
+});
+const sqliteAvailable = Number(process.versions.node.split(".")[0]) >= 22;
+test("sqlite store supports get, set, increment, delete and expiration", { skip: !sqliteAvailable }, async () => {
+    let now = 1_000_000;
+    const store = new SqliteStore(":memory:", () => now);
+    assert.equal(await store.get("missing"), null);
+    await store.set("key", "value");
+    assert.equal(await store.get("key"), "value");
+    assert.equal(await store.incr("counter"), 1);
+    assert.equal(await store.incr("counter", 10), 2);
+    assert.equal(await store.get("counter"), "2");
+    await store.set("temporary", "value", 5);
+    assert.equal(await store.get("temporary"), "value");
+    now += 5000;
+    assert.equal(await store.get("temporary"), null);
+    await store.del("key");
+    assert.equal(await store.get("key"), null);
+    store.close();
+});
+test("sqlite store preserves values across database connections", { skip: !sqliteAvailable }, async () => {
+    const directory = mkdtempSync(join(tmpdir(), "proactive-gate-"));
+    const path = join(directory, "store.sqlite");
+    try {
+        const first = new SqliteStore(path);
+        await first.set("key", "value");
+        assert.equal(await first.incr("counter"), 1);
+        first.close();
+        const second = new SqliteStore(path);
+        assert.equal(await second.get("key"), "value");
+        assert.equal(await second.get("counter"), "1");
+        second.close();
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
 test("adaptive timing never rejects; it defers and can narrow surfaces", async () => {
     const later = new Date("2026-09-04T15:00:00Z");
     const gate = createGate({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Decide whether a proactive AI agent may reach a user right now, and log why not. Ordered checks: kill switch, consent, quiet hours, trust ramp, dismissal cooldown, daily budget.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -23,7 +23,9 @@
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test dist/test/gate.test.js",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "examples": "npm run build && node dist/src/cli.js replay examples/day.jsonl --policy examples/policy.js --commit",
+    "bench": "npm run build && node bench/evaluate.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -47,7 +49,9 @@
   },
   "homepage": "https://github.com/Bubblegunn/proactive-gate#readme",
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "typescript": "^5.8.0"
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/node": "^26.4.1",
+    "publint": "^0.3.24",
+    "typescript": "^7.0.2"
   }
 }