proactive-gate 0.1.2 → 0.2.0

package/README.md

@@ -37,11 +37,24 @@ if (decision.allowed && (await gate.commit(decision, { user, candidate }))) {
 }
 ```
 
+Or start from a policy file and the wiring for your framework, in one command:
+
+```
+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
+platform and legal presets and the four frameworks.
+
 Zero dependencies. TypeScript. Node 20 or newer. Framework-agnostic: the gate sits
 between "the model produced something" and "the user's phone buzzed", whichever
 model or framework produced it. Examples: [`examples/vercel-ai-sdk.ts`](examples/vercel-ai-sdk.ts),
 [`examples/mastra.ts`](examples/mastra.ts), [`examples/langgraph.ts`](examples/langgraph.ts), and a
-replayable policy in [`examples/policy.js`](examples/policy.js). API reference: [`docs/api`](docs/api/README.md).
+replayable policy in [`examples/policy.json`](examples/policy.json). Docs and a browser playground:
+[bubblegunn.github.io/proactive-gate](https://bubblegunn.github.io/proactive-gate/). API reference:
+[`docs/api`](docs/api/README.md). Python: [`python/`](python/README.md).
 
 ## What a decision looks like
 
@@ -67,7 +80,10 @@ replayable policy in [`examples/policy.js`](examples/policy.js). API reference:
 }
 ```
 
-<p align="center"><img src="assets/trace.png" width="900" alt="A real decision trace: eight checks ran, quiet hours rejected, each with its reason and cost"></p>
+<p align="center"><img src="docs/assets/trace.svg" width="900" alt="Two real decision traces side by side: candidate a1 rejected by quietHours after eight checks, candidate a5 allowed after thirteen, each check with its outcome, reason and cost"></p>
+
+The figure is drawn from the replay's `--json` output by `node scripts/trace-svg.mjs`, every
+line verbatim; the left decision is the one printed above.
 
 With one gate and a logged reason, "why was the user not told about this" has an
 answer. With checks scattered through a pipeline, the honest answer is "somewhere,
@@ -138,6 +154,102 @@ Mark a check `nonRejecting: true` when it may only move timing or narrow surface
 gate then ignores a reject from it and says so in the trace, so a bug in a timing model
 cannot silence a user.
 
+## A policy is data
+
+The same checks as a JSON document, so a product team can change the rules without a
+deploy and the same file runs in TypeScript, in Python, in the CLI and in the
+[playground](https://bubblegunn.github.io/proactive-gate/playground/):
+
+```json
+{
+  "specVersion": "1.0.0",
+  "checks": [
+    { "id": "consent" },
+    { "id": "snooze", "defer": true },
+    { "id": "quietHours", "priorityFloor": "high" },
+    { "preset": "usTcpa" },
+    { "id": "utilityFloor", "costFalseAlarm": 1, "costMissedHelp": 2, "shadow": true },
+    { "id": "dailyBudget", "limit": 3, "bypassPriority": "critical", "nearLimit": 0.67 }
+  ]
+}
+```
+
+```ts
+const gate = createGate({ policy: JSON.parse(await readFile("policy.json", "utf8")), store });
+```
+
+Each entry names a check `id` or a `preset` plus that check's options. An unknown id throws
+and names the known ones. `compilePolicy` is exported for callers that want the check list,
+and the schema is at [`spec/schema/policy.schema.json`](spec/schema/policy.schema.json).
+`examples/policy.js` stays as the escape hatch for checks that need functions.
+
+## Defer, shadow mode, near-limit notes and hooks
+
+A check can `defer` instead of rejecting: the decision has `allowed: false`, `deferredBy` and
+`retryAt`, and the caller knows when to try again. `snooze({ defer: true })` is the built-in
+example.
+
+A check with `shadow: true` runs and is traced with its real outcome, but cannot stop the
+message; its id lands in `decision.shadowed`. Ship a new rule in shadow for a week, count how
+often it would have fired, then turn it on.
+
+Budgets report `nearLimit: { used, limit }` on the pass that reaches the threshold (80 percent
+by default), listed under `decision.nearLimit`, so a dashboard can show who is about to go
+quiet.
+
+`hooks: { before, after, error, finally }` observe every check with its cost in milliseconds;
+a hook that throws is routed to `error` and never changes the decision. `examples/otel.ts`
+turns them into one span per check. Every decision has an `id`, and `commit` is idempotent on
+it: a retry after a timeout does not consume a second unit.
+
+## Optional checks, fed by your own model
+
+Both ship off. They read numbers the caller puts on the candidate.
+
+- `utilityFloor({ costFalseAlarm, costMissedHelp })` acts only when `candidate.pAccept` clears
+  `tau = cFA / (cFA + pNeed * cFN)` (`pNeed` defaults to 1) and skips when there is no
+  `pAccept`. This is Horvitz's expected-utility rule with the PRISM threshold.
+- `boundedDeferral({ lambda, interruptCost, staleness, boundSeconds })` never rejects. When
+  `candidate.busy` is true it moves `deliverAt` to `now + t*`, with
+  `t* = min(bound, lambda * interruptCost / (2 * staleness))`; the defaults give 116 seconds.
+
+Neither check ships a model, a cost or a probability. `costFalseAlarm`, `costMissedHelp`,
+`interruptCost` and `staleness` are yours to measure, and the package has no opinion about
+what an interruption costs your users. The rules come from Eric Horvitz's work on
+attention-sensitive alerting and bounded deferral; the field measurement people usually
+reach for is [Iqbal and Horvitz, "Disruption and recovery of computing tasks", CHI
+2007](https://erichorvitz.com/CHI_2007_Iqbal_Horvitz.pdf), which logged real users and put
+the return to a suspended task in the region of 11 to 16 minutes. The widely repeated "23
+minutes 15 seconds" figure is not from a peer-reviewed paper and is not used here.
+
+## Presets: platform quotas and legal limits, with sources
+
+```ts
+import { presets } from "proactive-gate/presets";
+const gate = createGate({ checks: [checks.consent(), ...presets.kakaoBrandMessage()] });
+```
+
+| preset | encodes |
+|---|---|
+| `lineMessagingApi({ plan })` | monthly push budget by LINE plan: 200, 5,000 or 30,000 |
+| `wechatSubscriptionMessage` | one message per subscription opt-in |
+| `wechatCustomerService` | within 48 h of the user's last message, at most 5 |
+| `wechatTemplateMessage` | only after a user action, 3 templates a day |
+| `wecomAppMessage` | 30 a minute and 1,000 an hour per member |
+| `kakaoAlimtalk` | consent only; AlimTalk has no time-of-day rule |
+| `kakaoBrandMessage` | advertising consent, 08:00 to 20:50 Asia/Seoul |
+| `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 |
+| `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 |
+| `slackApp` | 1 a second per channel |
+
+Each preset carries `sources` (the pages the numbers come from) and a `note` on what it leaves
+out. Reviewable defaults, not legal advice: several official sources disagree with each other,
+and the note says which value was chosen and why.
+
 ## The budget is enforced at commit, not at evaluate
 
 Two instances can both evaluate a candidate for the same user, both see four of
@@ -210,22 +322,115 @@ to keep once the checks are scattered:
 - A policy can be replayed over a day of real candidates before it ships, and a non-rejecting
   check cannot reject even if a bug makes it try.
 
+Those are claims, so the repository runs them. `npm run bench:compare` replays a
+committed day of 21 candidates for 7 users through `bench/naive.mjs`, an honest
+hand-rolled policy of five `if` statements, and through a gate built from
+`bench/fixtures/policy.json`:
+
+```
+gate:        11 sent, 10 stopped
+hand-rolled: 13 sent, 8 stopped
+
+6 disagreements, and none of them is a matter of taste:
+  a5  a critical alert: the gate lets priority bypass the cap, the cap in the if statements does not
+  b1  a two-day-old account: the gate holds normal messages back for a week, the if statements never knew
+  c1  the user pressed snooze: the gate defers to when it ends, the if statements have no snooze
+  e1  three dismissals of this type: the gate is silent for a week, the if statements do not track outcomes
+  f4  01:00 in Tokyo, a new local day: the gate resets the cap, the UTC-day key stays on yesterday for nine more hours
+  g4  18:00 in Los Angeles, still the same local day: the UTC-day key already rolled, so the cap pays out twice
+```
+
+The hand-rolled policy is not a straw man. It checks consent, enabled, mute, quiet
+hours and a daily cap, which is what actually gets written, and it takes the three
+shortcuts that actually get taken: a fixed UTC offset per zone, the cap keyed by the
+UTC calendar day, and the cap read then written. `test/naive.test.mjs` pins each one
+against a real instant:
+
+- The clocks change. At `2026-11-01T12:30:00Z` New York has left daylight time, so it is
+  07:30 there and inside quiet hours; an offset captured in the summer computes 08:00 and
+  sends. That is twice a year, for every zone that observes it.
+- The day boundary is local. The same UTC-day key silences the Tokyo user for the nine
+  hours between local midnight and 09:00, and hands the Los Angeles user a second full
+  budget at 17:00 while it is still their afternoon.
+- Two deliveries are in flight. Read, compare, write lets both take the last slot, and the
+  counter still reads 2 afterwards, so nothing looks wrong. `commit()` takes the unit with
+  an atomic increment and returns `false` to the loser.
+
 A feature-flag system does a different job better: rolling a behaviour out to a percentage
 of users, per-tenant overrides, and an audit trail of who flipped what. Use flags to decide
 whether the gate runs at all, and the gate to decide whether this message reaches this
 person now.
 
-## Integrations
+## Adapters
 
-| framework | example | where the gate sits |
+| subpath | framework | where the gate sits |
 |---|---|---|
-| Vercel AI SDK | [`examples/vercel-ai-sdk.ts`](examples/vercel-ai-sdk.ts) | after `generateText`, before the push |
-| Mastra | [`examples/mastra.ts`](examples/mastra.ts) | after `agent.generate`, before the send |
-| LangGraph | [`examples/langgraph.ts`](examples/langgraph.ts) | inside the `notify` node, before the tool call |
+| `proactive-gate/ai-sdk` | Vercel AI SDK | answers a tool's `needsApproval` ([`examples/vercel-ai-sdk.ts`](examples/vercel-ai-sdk.ts); runnable offline: [`examples/ai-sdk/`](examples/ai-sdk/)) |
+| `proactive-gate/mastra` | Mastra | an output processor before the send ([`examples/mastra.ts`](examples/mastra.ts); runnable offline: [`examples/mastra/`](examples/mastra/)) |
+| `proactive-gate/langchain` | LangChain | middleware around the send tool |
+| `proactive-gate/openai-agents` | OpenAI Agents | a guardrail |
+| `npx proactive-gate hook` | Claude Code | a `PreToolUse` hook ([`examples/claude-code-hook.json`](examples/claude-code-hook.json)) |
+
+The adapters are typed against the shape of a call, not against the framework package, so
+nothing else has to be installed. Each denies with the gate's reason and commits the budget on
+approval. The pattern is the same everywhere: the model decides whether there is something to
+say, `gate.evaluate` decides whether it may be said now, and `gate.commit` runs right before
+the message leaves. [`examples/langgraph.ts`](examples/langgraph.ts) shows the same thing
+inside a LangGraph node.
+
+Two of the examples run without the framework installed and without a network: `node
+examples/mastra/run.mjs` makes the same `processOutputResult` call Mastra makes, over a day of
+candidates with the clock taken from each line, and `node examples/ai-sdk/run.mjs` answers a
+day of tool-approval requests, one of which is a critical alert that a legal window (the TCPA
+preset) still refuses. Both are part of `npm run examples` and of the test suite.
+
+## Python
+
+```
+pip install proactive-gate
+```
 
-The pattern is the same everywhere: the model decides whether there is something to say,
-`gate.evaluate` decides whether it may be said now, and `gate.commit` runs right before the
-message leaves.
+```python
+from proactive_gate import Gate
+gate = Gate.from_policy(policy)          # the same policy.json
+decision = gate.evaluate(inp)
+if decision.allowed and gate.commit(decision, inp): send(...)
+```
+
+`python/` is a sibling, not a port that drifts: it passes every fixture under `spec/fixtures`
+through a sync `Gate` and an `AsyncGate` (Redis over `redis.asyncio`), with mypy strict, on
+Python 3.11 and 3.13 in CI. See [`python/README.md`](python/README.md).
+
+## Properties, not just examples
+
+`test/properties.test.ts` generates gates, users and candidates from a seeded
+32-bit PRNG and asserts what has to hold for all of them, rather than for the
+cases someone thought of:
+
+- The trace is always a prefix of the declared check order. Nothing is skipped,
+  nothing is reordered, every check reports exactly once, and a stopped decision
+  ends on the check that stopped it with a reason attached.
+- A check marked `nonRejecting` cannot stop a decision even when it returns a
+  rejection on purpose.
+- However many deliveries race, `commit()` hands out exactly `min(racers, limit)`
+  units, and replaying one decision any number of times spends one.
+- `MemoryStore` and `SqliteStore` answer the same random sequence of `get`, `set`,
+  `incr`, `del` and clock movement identically, TTLs included.
+
+The generator is forty lines because the package has no dependencies; a property
+library would shrink failures better. Each assertion prints its seed, so a failure
+reproduces exactly. The race property was checked against a mutant: rewriting
+`consume` as read-then-write, the shortcut in `bench/naive.mjs`, makes it fail.
+
+## The spec, and writing a second implementation
+
+[`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
+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.
 
 ## Performance
 
