proactive-gate 0.4.1 → 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:
 
 ```
@@ -44,7 +105,7 @@ npx proactive-gate init --preset usTcpa --framework mastra
 
 That writes `proactive-gate.policy.json` with the ten checks in order, appends the
 preset you named, and prints the preset's own source next to the few lines that plug
-the gate into that framework. `npx proactive-gate init --list` shows the fourteen
+the gate into that framework. `npx proactive-gate init --list` shows the fifteen
 platform and legal presets and the four frameworks.
 
 If you would rather see the argument than read it: `npm run bench:compare` replays a
@@ -361,6 +422,7 @@ const gate = createGate({ checks: [checks.consent(), ...presets.kakaoBrandMessag
 | `krNetworkAct50` | advertising consent, plus night consent for 21:00 to 08:00 local |
 | `jpAntiSpamLaw` | opt-in |
 | `cnMinorMode` | for minors: 06:00 to 22:00 Asia/Shanghai and one a day |
+| `inTcccp` | promotional consent; the default-off bands 00:00 to 10:00 and 21:00 to 24:00 need their own opt-in |
 | `usTcpa` | 08:00 to 21:00 at the user's local time (47 CFR 64.1200) |
 | `euEprivacy` | marketing consent with the soft opt-in for existing customers |
 | `telegramBot` | 1 a second and 20 a minute per chat |
@@ -371,23 +433,30 @@ out. Reviewable defaults, not legal advice: several official sources disagree wi
 and the note says which value was chosen and why.
 
 **Read the scope before you reach for a legal preset.** Every instrument above regulates
-*commercial* communication. `usTcpa`, `euEprivacy`, `krNetworkAct50` and `jpAntiSpamLaw` are
-marketing rules, so they bind your message only when the message itself is commercial. A
-reminder your user asked for is not advertising, and pulling in a marketing preset for it
+*commercial* communication. `usTcpa`, `euEprivacy`, `krNetworkAct50`, `jpAntiSpamLaw` and
+`inTcccp` are marketing rules, so they bind your message only when the message itself is
+commercial. A reminder your user asked for is not advertising, and pulling in a marketing preset for it
 imports a restriction the law never placed on you, which is its own kind of wrong answer.
 Use them when the candidate is promotional; when it is not, the platform quotas and your own
-quiet hours are the honest constraints.
+quiet hours are the honest constraints. A preset that reads the recipient's own zone
+(`usTcpa`, `krNetworkAct50`, `inTcccp`) has no local time to compare without `user.timezone`,
+so those checks skip and the message goes out; each preset's note says so, and a user with no
+zone is the case to handle before you rely on one of them.
 
 That scope test is also why some jurisdictions people ask for are missing. Canada's CASL and
 Australia's Spam Act 2003 set consent, identification and unsubscribe duties, and neither
 carries a time-of-day rule at all. The Brazilian window quoted around the web comes from bill
 PLS 48/2018, a proposal rather than enacted law, and it covers telemarketing calls. India is
-the interesting one: the widely repeated "9am to 9pm" is not what the primary text says. The
-Telecom Commercial Communications Customer Preference Regulations make time bands a
+the interesting one, and the widely repeated "9am to 9pm" is not what the primary text says.
+The Telecom Commercial Communications Customer Preference Regulations make time bands a
 *preference the subscriber registers* with their access provider, alongside content category
 and day type, not a fixed statutory quiet window, and the secondary sources that quote a
-window disagree with each other about whether it starts at 09:00 or 10:00. A preset built on
-that would encode a number no primary source states, so there is none.
+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. 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
 
@@ -653,7 +722,7 @@ reproduces exactly. The race property was checked against a mutant: rewriting
 [`spec/SPEC.md`](spec/SPEC.md) states the behaviour as numbered requirements, and
 [`spec/fixtures`](spec/fixtures) holds language-neutral cases: the DST edge in
 America/New_York, Pacific/Apia, a wall-clock case in 2031, atomic commit, the ISO week,
-deferral, shadow mode, the optional checks and four presets. The TypeScript tests and the
+deferral, shadow mode, the optional checks and six presets. The TypeScript tests and the
 Python tests both run all of them; `npx proactive-gate replay --fixtures spec/fixtures` runs
 them from the command line. A third implementation starts from the fixtures, not from this
 source.
@@ -664,7 +733,7 @@ package's release tags, so an implementation in any language can pin it without
 or PyPI:
 
 ```sh
