proactive-gate 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,16 @@
 # proactive-gate
 
+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
@@ -28,7 +39,9 @@ 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.
+model or framework produced it. Examples: [`examples/vercel-ai-sdk.ts`](examples/vercel-ai-sdk.ts),
+[`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
 
@@ -54,6 +67,8 @@ model or framework produced it.
 }
 ```
 
+<p align="center"><img src="assets/trace.png" width="900" alt="A real decision trace: eight checks ran, quiet hours rejected, each with its reason and cost"></p>
+
 With one gate and a logged reason, "why was the user not told about this" has an
 answer. With checks scattered through a pipeline, the honest answer is "somewhere,
 something returned false".
@@ -75,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.
@@ -92,6 +113,31 @@ const gate = createGate({
 });
 ```
 
+### Writing your own check
+
+A check is an object with an `id` and a `run` function. It receives the user, the
+candidate, the clock, the resolved priority, the store and the surfaces still on the
+table, and returns `pass`, `reject` with a reason, `adjust`, or `skip`. It appears in the
+trace like every built-in one.
+
+```ts
+const weekendFloor = {
+  id: "weekendFloor",
+  run: ({ now, priority }) => {
+    const day = now.getUTCDay();
+    if ((day === 0 || day === 6) && priority !== "high" && priority !== "critical") {
+      return { kind: "reject", reason: "weekend: only high priority" };
+    }
+    return { kind: "pass" };
+  },
+};
+const gate = createGate({ checks: [checks.consent(), weekendFloor, checks.dailyBudget({ limit: 5 })] });
+```
+
+Mark a check `nonRejecting: true` when it may only move timing or narrow surfaces; the
+gate then ignores a reject from it and says so in the trace, so a bug in a timing model
+cannot silence a user.
+
 ## The budget is enforced at commit, not at evaluate
 
 Two instances can both evaluate a candidate for the same user, both see four of
@@ -109,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
@@ -142,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/README.tr.md

@@ -0,0 +1,216 @@
+# proactive-gate
+
+[English](README.md) | Türkçe
+
+Proaktif bir yapay zekâ ajanının kullanıcıya şu an ulaşıp ulaşamayacağına karar verir ve
+neden ulaşamadığını kaydeder.
+
+Proaktif bir asistanın iki yarısı vardır. Üreten yarı neyin söylenmeye değer olduğuna karar
+verir. Bastıran yarı ise onu şimdi mi, sonra mı, hiç mi söyleyeceğine karar verir. Proaktif
+yapay zekâ üzerine yazılan hemen her şey ilk yarı hakkındadır. Bu paket ikinci yarıdır: tek
+kapı, sıralı bir kontrol listesi ve her ret için bir gerekçe.
+
+```
+npm install proactive-gate
+```
+
+```ts
+import { createGate, defaultChecks, RedisStore } from "proactive-gate";
+
+const gate = createGate({
+  store: new RedisStore(redis),                  // MemoryStore() for one instance
+  checks: defaultChecks({ dailyLimit: 3, quietHoursFloor: "high" }),
+  onDecision: (d) => log.info("gate", d),        // every decision, allowed or not
+});
+
+const decision = await gate.evaluate({ user, candidate });
+if (decision.allowed && (await gate.commit(decision, { user, candidate }))) {
+  await send(decision.surfaces, candidate.payload);
+}
+```
+
+Sıfır bağımlılık. TypeScript. Node 20 ya da üstü. Framework'ten bağımsız: kapı, "model bir
+şey üretti" ile "kullanıcının telefonu titredi" arasında durur; hangi model ya da framework
+üretmiş olursa olsun. Örnekler: [`examples/vercel-ai-sdk.ts`](examples/vercel-ai-sdk.ts),
+[`examples/mastra.ts`](examples/mastra.ts) ve yeniden oynatılabilir bir politika olarak
+[`examples/policy.js`](examples/policy.js).
+
+## Bir karar neye benzer
+
+```ts
+{
+  allowed: false,
+  userId: "ayse",
+  candidateId: "a1",
+  rejectedBy: "quietHours",
+  reason: "quiet hours 22:00 to 08:00 Europe/Istanbul; priority normal is below the floor (high)",
+  surfaces: [],
+  trace: [
+    { id: "killSwitch", outcome: "pass", ms: 0.02 },
+    { id: "consent",    outcome: "pass", ms: 0.01 },
+    { id: "enabled",    outcome: "pass", ms: 0.01 },
+    { id: "mode",       outcome: "pass", ms: 0.01 },
+    { id: "snooze",     outcome: "pass", ms: 0.02 },
+    { id: "mute",       outcome: "pass", ms: 0.01 },
+    { id: "intensity",  outcome: "pass", ms: 0.02 },
+    { id: "quietHours", outcome: "reject", reason: "quiet hours 22:00 to 08:00 …", ms: 0.09 }
+  ],
+  evaluatedAt: 2026-09-04T03:00:00.000Z
+}
+```
+
+<p align="center"><img src="assets/trace.png" width="900" alt="Gerçek bir karar izi: sekiz kontrol çalıştı, sessiz saatler reddetti, her biri gerekçesi ve maliyetiyle"></p>
+
+Tek kapı ve kayıtlı bir gerekçe ile "kullanıcıya bu neden söylenmedi" sorusunun bir cevabı
+olur. Kontroller bir boru hattına dağılmışken dürüst cevap "bir yerde bir şey false döndü"
+olurdu.
+
+## Kontroller, varsayılanın çalıştırdığı sırayla
+
+| # | kontrol | ne zaman reddeder | not |
+|---|---|---|---|
+| 1 | `killSwitch(isOn)` | bayrağınız açıksa | üretim acil durdurma; her üreticiyi aynı anda susturur |
+| 2 | `consent()` | `user.consent` false ise | her şeyden önce gelir, yoksa hiç rıza vermemiş biri için tercih değerlendirmiş olursunuz |
+| 3 | `enabled()` | `user.proactiveEnabled === false` ise | profil başına anahtar |
+| 4 | `mode({ allow })` | `user.mode` listede değilse | örneğin yalnızca `"normal"`, asla `"focus"` |
+| 5 | `snooze()` | `user.snoozedUntil` gelecekteyse | genel duraklatma |
+| 6 | `mute()` | `candidate.type`, `user.mutedTypes` içindeyse | tür bazlı susturma |
+| 7 | `intensity()` | öncelik, kullanıcının yoğunluk tabanının altındaysa | low yalnızca high duyar, normal normal ve üstünü, high her şeyi |
+| 8 | `quietHours({ priorityFloor })` | kullanıcının yerel sessiz penceresi içindeyse | IANA saat dilimi, pencere gece yarısını geçebilir, taban ve üstünde atlanır |
+| 9 | `trustRamp({ days, minPriority })` | kullanıcı `days` günden yeniyse ve öncelik tabanın altındaysa | sistem, kullanıcı en az bağışlayıcıyken en az kalibredir |
+| 10 | `dismissalCooldown({ dismissals, withinDays, silenceDays })` | kullanıcı o türü pencere içinde `dismissals` kez reddettiyse | `gate.record(user, candidate, "dismissed")` ile beslenir; her yeni ret sessizliği yeniden başlatır |
+| 11 | `adaptiveTiming({ nextGoodMoment, surfacesFor })` | asla | reddetmez: `deliverAt` değerini taşır ya da yüzeyleri daraltır; `nonRejecting` işaretli bir kontrol istese de reddedemez |
+| 12 | `dailyBudget({ limit, bypassPriority })` | kullanıcının yerel gün sayacı sınırdaysa | `evaluate` okur, `commit` atomik artırır ve yine de reddedebilir |
+
+Sıra bir tasarım kararıdır ve görünür olmalıdır. Rıza her şeyden önce gelmelidir. Sessiz
+saatler bütçeden önce gelmelidir, yoksa reddedilen bir aday hiç yapmadığı bir teslimi
+tüketir. İstediğiniz gibi yeniden sıralayın; iz ne yaptığınızı gösterecektir.
+
+```ts
+import { createGate, checks } from "proactive-gate";
+
+const gate = createGate({
+  checks: [
+    checks.consent(),
+    checks.quietHours({ priorityFloor: "high" }),
+    checks.dailyBudget({ limit: 3, bypassPriority: "critical" }),
+    myOwnCheck, // { id, run(ctx) => pass | reject | adjust | skip }
+  ],
+});
+```
+
+### Kendi kontrolünüzü yazmak
+
+Bir kontrol, `id` ve `run` fonksiyonu olan bir nesnedir. Kullanıcıyı, adayı, saati, çözülmüş
+önceliği, depoyu ve hâlâ masada olan yüzeyleri alır; `pass`, gerekçeli `reject`, `adjust` ya
+da `skip` döndürür. İzde yerleşik kontroller gibi görünür.
+
+```ts
+const weekendFloor = {
+  id: "weekendFloor",
+  run: ({ now, priority }) => {
+    const day = now.getUTCDay();
+    if ((day === 0 || day === 6) && priority !== "high" && priority !== "critical") {
+      return { kind: "reject", reason: "weekend: only high priority" };
+    }
+    return { kind: "pass" };
+  },
+};
+const gate = createGate({ checks: [checks.consent(), weekendFloor, checks.dailyBudget({ limit: 5 })] });
+```
+
+Bir kontrol yalnızca zamanlamayı taşıyabiliyor ya da yüzeyleri daraltabiliyorsa
+`nonRejecting: true` işaretleyin; kapı ondan gelen bir reddi yok sayar ve bunu izde söyler,
+böylece bir zamanlama modelindeki hata bir kullanıcıyı susturamaz.
+
+## Bütçe evaluate'te değil, commit'te uygulanır
+
+İki örnek aynı kullanıcı için aynı adayı değerlendirebilir, ikisi de beşte dördün kullanıldığını
+görebilir ve ikisi de göndermeye karar verebilir. Bir sınırı yarış durumuna karşı güvenle
+uygulayabileceğiniz tek yer, göndermeden hemen önceki atomik artırmadır:
+
+```ts
+const decision = await gate.evaluate(input);        // reads the counter
+if (decision.allowed && await gate.commit(decision, input)) {   // INCR, returns false on the sixth
+  await send(...);
+}
+```
+
+`RedisStore`, `INCR` kullanır ve günün TTL'sini ilk artırmada ekler. Sayaç kullanıcının yerel
+gününe göre anahtarlanır, bu yüzden bütçe UTC'de değil kullanıcının gece yarısında sıfırlanır.
+
+## Bilerek açık başarısız olur
+
+Depoya bağlı bir kontrol hata fırlattığında (Redis düştü), varsayılan adayı geçirir ve ize
+`outcome: "skip", reason: "check threw (…); failing open"` yazar. Bir önbellek kesintisi, bütün
+amacı konuşmak olan bir ürünün her kullanıcısını susturmamalıdır. Ürününüz sessiz kalmayı
+tercih ediyorsa `onStoreError: "closed"` geçin; aynı hata, kontrolü adıyla anan bir ret olur.
+
+## Bir politikayı yayınlamadan önce bir günü yeniden oynatın
+
+CLI, `{ user, candidate, now }` satırlarından oluşan bir JSONL dosyası alır ve bir politikanın
+ne yapacağını raporlar. `--commit`, üretimde olduğu gibi bütçeyi sırayla tüketir.
+
+```
+npx proactive-gate replay examples/day.jsonl --commit
+```
+
+```
+17 candidates  ·  7 allowed (41.2%)  ·  10 rejected
+
+check        rejected  example
+---------------------------------------------------------------
+intensity           3  priority low is below the "normal" intensity floor (normal)
+consent             3  user has not consented to proactive behaviour
+mode                2  operating mode "focus" does not allow proactive messages
+quietHours          1  quiet hours 22:00 to 08:00 Europe/Istanbul; priority normal is below the floor (critical)
+dailyBudget         1  daily budget of 5 used (5)
+```
+
+`--policy examples/policy.js` kendi kapınızı yükler; `--json` bir not defteri için satır başına
+tam bir karar basar. Bir haftalık gerçek adayı önerilen bir politikaya karşı oynatın; izin oranını
+ve sessizlik nedenlerini tek bir kullanıcı öğrenmeden önce bilirsiniz.
+
+## Olandan öğrenmek
+
+```ts
+await gate.record(user, candidate, "dismissed");   // feeds dismissalCooldown
+await gate.record(user, candidate, "acted");       // recorded for you to extend
+await gate.inspect(user);                          // { budgetUsed, dismissals }
+```
+
+Sessizlik ölçülebilir olmalıdır, yoksa bahaneye dönüşür. Her kararı `onDecision` ile
+kaydedin; izin oranı, en sık ret nedenleri ve izin verilenlerin reddedilme oranı, kapının
+ayarlı olup olmadığını söyleyen üç sayıdır.
+
+## Bunu yapmaz
+
+- Neyin söylenmeye değer olduğuna karar vermez. O üreten yarıdır ve modelinize ve ürününüze
+  aittir.
+- Değeri dikkate karşı puanlamaz. `adaptiveTiming`, kullanıcının bir sonraki iyi anı için
+  kendi modelinize bir kancadır; paket böyle bir model içermez.
+- Ürünler arasında koordinasyon yapmaz. Üç ajan her biri üçlük bir bütçeye uyarsa kullanıcı
+  yine dokuz alır. Ajanlar arası katman ayrı bir problemdir.
+- Rıza hukukunun yerine geçmez. `consent()` sizin belirlediğiniz bir boolean'ı kontrol eder;
+  onu nasıl aldığınız size aittir.
+
+## Nereden geliyor
+
+Bu, Şubat 2026'dan beri tek başıma geliştirdiğim proaktif asistan
+[LILA](https://efe-genc-portfolio.vercel.app/projects/lila/)'nın teslim kapısıdır; çıkarılıp
+framework'ten bağımsız hâle getirildi. On iki kontrolün sırası, güven rampası, otuzda üç
+soğuması ve açık başarısız olan bütçe, üretimde verilmiş ve
+[The hardest part of a proactive assistant is knowing when not to speak](https://efe-genc-portfolio.vercel.app/writing/knowing-when-not-to-speak/)
+yazısında savunulmuş kararlardır. Tian Pan'ın
+[bildirim bütçesi](https://tianpan.co/blog/2026-05-13-background-agents-notification-budget-attention-economy)
+yazısı aynı davayı ürün tarafından savunur ve günde üç ile beş arası bir tavan önerir;
+`defaultChecks({ dailyLimit })` varsayılanı beştir.
+
+## Geliştirme
+
+```
+npm ci
+npm test        # tsc build, then node:test over dist/test
+```
+
+MIT.

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({
@@ -190,3 +240,22 @@ test("replay summarises a day of candidates and consumes the budget in order", a
     assert.match(text, /quietHours/);
     assert.match(text, /consent/);
 });
+test("a custom check is an ordinary object: it runs in order, reads the context, and shows in the trace", async () => {
+    const weekendsOnlyHigh = {
+        id: "weekendFloor",
+        run: ({ now, priority }) => {
+            const day = now.getUTCDay();
+            if ((day === 0 || day === 6) && priority !== "high" && priority !== "critical")
+                return { kind: "reject", reason: "weekend: only high priority" };
+            return { kind: "pass" };
+        },
+    };
+    const gate = createGate({ checks: [checks.consent(), weekendsOnlyHigh, checks.dailyBudget({ limit: 5 })] });
+    const saturday = new Date("2026-09-05T10:00:00Z");
+    const d = await gate.evaluate({ user: user(), candidate: candidate(), now: saturday });
+    assert.equal(d.rejectedBy, "weekendFloor");
+    assert.deepEqual(d.trace.map((t) => `${t.id}:${t.outcome}`), ["consent:pass", "weekendFloor:reject"]);
+    const monday = await gate.evaluate({ user: user(), candidate: candidate(), now: new Date("2026-09-07T10:00:00Z") });
+    assert.equal(monday.allowed, true);
+    assert.equal(monday.trace.length, 3);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.1.0",
+  "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"
   }
 }