@@ -275,11 +480,18 @@ Tian Pan's
 essay argues the same case from the product side and suggests a daily cap of three
 to five; `defaultChecks({ dailyLimit })` defaults to five.
 
+The shape has older relatives. Matrix push rules are an ordered list where the first matching
+rule decides. Android notification channels and iOS interruption levels give the user a
+per-type switch and a priority floor that bypasses quiet time. Horvitz's work on mixed
+initiative supplied the two optional checks. This package puts those ideas in one list with a
+trace, and adds the part they leave out: the budget consumed at send time.
+
 ## Development
 
 ```
 npm ci
-npm test        # tsc build, then node:test over dist/test
+npm test               # tsc build, spec-lint, then node:test over dist/test
+cd python && pytest    # the Python sibling against the same fixtures
 ```
 
 MIT.

package/README.tr.md

@@ -33,7 +33,9 @@ Sıfır bağımlılık. TypeScript. Node 20 ya da üstü. Framework'ten bağıms
 şey üretti" ile "kullanıcının telefonu titredi" arasında durur; hangi model ya da framework
 üretmiş olursa olsun. Örnekler: [`examples/vercel-ai-sdk.ts`](examples/vercel-ai-sdk.ts),
 [`examples/mastra.ts`](examples/mastra.ts) ve yeniden oynatılabilir bir politika olarak
