proactive-gate 0.5.0 → 0.6.0

package/README.md

@@ -36,6 +36,67 @@ if (decision.allowed && (await gate.commit(decision, { user, candidate }))) {
 }
 ```
 
+## What it changes, before you install anything
+
+```
+npx proactive-gate simulate
+```
+
+No key, no account, nothing to configure. It replays one week of an assistant that fires when its
+own data arrives rather than when the recipient is awake, first with no gate and then through the
+default order, and prints what each one did with every candidate.
+
+|                                                             | no gate | proactive-gate |
+| ----------------------------------------------------------- | ------: | -------------: |
+| delivered                                                   |     171 |             74 |
+| held                                                        |       0 |             97 |
+| **delivered inside the recipient's own quiet hours**        |  **52** |          **3** |
+| of those, critical, which the documented floor lets through  |       5 |              3 |
+| most one person received in one local day                   |       6 |              5 |
+
+The row in bold is the one worth reading twice. It counts deliveries inside the window each person
+set for themselves, not inside a curfew somebody picked for them: the user in the week who asked for
+no quiet hours at all is not protected from herself, and the one whose window runs 00:00 to 06:00 is
+not judged against anyone else's night. Under the default order the only three that landed there were
+critical, which is what the documented priority floor is for.
+
+**Scope and method, because a number without them is decoration.** The week is a generator plus a
+seed, not anybody's traffic: eight users in five time zones, candidate instants drawn uniformly
+across the UTC day, parameters written down in `src/demo-week.ts` and dumped to
+[`examples/week.jsonl`](examples/week.jsonl) so you can read what it produced. It measures what a
+policy does to a stream. It cannot tell you whether a message was wanted, or what its recipient did
+with it. Every user in it has consented and no dismissals are seeded, so `consent`, `enabled`,
+`killSwitch`, `dedupe` and `dismissalCooldown` never fire in that run.
+
+Three more ways to run it:
+
+```
+npx proactive-gate simulate --disagreements --why          # the sentence behind each hold
+npx proactive-gate simulate your-candidates.jsonl          # your traffic, not a generated week
+npx proactive-gate simulate --policy examples/policies/aggressive.json \
+                            --policy examples/policies/respectful.json
+```
+
+The last one is the comparison to run before changing a policy in production: same stream, two
+policies, and the 73 candidates they disagree about listed one by one.
+
+## What this will not do
+
+This repository is young and grew quickly, so the boundary is written down rather than left to be
+inferred from what happens to be in it.
+
+- **The twelve checks are the policy surface.** A thirteenth needs a deployment whose rule the
+  twelve cannot express, not a rule that exists somewhere in the world.
+- **The preset catalogue is frozen at what is merged.** A new preset needs someone who is shipping
+  to that channel, or under that instrument, and who says so on the issue. "This country also has a
+  law" is not the bar, because every country does, and a preset nobody ships against rots unread.
+- **Adapters and stores are frozen on the same terms.** The next one arrives with the person who
+  needs it.
+- **What grows instead is evidence**: the simulator above, the conformance suite, and an
+  implementation of the specification by somebody who is not us.
+- **What will never be here**: anything that needs a server, a hosted account, or reads the content
+  of a message.
+
 Or start from a policy file and the wiring for your framework, in one command:
 
 ```
@@ -393,7 +454,9 @@ and day type, not a fixed statutory quiet window, and the secondary sources that
 window disagree with each other about whether it starts at 09:00 or 10:00. What the
 regulation does fix is the default: four of the nine Schedule-II bands, covering 00:00 to
 10:00 and 21:00 to 24:00, are off for every customer until the subscriber switches that band
