proactive-gate 0.1.2 → 0.2.1

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,
@@ -96,6 +112,22 @@ consumed in check order at commit, so when a weekly check passes and the daily o
 refuses, that weekly unit is spent without a delivery. It only happens when two commits
 race after a shared evaluate.
 
+### Two limits you should know before you adopt this
+
+Neither is a bug, and both are pinned by tests so a future change has to be deliberate.
+
+**The week is the ISO week, so the weekly budget refills on Monday.** Where the working
+week runs Sunday to Thursday, that refill lands one day in: a user who spends the budget on
+Sunday has it back on Monday, with four working days still to run. Changing the key would
+move every counter already in your store, so it is documented rather than quietly altered.
+Pass your own budget check keyed how you like if the ISO week is wrong for your users.
+
+**Quiet hours are a single window, the same on every day of the week.** A user carries one
+`start` and one `end`, so a Friday window, a Shabbat window or a public holiday cannot be
+expressed. The day of the week is never read. If you need one, write a check: it is an
+object with an `id` and a `run`, it composes in the order you choose, and the trace will
+show it firing beside the built-in ones.
+
 Order is a design decision and it should be visible. Consent has to come before
 everything. Quiet hours have to come before the budget, or a rejected candidate
 consumes a delivery it never made. Reorder freely; the trace will show what you did.
