proactive-gate 0.3.0 → 0.4.0

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),
@@ -247,6 +252,29 @@ a hook that throws is routed to `error` and never changes the decision. `example
 turns them into one span per check. Every decision has an `id`, and `commit` is idempotent on
 it: a retry after a timeout does not consume a second unit.
 
+## A rejection reason a product manager can read
+
+`decision.reason` is written for the engineer holding the trace. `explain(decision)` renders
+the same decision as sentences for the person who decides whether the assistant is too chatty:
+
+```ts
+import { explain } from "proactive-gate";
+
+explain(decision).summary;
+// "Held until 08:00 because the user's quiet hours run 22:00 to 08:00 Europe/Istanbul and
+//  normal priority is below the critical floor needed to override them."
+```
+
+It answers "why did this go out at 22:30" too: an allowed decision explains itself, and
+`explanation.checks` carries one sentence per check that ran, in order. The renderer is a
+pure function of the decision; it invents nothing, and a check whose reason matches nothing
+known is quoted verbatim rather than guessed. `language` is a parameter: English ships as
+`en`, and any other language is a `Partial<Sentences>` in `catalogs`, merged over English so
+a partial translation still renders. The Python sibling ships the same sentences, and CI
+compares both renderings of every fixture decision on each push. It was contributed by
+[@LouisDeconinck](https://github.com/LouisDeconinck) in
+[#28](https://github.com/Bubblegunn/proactive-gate/pull/28), in TypeScript and Python together.
+
 ## Optional checks, fed by your own model
 
 Both ship off. They read numbers the caller puts on the candidate.
@@ -433,8 +461,12 @@ 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:
@@ -448,7 +480,7 @@ It checks `get`, `set` and `del`, `incr` from an absent key, concurrent `incr` a
 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
+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).
@@ -563,6 +595,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
 
 ```