-on, so `inTcccp` encodes those as one opt-in consent per band rather than a hard window.
+on, so `inTcccp` encodes those as one opt-in consent per band rather than a hard window. It was
+contributed by [@LouisDeconinck](https://github.com/LouisDeconinck) in
+[#29](https://github.com/Bubblegunn/proactive-gate/pull/29), in TypeScript and Python together.
 
 ## The budget is enforced at commit, not at evaluate
 
@@ -791,7 +854,7 @@ before. [@Aaqibhafeezkhan](https://github.com/Aaqibhafeezkhan) wrote `SqliteStor
 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.
+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. His third, hours later, was the India preset ([#29](https://github.com/Bubblegunn/proactive-gate/pull/29), in 0.5.0): he read TRAI's Schedule-II rather than the summaries everyone repeats, found that the "9am to 9pm" everybody quotes is not in the primary text, and encoded the four default-off bands as the opt-ins the regulation actually describes.
 
 ## Cite this
 

package/README.tr.md

@@ -29,6 +29,51 @@ if (decision.allowed && (await gate.commit(decision, { user, candidate }))) {
 }
 ```
 
+## Kurmadan önce ne değiştirdiğini görün
+
+```
+npx proactive-gate simulate
+```
+
+Anahtar yok, hesap yok, ayar yok. Verisi hazır olduğunda tetiklenen, yani kullanıcının uyanık olup
+olmadığına bakmayan bir asistanın bir haftasını önce hiç geçit olmadan, sonra varsayılan sırayla
+tekrar oynatır ve her adaya ne olduğunu yazar.
+
+|                                                        | geçit yok | proactive-gate |
+| ------------------------------------------------------ | --------: | -------------: |
+| iletildi                                               |       171 |             74 |
+| tutuldu                                                |         0 |             97 |
+| **kişinin kendi sessiz saatleri içinde iletilen**      |    **52** |          **3** |
+| bunlardan kritik olanlar (eşiğin geçirdiği)            |         5 |              3 |
+| bir kişinin bir günde aldığı en yüksek sayı            |         6 |              5 |
+
+Koyu satır iki kez okunmaya değer: herkesin **kendi** belirlediği pencereyi sayar, birinin başkası
+için seçtiği bir sokağa çıkma yasağını değil. Varsayılan sırada o pencereye giren üç mesajın üçü de
+kritikti, ki belgelenmiş öncelik eşiği tam bunun için var.
+
+**Kapsam ve yöntem, çünkü bunlar olmadan sayı süstür.** Hafta bir üretici ve bir tohumdur, kimsenin
+gerçek trafiği değil: beş saat diliminde sekiz kullanıcı, adayların anları UTC günü boyunca düzgün
+dağılımla seçilmiş, bütün parametreler `src/demo-week.ts` içinde yazılı ve
+[`examples/week.jsonl`](examples/week.jsonl) dosyasına dökülmüş. Bir politikanın bir akışa ne
+yaptığını ölçer; bir mesajın istenip istendiğini ya da alıcının onunla ne yaptığını ölçemez.
+
+```
+npx proactive-gate simulate --disagreements --why      # her tutmanın arkasındaki cümle
+npx proactive-gate simulate kendi-adaylarim.jsonl      # üretilmiş hafta değil, sizin trafiğiniz
+```
+
+## Bu kütüphanenin yapmayacağı şeyler
+
+- **On iki kontrol, politika yüzeyinin tamamıdır.** On üçüncüsü için, on ikisinin ifade edemediği
+  bir kuralı olan gerçek bir kurulum gerekir.
+- **Preset kataloğu birleşmiş hâliyle donduruldu.** Yeni bir preset için, o kanala ya da o mevzuata
+  göre gerçekten ürün gönderen ve bunu issue'da söyleyen birine ihtiyaç var. "Bu ülkenin de bir
+  yasası var" yeterli değil, çünkü her ülkenin var; kimsenin kullanmadığı preset çürür.
+- **Adaptörler ve store'lar da aynı kuralla dondu.** Bir sonraki, ona ihtiyacı olan kişiyle gelir.
+- **Bunun yerine büyüyen şey kanıt**: yukarıdaki simülatör, uygunluk paketi ve spesifikasyonun
+  bizim dışımızda biri tarafından yazılmış bir uygulaması.
+- **Asla olmayacaklar**: sunucu, barındırılan hesap ya da mesaj içeriğini okuyan herhangi bir şey.
+
 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),
@@ -323,7 +368,7 @@ const gate = createGate({ checks: [checks.consent(), ...presets.kakaoBrandMessag
 | `krNetworkAct50` | reklam rızası, ayrıca 21:00 ile 08:00 yerel saat için gece rızası |
 | `jpAntiSpamLaw` | opt-in |
 | `cnMinorMode` | reşit olmayanlar için: 06:00 ile 22:00 Asia/Shanghai ve günde bir |
-| `inTcccp` | promosyon rızası; varsayılan olarak kapalı olan 00:00-10:00 ve 21:00-24:00 bantları ayrı ayrı opt-in ister |
+| `inTcccp` | promosyon rızası; varsayılan olarak kapalı olan 00:00-10:00 ve 21:00-24:00 bantları ayrı ayrı opt-in ister ([@LouisDeconinck](https://github.com/LouisDeconinck), [#29](https://github.com/Bubblegunn/proactive-gate/pull/29)) |
 | `usTcpa` | kullanıcının yerel saatiyle 08:00 ile 21:00 (47 CFR 64.1200) |
 | `euEprivacy` | pazarlama rızası, mevcut müşteriler için yumuşak opt-in |
 | `telegramBot` | sohbet başına saniyede 1 ve dakikada 20 |

package/dist/src/cli.d.ts

@@ -4,6 +4,8 @@ import type { Decision, EvaluateInput } from "./types.js";
 export declare function loadPolicy(path?: string): Promise<Gate>;
 export declare function replay(lines: string[], gate: Gate, commit: boolean): Promise<Decision[]>;
 export declare function summarize(decisions: Decision[]): string;
+/** One JSONL line per candidate, the same shape `replay` reads. */
+export declare function parseEvents(text: string): EvaluateInput[];
 interface PreToolUseEvent {
     tool_name?: string;
     tool_input?: {

package/dist/src/cli.js

@@ -21,12 +21,33 @@ import { createRequire } from "node:module";
 import { createGate } from "./gate.js";
 import { defaultChecks } from "./checks.js";
 import { loadFixtures, readSkips, runFixture } from "./conformance.js";
+import { simulate } from "./simulate.js";
+import { formatSimulation } from "./simulate-report.js";
+import { DEMO_WEEK_NOTE, demoWeek, demoWeekPeople } from "./demo-week.js";
 import { FRAMEWORKS, listText, plan } from "./init.js";
-const HELP = `usage: proactive-gate init [--preset <name>] [--framework <name>] [--out <file>]
+const HELP = `usage: proactive-gate simulate [events.jsonl] [--policy <file>]... [--seed <n>]
+       proactive-gate init [--preset <name>] [--framework <name>] [--out <file>]
        proactive-gate replay <events.jsonl> [--policy <file>] [--json] [--commit]
        proactive-gate replay --fixtures <dir> [--skip <file>]
        proactive-gate hook --policy <file> [--tool <name>]
 
+simulate runs one stream of candidates under two policies and shows what each one did
+with every candidate: sent, held and why, deferred and until when, which budget it spent.
+With no arguments it runs a generated week against no gate at all, which is the comparison
+that answers what installing this would change. It adds nothing to the decision path: the
+same gate runs twice.
+
+  events.jsonl       your own candidates, one EvaluateInput per line (default: a generated week)
+  --policy <file>    a policy.json to run. Given once, it is compared against no gate; given
+                     twice, the two policies are compared against each other
+  --seed <n>         seeds the generated week and the simulated transport (default 7)
+  --limit <n>        timeline rows to print, 0 for all (default 20)
+  --disagreements    print only the candidates the policies disagreed about
+  --why              print each held candidate's sentence under its row
+  --transport-failure-rate <f>  fraction of simulated sends that fail (default 0)
+  --dump-events <f>  write the generated week to <f> as JSONL and exit
+  --json             the whole result, for computing your own figures
+
 init writes a policy you can read and edit, and prints the lines that wire it in.
 
   --preset <name>    a platform or legal preset to append (see --list)
@@ -125,6 +146,30 @@ export function summarize(decisions) {
     return lines.join("\n");
 }
 const pct = (n, total) => (total ? `${((100 * n) / total).toFixed(1)}%` : "0%");
+/** Every value of a flag that may be repeated, in the order it was given. */
+const argValues = (argv, flag) => {
+    const out = [];
+    for (const [i, a] of argv.entries())
+        if (a === flag && argv[i + 1] !== undefined)
+            out.push(argv[i + 1]);
+    return out;
+};
+/** One JSONL line per candidate, the same shape `replay` reads. */
+export function parseEvents(text) {
+    const events = [];
+    for (const [i, line] of text.split("\n").entries()) {
+        if (!line.trim())
+            continue;
+        try {
+            const raw = JSON.parse(line);
+            events.push({ ...raw, ...(raw.now ? { now: new Date(raw.now) } : {}) });
+        }
+        catch (error) {
+            throw new Error(`line ${i + 1}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return events;
+}
 const argValue = (argv, flag) => {
     const i = argv.indexOf(flag);
     return i >= 0 ? argv[i + 1] : undefined;
@@ -189,6 +234,52 @@ async function main(argv) {
         return;
     }
     const [command, file] = argv;
+    if (command === "simulate") {
+        const seed = Number(argValue(argv, "--seed") ?? 7);
+        if (!Number.isFinite(seed)) {
+            console.error("--seed takes a number");
+            process.exit(2);
+        }
+        const eventsFile = file && !file.startsWith("--") ? file : undefined;
+        const events = eventsFile ? parseEvents(await readFile(eventsFile, "utf8")) : demoWeek(seed);
+        const dump = argValue(argv, "--dump-events");
+        if (dump) {
+            const lines = events.map((e) => JSON.stringify({ user: e.user, candidate: e.candidate, now: e.now?.toISOString() }));
+            await writeFile(dump, `${lines.join("\n")}\n`);
+            console.log(`wrote ${events.length} events to ${dump}`);
+            return;
+        }
+        const policyFiles = argValues(argv, "--policy");
+        const policies = [];
+        for (const path of policyFiles) {
+            if (!path.endsWith(".json")) {
+                console.error(`simulate reads policy documents, not modules: ${path} must be a .json policy, because the simulation owns the store it reads budgets back out of`);
+                process.exit(2);
+            }
+            const label = path.replace(/^.*[/\\]/, "").replace(/\.json$/, "");
+            policies.push({ label, policy: JSON.parse(await readFile(path, "utf8")) });
+        }
+        // No policy given: the comparison a stranger wants, no gate against the default order.
+        // One policy given: the same comparison, against theirs. Two or more: theirs against theirs.
+        if (policies.length === 0)
+            policies.push({ label: "proactive-gate", checks: defaultChecks() });
+        if (policies.length === 1)
+            policies.unshift({ label: "no gate" });
+        const failureRate = Number(argValue(argv, "--transport-failure-rate") ?? 0);
+        const result = await simulate({ events, policies, seed, transportFailureRate: failureRate });
+        if (argv.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const limitArg = argValue(argv, "--limit");
+        console.log(formatSimulation(result, {
+            ...(limitArg === undefined ? {} : { limit: Number(limitArg) }),
+            disagreementsOnly: argv.includes("--disagreements"),
+            why: argv.includes("--why"),
+            ...(eventsFile ? {} : { note: DEMO_WEEK_NOTE, people: demoWeekPeople() }),
+        }));
+        return;
+    }
     if (command === "init") {
         if (argv.includes("--list")) {
             console.log(listText());

package/dist/src/demo-week.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The week `proactive-gate simulate` runs when you give it nothing of your own.
+ *
+ * It is a generator plus a seed, not a committed blob, so it is auditable in a way a data file
+ * is not: the parameters below are the whole definition, and `--dump-events` writes out exactly
+ * what they produced. It adds nothing to the published package.
+ *
+ * What it is: eight users in five time zones over seven days, with an assistant that fires when
+ * its own data arrives rather than when the recipient is awake. That is the ordinary failure
+ * mode this library exists for, and it is why candidate instants are drawn uniformly across the
+ * UTC day rather than placed politely inside each user's waking hours.
+ *
+ * What it is not: anybody's real traffic, and not a measurement of one. It cannot tell you how
+ * often a real assistant has something to say, whether a message was wanted, or what a user did
+ * with it. It measures what a policy does to a stream, which is the only thing a policy decides.
+ *
+ * What it does not reach, said plainly so nobody reads a clean run as full coverage: every user
+ * here has consented and is enabled, so `consent`, `enabled` and `killSwitch` never fire; no
+ * dismissals are seeded, so `dismissalCooldown` never fires; no candidate carries a `dedupeKey`,
+ * `pAccept` or `busy`, so `dedupe`, `utilityFloor` and `boundedDeferral` stay quiet; and no
+ * preset is involved. The checks it does exercise are quiet hours with its priority floor,
+ * mode, mute, snooze, intensity, the trust ramp and the daily budget.
+ */
+import type { EvaluateInput } from "./types.js";
+/** First and last instant of the generated week, inclusive of the first, exclusive of the last. */
+export declare const DEMO_WEEK_START = "2026-09-07T00:00:00.000Z";
+export declare const DEMO_WEEK_DAYS = 7;
+/**
+ * The generated week, in instant order.
+ *
+ * Ordered by instant rather than grouped by user because that is the order a server produces
+ * them in, and because the budget and the deferral queue both depend on the order they arrive.
+ */
+export declare function demoWeek(seed?: number): EvaluateInput[];
+/** One line per person, for the footer of the table, so the week is legible without reading code. */
+export declare const demoWeekPeople: () => string[];
+/** What the week is and is not, printed under any table built from it. */
+export declare const DEMO_WEEK_NOTE: string;

package/dist/src/demo-week.js

@@ -0,0 +1,115 @@
+/** First and last instant of the generated week, inclusive of the first, exclusive of the last. */
+export const DEMO_WEEK_START = "2026-09-07T00:00:00.000Z";
+export const DEMO_WEEK_DAYS = 7;
+/** One line per user, and every field on it is there to make a particular check reachable. */
+const PEOPLE = [
+    {
+        user: { id: "ayse", proactiveEnabled: true, mode: "normal", intensity: "normal", timezone: "Europe/Istanbul", quietHours: { start: "22:00", end: "08:00" }, createdAt: "2026-04-02T00:00:00Z" },
+        why: "the ordinary case: an established account with ordinary quiet hours",
+    },
+    {
+        user: { id: "ben", proactiveEnabled: true, mode: "normal", intensity: "low", timezone: "America/New_York", quietHours: { start: "23:00", end: "07:00" }, createdAt: "2026-01-15T00:00:00Z" },
+        why: "intensity low, so the floor rises and ordinary messages stop being worth sending",
+    },
+    {
+        user: { id: "chika", proactiveEnabled: true, mode: "normal", intensity: "normal", timezone: "Asia/Tokyo", quietHours: { start: "22:30", end: "06:30" }, createdAt: "2026-09-04T00:00:00Z" },
+        why: "three days old at the start of the week, so the trust ramp is still on",
+    },
+    {
+        user: { id: "dilan", proactiveEnabled: true, mode: "normal", intensity: "normal", timezone: "Europe/Istanbul", quietHours: { start: "22:00", end: "08:00" }, mutedTypes: ["digest"], createdAt: "2026-03-01T00:00:00Z" },
+        why: "one type muted, which is a user's own decision and not a budget",
+    },
+    {
+        user: { id: "emre", proactiveEnabled: true, mode: "normal", intensity: "normal", timezone: "America/Sao_Paulo", quietHours: { start: "23:00", end: "07:00" }, snoozedUntil: "2026-09-10T12:00:00Z", createdAt: "2026-02-20T00:00:00Z" },
+        why: "snoozed into the middle of the week, so the first days are held rather than dropped",
+    },
+    {
+        user: { id: "fatima", proactiveEnabled: true, mode: "focus", intensity: "normal", timezone: "Europe/London", quietHours: { start: "22:00", end: "07:30" }, createdAt: "2025-11-11T00:00:00Z" },
+        why: "in focus mode all week, which the default order only lets critical through",
+    },
+    {
+        user: { id: "gabriel", proactiveEnabled: true, mode: "normal", intensity: "normal", timezone: "America/New_York", quietHours: { start: "00:00", end: "06:00" }, createdAt: "2026-09-06T00:00:00Z" },
+        why: "one day old, with a narrow night: a new account is the strictest case there is",
+    },
+    {
+        user: { id: "hana", proactiveEnabled: true, mode: "normal", intensity: "high", timezone: "Asia/Tokyo", quietHours: null, createdAt: "2025-08-01T00:00:00Z" },
+        why: "intensity high and no quiet hours at all: the person who wants everything",
+    },
+];
+/** Types an assistant of this shape actually produces, and nothing invented for the demo. */
+const TYPES = ["reminder", "insight", "digest", "alert", "nudge"];
+/** Priorities, weighted the way a real stream is: mostly ordinary, rarely an emergency. */
+const PRIORITIES = [
+    { value: "low", weight: 15 },
+    { value: "normal", weight: 60 },
+    { value: "high", weight: 20 },
+    { value: "critical", weight: 5 },
+];
+/**
+ * Candidates per user per day, drawn uniformly from this list: a mean of about three, which is
+ * a product that surfaces a couple of reminders, a digest and the occasional alert. Chosen
+ * before the run rather than after seeing it, and wide enough that the default daily budget of
+ * five binds for the chattier days instead of never being reached.
+ */
+const PER_DAY = [1, 2, 3, 3, 4, 6];
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const pick = (random, values) => values[Math.floor(random() * values.length)];
+function pickPriority(random) {
+    const total = PRIORITIES.reduce((n, p) => n + p.weight, 0);
+    let roll = random() * total;
+    for (const p of PRIORITIES) {
+        roll -= p.weight;
+        if (roll <= 0)
+            return p.value;
+    }
+    return "normal";
+}
+/**
+ * The generated week, in instant order.
+ *
+ * Ordered by instant rather than grouped by user because that is the order a server produces
+ * them in, and because the budget and the deferral queue both depend on the order they arrive.
+ */
+export function demoWeek(seed = 7) {
+    const random = mulberry32(seed);
+    const start = Date.parse(DEMO_WEEK_START);
+    const events = [];
+    let n = 0;
+    for (const { user } of PEOPLE) {
+        for (let day = 0; day < DEMO_WEEK_DAYS; day += 1) {
+            const count = pick(random, PER_DAY);
+            for (let i = 0; i < count; i += 1) {
+                const minuteOfDay = Math.floor(random() * 24 * 60);
+                const at = new Date(start + day * 86400000 + minuteOfDay * 60000);
+                const candidate = {
+                    id: `c${(n += 1)}`,
+                    type: pick(random, TYPES),
+                    priority: pickPriority(random),
+                    surfaces: ["push", "feed"],
+                };
+                events.push({ user: { ...user, consent: true }, candidate, now: at });
+            }
+        }
+    }
+    return events.sort((a, b) => (a.now?.getTime() ?? 0) - (b.now?.getTime() ?? 0));
+}
+/** One line per person, for the footer of the table, so the week is legible without reading code. */
+export const demoWeekPeople = () => PEOPLE.map(({ user, why }) => `${user.id} (${user.timezone}): ${why}`);
+/** What the week is and is not, printed under any table built from it. */
+export const DEMO_WEEK_NOTE = [
+    "This is a generated week, not anybody's traffic: eight users in five time zones over seven days,",
+    "with candidate instants drawn uniformly across the UTC day, which is how an assistant that fires",
+    "when its data arrives meets a person who is asleep. It measures what a policy does to a stream.",
+    "It cannot tell you whether a message was wanted, or what its recipient did with it.",
+    "Every user here has consented and no dismissals are seeded, so consent, enabled, killSwitch,",
+    "dedupe and dismissalCooldown never fire in this run. Point --events at your own JSONL for a",
+    "number about your own traffic.",
+].join("\n");

package/dist/src/simulate-report.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The simulation as a table. Rendering only: every number here was computed in simulate.ts,
+ * and nothing in this file recounts anything, so the terminal output and `--json` cannot
+ * disagree with each other.
+ */
+import { DEMO_WEEK_NOTE } from "./demo-week.js";
+import type { SimResult } from "./simulate.js";
+export interface ReportOptions {
+    /** How many timeline rows to print. 0 prints all of them. */
+    limit?: number;
+    /** Print only the candidates the policies disagreed about. */
+    disagreementsOnly?: boolean;
+    /** Print each held candidate's sentence under its row. */
+    why?: boolean;
+    /** Which run the sentences and the stopped-by table describe; the last policy by default. */
+    reasonsFor?: number;
+    night?: {
+        start: number;
+        end: number;
+    };
+    /** Appended under the tables, for a generated stream that has to say so. */
+    note?: string;
+    /** One line per user, for a generated stream whose people were chosen for a reason. */
+    people?: string[];
+}
+export declare function formatSimulation(result: SimResult, options?: ReportOptions): string;
+export { DEMO_WEEK_NOTE };

package/dist/src/simulate-report.js

@@ -0,0 +1,128 @@
+/**
+ * The simulation as a table. Rendering only: every number here was computed in simulate.ts,
+ * and nothing in this file recounts anything, so the terminal output and `--json` cannot
+ * disagree with each other.
+ */
+import { DEMO_WEEK_NOTE } from "./demo-week.js";
+const VERDICT = {
+    sent: "sent",
+    held: "held",
+    deferred: "deferred",
+    expired: "expired",
+    lostAtCommit: "lost at commit",
+    spentNotDelivered: "spent, not delivered",
+};
+/** Outcome plus the check that produced it, which is the whole verdict in one cell. */
+const verdictOf = (cell) => {
+    if (!cell)
+        return "";
+    const word = VERDICT[cell.outcome] ?? cell.outcome;
+    return cell.check && cell.outcome !== "sent" ? `${word} ${cell.check}` : word;
+};
+const pad = (s, w) => (s.length > w ? `${s.slice(0, Math.max(0, w - 1))}…` : s.padEnd(w));
+/** The widest cell in a column, so nothing is truncated that would have fitted. */
+const widthOf = (values, min) => Math.max(min, ...values.map((v) => v.length));
+function timelineTable(result, rows, why) {
+    const labels = result.runs.map((r) => r.label);
+    const cols = labels.map((label, i) => ({
+        label,
+        width: widthOf([label, ...rows.map((r) => verdictOf(r.cells[i]))], 8),
+    }));
+    const userW = widthOf(["user", ...rows.map((r) => r.userId)], 4);
+    const typeW = widthOf(["type", ...rows.map((r) => r.type)], 4);
+    const priW = widthOf(["pri", ...rows.map((r) => r.priority)], 3);
+    const head = `${pad("when (local)", 13)}  ${pad("user", userW)}  ${pad("type", typeW)}  ${pad("pri", priW)}  ${cols.map((c) => pad(c.label, c.width)).join("  ")}`;
+    const out = [head, "-".repeat(head.length)];
+    for (const row of rows) {
+        const cells = cols.map((c, i) => pad(verdictOf(row.cells[i]), c.width)).join("  ");
+        out.push(`${pad(row.localTime, 13)}  ${pad(row.userId, userW)}  ${pad(row.type, typeW)}  ${pad(row.priority, priW)}  ${cells}`.trimEnd());
+        // --why prints the sentence explain() already produces, under the row it belongs to.
+        const cell = why === null ? undefined : row.cells[why];
+        if (cell && cell.outcome !== "sent" && cell.sentence)
+            out.push(`               ${cell.sentence}`);
+    }
+    return out;
+}
+function summaryTable(runs, night) {
+    const labels = runs.map((r) => r.label);
+    const nightLabel = `delivered ${String(night.start).padStart(2, "0")}:00-${String(night.end).padStart(2, "0")}:00 local`;
+    const quietLabel = "delivered inside their own quiet hours";
+    const rows = [
+        ["delivered", runs.map((r) => String(r.counts.sent))],
+        ["held", runs.map((r) => String(r.counts.held))],
+        ["deferred, then delivered", runs.map((r) => String(r.counts.sentAfterDeferral))],
+        ["moved to a later moment", runs.map((r) => String(r.counts.sentAtALaterMoment))],
+        ["deferred, then expired", runs.map((r) => String(r.counts.expired))],
+        ["lost at commit", runs.map((r) => String(r.counts.lostAtCommit))],
+        ["spent, not delivered", runs.map((r) => String(r.counts.spentNotDelivered))],
+        [quietLabel, runs.map((r) => String(r.counts.sentInQuietHours))],
+        ["  of those, critical (what the floor lets through)", runs.map((r) => String(r.counts.sentInQuietHoursByFloor))],
+        [`${nightLabel} (a fixed window)`, runs.map((r) => String(r.counts.sentAtNight))],
+        ["most one person got in a day", runs.map((r) => String(r.counts.busiestUserDay))],
+    ];
+    const labelW = widthOf(["", ...rows.map((r) => r[0])], 12);
+    const colW = labels.map((l, i) => widthOf([l, ...rows.map((r) => r[1][i] ?? "")], 6));
+    const out = [
+        `${pad("", labelW)}  ${labels.map((l, i) => pad(l, colW[i] ?? 6)).join("  ")}`,
+        "-".repeat(labelW + 2 + colW.reduce((n, w) => n + w + 2, 0)),
+    ];
+    for (const [label, values] of rows) {
+        if (values.every((v) => v === "0"))
+            continue;
+        out.push(`${pad(label, labelW)}  ${values.map((v, i) => pad(v, colW[i] ?? 6)).join("  ")}`.trimEnd());
+    }
+    return out;
+}
+function stoppedTable(run) {
+    if (!run.counts.stoppedBy.length)
+        return [];
+    const checkW = widthOf(["check", ...run.counts.stoppedBy.map((s) => s.check)], 5);
+    const out = [
+        `${pad("check", checkW)}  ${pad("stopped", 7)}  example`,
+        "-".repeat(checkW + 2 + 7 + 2 + 40),
+    ];
+    for (const s of run.counts.stoppedBy)
+        out.push(`${pad(s.check, checkW)}  ${String(s.count).padStart(7)}  ${s.example}`);
+    return out;
+}
+export function formatSimulation(result, options = {}) {
+    const limit = options.limit ?? 20;
+    const night = options.night ?? { start: 22, end: 8 };
+    const users = new Set(result.timeline.map((r) => r.userId)).size;
+    const source = options.disagreementsOnly ? result.disagreements : result.timeline;
+    const rows = limit > 0 ? source.slice(0, limit) : source;
+    const reasonsFor = options.reasonsFor ?? result.runs.length - 1;
+    const out = [
+        `proactive-gate simulate  ·  seed ${result.seed}  ·  ${result.events} candidates, ${users} users`,
+        `policies: ${result.runs.map((r) => r.label).join("  |  ")}`,
+        "rows are in the order a server produced them; the time is the recipient's own clock",
+        "",
+        ...timelineTable(result, rows, options.why ? reasonsFor : null),
+    ];
+    if (rows.length < source.length) {
+        out.push(`${source.length - rows.length} more ${options.disagreementsOnly ? "disagreements" : "candidates"} not shown; --limit 0 prints every row, --json prints everything`);
+    }
+    out.push("", `the policies disagreed about ${result.disagreements.length} of ${result.events} candidates`, "");
+    out.push(...summaryTable(result.runs, night));
+    const subject = result.runs[reasonsFor];
+    if (subject && subject.counts.stoppedBy.length) {
+        out.push("", `why ${subject.label} did not send`, "");
+        out.push(...stoppedTable(subject));
+    }
+    const budget = subject?.budget ?? [];
+    if (budget.length) {
+        const busiest = [...budget].sort((a, b) => b.used - a.used || a.userId.localeCompare(b.userId)).slice(0, 5);
+        out.push("", `budget spent, read back out of the store (top ${busiest.length} of ${budget.length} user-days)`, "");
+        for (const row of busiest)
+            out.push(`  ${pad(row.userId, 10)} ${row.localDay}  ${row.used}`);
+    }
+    if (options.people?.length) {
+        out.push("", "who is in the week, and why each one is here", "");
+        for (const line of options.people)
+            out.push(`  ${line}`);
+    }
+    if (options.note)
+        out.push("", options.note);
+    return out.join("\n");
+}
+export { DEMO_WEEK_NOTE };

package/dist/src/simulate.d.ts

@@ -0,0 +1,118 @@
+import type { Check, EvaluateInput, Policy } from "./types.js";
+/** What became of one candidate under one policy. */
+export type SimOutcome = "sent" | "held" | "deferred" | "expired" | "lostAtCommit" | "spentNotDelivered";
+export interface SimRecord {
+    candidateId: string;
+    userId: string;
+    /** The instant this attempt was evaluated at, which for a retry is the deferral's own time. */
+    at: string;
+    /** 1 for the first evaluation, 2 and up for re-evaluations after a deferral. */
+    attempt: number;
+    outcome: SimOutcome;
+    rejectedBy?: string;
+    deferredBy?: string;
+    retryAt?: string;
+    /** Set when a non-rejecting check asked for the send to happen at a later moment. */
+    deliverAt?: string;
+    /** The check's own reason, as the library words it. */
+    reason?: string;
+    /** The whole decision as one sentence, from `explain()`. */
+    sentence?: string;
+}
+export interface SimCounts {
+    candidates: number;
+    /**
+     * Every count below is over final outcomes, one per candidate: a candidate deferred and then
+     * sent is one send, not a deferral and a send. `deferredAtLeastOnce` and `sentAfterDeferral`
+     * are how the holding shows up, and they are the argument that a deferral is not a drop.
+     */
+    sent: number;
+    held: number;
+    expired: number;
+    lostAtCommit: number;
+    spentNotDelivered: number;
+    deferredAtLeastOnce: number;
+    sentAfterDeferral: number;
+    /** Sends a non-rejecting check moved to a later moment, which is neither a hold nor a drop. */
+    sentAtALaterMoment: number;
+    /**
+     * Sends that landed inside the recipient's **own** quiet hours. This is the number that says
+     * whether a stated preference was honoured; a fixed curfew would punish `hana`, who asked for
+     * no quiet hours at all, and would miss a user whose window is 18:00 to 09:00.
+     */
+    sentInQuietHours: number;
+    /** Of those, the ones the documented priority floor lets through on purpose. */
+    sentInQuietHoursByFloor: number;
+    /** Sends inside a fixed 22:00 to 08:00 local window, which is nobody's preference. */
+    sentAtNight: number;
+    /** The most sends one person received in one of their own local days. */
+    busiestUserDay: number;
+    /** How many candidates each check stopped, deferrals included, highest first. */
+    stoppedBy: Array<{
+        check: string;
+        count: number;
+        example: string;
+    }>;
+}
+export interface SimRun {
+    label: string;
+    records: SimRecord[];
+    counts: SimCounts;
+    /** Budget units spent, read back out of the store rather than counted in a local variable. */
+    budget: Array<{
+        userId: string;
+        localDay: string;
+        used: number;
+    }>;
+}
+export interface SimTimelineRow {
+    candidateId: string;
+    userId: string;
+    at: string;
+    /** Month-day and time in the recipient's own zone, which is the clock that judges a message. */
+    localTime: string;
+    type: string;
+    priority: string;
+    /** One cell per policy, in the order the policies were given. */
+    cells: Array<{
+        outcome: SimOutcome;
+        check?: string;
+        sentence?: string;
+        retryAt?: string;
+    }>;
+}
+export interface SimResult {
+    seed: number;
+    events: number;
+    runs: SimRun[];
+    timeline: SimTimelineRow[];
+    /** The candidates the policies disagreed about: the whole argument, in one list. */
+    disagreements: SimTimelineRow[];
+}
+/** A policy to run. Leave both `policy` and `checks` out for the no-gate baseline. */
+export interface SimPolicy {
+    label: string;
+    policy?: Policy;
+    checks?: Check[];
+}
+export interface SimOptions {
+    events: EvaluateInput[];
+    policies: SimPolicy[];
+    /** Seeds the simulated transport, and nothing else. */
+    seed?: number;
+    /** Fraction of simulated sends the fake transport fails. 0 keeps the run about the policy. */
+    transportFailureRate?: number;
+    /** How long a deferred candidate stays worth sending before this scheduler drops it. */
+    expirySeconds?: number;
+    /** The local window counted as night in `sentAtNight`. */
+    night?: {
+        start: number;
+        end: number;
+    };
+}
+export declare const DEFAULT_NIGHT: {
+    start: number;
+    end: number;
+};
+export declare const DEFAULT_EXPIRY_SECONDS: number;
+export declare function simulate(options: SimOptions): Promise<SimResult>;

package/dist/src/simulate.js

@@ -0,0 +1,269 @@
+/**
+ * One stream of candidates, two or more policies, every figure recomputed from the run.
+ *
+ * This adds no check and no store and does not touch the decision path: it runs the gate that
+ * already exists once per policy over the same events and records what happened to each
+ * candidate. The point is the difference between the columns, which is the only honest way this
+ * repository can answer "what would installing this change for me" without asking anyone to
+ * take a number on trust.
+ *
+ * Three distinctions the output keeps apart, because collapsing them is how a simulation lies:
+ *
+ * - **allowed is not sent.** `evaluate` says a message may go, `commit` takes the budget unit
+ *   and can still refuse when a concurrent delivery took the last one, and only then does a
+ *   transport run. `lostAtCommit` and `spentNotDelivered` are counted apart from `sent`.
+ * - **deferred is not rejected.** A deferral carries `retryAt`, and the candidate is
+ *   re-evaluated from scratch at that instant against the same store, so consent, the clock and
+ *   the budget are read again. An old allowed decision is never a standing permission to send.
+ *   A deferral nobody could still act on is counted as `expired` rather than quietly dropped.
+ * - **no gate is not a policy.** The baseline bypasses the gate entirely: every candidate is
+ *   sent. A policy with no checks is not expressible, and a rival built to lose would measure
+ *   nothing. The baseline is what a product does before this library is installed.
+ *
+ * Nothing here reads a wall clock. Every event carries its own `now`, the deferral scheduler
+ * runs on those same instants, and the simulated transport draws from a seeded generator, so a
+ * replay gives the same result on any machine on any day.
+ */
+import { createGate } from "./gate.js";
+import { budgetKey, localClock, quietAt } from "./checks.js";
+import { explain } from "./explain.js";
+import { MemoryStore } from "./stores.js";
+export const DEFAULT_NIGHT = { start: 22, end: 8 };
+export const DEFAULT_EXPIRY_SECONDS = 4 * 60 * 60;
+/** Small deterministic PRNG, so a seed is the whole definition of a run. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const iso = (d) => d.toISOString();
+/** The recipient's own clock, which is the only one a notification is judged by. */
+function localOf(timezone, at) {
+    const clock = localClock(at, timezone ?? "UTC");
+    const hour = Math.floor(clock.minutes / 60);
+    const minute = clock.minutes % 60;
+    return { hour, minute, day: clock.day, text: `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}` };
+}
+const inNight = (hour, night) => night.start <= night.end ? hour >= night.start && hour < night.end : hour >= night.start || hour < night.end;
+function countsOf(records, events, night) {
+    const zones = new Map(events.map((e) => [e.user.id, e.user.timezone]));
+    const quiet = new Map(events.map((e) => [e.user.id, e.user.quietHours]));
+    const floor = new Map(events.map((e) => [e.candidate.id, e.candidate.priority ?? "normal"]));
+    const perUserDay = new Map();
+    const stopped = new Map();
+    // One row per candidate, the last attempt, because that is what became of it. Counting every
+    // attempt would report a candidate that was held until morning as both a deferral and a send.
+    const finals = new Map();
+    for (const r of records)
+        finals.set(r.candidateId, r);
+    const deferredIds = new Set(records.filter((r) => r.outcome === "deferred").map((r) => r.candidateId));
+    let sentAtNight = 0;
+    let sentInQuietHours = 0;
+    let sentInQuietHoursByFloor = 0;
+    for (const r of finals.values()) {
+        if (r.outcome === "sent") {
+            const at = new Date(r.at);
+            const local = localOf(zones.get(r.userId), at);
+            if (inNight(local.hour, night))
+                sentAtNight += 1;
+            const window = quiet.get(r.userId);
+            if (window && quietAt(window, local.day, local.hour * 60 + local.minute)) {
+                sentInQuietHours += 1;
+                if (floor.get(r.candidateId) === "critical")
+                    sentInQuietHoursByFloor += 1;
+            }
+            const key = `${r.userId}:${local.day}`;
+            perUserDay.set(key, (perUserDay.get(key) ?? 0) + 1);
+            continue;
+        }
+        const by = r.rejectedBy ?? r.deferredBy;
+        if (!by)
+            continue;
+        const seen = stopped.get(by);
+        if (seen)
+            seen.count += 1;
+        else
+            stopped.set(by, { count: 1, example: r.reason ?? r.sentence ?? "" });
+    }
+    const finalRows = [...finals.values()];
+    const count = (outcome) => finalRows.filter((r) => r.outcome === outcome).length;
+    return {
+        candidates: finals.size,
+        sent: count("sent"),
+        held: count("held"),
+        expired: count("expired"),
+        lostAtCommit: count("lostAtCommit"),
+        spentNotDelivered: count("spentNotDelivered"),
+        deferredAtLeastOnce: deferredIds.size,
+        sentAfterDeferral: finalRows.filter((r) => r.outcome === "sent" && r.attempt > 1).length,
+        sentAtALaterMoment: finalRows.filter((r) => r.outcome === "sent" && r.deliverAt).length,
+        sentInQuietHours,
+        sentInQuietHoursByFloor,
+        sentAtNight,
+        busiestUserDay: perUserDay.size ? Math.max(...perUserDay.values()) : 0,
+        stoppedBy: [...stopped.entries()]
+            .map(([check, v]) => ({ check, count: v.count, example: v.example }))
+            .sort((a, b) => b.count - a.count || a.check.localeCompare(b.check)),
+    };
+}
+/**
+ * One stream through one gate, with a scheduler for deferrals that belongs to this simulation
+ * rather than to the library: the library never runs a queue. The queue is drained per user just
+ * before that user's next event and again at the end, because budgets are keyed per user and
+ * local day, so each user's own order is what keeps their counter honest.
+ */
+async function runGate(label, gate, store, events, send, expirySeconds, night) {
+    const records = [];
+    const pending = [];
+    const evaluateOnce = async (user, candidate, now, attempt) => {
+        const input = { user, candidate, now };
+        const decision = await gate.evaluate(input);
+        const record = {
+            candidateId: candidate.id,
+            userId: user.id,
+            at: iso(now),
+            attempt,
+            outcome: "held",
+            ...(decision.rejectedBy ? { rejectedBy: decision.rejectedBy } : {}),
+            ...(decision.deferredBy ? { deferredBy: decision.deferredBy } : {}),
+            ...(decision.retryAt ? { retryAt: iso(decision.retryAt) } : {}),
+            ...(decision.deliverAt ? { deliverAt: iso(decision.deliverAt) } : {}),
+            ...(decision.reason ? { reason: decision.reason } : {}),
+            sentence: explain(decision).summary,
+        };
+        if (decision.deferredBy) {
+            const due = decision.retryAt ?? now;
+            const stillWorthIt = due.getTime() <= now.getTime() + expirySeconds * 1000;
+            record.outcome = stillWorthIt ? "deferred" : "expired";
+            if (stillWorthIt)
+                pending.push({ user, candidate, due, attempt: attempt + 1 });
+            records.push(record);
+            return;
+        }
+        if (!decision.allowed) {
+            records.push(record);
+            return;
+        }
+        if (!(await gate.commit(decision, input))) {
+            record.outcome = "lostAtCommit";
+            record.rejectedBy = "commit";
+            record.reason = "a budget was exhausted at commit";
+            records.push(record);
+            return;
+        }
+        record.outcome = send() ? "sent" : "spentNotDelivered";
+        records.push(record);
+    };
+    /** Re-evaluate every deferral for this user due by `upTo`; both null drains what is left. */
+    const drain = async (userId, upTo) => {
+        for (;;) {
+            const index = pending.findIndex((p) => (userId === null || p.user.id === userId) && (upTo === null || p.due.getTime() <= upTo.getTime()));
+            if (index < 0)
+                return;
+            const [item] = pending.splice(index, 1);
+            if (!item)
+                return;
+            await evaluateOnce(item.user, item.candidate, item.due, item.attempt);
+        }
+    };
+    for (const event of events) {
+        const now = event.now ?? new Date(0);
+        await drain(event.user.id, now);
+        await evaluateOnce(event.user, event.candidate, now, 1);
+    }
+    await drain(null, null);
+    // Budget rows come out of the store, one per user and per local day, because that is how the
+    // key is shaped (spec/SPEC.md 5.1). One number per user would report a counter that has just
+    // rolled over and hide what the day before spent.
+    const zones = new Map(events.map((e) => [e.user.id, e.user.timezone]));
+    const wanted = new Map();
+    for (const r of records) {
+        const key = budgetKey(r.userId, new Date(r.at), zones.get(r.userId));
+        if (!wanted.has(key))
+            wanted.set(key, { userId: r.userId, localDay: key.slice(key.lastIndexOf(":") + 1), key });
+    }
+    const budget = [];
+    for (const row of [...wanted.values()].sort((a, b) => a.userId.localeCompare(b.userId) || a.localDay.localeCompare(b.localDay))) {
+        const used = Number((await store.get(`pg:${row.key}`)) ?? 0);
+        if (used > 0)
+            budget.push({ userId: row.userId, localDay: row.localDay, used });
+    }
+    return { label, records, counts: countsOf(records, events, night), budget };
+}
+/** Every candidate is sent. What a product does before this library is installed. */
+function runBaseline(label, events, send, night) {
+    const records = events.map((e) => ({
+        candidateId: e.candidate.id,
+        userId: e.user.id,
+        at: iso(e.now ?? new Date(0)),
+        attempt: 1,
+        outcome: send() ? "sent" : "spentNotDelivered",
+    }));
+    return { label, records, counts: countsOf(records, events, night), budget: [] };
+}
+/** The last attempt is what became of a candidate; earlier attempts are how it got there. */
+function finalOf(run, candidateId) {
+    const attempts = run.records.filter((r) => r.candidateId === candidateId);
+    return attempts.length ? attempts[attempts.length - 1] : undefined;
+}
+export async function simulate(options) {
+    const seed = options.seed ?? 1;
+    const failureRate = options.transportFailureRate ?? 0;
+    const expirySeconds = options.expirySeconds ?? DEFAULT_EXPIRY_SECONDS;
+    const night = options.night ?? DEFAULT_NIGHT;
+    const { events, policies } = options;
+    if (!events.length)
+        throw new Error("simulate: no events to run");
+    if (!policies.length)
+        throw new Error("simulate: no policies to run");
+    const runs = [];
+    for (const entry of policies) {
+        // A transport per run, seeded identically, so one run's failures cannot move another's.
+        const random = mulberry32(seed);
+        const send = () => random() >= failureRate;
+        if (!entry.policy && !entry.checks) {
+            runs.push(runBaseline(entry.label, events, send, night));
+            continue;
+        }
+        const store = new MemoryStore();
+        const gate = entry.policy
+            ? createGate({ policy: entry.policy, store })
+            : createGate({ checks: entry.checks ?? [], store });
+        runs.push(await runGate(entry.label, gate, store, events, send, expirySeconds, night));
+    }
+    const timeline = events.map((event) => {
+        const at = event.now ?? new Date(0);
+        const local = localOf(event.user.timezone, at);
+        return {
+            candidateId: event.candidate.id,
+            userId: event.user.id,
+            at: iso(at),
+            localTime: `${local.day.slice(5)} ${local.text}`,
+            type: event.candidate.type,
+            priority: event.candidate.priority ?? "normal",
+            cells: runs.map((run) => {
+                const record = finalOf(run, event.candidate.id);
+                if (!record)
+                    return { outcome: "held" };
+                const check = record.rejectedBy ?? record.deferredBy;
+                return {
+                    outcome: record.outcome,
+                    ...(check ? { check } : {}),
+                    ...(record.sentence ? { sentence: record.sentence } : {}),
+                    ...(record.retryAt ? { retryAt: record.retryAt } : {}),
+                };
+            }),
+        };
+    });
+    return {
+        seed,
+        events: events.length,
+        runs,
+        timeline,
+        disagreements: timeline.filter((row) => new Set(row.cells.map((c) => c.outcome)).size > 1),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.5.0",
+  "version": "0.6.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 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",
+    "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/simulate.test.js dist/test/monotonicity.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/playground-render.test.mjs test/playground-scenarios.test.mjs test/snippet.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",
@@ -61,7 +61,8 @@
     "bench:compare": "npm run build && node bench/compare.mjs",
     "conformance-table": "node scripts/conformance-table.mjs",
     "explain-parity": "node scripts/explain-parity.mjs",
-    "og": "npm run build && node scripts/og-image.mjs"
+    "og": "npm run build && node scripts/og-image.mjs",
+    "simulate": "npm run build && node dist/src/cli.js simulate"
   },
   "engines": {
     "node": ">=20"

package/spec/CONFORMANCE.md

@@ -83,3 +83,47 @@ weaker evidence than it looks: agreement between two implementations by one auth
 consistency check than to independent verification. A third implementation, written from `SPEC.md`
 by someone who has not read the source, is what would test whether this document is enough. Until
 that exists, treat the suite as a contract that has been used twice, not as a proven standard.
+
+## Implementing this in your language
+
+This is the one thing the project is actively asking for, and it is deliberately the last section
+of this document: everything above is what you need, and nothing below it is required of you.
+
+**The shape of the work.** A conforming implementation is a decision loop over an ordered list of
+checks and a key-value store with a counter. There is no network, no dependency, no framework and
+no content inspection anywhere in it. The TypeScript version is about 1,400 lines of source and the
+Python sibling about the same, and most of that is the twelve checks, each of which is a small pure
+function over a user, a candidate and an instant.
+
+**The order to do it in**, which is how both existing versions were built:
+
+1. Vendor the suite at a tag rather than a branch: `git clone --depth 1 --branch spec/vX.Y.Z` or a
+   subtree, and assert in your tests that the `SPEC_VERSION` you vendored is the one you claim.
+2. Write the fixture loader first. Each file under `fixtures/` is a policy plus a list of cases,
+   each case an input and an expectation, and the loader is the only part that touches JSON.
+3. Make one fixture pass, in this order: `consent`, then `quiet-hours/istanbul`, then
+   `budget/daily-atomic-commit`. Those three exercise the whole spine: ordering, a wall clock in a
+   named zone, and a counter that has to be atomic at commit.
+4. Then the rest, in whatever order the failures suggest. `spec/SPEC.md` is numbered, and every
+   fixture names the requirement it came from.
+
+**What passing means** is defined above and is not negotiable in one direction: a fixture you do
+not pass is declared in your skip file with a reason, in the open. Silence about a failing fixture
+is the one thing that makes a conformance claim worthless.
+
+**What you may leave out.** Presets, adapters, the JSON policy compiler, `explain()`, the CLI and
+the simulator are all optional; the fixtures that exercise them are the ones to declare as skipped.
+The twelve checks, the ordering rules, the store contract and the commit-time budget are not
+optional, because they are what the word conform refers to.
+
+**What we will do with it.** If you say it conforms and the fixtures agree, it goes in the README
+next to the other two implementations, under your name, with the version of the spec it targets.
+If it does not conform yet, say which fixtures and it goes in as a work in progress, because an
+honest partial claim is more useful to a reader than an absent one.
+
+**What we will not do.** We will not write it for you and then call it independent. The value of a
+third implementation is exactly that its author was not us, so a version written here would be
+worth less than the four days it took somebody else.
+
+Issue [#16](https://github.com/Bubblegunn/proactive-gate/issues/16) is the place to say you are
+starting, so two people do not write the same one.