@@ -138,6 +170,168 @@ 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`. That threshold is the classical Bayes decision boundary: alerting costs
+  `(1 - p) * cFA`, silence costs `p * cFN`, so you alert when the first is the smaller.
+  The alerting application is [Horvitz, Jacobs and Hovel, "Attention-Sensitive Alerting",
+  UAI 1999](https://arxiv.org/abs/1301.6707), whose system is named Priorities.
+- `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 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.
+
+`boundedDeferral` implements the derivation in [Achlioptas and Horvitz, "Principles of
+Bounded Deferral for Balancing Information Awareness with
+Interruption"](http://erichorvitz.com/Bounded_Deferral.pdf): expected cost is stationary
+where `f'(t0) = lambda * c`, so a quadratic staleness `f(t) = s * t²` gives
+`t* = lambda * c / (2 * s)`.
+
+## Which defaults are measured and which are ours
+
+Every default here is either taken from a study, which is then named, or chosen by
+judgement, which is then admitted. There is one of the first kind.
+
+| default | where it comes from |
+|---|---|
+| `lambda = 1/43` in `boundedDeferral` | Measured. Achlioptas and Horvitz above: 113 Microsoft employees (42 program managers, 25 developers, 19 testers, 10 administrators, 9 managers, 4 in sales and marketing, 4 research scientists), three sequential business days between 10am and 4pm, 4,803 busy situations, mean busy session 43.12 s, standard deviation 51.79 s |
+| `staleness = 0.0001`, `boundSeconds = 240` | Scale choices. Only the ratio `interruptCost / staleness` changes `t*`, so this pair is one way to write "a few minutes". Nothing fixes either number |
+| `trustRamp` 7 days | Ours. No study sets it |
+| `dismissalCooldown` 3 in 30 days buying 7 days | Ours. A dismissal is the clearest signal a user gives, so the shape is defensible; the three numbers are not from anywhere |
+| `dailyBudget` 5 | Ours, in a supported direction. Pielot and Rello (below) cite an in-situ log study where participants received a median of 63.5 notifications a day, so a handful sits far below the ambient load. Nothing in that work says five |
+
+The spread inside the one measured number is worth more than the number. The same paper's
+two-subject analysis puts the mean time to a lower-cost state after an alert at 11 seconds
+for one person and 101 seconds for the other, so the variation between two people is larger
+than the default itself. Measure your own users before you trust it.
+
+### Deferring is supported; silence is not free
+
+The strongest evidence that deferral works at all is [Okoshi, Tsubouchi and Tokuda,
+"Real-world large-scale study on adaptive notification scheduling on smartphones",
+*Pervasive and Mobile Computing* 50:1-24
+(2018)](https://keio.elsevierpure.com/en/publications/real-world-large-scale-study-on-adaptive-notification-scheduling-/):
+the Yahoo! JAPAN Android app, more than 680,000 users over three weeks, where holding a
+notification until an interruptible moment was detected cut response time by 49.7 percent
+against immediate delivery. That supports the direction. It says nothing about any window,
+budget or cooldown in this package.
+
+The counterweight belongs here too, because a gate that suppresses is not free. In [Pielot
+and Rello, "Productive, Anxious, Lonely: 24 Hours Without Push Notifications", MobileHCI
+2017](https://arxiv.org/abs/1612.02314), 30 volunteers switched notifications off for a day.
+They were less distracted, and they also worried about missing information, checked their
+phones more often, and felt less connected to the people around them. Fifteen of the thirty
+agreed they were afraid of missing something urgent. Three people approached for the study
+refused outright, because their workplace expected them to be reachable. A silence your user
+did not choose costs them something, and that cost does not appear in any trace this library
+prints.
+
+## 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.
+
+**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
+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.
+
+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
+*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.
+
 ## 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 +404,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
+```
+
+```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(...)
+```
 
-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/` 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 +562,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,200 @@ 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 eşik klasik Bayes karar sınırıdır: konuşmanın maliyeti
+  `(1 - p) * cFA`, susmanın maliyeti `p * cFN`, hangisi küçükse o seçilir. Uyarı alanındaki
+  karşılığı [Horvitz, Jacobs ve Hovel, "Attention-Sensitive Alerting", UAI
+  1999](https://arxiv.org/abs/1301.6707); o makaledeki sistemin adı Priorities.
+- `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.
+  Türetim [Achlioptas ve Horvitz, "Principles of Bounded
+  Deferral"](http://erichorvitz.com/Bounded_Deferral.pdf) makalesinden.
+
+## Hangi varsayılan ölçüldü, hangisi bizim tercihimiz
+
+Buradaki her varsayılan ya bir çalışmadan geliyor ve kaynağı yazılıyor, ya da bir kanaat ve
+bunu söylüyoruz. Birinci türden tek bir tane var.
+
+| varsayılan | nereden geliyor |
+|---|---|
+| `boundedDeferral` içindeki `lambda = 1/43` | Ölçüm. Yukarıdaki makale: 113 çalışan, üç ardışık iş günü, 10.00 ile 16.00 arası, 4.803 meşgul durum, ortalama meşguliyet süresi 43,12 saniye, standart sapma 51,79 saniye |
+| `staleness = 0.0001`, `boundSeconds = 240` | Ölçek tercihi. `t*` yalnızca `interruptCost / staleness` oranına bağlı; bu çift "birkaç dakika" demenin bir yolu, iki sayıyı da sabitleyen bir bulgu yok |
+| `trustRamp` 7 gün | Bizim. Hiçbir çalışma bu sayıyı vermiyor |
+| `dismissalCooldown` 30 günde 3 kapatma, 7 gün sessizlik | Bizim. Kapatma, kullanıcının verdiği en net sinyal olduğu için biçim savunulabilir; üç sayı bize ait |
+| `dailyBudget` 5 | Bizim, ama yönü destekli. Pielot ve Rello'nun aktardığı yerinde günlük kayıt çalışmasında katılımcılar günde ortanca 63,5 bildirim alıyor; bir avuç mesaj bunun çok altında. O çalışma "beş" demiyor |
+
+Ölçülen tek sayının içindeki dağılım, sayının kendisinden değerli: aynı makalenin iki kişilik
+çözümlemesinde uyarı sonrası düşük maliyetli duruma geçiş ortalaması birinde 11, diğerinde
+101 saniye. İki kişi arasındaki fark varsayılanın kendisinden büyük.
+
+### Ertelemenin dayanağı var, susmanın bedeli de var
+
+Ertelemenin işe yaradığına dair en güçlü kanıt [Okoshi, Tsubouchi ve Tokuda, *Pervasive and
+Mobile Computing* 50:1-24
+(2018)](https://keio.elsevierpure.com/en/publications/real-world-large-scale-study-on-adaptive-notification-scheduling-/):
+Yahoo! JAPAN Android uygulaması, 680.000'den fazla kullanıcı, üç hafta; bildirimi uygun ana
+kadar bekletmek yanıt süresini yüzde 49,7 kısaltmış. Bu, yönü destekler; bu paketteki
+hiçbir pencereyi, bütçeyi veya bekleme süresini desteklemez.
+
+Karşı ağırlık da burada durmalı, çünkü susturan bir kapı bedelsiz değil. [Pielot ve Rello,
+MobileHCI 2017](https://arxiv.org/abs/1612.02314) çalışmasında 30 gönüllü bir gün boyunca
+bildirimleri kapatmış. Daha az dağılmışlar, ama aynı zamanda bir şeyi kaçırmaktan
+endişelenmiş, telefonlarına daha sık bakmış ve çevrelerinden kopuk hissetmişler. Otuz kişiden
+on beşi acil bir şeyi kaçırmaktan korktuğunu söylemiş. Çalışma için görüşülen üç kişi,
+işyerinde sürekli ulaşılabilir olmaları beklendiği için katılmayı reddetmiş. Kullanıcının
+seçmediği bir sessizliğin bir bedeli var ve o bedel bu kütüphanenin yazdığı hiçbir izde
+görünmüyor.
+
+## Benimsemeden önce bilmeniz gereken iki sınır
+
+İkisi de hata değil ve ikisi de testle sabitlendi, böylece ileride değişecekse bilerek değişir.
+
+**Hafta, ISO haftasıdır; haftalık bütçe pazartesi yenilenir.** Çalışma haftası pazardan
+perşembeye uzanan yerlerde bu yenilenme haftanın birinci gününe denk gelir: pazar günü
+bütçesini harcayan bir kullanıcı pazartesi sabahı bütçesini geri alır ve önünde hâlâ dört
+iş günü vardır. Anahtarı değiştirmek deponuzdaki bütün sayaçları kaydıracağı için bunu
+sessizce değiştirmek yerine yazıyoruz. ISO haftası sizin kullanıcılarınız için yanlışsa
+kendi bütçe kontrolünüzü istediğiniz anahtarla yazabilirsiniz.
+
+**Sessiz saatler tek bir penceredir ve haftanın her günü aynıdır.** Kullanıcıda tek bir
+`start` ve tek bir `end` vardır; cuma penceresi, Şabat penceresi veya resmî tatil
+tanımlanamaz. Haftanın günü hiç okunmaz. Böyle bir kurala ihtiyacınız varsa kendi
+kontrolünüzü yazın: `id` ve `run` taşıyan bir nesnedir, istediğiniz sırada dizilir ve izde
+yerleşik kontrollerin yanında görünür.
+
+## 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.
+
+**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
+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.
+
+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
+yükümlülükleri getirir; ikisinde de saat kısıtı yoktur. İnternette dolaşan Brezilya penceresi
+PLS 48/2018 sayılı kanun *teklifinden* gelir, yürürlükteki bir kanundan değil, ve
+telefonla pazarlama aramalarını kapsar. Hindistan ilginç olanı: sıkça tekrarlanan "09.00-21.00"
+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.
+
+## 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 +405,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;