-[`examples/policy.js`](examples/policy.js).
+[`examples/policy.json`](examples/policy.json). Dokümantasyon ve tarayıcıda oyun alanı:
+[bubblegunn.github.io/proactive-gate](https://bubblegunn.github.io/proactive-gate/). Python:
+[`python/`](python/README.md).
 
 ## Bir karar neye benzer
 
@@ -59,7 +61,10 @@ Sıfır bağımlılık. TypeScript. Node 20 ya da üstü. Framework'ten bağıms
 }
 ```
 
-<p align="center"><img src="assets/trace.png" width="900" alt="Gerçek bir karar izi: sekiz kontrol çalıştı, sessiz saatler reddetti, her biri gerekçesi ve maliyetiyle"></p>
+<p align="center"><img src="docs/assets/trace.svg" width="900" alt="Yan yana iki gerçek karar izi: a1 adayı sekiz kontrolden sonra sessiz saatlerde reddedildi, a5 adayı on üç kontrolden sonra geçti; her kontrol sonucu, gerekçesi ve maliyetiyle"></p>
+
+Şekil, replay komutunun `--json` çıktısından `node scripts/trace-svg.mjs` ile çizilir; her satır
+olduğu gibi alınmıştır.
 
 Tek kapı ve kayıtlı bir gerekçe ile "kullanıcıya bu neden söylenmedi" sorusunun bir cevabı
 olur. Kontroller bir boru hattına dağılmışken dürüst cevap "bir yerde bir şey false döndü"
@@ -123,6 +128,125 @@ Bir kontrol yalnızca zamanlamayı taşıyabiliyor ya da yüzeyleri daraltabiliy
 `nonRejecting: true` işaretleyin; kapı ondan gelen bir reddi yok sayar ve bunu izde söyler,
 böylece bir zamanlama modelindeki hata bir kullanıcıyı susturamaz.
 
+## Politika bir veridir
+
+Aynı kontroller bir JSON belgesi olarak da yazılabilir; ürün ekibi kuralları dağıtım yapmadan
+değiştirir ve aynı dosya TypeScript'te, Python'da, CLI'da ve
+[oyun alanında](https://bubblegunn.github.io/proactive-gate/playground/) çalışır:
+
+```json
+{
+  "specVersion": "1.0.0",
+  "checks": [
+    { "id": "consent" },
+    { "id": "snooze", "defer": true },
+    { "id": "quietHours", "priorityFloor": "high" },
+    { "preset": "usTcpa" },
+    { "id": "utilityFloor", "costFalseAlarm": 1, "costMissedHelp": 2, "shadow": true },
+    { "id": "dailyBudget", "limit": 3, "bypassPriority": "critical", "nearLimit": 0.67 }
+  ]
+}
+```
+
+```ts
+const gate = createGate({ policy: JSON.parse(await readFile("policy.json", "utf8")), store });
+```
+
+Her girdi bir kontrol `id`'si ya da bir `preset` ve o kontrolün seçeneklerini taşır. Bilinmeyen
+bir id hata fırlatır ve bilinenleri sayar. Şema
+[`spec/schema/policy.schema.json`](spec/schema/policy.schema.json) dosyasındadır;
+`examples/policy.js`, fonksiyon gerektiren kontroller için kaçış yolu olarak durur.
+
+## Erteleme, gölge modu, sınıra yakınlık notları ve kancalar
+
+Bir kontrol reddetmek yerine `defer` diyebilir: karar `allowed: false`, `deferredBy` ve
+`retryAt` taşır, çağıran ne zaman tekrar deneyeceğini bilir. `snooze({ defer: true })` yerleşik
+örnektir.
+
+`shadow: true` işaretli bir kontrol çalışır ve izde gerçek sonucuyla görünür, ama mesajı
+durduramaz; id'si `decision.shadowed` listesine düşer. Yeni bir kuralı bir hafta gölgede
+çalıştırın, kaç kez ateşleyeceğini sayın, sonra açın.
+
+Bütçeler eşiğe (varsayılan yüzde 80) ulaşan geçişte `nearLimit: { used, limit }` bildirir;
+`decision.nearLimit` altında listelenir, böylece bir pano kimin susmak üzere olduğunu gösterir.
+
+`hooks: { before, after, error, finally }` her kontrolü milisaniye maliyetiyle gözler; hata
+fırlatan bir kanca `error` kancasına yönlendirilir ve kararı asla değiştirmez.
+`examples/otel.ts` bunları kontrol başına bir span'e çevirir. Her kararın bir `id`'si vardır ve
+`commit` bu id üzerinde tekrarlanabilir: zaman aşımından sonraki bir yeniden deneme ikinci
+bir birim tüketmez.
+
+## İsteğe bağlı, kendi modelinizin beslediği kontroller
+
+İkisi de kapalı gelir; adayın üzerine çağıranın koyduğu sayıları okurlar.
+
+- `utilityFloor({ costFalseAlarm, costMissedHelp })` yalnızca `candidate.pAccept` değeri
+  `tau = cFA / (cFA + pNeed * cFN)` eşiğini geçtiğinde konuşur (`pNeed` varsayılanı 1);
+  `pAccept` yoksa atlar. Bu, Horvitz'in beklenen fayda kuralı ve PRISM eşiğidir.
+- `boundedDeferral({ lambda, interruptCost, staleness, boundSeconds })` asla reddetmez.
+  `candidate.busy` doğruysa `deliverAt` değerini `now + t*` yapar;
+  `t* = min(bound, lambda * interruptCost / (2 * staleness))`, varsayılanlar 116 saniye verir.
+
+## Hazır paketler: platform kotaları ve yasal sınırlar, kaynaklarıyla
+
+```ts
+import { presets } from "proactive-gate/presets";
+const gate = createGate({ checks: [checks.consent(), ...presets.kakaoBrandMessage()] });
+```
+
+| paket | ne kodlar |
+|---|---|
+| `lineMessagingApi({ plan })` | LINE planına göre aylık push bütçesi: 200, 5.000 ya da 30.000 |
+| `wechatSubscriptionMessage` | abonelik onayı başına bir mesaj |
+| `wechatCustomerService` | kullanıcının son mesajından sonraki 48 saat içinde en çok 5 |
+| `wechatTemplateMessage` | yalnızca kullanıcı eyleminden sonra, günde 3 şablon |
+| `wecomAppMessage` | üye başına dakikada 30 ve saatte 1.000 |
+| `kakaoAlimtalk` | yalnızca rıza; AlimTalk'ta saat kuralı yok |
+| `kakaoBrandMessage` | reklam rızası, 08:00 ile 20:50 Asia/Seoul |
+| `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 |
+| `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 |
+| `slackApp` | kanal başına saniyede 1 |
+
+Her paket `sources` (sayıların geldiği sayfalar) ve neyi dışarıda bıraktığını söyleyen bir
+`note` taşır. Gözden geçirilebilir varsayılanlar, hukuki tavsiye değil: birkaç resmi kaynak
+birbiriyle çelişir ve not hangi değerin neden seçildiğini söyler.
+
+## Adaptörler
+
+| alt yol | framework | kapı nerede durur |
+|---|---|---|
+| `proactive-gate/ai-sdk` | Vercel AI SDK | bir aracın `needsApproval` sorusunu yanıtlar (çevrimdışı çalışan örnek: [`examples/ai-sdk/`](examples/ai-sdk/)) |
+| `proactive-gate/mastra` | Mastra | gönderimden önce bir çıktı işlemcisi (çevrimdışı çalışan örnek: [`examples/mastra/`](examples/mastra/)) |
+| `proactive-gate/langchain` | LangChain | gönderim aracının çevresinde middleware |
+| `proactive-gate/openai-agents` | OpenAI Agents | bir guardrail |
+| `npx proactive-gate hook` | Claude Code | bir `PreToolUse` kancası ([`examples/claude-code-hook.json`](examples/claude-code-hook.json)) |
+
+Adaptörler framework paketine değil, çağrının biçimine göre tiplenmiştir; başka bir şey
+kurmak gerekmez. Her biri kapının gerekçesiyle reddeder ve onayda bütçeyi tüketir.
+
+## Python
+
+```
+pip install proactive-gate
+```
+
+`python/` sapan bir port değil, bir kardeştir: `spec/fixtures` altındaki her senaryoyu senkron
+`Gate` ve `AsyncGate` (Redis, `redis.asyncio` üzerinden) ile geçer; mypy strict, CI'da Python
+3.11 ve 3.13. Bkz. [`python/README.md`](python/README.md).
+
+## Sözleşme ve ikinci bir uygulama yazmak
+
+[`spec/SPEC.md`](spec/SPEC.md) davranışı numaralı gereksinimler olarak yazar;
+[`spec/fixtures`](spec/fixtures) dile bağlı olmayan senaryoları tutar: America/New_York'taki
+yaz saati kenarı, Pacific/Apia, 2031'de bir duvar saati senaryosu, atomik commit, ISO haftası,
+erteleme, gölge modu, isteğe bağlı kontroller ve dört hazır paket. TypeScript ve Python
+testleri hepsini çalıştırır; `npx proactive-gate replay --fixtures spec/fixtures` komut
+satırından çalıştırır. Üçüncü bir uygulama bu kaynaktan değil, senaryolardan başlar.
+
 ## Bütçe evaluate'te değil, commit'te uygulanır
 
 İki örnek aynı kullanıcı için aynı adayı değerlendirebilir, ikisi de beşte dördün kullanıldığını
@@ -206,11 +330,18 @@ yazısında savunulmuş kararlardır. Tian Pan'ın
 yazısı aynı davayı ürün tarafından savunur ve günde üç ile beş arası bir tavan önerir;
 `defaultChecks({ dailyLimit })` varsayılanı beştir.
 
+Biçimin daha eski akrabaları var. Matrix push kuralları, ilk eşleşen kuralın karar verdiği
+sıralı bir listedir. Android bildirim kanalları ve iOS kesinti seviyeleri kullanıcıya tür
+başına bir anahtar ve sessiz saati aşan bir öncelik tabanı verir. Horvitz'in karma girişim
+çalışmaları iki isteğe bağlı kontrolü sağladı. Bu paket o fikirleri izli tek bir listeye
+koyar ve onların dışarıda bıraktığı parçayı ekler: gönderim anında tüketilen bütçe.
+
 ## Geliştirme
 
 ```
 npm ci