-git clone --depth 1 --branch spec/v1.2.0 https://github.com/Bubblegunn/proactive-gate
+git clone --depth 1 --branch spec/v1.3.0 https://github.com/Bubblegunn/proactive-gate
 ```
 
 The npm package also ships it, so `node_modules/proactive-gate/spec/fixtures` exists after an
@@ -677,8 +746,8 @@ Generated by `npm run conformance-table`; CI fails when it is stale.
 
 | implementation | spec version | fixtures passed | declared skips |
 |---|---|---:|---|
-| TypeScript | 1.2.0 | 32 of 32 | none |
-| Python | 1.2.0 | 32 of 32 | none |
+| TypeScript | 1.3.0 | 33 of 33 | none |
+| Python | 1.3.0 | 33 of 33 | none |
 <!-- conformance:end -->
 
 ### What made this work elsewhere, and why it might not here
@@ -785,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,6 +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 ([@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 |
@@ -333,11 +379,15 @@ Her paket `sources` (sayıların geldiği sayfalar) ve neyi dışarıda bırakt
 birbiriyle çelişir ve not hangi değerin neden seçildiğini söyler.
 
 **Yasal bir pakete uzanmadan önce kapsamını okuyun.** Yukarıdaki bütün düzenlemeler *ticari*
-iletişimi düzenler. `usTcpa`, `euEprivacy`, `krNetworkAct50` ve `jpAntiSpamLaw` birer pazarlama
+iletişimi düzenler. `usTcpa`, `euEprivacy`, `krNetworkAct50`, `jpAntiSpamLaw` ve `inTcccp` birer pazarlama
 kuralıdır; yani mesajınızı ancak mesajın kendisi ticari olduğunda bağlar. Kullanıcının kendi
 istediği bir hatırlatma reklam değildir ve onun için pazarlama paketi kullanmak, yasanın size
 hiç koymadığı bir kısıtı kendi elinizle içeri almak olur. Aday promosyon niteliğindeyse
 kullanın; değilse dürüst sınırlar platform kotaları ve kendi sessiz saatlerinizdir.
+Alıcının kendi saat dilimini okuyan paketlerde (`usTcpa`, `krNetworkAct50`, `inTcccp`)
+`user.timezone` yoksa karşılaştırılacak yerel saat de yoktur: o kontroller atlanır ve mesaj
+çıkar. Her paketin notu bunu söyler; saat dilimi olmayan kullanıcı, bu paketlerden birine
+güvenmeden önce çözülmesi gereken durumdur.
 
 Bazı ülkelerin neden burada olmadığı da aynı kapsam sınavıyla açıklanır. Kanada'nın CASL'i ve
 Avustralya'nın 2003 tarihli Spam Act'i rıza, gönderen kimliği ve abonelikten çıkma
@@ -347,8 +397,10 @@ telefonla pazarlama aramalarını kapsar. Hindistan ilginç olanı: sıkça tekr
 birincil metinde yazmaz. TRAI düzenlemesi zaman bantlarını, içerik kategorisi ve gün tipiyle
 birlikte, abonenin operatörüne *kaydettirdiği bir tercih* yapar; sabit bir yasal sessizlik
 penceresi değildir. Üstelik pencereyi aktaran ikincil kaynaklar başlangıcın 09.00 mı 10.00 mı
-olduğunda birbiriyle çelişir. Bunun üzerine kurulacak bir paket, hiçbir birincil kaynağın
-yazmadığı bir sayıyı kodlardı; o yüzden yok.
+olduğunda birbiriyle çelişir. Düzenlemenin sabitlediği şey varsayılan durumdur:
+Schedule-II'deki dokuz bandın dördü, yani 00:00-10:00 ve 21:00-24:00 arasını kapsayanlar,
+abone o bandı açmadıkça her müşteri için kapalıdır. `inTcccp` bu bantları sabit bir pencere
+yerine bant başına birer opt-in rızası olarak kodlar.
 
 ## Adaptörler
 

package/dist/src/checks.js

@@ -489,8 +489,10 @@ export function requiresConsent(options) {
                 const zone = zoneOf(ctx, when.timezone);
                 if (!zone)
                     return skip("no timezone on the user; consent window cannot be evaluated");
+                // A bare pass here would be indistinguishable from "the consent is on file",
+                // and explain() said exactly that about a consent nobody had given.
                 if (!inWindow(localClock(ctx.now, zone).minutes, when.start, when.end))
-                    return pass;
+                    return { kind: "pass", reason: `outside the consent window ${options.when.start} to ${options.when.end}` };
             }
             return ctx.user.consents?.[options.name] ? pass : reject(`consent "${options.name}" is missing${when ? ` (required ${options.when.start} to ${options.when.end})` : ""}`);
         },

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/explain.js

@@ -89,7 +89,11 @@ export const en = {
     "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.pass": (f) => f.start
+        ? `the ${f.name ? `"${f.name}" ` : ""}consent is only needed between ${f.start} and ${f.end}, and it was outside those hours`
+        : 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",
@@ -163,6 +167,7 @@ const PARSERS = {
     },
     requiresConsent: {
         stop: match(/^consent "(.+)" is missing(?: \(required (\S+) to (\S+)\))?$/, ["name", "start", "end"]),
+        passReason: match(/^outside the consent window (\S+) to (\S+)$/, ["start", "end"]),
         idFacts: (id) => (id.startsWith("consent:") ? { name: id.slice("consent:".length) } : {}),
         skip: fixed("no timezone on the user; consent window cannot be evaluated"),
     },
@@ -245,8 +250,9 @@ function entryBody(entry, s) {
         case "pass": {
             if (reason) {
                 const facts = key ? PARSERS[key]?.passReason?.(reason) : BUDGET_NEAR(reason);
+                // The id carries facts a reason does not, like which consent this is.
                 if (facts)
-                    return t(s, `${key ?? "budget"}.pass`, facts);
+                    return t(s, `${key ?? "budget"}.pass`, { ...(key ? (PARSERS[key]?.idFacts?.(entry.id) ?? {}) : {}), ...facts });
                 return t(s, "fallback.pass", { id: entry.id, reason });
             }
             const facts = key ? (PARSERS[key]?.idFacts?.(entry.id) ?? {}) : {};

package/dist/src/presets.js

@@ -27,7 +27,7 @@ export const presets = {
     wecomAppMessage: define(() => [c.rateLimit({ limit: 30, perSeconds: 60, id: "rate:30/min" }), c.rateLimit({ limit: 1000, perSeconds: 3600, id: "rate:1000/h" })], ["https://developer.work.weixin.qq.com/document/path/96212"], "WeCom application messages per app per member: 30 a minute and 1,000 an hour; the platform drops the excess silently, this preset refuses it with a reason."),
     kakaoAlimtalk: define(() => [c.consent()], ["https://kakaobusiness.gitbook.io/main/ad/infotalk"], "AlimTalk is informational and carries no time-of-day limit; consent is the only gate."),
     kakaoBrandMessage: define(() => [c.requiresConsent({ name: "ad" }), c.allowedWindow({ start: "08:00", end: "20:50", timezone: "Asia/Seoul", id: "window:kakao" })], ["https://kakaobusiness.gitbook.io/main/ad/moment/messagead/channelmessage/new/send"], "Brand messages need advertising consent and go out 08:00 to 20:50 Korea time regardless of the recipient's location. Official sources also quote 20:00 and 20:55; 20:50 is the stricter documented value."),
-    krNetworkAct50: define(() => [c.requiresConsent({ name: "ad" }), c.requiresConsent({ name: "night", when: { start: "21:00", end: "08:00", timezone: "user" } })], ["https://www.law.go.kr", "https://developers.fingerpush.com/biz-message/console/ads-guide"], "Network Act article 50: prior consent for advertising, and a separate consent for 21:00 to 08:00 (email is exempt). The two-year re-confirmation is not encoded."),
+    krNetworkAct50: define(() => [c.requiresConsent({ name: "ad" }), c.requiresConsent({ name: "night", when: { start: "21:00", end: "08:00", timezone: "user" } })], ["https://www.law.go.kr", "https://developers.fingerpush.com/biz-message/console/ads-guide"], "Network Act article 50: prior consent for advertising, and a separate consent for 21:00 to 08:00 (email is exempt). Without user.timezone the night consent cannot be placed in the day and skips; the advertising consent still applies. The two-year re-confirmation is not encoded."),
     jpAntiSpamLaw: define(() => [c.requiresConsent({ name: "optIn" })], ["https://www.soumu.go.jp/main_sosiki/cybersecurity/kokumin/basic/legal/08/"], "Opt-in since 2008 with sender identity and an opt-out route. There is no time-of-day rule in the law; a Japanese quiet-hours window would be etiquette, so none is encoded."),
     cnMinorMode: define(() => {
         const window = c.allowedWindow({ start: "06:00", end: "22:00", timezone: "Asia/Shanghai", id: "window:minor" });
@@ -38,7 +38,21 @@ export const presets = {
             { id: budget.id, limit: budget.limit, run: (ctx) => (ctx.user.minor ? budget.run(ctx) : adult(ctx)), consume: (ctx) => (ctx.user.minor ? budget.consume(ctx) : Promise.resolve(true)) },
         ];
     }, ["https://www.cac.gov.cn/2024-11/15/c_1733364304749288.htm", "https://www.cac.gov.cn/2022-01/04/c_1642894606364259.htm"], "Minor mode: no service 22:00 to 06:00 China time and a daily budget of one when user.minor is true; adults pass both checks. Per-age daily durations are not encoded."),
-    usTcpa: define(() => [c.allowedWindow({ start: "08:00", end: "21:00", timezone: "user", id: "window:tcpa" })], ["https://www.law.cornell.edu/cfr/text/47/64.1200"], "47 CFR 64.1200: no solicitation before 8 a.m. or after 9 p.m. at the called party's local time."),
+    // India: TCCCPR 2018 (6 of 2018). Regulation 9 lets a commercial communication reach a
+    // recipient only per the recipient's registered preference or consent; Schedule-II item 3
+    // fixes nine time bands and keeps (i) 00:00-06:00, (ii) 06:00-08:00, (iii) 08:00-10:00
+    // and (ix) 21:00-24:00 default OFF for every customer until the subscriber switches that
+    // band on, which the four band flags below carry. The second source is the gazetted
+    // regulation and the third is the May 2026 consolidation, which says on its own first
+    // page that the gazetted text prevails where they differ. Read 2026-09-12.
+    inTcccp: define(() => [
+        c.requiresConsent({ name: "promotional" }),
+        c.requiresConsent({ name: "band00to06", when: { start: "00:00", end: "06:00", timezone: "user" } }),
+        c.requiresConsent({ name: "band06to08", when: { start: "06:00", end: "08:00", timezone: "user" } }),
+        c.requiresConsent({ name: "band08to10", when: { start: "08:00", end: "10:00", timezone: "user" } }),
+        c.requiresConsent({ name: "band21to24", when: { start: "21:00", end: "24:00", timezone: "user" } }),
+    ], ["https://trai.gov.in/tcccpr", "https://www.trai.gov.in/sites/default/files/2025-01/RegulationUcc19072018.pdf", "https://www.trai.gov.in/sites/default/files/2026-05/CA_21052026.pdf"], "TCCCPR 2018: commercial communication needs the recipient's registered preference or consent (consents.promotional), and the Schedule-II default-off bands pass only when the subscriber opted that band in (the consents.band* flags, at the recipient's local time). The preference machinery is about promotional communication: the regulation's own block options exempt transactional and service communication and government communication (Schedule-II item 1 Note-4, item 3 Note-4), so pointing this preset at a transactional message imports a restriction the regulation does not place on it. Without user.timezone the four band checks skip and only the promotional consent is left. Opt-outs inside the default-on 10:00 to 21:00, day-type and per-category preferences are per-subscriber state a fixed check list cannot express; carry them in user.quietHours and consents. It binds SMS and voice calls on access networks, not in-app notifications or email; 1909 and DLT registration are out of scope. Sources read 2026-09-12."),
+    usTcpa: define(() => [c.allowedWindow({ start: "08:00", end: "21:00", timezone: "user", id: "window:tcpa" })], ["https://www.law.cornell.edu/cfr/text/47/64.1200"], "47 CFR 64.1200: no solicitation before 8 a.m. or after 9 p.m. at the called party's local time. Without user.timezone there is no local time to compare, so the check skips and the caller is not covered."),
     euEprivacy: define(() => [{ ...c.requiresConsent({ name: "marketing" }), run: (ctx) => (ctx.user.existingCustomer ? { kind: "pass", reason: "existing customer, soft opt-in" } : c.requiresConsent({ name: "marketing" }).run(ctx)) }], ["https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32002L0058"], "Directive 2002/58/EC article 13: prior consent for direct marketing, with the soft opt-in for existing customers (user.existingCustomer)."),
     telegramBot: define(() => [c.rateLimit({ limit: 1, perSeconds: 1, keyBy: "channel", id: "rate:1/s" }), c.rateLimit({ limit: 20, perSeconds: 60, keyBy: "channel", id: "rate:20/min" })], ["https://core.telegram.org/bots/faq"], "One message a second per chat and twenty a minute per group, keyed by candidate.channel. The broadcast rate of roughly thirty a second is not encoded."),
     slackApp: define(() => [c.rateLimit({ limit: 1, perSeconds: 1, keyBy: "channel", id: "rate:1/s" })], ["https://docs.slack.dev/apis/web-api/rate-limits/"], "chat.postMessage: one message a second per channel, keyed by candidate.channel."),