@@ -737,13 +778,15 @@ 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. @aaqib-hafeez-khan-in came back for a
+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). He then took [#23](https://github.com/Bubblegunn/proactive-gate/issues/23), the issue asking for a rejection reason a product manager could read, and wrote its sixty-seven sentence templates in both languages ([#28](https://github.com/Bubblegunn/proactive-gate/pull/28), in 0.4.0). That is the work in this library that is hardest to review and easiest to get wrong, because it lives in the wording rather than in the code.
+
 ## Cite this
 
 Every release is archived on Zenodo with a DOI, so a paper or a report can point at the

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
@@ -201,6 +209,31 @@ fırlatan bir kanca `error` kancasına yönlendirilir ve kararı asla değiştir
 `commit` bu id üzerinde tekrarlanabilir: zaman aşımından sonraki bir yeniden deneme ikinci
 bir birim tüketmez.
 
+## Bir ürün yöneticisinin okuyabileceği ret gerekçesi
+
+`decision.reason` izi elinde tutan mühendis için yazılmıştır. `explain(decision)` aynı kararı,
+asistanın fazla konuşkan olup olmadığına karar veren kişi için cümlelere çevirir; aynı izden,
+hiçbir şey eklemeden:
+
+```ts
+import { explain } from "proactive-gate";
+
+explain(decision).summary;
+// "Held until 08:00 because the user's quiet hours run 22:00 to 08:00 Europe/Istanbul and
+//  normal priority is below the critical floor needed to override them."
+```
+
+"Bu mesaj 22:30'da neden gitti" sorusunun da bir yanıtı olur: izin verilen karar da kendini
+anlatır, `explanation.checks` ise çalışan her kontrol için sırayla bir cümle taşır. Renderer
+kararın saf bir fonksiyonudur: saat okumaz, adaya da kullanıcıya da bakmaz, dolayısıyla
+gate'in vermediği bir kararı anlatamaz. Hiçbir şablona uymayan bir gerekçe tahmin edilmez,
+olduğu gibi alıntılanır ve söyleyen kontrolün adıyla verilir. `language` bir parametredir:
+İngilizce `en` olarak gelir, başka bir dil `catalogs` içinde İngilizcenin üzerine birleşen bir
+`Partial<Sentences>`'tır, böylece yarım bir çeviri de görüntülenir. Python kardeşi aynı
+cümleleri yollar, CI her push'ta iki uygulamanın her fixture kararını karşılaştırır. Bu bölümü
+[@LouisDeconinck](https://github.com/LouisDeconinck)
+[#28](https://github.com/Bubblegunn/proactive-gate/pull/28) ile iki dilde birden yazdı.
+
 ## İsteğe bağlı, kendi modelinizin beslediği kontroller
 
 İkisi de kapalı gelir; adayın üzerine çağıranın koyduğu sayıları okurlar.
@@ -330,6 +363,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 +380,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/explain.d.ts

@@ -0,0 +1,130 @@
+/**
+ * explain(): a decision rendered as sentences a non-engineer can read.
+ *
+ * The renderer is a pure function of the decision. Every fact in a sentence
+ * comes from a trace entry's own reason or from a decision field, so it can
+ * only describe a decision the gate actually made; a check that never ran has
+ * no sentence. The machine reasons are the contract both implementations pin
+ * word for word, which is what makes them safe to read back here. When a
+ * reason does not match what a check emits, the sentence quotes it verbatim
+ * rather than guessing.
+ *
+ * `decision.reason` is unchanged: the plain sentence and the machine reason
+ * sit side by side and neither replaces the other.
+ */
+import type { Decision, TraceEntry } from "./types.js";
+/** Fields a parser pulled out of a machine reason; a template reads them. */
+export type SentenceFacts = Record<string, string | undefined>;
+export type SentenceTemplate = (facts: SentenceFacts) => string;
+/**
+ * Every sentence the renderer can emit, as one flat template table. A new
+ * language is a `Partial<Sentences>` merged over English, so a partial
+ * translation still renders. Keys are `check.outcome` plus the summary,
+ * note, gate and fallback entries.
+ */
+export interface Sentences {
+    /** A catalog may define keys beyond this table; explain() only reads the named ones. */
+    [key: string]: SentenceTemplate | undefined;
+    /** Whole-decision line for a reject or defer. `until` is set when the trace names the instant the hold lifts. */
+    "summary.held": SentenceTemplate;
+    /** Whole-decision line for an allowed decision. `notes` is pre-joined, leading semicolon included. */
+    "summary.allowed": SentenceTemplate;
+    /** Allowed with an empty trace. */
+    "summary.allowedEmpty": SentenceTemplate;
+    /** Not allowed but no stopping entry found; the decision was built by hand. */
+    "summary.heldUnknown": SentenceTemplate;
+    "note.deliverAt": SentenceTemplate;
+    "note.nearLimit": SentenceTemplate;
+    "note.shadowed": SentenceTemplate;
+    /** Wraps a shadowed stop: `body` is the clause the check would have produced. */
+    "entry.shadow": SentenceTemplate;
+    "killSwitch.pass": SentenceTemplate;
+    "killSwitch.reject": SentenceTemplate;
+    "consent.pass": SentenceTemplate;
+    "consent.reject": SentenceTemplate;
+    "enabled.pass": SentenceTemplate;
+    "enabled.reject": SentenceTemplate;
+    "mode.pass": SentenceTemplate;
+    "mode.reject": SentenceTemplate;
+    "snooze.pass": SentenceTemplate;
+    "snooze.reject": SentenceTemplate;
+    "mute.pass": SentenceTemplate;
+    "mute.reject": SentenceTemplate;
+    "intensity.pass": SentenceTemplate;
+    "intensity.reject": SentenceTemplate;
+    "quietHours.pass": SentenceTemplate;
+    "quietHours.reject": SentenceTemplate;
+    "quietHours.skip": SentenceTemplate;
+    "trustRamp.pass": SentenceTemplate;
+    "trustRamp.reject": SentenceTemplate;
+    "trustRamp.skip": SentenceTemplate;
+    "dismissalCooldown.pass": SentenceTemplate;
+    "dismissalCooldown.reject": SentenceTemplate;
+    "adaptiveTiming.pass": SentenceTemplate;
+    "adaptiveTiming.adjust": SentenceTemplate;
+    "dedupe.pass": SentenceTemplate;
+    "dedupe.reject": SentenceTemplate;
+    "dedupe.skip": SentenceTemplate;
+    "dailyBudget.pass": SentenceTemplate;
+    "dailyBudget.reject": SentenceTemplate;
+    "weeklyBudget.pass": SentenceTemplate;
+    "weeklyBudget.reject": SentenceTemplate;
+    "monthlyBudget.pass": SentenceTemplate;
+    "monthlyBudget.reject": SentenceTemplate;
+    "windowBudget.pass": SentenceTemplate;
+    "windowBudget.reject": SentenceTemplate;
+    "rateLimit.pass": SentenceTemplate;
+    "rateLimit.reject": SentenceTemplate;
+    "budget.pass": SentenceTemplate;
+    "budget.reject": SentenceTemplate;
+    "utilityFloor.pass": SentenceTemplate;
+    "utilityFloor.reject": SentenceTemplate;
+    "utilityFloor.skip": SentenceTemplate;
+    "boundedDeferral.pass": SentenceTemplate;
+    "boundedDeferral.adjust": SentenceTemplate;
+    "allowedWindow.pass": SentenceTemplate;
+    "allowedWindow.reject": SentenceTemplate;
+    "allowedWindow.skip": SentenceTemplate;
+    "requiresConsent.pass": SentenceTemplate;
+    "requiresConsent.reject": SentenceTemplate;
+    "requiresConsent.skip": SentenceTemplate;
+    "recentInteraction.pass": SentenceTemplate;
+    "recentInteraction.reject": SentenceTemplate;
+    /** The gate's own trace reasons, not any check's: store failures and ignored non-rejecting stops. */
+    "gate.failOpen": SentenceTemplate;
+    "gate.failClosed": SentenceTemplate;
+    "gate.nonRejecting": SentenceTemplate;
+    /** Unknown check ids and reasons that match nothing: quote the trace, invent nothing. */
+    "fallback.stop": SentenceTemplate;
+    "fallback.pass": SentenceTemplate;
+    "fallback.skip": SentenceTemplate;
+    "fallback.adjust": SentenceTemplate;
+}
+/** One trace entry rendered: which check, what it said, and the sentence for it. */
+export interface CheckSentence {
+    id: string;
+    outcome: TraceEntry["outcome"];
+    shadow?: boolean;
+    sentence: string;
+}
+export interface Explanation {
+    /** The decision as one sentence: "held until 08:00 because ...", "allowed because ...". */
+    summary: string;
+    /** One sentence per check that ran, in the order it ran. */
+    checks: CheckSentence[];
+}
+export interface ExplainOptions {
+    /**
+     * Language of the sentences. Only "en" ships with the package; any other
+     * code needs a matching entry in `catalogs`, which is merged over English
+     * so a partial translation still renders.
+     */
+    language?: string;
+    catalogs?: Record<string, Partial<Sentences>>;
+}
+export declare const en: Sentences;
+/**
+ * Render a decision as sentences. Deterministic: the same decision always
+ * produces the same explanation, and nothing outside the decision is read.
+ */
+export declare function explain(decision: Decision, options?: ExplainOptions): Explanation;

package/dist/src/explain.js

@@ -0,0 +1,336 @@
+/* English ---------------------------------------------------------------- */
+const plural = (n, unit) => `${n} ${unit}${n === 1 ? "" : "s"}`;
+/** "1d" to "within the last day", "24h" to "within the last 24 hours": the dedupe window, said long. */
+const spanWords = (label) => {
+    const m = /^(\d+)([dhms])$/.exec(label);
+    if (!m)
+        return `within the last ${label}`;
+    const unit = { d: "day", h: "hour", m: "minute", s: "second" }[m[2]];
+    const n = Number(m[1]);
+    return n === 1 ? `within the last ${unit}` : `within the last ${plural(n, unit)}`;
+};
+/** "86400" to "day", "7200" to "2 hours": a rate-limit period in seconds, said long. */
+const secondsWords = (text) => {
+    const n = Number(text);
+    if (!Number.isFinite(n))
+        return `${text} seconds`;
+    // "per hour", not "per 1 hour": the same singular spanWords already says as "the last day".
+    const period = (count, unit) => (count === 1 ? unit : plural(count, unit));
+    if (n % 86400 === 0)
+        return period(n / 86400, "day");
+    if (n % 3600 === 0)
+        return period(n / 3600, "hour");
+    if (n % 60 === 0)
+        return period(n / 60, "minute");
+    return period(n, "second");
+};
+/** The spend note is true only when the pass really read the counter: a bypassed budget returns a bare pass, a near-limit pass cannot be a bypass. */
+const budgetPass = (label) => (f) => f.used !== undefined
+    ? `the ${label} had room, but only just: ${f.used} of ${f.limit} already used; the unit is spent when the message actually goes out`
+    : `the ${label} did not stop it`;
+const budgetReject = (label) => (f) => `the ${label} of ${f.limit} was already spent (${f.used} used)`;
+export const en = {
+    "summary.held": (f) => `held${f.until ? ` until ${f.until}` : ""} because ${f.clause}`,
+    "summary.allowed": (f) => `allowed at ${f.at} because no check stopped it${f.notes ?? ""}`,
+    "summary.allowedEmpty": () => "allowed; no checks ran",
+    "summary.heldUnknown": () => "held; the trace does not name the check that stopped it",
+    "note.deliverAt": (f) => `delivery waits until ${f.at}`,
+    "note.nearLimit": (f) => `${f.check} was close to its limit (${f.used} of ${f.limit} used)`,
+    "note.shadowed": (f) => `${f.check} would have stopped it but ran in shadow mode`,
+    "entry.shadow": (f) => `it would have stopped the message (${f.body}), but the check ran in shadow mode so evaluation continued`,
+    "killSwitch.pass": () => "the kill switch was off",
+    "killSwitch.reject": () => "the kill switch is on, which stops every message",
+    "consent.pass": () => "the user has agreed to proactive messages",
+    "consent.reject": () => "the user has not agreed to proactive messages",
+    "enabled.pass": () => "proactive messages are switched on for this profile",
+    "enabled.reject": () => "proactive messages are switched off on this user's profile",
+    "mode.pass": () => "the user's operating mode did not block it",
+    "mode.reject": (f) => `the user's operating mode is "${f.mode}", which does not allow proactive messages`,
+    "snooze.pass": () => "no snooze was in effect",
+    "snooze.reject": (f) => `the user has snoozed the assistant until ${f.until}`,
+    "mute.pass": () => "this type of message is not muted",
+    "mute.reject": (f) => `the user has muted "${f.type}" messages`,
+    "intensity.pass": () => "the message's priority satisfied the user's intensity setting",
+    "intensity.reject": (f) => `the message was ${f.priority} priority, and the user's "${f.level}" intensity setting allows only ${f.floor} and above`,
+    "quietHours.pass": () => "quiet hours did not block it",
+    "quietHours.reject": (f) => `the user's quiet hours run ${f.start} to ${f.end} ${f.tz}${f.from ? `, a window belonging to ${f.from},` : ""} and ${f.priority} priority is below the ${f.floor} floor needed to override them`,
+    "quietHours.skip": () => "the user has quiet hours but no time zone, so the check could not run",
+    "trustRamp.pass": () => "the new-user trust period did not block it",
+    "trustRamp.reject": (f) => `the user is on day ${f.day} of a ${f.days}-day trust period for new users, which allows only ${f.floor} priority and above, and the message was ${f.priority}`,
+    "trustRamp.skip": () => "the user's sign-up date is not on record, so the new-user trust period could not be checked",
+    "dismissalCooldown.pass": () => "the user has not dismissed this type enough to silence it",
+    "dismissalCooldown.reject": (f) => `the user has dismissed "${f.type}" messages ${f.count} times in ${f.within} days, so this type stays silent until ${f.until}`,
+    "adaptiveTiming.pass": () => "the timing check left the message as it was",
+    "adaptiveTiming.adjust": (f) => f.at && f.surfaces
+        ? `delivery was moved to ${f.at} and narrowed to ${f.surfaces.split(",").join(", ")}`
+        : f.at
+            ? `delivery was moved to ${f.at}`
+            : `delivery was narrowed to ${(f.surfaces ?? "").split(",").join(", ")}`,
+    "dedupe.pass": () => "this event had not already produced a message; the event is claimed when the message actually goes out",
+    "dedupe.reject": (f) => `the same event already produced a message ${spanWords(f.window ?? "")}`,
+    "dedupe.skip": () => "the candidate carried no event key, so duplicate detection could not run",
+    "dailyBudget.pass": budgetPass("daily budget"),
+    "dailyBudget.reject": budgetReject("user's daily budget"),
+    "weeklyBudget.pass": budgetPass("weekly budget"),
+    "weeklyBudget.reject": budgetReject("user's weekly budget"),
+    "monthlyBudget.pass": budgetPass("monthly budget"),
+    "monthlyBudget.reject": budgetReject("user's monthly budget"),
+    "windowBudget.pass": budgetPass("window budget"),
+    "windowBudget.reject": (f) => `the budget for the window opened by the user's last message was already spent (${f.used} of ${f.limit} used)`,
+    "rateLimit.pass": () => "the rate limit did not stop it",
+    "rateLimit.reject": (f) => `the rate limit of ${f.limit} messages per ${secondsWords(f.per ?? "")} was already reached (${f.used} used)`,
+    "budget.pass": (f) => `the budget had room, but only just: ${f.used} of ${f.limit} already used; the unit is spent when the message actually goes out`,
+    "budget.reject": (f) => `the ${f.label} was already used up (${f.used} of ${f.limit} used)`,
+    "utilityFloor.pass": () => "the estimated acceptance chance cleared the utility floor",
+    "utilityFloor.reject": (f) => `the estimated chance the user would accept this message was ${f.pAccept}, below the utility floor of ${f.tau}`,
+    "utilityFloor.skip": () => "the candidate carried no acceptance estimate, so the utility floor could not run",
+    "boundedDeferral.pass": () => "the user did not look busy",
+    "boundedDeferral.adjust": (f) => `the user looked busy, so delivery was deferred ${f.tStar} seconds to ${f.at}`,
+    "allowedWindow.pass": (f) => (f.name ? `the "${f.name}" allowed window did not block it` : "the allowed window did not block it"),
+    "allowedWindow.reject": (f) => `messages may only go out between ${f.start} and ${f.end} (${f.zone}), and the local time was outside that window`,
+    "allowedWindow.skip": () => "the user has no time zone, so the allowed window could not be checked",
+    "requiresConsent.pass": (f) => (f.name ? `the "${f.name}" consent the check needs was in place` : "the consent the check needs was in place"),
+    "requiresConsent.reject": (f) => `the user has not given the required "${f.name}" consent${f.start ? `, which applies between ${f.start} and ${f.end}` : ""}`,
+    "requiresConsent.skip": () => "the user has no time zone, so the hours this consent applies could not be checked",
+    "recentInteraction.pass": () => "the user had written to the assistant recently enough",
+    "recentInteraction.reject": (f) => f.age ? `the user's last message to the assistant was ${f.age} h ago, outside the ${f.within} h window` : "the user has never written to the assistant, and this rule allows messages only after they do",
+    "gate.failOpen": (f) => `the "${f.id}" check failed with "${f.error}", and the gate is set to let messages through when a check fails`,
+    "gate.failClosed": (f) => `the "${f.id}" check failed with "${f.error}", and the gate is set to stop messages when a check fails`,
+    "gate.nonRejecting": (f) => `the "${f.id}" check tried to ${f.kind} ("${f.reason}") but is marked non-rejecting, so the gate ignored it`,
+    "fallback.stop": (f) => `the "${f.id}" check stopped it: ${f.reason}`,
+    "fallback.pass": (f) => `the "${f.id}" check let it through${f.reason ? ` (${f.reason})` : ""}`,
+    "fallback.skip": (f) => `the "${f.id}" check did not weigh in: ${f.reason}`,
+    "fallback.adjust": (f) => `the "${f.id}" check adjusted it: ${f.reason}`,
+};
+const match = (pattern, keys) => (reason) => {
+    const m = pattern.exec(reason);
+    if (!m)
+        return null;
+    const facts = {};
+    keys.forEach((key, i) => {
+        const value = m[i + 1];
+        if (value !== undefined)
+            facts[key] = value;
+    });
+    return facts;
+};
+const fixed = (text) => (reason) => (reason === text ? {} : null);
+const first = (...parsers) => (reason) => {
+    for (const parse of parsers) {
+        const facts = parse(reason);
+        if (facts)
+            return facts;
+    }
+    return null;
+};
+const BUDGET_STOP = match(/^.* of (\d+) used \((\d+)\)$/, ["limit", "used"]);
+const BUDGET_NEAR = match(/^(\d+) of (\d+) used$/, ["used", "limit"]);
+const parseQuietHours = (reason) => {
+    const m = /^quiet hours (\S+) to (\S+)(?: \((\w+) (\S+)\))? (\S+); priority (\w+) is below the floor \((\w+)\)$/.exec(reason);
+    if (!m)
+        return null;
+    // holdUntil is the fact the summary headlines ("held until 08:00"); checks
+    // whose clause already says the instant (snooze, cooldown) leave it unset.
+    const facts = { start: m[1], end: m[2], tz: m[5], priority: m[6], floor: m[7], holdUntil: m[2] };
+    if (m[3] !== undefined)
+        facts.from = `${m[3]} ${m[4]}`;
+    return facts;
+};
+const PARSERS = {
+    killSwitch: { stop: fixed("engine kill switch is on") },
+    consent: { stop: fixed("user has not consented to proactive behaviour") },
+    enabled: { stop: fixed("proactive behaviour is disabled on this profile") },
+    mode: { stop: match(/^operating mode "(.+)" does not allow proactive messages$/, ["mode"]) },
+    snooze: { stop: match(/^snoozed until (.+)$/, ["until"]) },
+    mute: { stop: match(/^type "(.+)" is muted by the user$/, ["type"]) },
+    intensity: { stop: match(/^priority (\w+) is below the "(\w+)" intensity floor \((\w+)\)$/, ["priority", "level", "floor"]) },
+    quietHours: { stop: parseQuietHours, skip: fixed("quiet hours set but no timezone on the user; cannot evaluate") },
+    trustRamp: { stop: match(/^trust ramp: day (\d+) of (\S+), priority (\w+) is below (\w+)$/, ["day", "days", "priority", "floor"]), skip: fixed("no createdAt on the user; ramp cannot be evaluated") },
+    dismissalCooldown: { stop: match(/^(\d+) dismissals of "(.+)" in (\S+) days; silent until (.+)$/, ["count", "type", "within", "until"]) },
+    adaptiveTiming: { adjust: first(match(/^deliver at (\S+); surfaces (.+)$/, ["at", "surfaces"]), match(/^deliver at (\S+)$/, ["at"]), match(/^surfaces (.+)$/, ["surfaces"])) },
+    dedupe: { stop: match(/^already delivered within the last (.+)$/, ["window"]), skip: fixed("no dedupeKey on the candidate; deduplication cannot be evaluated") },
+    dailyBudget: { stop: BUDGET_STOP, passReason: BUDGET_NEAR },
+    weeklyBudget: { stop: BUDGET_STOP, passReason: BUDGET_NEAR },
+    monthlyBudget: { stop: BUDGET_STOP, passReason: BUDGET_NEAR },
+    windowBudget: { stop: BUDGET_STOP, passReason: BUDGET_NEAR },
+    rateLimit: { stop: match(/^rate limit (\d+) per (\d+) s of \d+ used \((\d+)\)$/, ["limit", "per", "used"]), passReason: BUDGET_NEAR },
+    utilityFloor: { stop: match(/^pAccept (\S+) < tau (\S+)$/, ["pAccept", "tau"]), skip: fixed("no pAccept on the candidate; utility floor cannot be evaluated") },
+    boundedDeferral: { adjust: match(/^user busy; deliver at (\S+) \(t\* (\d+) s\)$/, ["at", "tStar"]) },
+    allowedWindow: {
+        stop: match(/^outside the allowed window (\S+) to (\S+) (.+)$/, ["start", "end", "zone"]),
+        idFacts: (id) => (id.startsWith("window:") ? { name: id.slice("window:".length) } : {}),
+        skip: fixed("no timezone on the user; window cannot be evaluated"),
+    },
+    requiresConsent: {
+        stop: match(/^consent "(.+)" is missing(?: \(required (\S+) to (\S+)\))?$/, ["name", "start", "end"]),
+        idFacts: (id) => (id.startsWith("consent:") ? { name: id.slice("consent:".length) } : {}),
+        skip: fixed("no timezone on the user; consent window cannot be evaluated"),
+    },
+    recentInteraction: {
+        stop: first(fixed("no inbound message from the user on record"), match(/^last inbound message (\d+) h ago, window is (\S+) h$/, ["age", "within"])),
+    },
+};
+/** The ids the package itself emits: the fixed check ids, plus consent:<name>, rate:<limit>/<period>s and window:<name>. */
+const keyForId = (id) => {
+    if (id in PARSERS)
+        return id;
+    if (id.startsWith("consent:"))
+        return "requiresConsent";
+    if (id.startsWith("rate:"))
+        return "rateLimit";
+    if (id.startsWith("window:"))
+        return "allowedWindow";
+    return undefined;
+};
+/** The gate's own trace entries: a store failure, or a non-rejecting check that tried to stop evaluation anyway. */
+const GATE_ENTRIES = [
+    { key: "gate.failOpen", parse: match(/^check threw \((.*)\); failing open$/, ["error"]) },
+    { key: "gate.failClosed", parse: match(/^check threw \((.*)\); failing closed$/, ["error"]) },
+    { key: "gate.nonRejecting", parse: match(/^non-rejecting check returned (\w+) \((.*)\); ignored$/, ["kind", "reason"]) },
+];
+/**
+ * Custom ids (a preset's "window:kakao", a caller's own wrapper) still emit the
+ * check's reason, so an unmatched id falls back to recognizing the reason's
+ * shape. Order is distinctiveness: each pattern names the check it sounds like.
+ */
+const STOP_SCAN = ["quietHours", "allowedWindow", "requiresConsent", "rateLimit", "dismissalCooldown", "snooze", "mute", "mode", "intensity", "trustRamp", "dedupe", "utilityFloor", "recentInteraction", "killSwitch", "consent", "enabled"];
+const SKIP_SCAN = ["quietHours", "trustRamp", "dedupe", "utilityFloor", "allowedWindow", "requiresConsent"];
+const ADJUST_SCAN = ["adaptiveTiming", "boundedDeferral"];
+const BUDGET_LABELS = { "daily budget": "dailyBudget", "weekly budget": "weeklyBudget", "monthly budget": "monthlyBudget", "window budget": "windowBudget" };
+/** A "label of N used (M)" reason from a budget whose id we do not know. */
+const scanBudget = (reason) => {
+    const m = /^(.+) of (\d+) used \((\d+)\)$/.exec(reason);
+    if (!m)
+        return null;
+    const known = BUDGET_LABELS[m[1]];
+    const facts = { label: m[1], limit: m[2], used: m[3] };
+    return { key: known ?? "budget", facts };
+};
+const cap = (text) => (text ? text[0].toUpperCase() + text.slice(1) : text);
+const sentenceOf = (fragment) => `${cap(fragment)}.`;
+const t = (s, key, facts) => s[key]?.(facts) ?? en[key]?.(facts) ?? facts.reason ?? "";
+/** The stopping entry's clause and, when the trace names it, the instant the hold lifts. */
+function stopFacts(entry) {
+    const reason = entry.reason ?? "";
+    for (const g of GATE_ENTRIES) {
+        const facts = g.parse(reason);
+        if (facts)
+            return { template: g.key, facts: { id: entry.id, ...facts } };
+    }
+    const key = keyForId(entry.id);
+    if (key && PARSERS[key]?.stop) {
+        const facts = PARSERS[key].stop(reason);
+        if (facts)
+            return { template: `${key}.reject`, facts };
+    }
+    for (const k of STOP_SCAN) {
+        const facts = PARSERS[k]?.stop?.(reason);
+        if (facts)
+            return { template: `${k}.reject`, facts };
+    }
+    const budget = scanBudget(reason);
+    if (budget)
+        return { template: `${budget.key}.reject`, facts: budget.facts };
+    return { template: "fallback.stop", facts: { id: entry.id, reason } };
+}
+function entryBody(entry, s) {
+    const reason = entry.reason ?? "";
+    const key = keyForId(entry.id);
+    switch (entry.outcome) {
+        case "reject":
+        case "defer": {
+            const stop = stopFacts(entry);
+            return t(s, stop.template, stop.facts);
+        }
+        case "pass": {
+            if (reason) {
+                const facts = key ? PARSERS[key]?.passReason?.(reason) : BUDGET_NEAR(reason);
+                if (facts)
+                    return t(s, `${key ?? "budget"}.pass`, facts);
+                return t(s, "fallback.pass", { id: entry.id, reason });
+            }
+            const facts = key ? (PARSERS[key]?.idFacts?.(entry.id) ?? {}) : {};
+            return t(s, key ? `${key}.pass` : "fallback.pass", { id: entry.id, ...facts });
+        }
+        case "skip": {
+            for (const g of GATE_ENTRIES) {
+                const facts = g.parse(reason);
+                if (facts)
+                    return t(s, g.key, { id: entry.id, ...facts });
+            }
+            if (key && PARSERS[key]?.skip) {
+                const facts = PARSERS[key].skip(reason);
+                if (facts)
+                    return t(s, `${key}.skip`, facts);
+            }
+            for (const k of SKIP_SCAN) {
+                const facts = PARSERS[k]?.skip?.(reason);
+                if (facts)
+                    return t(s, `${k}.skip`, facts);
+            }
+            return t(s, "fallback.skip", { id: entry.id, reason });
+        }
+        case "adjust": {
+            if (key && PARSERS[key]?.adjust) {
+                const facts = PARSERS[key].adjust(reason);
+                if (facts)
+                    return t(s, `${key}.adjust`, facts);
+            }
+            for (const k of ADJUST_SCAN) {
+                const facts = PARSERS[k]?.adjust?.(reason);
+                if (facts)
+                    return t(s, `${k}.adjust`, facts);
+            }
+            return t(s, "fallback.adjust", { id: entry.id, reason });
+        }
+    }
+}
+function explainEntry(entry, s) {
+    const body = entryBody(entry, s);
+    // Shadow is only a would-have-stopped when the outcome could have stopped.
+    const shadowedStop = entry.shadow === true && (entry.outcome === "reject" || entry.outcome === "defer");
+    return {
+        id: entry.id,
+        outcome: entry.outcome,
+        ...(entry.shadow ? { shadow: true } : {}),
+        sentence: sentenceOf(shadowedStop ? t(s, "entry.shadow", { body }) : body),
+    };
+}
+function summarize(decision, s) {
+    if (decision.allowed) {
+        if (!decision.trace.length)
+            return sentenceOf(t(s, "summary.allowedEmpty", {}));
+        const notes = [];
+        if (decision.deliverAt)
+            notes.push(t(s, "note.deliverAt", { at: decision.deliverAt.toISOString() }));
+        for (const n of decision.nearLimit)
+            notes.push(t(s, "note.nearLimit", { check: n.check, used: String(n.used), limit: String(n.limit) }));
+        for (const id of decision.shadowed)
+            notes.push(t(s, "note.shadowed", { check: id }));
+        return sentenceOf(t(s, "summary.allowed", { at: decision.evaluatedAt.toISOString(), notes: notes.length ? `; ${notes.join("; ")}` : "" }));
+    }
+    const stopId = decision.rejectedBy ?? decision.deferredBy;
+    const entry = stopId ? [...decision.trace].reverse().find((e) => e.id === stopId && (e.outcome === "reject" || e.outcome === "defer")) : undefined;
+    if (!entry)
+        return sentenceOf(t(s, "summary.heldUnknown", {}));
+    const stop = stopFacts(entry);
+    const clause = t(s, stop.template, stop.facts);
+    // For a deferral the hold ends at retryAt; when the clause already names the
+    // instant (snooze's reason is "snoozed until X"), naming it twice reads worse.
+    const clauseSaysWhen = stop.facts.until !== undefined;
+    const until = stop.facts.holdUntil ?? (!clauseSaysWhen && decision.deferredBy ? decision.retryAt?.toISOString() : undefined);
+    return sentenceOf(t(s, "summary.held", { clause, ...(until ? { until } : {}) }));
+}
+/**
+ * Render a decision as sentences. Deterministic: the same decision always
+ * produces the same explanation, and nothing outside the decision is read.
+ */
+export function explain(decision, options = {}) {
+    const language = options.language ?? "en";
+    const overlay = options.catalogs?.[language];
+    if (language !== "en" && !overlay) {
+        throw new Error(`no sentence catalog for language "${language}"; pass one with the catalogs option`);
+    }
+    const s = { ...en, ...overlay };
+    return { summary: summarize(decision, s), checks: decision.trace.map((entry) => explainEntry(entry, s)) };
+}

package/dist/src/index.d.ts

@@ -1,5 +1,7 @@
 export { createGate } from "./gate.js";
 export type { Gate, PolicyGateOptions } from "./gate.js";
+export { explain, en } from "./explain.js";
+export type { CheckSentence, Explanation, ExplainOptions, SentenceFacts, Sentences, SentenceTemplate } from "./explain.js";
 export { compilePolicy, KNOWN_CHECKS } from "./policy.js";
 export { presets } from "./presets.js";
 export type { Preset } from "./presets.js";

package/dist/src/index.js

@@ -1,4 +1,5 @@
 export { createGate } from "./gate.js";
+export { explain, en } from "./explain.js";
 export { compilePolicy, KNOWN_CHECKS } from "./policy.js";
 export { presets } from "./presets.js";
 export { MemoryStore, RedisStore, SqliteStore } from "./stores.js";

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.3.0",
+  "version": "0.4.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",
@@ -48,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 dist/test/explain.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",
@@ -59,7 +59,9 @@
     "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",
+    "explain-parity": "node scripts/explain-parity.mjs",
+    "og": "npm run build && node scripts/og-image.mjs"
   },
   "engines": {
     "node": ">=20"