-npm test        # tsc build, then node:test over dist/test
+npm test               # tsc build, spec-lint, then node:test over dist/test
+cd python && pytest    # the Python sibling against the same fixtures
 ```
 
 MIT.

package/dist/src/adapters/ai-sdk.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Vercel AI SDK tool approvals. Give the send tool `needsApproval: true` and
+ * answer each approval request through the gate:
+ *
+ *   const approve = gateToolApproval({ gate, toInput: (call) => call.input.gate });
+ *   const { approved, reason } = await approve(call);
+ *   // then addToolApprovalResponse({ id: call.approvalId, approved, reason })
+ *
+ * Typed against the shape of a tool call, not against the `ai` package, so
+ * nothing needs to be installed to build proactive-gate.
+ */
+import type { Gate } from "../gate.js";
+import type { EvaluateInput } from "../types.js";
+export interface ToolApprovalRequest {
+    toolName?: string;
+    toolCallId?: string;
+    approvalId?: string;
+    input?: unknown;
+}
+export interface ToolApprovalResult {
+    approved: boolean;
+    reason?: string;
+}
+export declare function gateToolApproval<T extends ToolApprovalRequest>(options: {
+    gate: Gate;
+    toInput: (call: T) => EvaluateInput;
+    /** Also consume the budget on approval. Default true. */
+    commit?: boolean;
+}): (call: T) => Promise<ToolApprovalResult>;
+export declare function describe(decision: {
+    rejectedBy?: string;
+    deferredBy?: string;
+    retryAt?: Date;
+    reason?: string;
+}): string;

package/dist/src/adapters/ai-sdk.js

@@ -0,0 +1,17 @@
+export function gateToolApproval(options) {
+    const commit = options.commit ?? true;
+    return async (call) => {
+        const input = options.toInput(call);
+        const decision = await options.gate.evaluate(input);
+        if (!decision.allowed)
+            return { approved: false, reason: describe(decision) };
+        if (commit && !(await options.gate.commit(decision, input)))
+            return { approved: false, reason: "a budget was exhausted at commit" };
+        return { approved: true, ...(decision.deliverAt ? { reason: `deliver at ${decision.deliverAt.toISOString()}` } : {}) };
+    };
+}
+export function describe(decision) {
+    if (decision.deferredBy)
+        return `deferred by ${decision.deferredBy} until ${decision.retryAt?.toISOString()}: ${decision.reason}`;
+    return `rejected by ${decision.rejectedBy}: ${decision.reason}`;
+}

package/dist/src/adapters/langchain.d.ts

@@ -0,0 +1,32 @@
+/**
+ * LangChain middleware that wraps tool calls. For the tools listed in `tools`
+ * the gate decides first; a rejection returns a tool message carrying the
+ * reason instead of running the tool.
+ *
+ *   createAgent({ tools: [sendMessage], middleware: [gateMiddleware({ gate, tools: ["send_message"], toInput: (req) => req.toolCall.args.gate })] })
+ */
+import type { Gate } from "../gate.js";
+import type { EvaluateInput } from "../types.js";
+export interface ToolCallRequest {
+    toolCall: {
+        name: string;
+        id?: string;
+        args: Record<string, unknown>;
+    };
+}
+export interface ToolMessageLike {
+    type: "tool";
+    content: string;
+    tool_call_id: string;
+    status: "success" | "error";
+}
+export interface ToolCallMiddleware<R extends ToolCallRequest = ToolCallRequest, T = unknown> {
+    name: string;
+    wrapToolCall(request: R, handler: (request: R) => Promise<T>): Promise<T | ToolMessageLike>;
+}
+export declare function gateMiddleware<R extends ToolCallRequest = ToolCallRequest, T = unknown>(options: {
+    gate: Gate;
+    tools: string[];
+    toInput: (request: R) => EvaluateInput;
+    commit?: boolean;
+}): ToolCallMiddleware<R, T>;

package/dist/src/adapters/langchain.js

@@ -0,0 +1,20 @@
+import { describe } from "./ai-sdk.js";
+export function gateMiddleware(options) {
+    const commit = options.commit ?? true;
+    const watched = new Set(options.tools);
+    return {
+        name: "proactive-gate",
+        async wrapToolCall(request, handler) {
+            if (!watched.has(request.toolCall.name))
+                return handler(request);
+            const input = options.toInput(request);
+            const decision = await options.gate.evaluate(input);
+            const refuse = (reason) => ({ type: "tool", content: `proactive-gate: ${reason}`, tool_call_id: request.toolCall.id ?? "", status: "error" });
+            if (!decision.allowed)
+                return refuse(describe(decision));
+            if (commit && !(await options.gate.commit(decision, input)))
+                return refuse("a budget was exhausted at commit");
+            return handler(request);
+        },
+    };
+}

package/dist/src/adapters/mastra.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A Mastra output processor. Put it in the agent's `outputProcessors`; when
+ * the gate rejects, the processor calls abort(reason) and the agent's result
+ * is stopped before it reaches the user.
+ *
+ *   outputProcessors: [gateProcessor({ gate, toInput: ({ messages }) => ({ user, candidate: { id, type: "reply" } }) })]
+ */
+import type { Gate } from "../gate.js";
+import type { EvaluateInput } from "../types.js";
+export interface ProcessorArgs<M = unknown> {
+    messages: M[];
+    abort: (reason?: string) => never;
+}
+export interface OutputProcessor<M = unknown> {
+    id: string;
+    processOutputResult(args: ProcessorArgs<M>): Promise<M[]>;
+}
+export declare function gateProcessor<M = unknown>(options: {
+    gate: Gate;
+    toInput: (args: {
+        messages: M[];
+    }) => EvaluateInput;
+    id?: string;
+    commit?: boolean;
+}): OutputProcessor<M>;

package/dist/src/adapters/mastra.js

@@ -0,0 +1,16 @@
+import { describe } from "./ai-sdk.js";
+export function gateProcessor(options) {
+    const commit = options.commit ?? true;
+    return {
+        id: options.id ?? "proactive-gate",
+        async processOutputResult({ messages, abort }) {
+            const input = options.toInput({ messages });
+            const decision = await options.gate.evaluate(input);
+            if (!decision.allowed)
+                return abort(`proactive-gate: ${describe(decision)}`);
+            if (commit && !(await options.gate.commit(decision, input)))
+                return abort("proactive-gate: a budget was exhausted at commit");
+            return messages;
+        },
+    };
+}

package/dist/src/adapters/openai-agents.d.ts

@@ -0,0 +1,31 @@
+/**
+ * An OpenAI Agents SDK tool input guardrail. Attach it to the send tool with
+ * `defineToolInputGuardrail`-compatible shape; a rejection trips the wire with
+ * the reason in outputInfo.
+ *
+ *   tool({ name: "send_message", inputGuardrails: [gateToolInputGuardrail({ gate, toInput: ({ input }) => input.gate })] })
+ */
+import type { Gate } from "../gate.js";
+import type { EvaluateInput } from "../types.js";
+export interface GuardrailArgs<I = unknown> {
+    input: I;
+    context?: unknown;
+}
+export interface GuardrailResult {
+    tripwireTriggered: boolean;
+    outputInfo: {
+        reason?: string;
+        surfaces?: string[];
+        deliverAt?: string;
+    };
+}
+export interface ToolInputGuardrail<I = unknown> {
+    name: string;
+    execute(args: GuardrailArgs<I>): Promise<GuardrailResult>;
+}
+export declare function gateToolInputGuardrail<I = unknown>(options: {
+    gate: Gate;
+    toInput: (args: GuardrailArgs<I>) => EvaluateInput;
+    name?: string;
+    commit?: boolean;
+}): ToolInputGuardrail<I>;

package/dist/src/adapters/openai-agents.js

@@ -0,0 +1,16 @@
+import { describe } from "./ai-sdk.js";
+export function gateToolInputGuardrail(options) {
+    const commit = options.commit ?? true;
+    return {
+        name: options.name ?? "proactive-gate",
+        async execute(args) {
+            const input = options.toInput(args);
+            const decision = await options.gate.evaluate(input);
+            if (!decision.allowed)
+                return { tripwireTriggered: true, outputInfo: { reason: describe(decision) } };
+            if (commit && !(await options.gate.commit(decision, input)))
+                return { tripwireTriggered: true, outputInfo: { reason: "a budget was exhausted at commit" } };
+            return { tripwireTriggered: false, outputInfo: { surfaces: decision.surfaces, ...(decision.deliverAt ? { deliverAt: decision.deliverAt.toISOString() } : {}) } };
+        },
+    };
+}