proactive-gate 0.2.5 → 0.3.0

package/README.md

@@ -436,6 +436,23 @@ 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
 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.
 
+**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 [@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) 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
 
 When a store-backed check throws (Redis is down), the default lets the candidate
@@ -724,7 +741,8 @@ before. [@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) wrote `
 ([#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. @aaqib-hafeez-khan-in came back for a
+second one and wrote the store contract suite in [#24](https://github.com/Bubblegunn/proactive-gate/pull/24).
 
 ## Cite this
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "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"
@@ -65,9 +69,9 @@
     "agents",
     "proactive",
     "notifications",
-    "rate-limit",
     "quiet-hours",
     "consent",
+    "rate-limit",
     "budget",
     "llm",
     "policy",