proactive-gate 0.2.5 → 0.3.1

package/README.md

@@ -4,10 +4,8 @@ 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">
   <a href="https://doi.org/10.5281/zenodo.22393512"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22393512-111111?style=flat-square" alt="DOI"></a>
 </p>
@@ -49,6 +47,13 @@ preset you named, and prints the preset's own source next to the few lines that
 the gate into that framework. `npx proactive-gate init --list` shows the fourteen
 platform and legal presets and the four frameworks.
 
+If you would rather see the argument than read it: `npm run bench:compare` replays a
+committed day through this gate and through five hand-written `if` statements, and prints
+the six places they disagree: a critical alert the cap should have let through, a two-day-old
+account, a snooze, a run of dismissals, and a local day boundary that silences one user and
+pays another twice. The output, and why none of the six is a matter of taste, is in
+[Compared with hand-rolled checks](#compared-with-hand-rolled-checks-and-feature-flags).
+
 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),
@@ -433,8 +438,29 @@ Set `windowSeconds` from your own transport's retry horizon.
 `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. It was contributed by
-[@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) in [#3](https://github.com/Bubblegunn/proactive-gate/pull/3). `SqliteStore` requires Node.js 22.5 or newer; the SQLite module
+[@Aaqibhafeezkhan](https://github.com/Aaqibhafeezkhan) in [#3](https://github.com/Bubblegunn/proactive-gate/pull/3). `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.
+Expired rows are removed when a read touches them, and every `set` or `incr` first removes the
+rows that have already expired, so a key nobody reads again still disappears: a year of daily
+budget keys leaves the live rows in the table rather than one dead row per day. The write-time sweep and its partial index were contributed by
+[@LouisDeconinck](https://github.com/LouisDeconinck) in [#27](https://github.com/Bubblegunn/proactive-gate/pull/27).
+
+**Writing your own store?** `proactive-gate/store-contract` exports the same suite these three are
+held to, so you can prove yours behaves rather than hope:
+
+```ts
+import { storeContract } from "proactive-gate/store-contract";
+storeContract("PostgresStore", (clock) => new PostgresStore({ clock }));
+```
+
+It checks `get`, `set` and `del`, `incr` from an absent key, concurrent `incr` atomicity, the
+expiry boundary, and that a TTL given to `set` and one given to `incr` agree, then replays a
+seeded random operation sequence against `MemoryStore`. A store whose backend owns the clock
+passes `expiry: "skip"` and those cases are reported as skipped rather than quietly dropped. It
+was contributed by [@Aaqibhafeezkhan](https://github.com/Aaqibhafeezkhan) in
+[#24](https://github.com/Bubblegunn/proactive-gate/pull/24), and lives on its own subpath so
+importing the package never pulls `node:test` into your bundle. See
+[docs/store-contract.md](docs/store-contract.md).
 
 ## Fail open, on purpose
 
@@ -546,6 +572,15 @@ candidates with the clock taken from each line, and `node examples/ai-sdk/run.mj
 day of tool-approval requests, one of which is a critical alert that a legal window (the TCPA
 preset) still refuses. Both are part of `npm run examples` and of the test suite.
 
+The other four, the `.ts` files, are illustrations rather than fixtures: they import
+`@langchain/langgraph`, `@mastra/core` and the AI SDK, none of which is a dependency here, so
+they are neither compiled nor executed and this README does not claim they are. What *is*
+checked is the half we control: `test/example-imports.test.mjs` asserts that every symbol they
+import from `proactive-gate` still exists, as a value or as a type, so renaming an export
+cannot leave a published snippet quietly telling readers to import something that is gone. It
+cannot tell you a framework changed its own API, and installing four agent frameworks to
+type-check four snippets is a worse trade than saying which files are executed.
+
 ## Python
 
 ```
@@ -720,11 +755,14 @@ trace, and adds the part they leave out: the budget consumed at send time.
 ## Thanks
 
 Two people sent pull requests on the day this was published, neither of whom I had spoken to
-before. [@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) wrote `SqliteStore`
+before. [@Aaqibhafeezkhan](https://github.com/Aaqibhafeezkhan) wrote `SqliteStore`
 ([#3](https://github.com/Bubblegunn/proactive-gate/pull/3)) and
 [@edwardsong08](https://github.com/edwardsong08) wrote the weekly budget
 ([#9](https://github.com/Bubblegunn/proactive-gate/pull/9)). Both shipped in 0.1.2 and are in
-every release since, including the one you install today.
+every release since, including the one you install today. @Aaqibhafeezkhan came back for a
+second one and wrote the store contract suite in [#24](https://github.com/Bubblegunn/proactive-gate/pull/24).
+
+A third person arrived from the other direction. [@LouisDeconinck](https://github.com/LouisDeconinck) took [#26](https://github.com/Bubblegunn/proactive-gate/issues/26), an issue this project filed against itself to admit that expired rows were never cleaned up, and twelve minutes later sent the fix in both languages with the test that would have caught the original bug ([#27](https://github.com/Bubblegunn/proactive-gate/pull/27), in 0.3.1).
 
 ## Cite this
 

package/README.tr.md

@@ -37,6 +37,14 @@ Sıfır bağımlılık. TypeScript. Node 20 ya da üstü. Framework'ten bağıms
 [bubblegunn.github.io/proactive-gate](https://bubblegunn.github.io/proactive-gate/). Python:
 [`python/`](python/README.md).
 
+Okumak yerine görmeyi tercih ederseniz: `npm run bench:compare`, kayıtlı bir günü hem bu kapıdan
+hem de elle yazılmış beş `if` ifadesinden geçirir ve ayrıştıkları altı yeri yazdırır: kotanın
+geçirmesi gereken kritik bir uyarı, iki günlük bir hesap, bir erteleme, arka arkaya gelen
+reddedişler, ve bir kullanıcıyı susturup bir diğerine iki kat mesaj veren yerel gün sınırı. Altısının da
+neden zevk meselesi olmadığı, bu dosyanın kısaltılmış olması nedeniyle yalnızca İngilizce
+README'de anlatılıyor: [Compared with hand-rolled
+checks](README.md#compared-with-hand-rolled-checks-and-feature-flags).
+
 ## Bir karar neye benzer
 
 ```ts
@@ -330,6 +338,16 @@ yazmadığı bir sayıyı kodlardı; o yüzden yok.
 Adaptörler framework paketine değil, çağrının biçimine göre tiplenmiştir; başka bir şey
 kurmak gerekmez. Her biri kapının gerekçesiyle reddeder ve onayda bütçeyi tüketir.
 
+Örneklerden ikisi framework kurulu olmadan ve ağ olmadan çalışır: `node examples/mastra/run.mjs`
+ve `node examples/ai-sdk/run.mjs`. İkisi de `npm run examples` ve test paketinin parçası.
+Diğer dört `.ts` dosyası ise fikstür değil, örnekleme: `@langchain/langgraph`, `@mastra/core` ve
+AI SDK'yı içe aktarıyorlar, hiçbiri buranın bağımlılığı değil, dolayısıyla ne derleniyor ne
+çalıştırılıyorlar ve bu README onların çalıştığını iddia etmiyor. Denetlenen şey, bizim
+denetleyebildiğimiz yarısı: `test/example-imports.test.mjs`, bu dosyaların `proactive-gate`'ten içe
+aktardığı her sembolün değer ya da tip olarak hâlâ var olduğunu doğrular, böylece bir export'un adı
+değiştiğinde yayımlanmış bir örnek okuyucuya artık var olmayan bir şeyi içe aktarmasını söylemeye
+sessizce devam edemez.
+
 ## Python
 
 ```
@@ -337,8 +355,10 @@ pip install proactive-gate
 ```
 
 Yayınlanmamış bir durumu denemek için depodan kurulur: `pip install "proactive-gate @
-git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`. Yayınlanan sürüm yerel bir
-derlemeden token ile yüklendi; npm paketinin aksine derleme kanıtı taşımıyor.
+git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`. Python paketi npm paketiyle
+aynı workflow tarafından yayımlanıyor, dolayısıyla her dosyayı hangi deponun ve hangi workflow'un
+ürettiğini adlandıran PyPI yayın attestation'ları taşıyor. 0.2.2 öncesi sürümler yerel bir
+derlemeden token ile yüklendi ve hiçbir kanıt taşımıyor.
 
 `python/` sapan bir port değil, bir kardeştir: `spec/fixtures` altındaki her senaryoyu senkron
 `Gate` ve `AsyncGate` (Redis, `redis.asyncio` üzerinden) ile geçer; mypy strict, CI'da Python

package/dist/src/store-contract.d.ts

@@ -0,0 +1,11 @@
+import type { Store } from "./types.js";
+export interface StoreContractHandle {
+    store: Store;
+    teardown?: () => void | Promise<void>;
+}
+export type StoreContractFactory = (clock?: () => number) => Store | StoreContractHandle | Promise<Store | StoreContractHandle>;
+export interface StoreContractOptions {
+    expiry?: "injected" | "skip";
+    skip?: string;
+}
+export declare function storeContract(name: string, factory: StoreContractFactory, options?: StoreContractOptions): void;

package/dist/src/store-contract.js

@@ -0,0 +1,118 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { MemoryStore } from "./stores.js";
+function asHandle(value) {
+    return "store" in value ? value : { store: value };
+}
+export function storeContract(name, factory, options = {}) {
+    const expiry = options.expiry ?? "injected";
+    const skip = options.skip;
+    const testOptions = skip ? { skip } : {};
+    const expiryOptions = expiry === "skip" ? { skip: "expiry cases skipped: this store does not accept an injected clock" } : testOptions;
+    const withStore = async (clock, run) => {
+        const handle = asHandle(await factory(clock));
+        try {
+            return await run(handle.store);
+        }
+        finally {
+            await handle.teardown?.();
+        }
+    };
+    test(`${name}: get, set and del`, testOptions, async () => {
+        await withStore(undefined, async (store) => {
+            assert.equal(await store.get("missing"), null);
+            await store.set("key", "value");
+            assert.equal(await store.get("key"), "value");
+            await store.del("key");
+            assert.equal(await store.get("key"), null);
+        });
+    });
+    test(`${name}: incr from absent starts at one`, testOptions, async () => {
+        await withStore(undefined, async (store) => {
+            assert.equal(await store.incr("counter"), 1);
+            assert.equal(await store.incr("counter"), 2);
+        });
+    });
+    test(`${name}: incr is atomic`, testOptions, async () => {
+        await withStore(undefined, async (store) => {
+            const results = await Promise.all(Array.from({ length: 100 }, () => store.incr("counter")));
+            assert.deepEqual([...results].sort((a, b) => a - b), Array.from({ length: 100 }, (_, i) => i + 1));
+            assert.equal(await store.get("counter"), "100");
+        });
+    });
+    test(`${name}: set and incr TTLs expire at the same boundary`, expiryOptions, async () => {
+        let now = 0;
+        const clock = () => now;
+        await withStore(clock, async (store) => {
+            await store.set("set", "value", 2);
+            await store.incr("incr", 2);
+            now = 1999;
+            assert.equal(await store.get("set"), "value");
+            assert.equal(await store.get("incr"), "1");
+            now = 2000;
+            assert.equal(await store.get("set"), null);
+            assert.equal(await store.get("incr"), null);
+        });
+    });
+    test(`${name}: expiry is inclusive at the boundary`, expiryOptions, async () => {
+        let now = 1000;
+        const clock = () => now;
+        await withStore(clock, async (store) => {
+            await store.set("key", "value", 1);
+            assert.equal(await store.get("key"), "value");
+            now = 1999;
+            assert.equal(await store.get("key"), "value");
+            now = 2000;
+            assert.equal(await store.get("key"), null);
+        });
+    });
+    test(`${name}: random operations match MemoryStore`, testOptions, async () => {
+        for (let seed = 1; seed <= 40; seed++) {
+            let now = 0;
+            const clock = () => now;
+            await withStore(expiry === "injected" ? clock : undefined, async (store) => {
+                const reference = new MemoryStore(clock);
+                const keys = ["a", "b", "c"];
+                let state = 0x6d2b79f5 ^ seed;
+                const random = () => {
+                    state = (Math.imul(state ^ (state >>> 16), 2246822507) + 3266489909) >>> 0;
+                    return state / 4294967296;
+                };
+                try {
+                    for (let step = 0; step < 40; step++) {
+                        const key = keys[Math.floor(random() * keys.length)];
+                        const ttl = expiry === "injected" && random() > 0.5 ? 1 + Math.floor(random() * 3) : undefined;
+                        const op = Math.floor(random() * 5);
+                        if (op === 0) {
+                            const value = String(Math.floor(random() * 100));
+                            await reference.set(key, value, ttl);
+                            await store.set(key, value, ttl);
+                        }
+                        else if (op === 1) {
+                            assert.equal(await store.incr(key, ttl), await reference.incr(key, ttl), `seed ${seed} step ${step}: incr disagreed`);
+                        }
+                        else if (op === 2) {
+                            await reference.del(key);
+                            await store.del(key);
+                        }
+                        else if (op === 3) {
+                            if (expiry === "injected")
+                                now += Math.floor(random() * 3000);
+                        }
+                        else {
+                            assert.equal(await store.get(key), await reference.get(key), `seed ${seed} step ${step}: get disagreed on ${key}`);
+                        }
+                    }
+                    for (const key of keys) {
+                        assert.equal(await store.get(key), await reference.get(key), `seed ${seed}: final state disagreed on ${key}`);
+                    }
+                }
+                finally {
+                    await reference.del("a");
+                    await reference.del("b");
+                    await reference.del("c");
+                }
+            });
+        }
+    });
+}

package/dist/src/stores.d.ts

@@ -40,10 +40,17 @@ export declare class SqliteStore implements Store {
     private readonly database;
     private readonly clock;
     constructor(path: string, clock?: () => number);
+    /**
+     * A read prunes only the key it touches; a write first clears every row that
+     * has already expired, so a key nobody reads again does not live forever.
+     */
+    private sweep;
     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>;
+    /** Test helper. */
+    size(): number;
     close(): void;
 }

package/dist/src/stores.js

@@ -78,6 +78,15 @@ export class SqliteStore {
         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)");
+        // The partial index keeps a sweep proportional to the dead rows instead of a table scan.
+        this.database.exec("CREATE INDEX IF NOT EXISTS proactive_gate_store_expires_at ON proactive_gate_store (expires_at) WHERE expires_at IS NOT NULL");
+    }
+    /**
+     * A read prunes only the key it touches; a write first clears every row that
+     * has already expired, so a key nobody reads again does not live forever.
+     */
+    sweep(now) {
+        this.database.prepare("DELETE FROM proactive_gate_store WHERE expires_at IS NOT NULL AND expires_at <= ?").run(now);
     }
     live(key) {
         const row = this.database.prepare("SELECT value, expires_at FROM proactive_gate_store WHERE key = ?").get(key);
@@ -93,7 +102,9 @@ export class SqliteStore {
         return this.live(key)?.value ?? null;
     }
     async set(key, value, ttlSeconds) {
-        const expiresAt = ttlSeconds ? this.clock() + ttlSeconds * 1000 : null;
+        const now = this.clock();
+        const expiresAt = ttlSeconds ? now + ttlSeconds * 1000 : null;
+        this.sweep(now);
         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);
@@ -101,6 +112,7 @@ export class SqliteStore {
     async incr(key, ttlSeconds) {
         const now = this.clock();
         const expiresAt = ttlSeconds ? now + ttlSeconds * 1000 : null;
+        this.sweep(now);
         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);
@@ -109,6 +121,11 @@ export class SqliteStore {
     async del(key) {
         this.database.prepare("DELETE FROM proactive_gate_store WHERE key = ?").run(key);
     }
+    /** Test helper. */
+    size() {
+        const row = this.database.prepare("SELECT COUNT(*) AS n FROM proactive_gate_store").get();
+        return row.n;
+    }
     close() {
         this.database.close();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "Decide whether a proactive AI agent may reach a user right now, and log why not. Ordered checks as code or JSON, a conformance spec, presets for platform and legal limits, adapters for AI SDK, Mastra, LangChain and OpenAI Agents, and a Python sibling.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -14,6 +14,10 @@
       "types": "./dist/src/presets.d.ts",
       "import": "./dist/src/presets.js"
     },
+    "./store-contract": {
+      "types": "./dist/src/store-contract.d.ts",
+      "import": "./dist/src/store-contract.js"
+    },
     "./ai-sdk": {
       "types": "./dist/src/adapters/ai-sdk.d.ts",
       "import": "./dist/src/adapters/ai-sdk.js"
@@ -44,7 +48,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node test/spec-lint.mjs && node --test dist/test/gate.test.js dist/test/conformance.test.js dist/test/presets.test.js dist/test/adapters.test.js dist/test/init.test.js dist/test/properties.test.js dist/test/dedupe.test.js test/release.test.mjs test/examples.test.mjs test/naive.test.mjs test/suite.test.mjs",
+    "test": "npm run build && node test/spec-lint.mjs && node --test dist/test/gate.test.js dist/test/conformance.test.js dist/test/presets.test.js dist/test/adapters.test.js dist/test/init.test.js dist/test/properties.test.js dist/test/dedupe.test.js test/release.test.mjs test/examples.test.mjs test/example-imports.test.mjs test/naive.test.mjs test/suite.test.mjs",
     "lint": "tsc -p tsconfig.json --noEmit",
     "spec-lint": "node test/spec-lint.mjs",
     "conformance": "npm run build && node dist/src/cli.js replay --fixtures spec/fixtures",
@@ -55,7 +59,8 @@
     "release-gate": "npm run build && node scripts/release-gate.mjs",
     "trace-svg": "npm run build && node scripts/trace-svg.mjs",
     "bench:compare": "npm run build && node bench/compare.mjs",
-    "conformance-table": "node scripts/conformance-table.mjs"
+    "conformance-table": "node scripts/conformance-table.mjs",
+    "og": "npm run build && node scripts/og-image.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -65,9 +70,9 @@
     "agents",
     "proactive",
     "notifications",
-    "rate-limit",
     "quiet-hours",
     "consent",
+    "rate-limit",
     "budget",
     "llm",
     "policy",