proactive-gate 0.2.0 → 0.2.1

package/README.md

@@ -112,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.
@@ -208,20 +224,67 @@ 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.
+  `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 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
+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
@@ -250,6 +313,25 @@ Each preset carries `sources` (the pages the numbers come from) and a `note` on
 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

package/README.tr.md

@@ -182,10 +182,67 @@ bir birim tüketmez.
 
 - `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.
+  `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
 
@@ -215,6 +272,24 @@ Her paket `sources` (sayıların geldiği sayfalar) ve neyi dışarıda bırakt
 `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 |

package/dist/src/checks.d.ts

@@ -36,6 +36,9 @@ export declare function quietHours(options?: {
  * For the first `days` after sign-up the user hears from the system only at
  * or above `minPriority`. A proactive assistant is least calibrated exactly
  * when the user is least forgiving.
+ *
+ * Seven days is a judgement, not a finding. No study sets this number, and
+ * none of the literature the package cites speaks to it.
  */
 export declare function trustRamp(options?: {
     days?: number;
@@ -45,6 +48,10 @@ export declare function trustRamp(options?: {
  * When the user has dismissed `dismissals` candidates of a type within
  * `withinDays`, that type stays silent for `silenceDays`. Fed by
  * gate.record(userId, candidate, "dismissed").
+ *
+ * Three in thirty buying seven days is a judgement, not a finding. The shape
+ * is defensible, since a dismissal is the clearest signal a user gives; the
+ * three numbers are ours and no study sets them.
  */
 export declare function dismissalCooldown(options?: {
     dismissals?: number;
@@ -74,15 +81,36 @@ export interface BudgetOptions {
 export declare const budgetKey: (userId: string, now: Date, timezone?: string) => string;
 export declare const weeklyBudgetKey: (userId: string, now: Date, timezone?: string) => string;
 export declare const monthlyBudgetKey: (userId: string, now: Date, timezone?: string) => string;
-/** At most `limit` deliveries per user per local day. */
+/**
+ * At most `limit` deliveries per user per local day.
+ *
+ * Five is a judgement, not a finding. The direction has support: Pielot and
+ * Rello, "Productive, Anxious, Lonely: 24 Hours Without Push Notifications",
+ * MobileHCI 2017 (https://arxiv.org/abs/1612.02314), cite an in-situ log study
+ * (Pielot, Church and de Oliveira, MobileHCI 2014) in which participants
+ * received a median of 63.5 notifications a day, so a handful is far below the
+ * ambient load. Nothing in that work says five.
+ */
 export declare function dailyBudget(options?: BudgetOptions): BudgetCheck;
-/** At most `limit` deliveries per user per local ISO week. */
+/**
+ * At most `limit` deliveries per user per local ISO week.
+ *
+ * The week is the ISO week, so the counter resets on Monday morning in the
+ * user's zone. For a Sunday-to-Thursday working week that reset lands
+ * mid-week. Documented rather than fixed; changing it would move every
+ * existing key.
+ */
 export declare function weeklyBudget(options?: BudgetOptions): BudgetCheck;
 /** At most `limit` deliveries per user per local calendar month. */
 export declare function monthlyBudget(options?: BudgetOptions): BudgetCheck;
 /**
- * Horvitz's expected-utility rule with the PRISM threshold: act only when the
- * caller's estimate of acceptance clears tau = cFA / (cFA + pNeed * cFN).
+ * Expected-utility alerting: act only when the caller's estimate of acceptance
+ * clears tau = cFA / (cFA + pNeed * cFN). That threshold is the classical Bayes
+ * decision boundary between the cost of alerting when the user did not want it,
+ * (1 - p) * cFA, and the cost of staying silent when they did, p * cFN.
+ * The alerting application is Horvitz, Jacobs and Hovel, "Attention-Sensitive
+ * Alerting", UAI 1999 (https://arxiv.org/abs/1301.6707); the system in that
+ * paper is named Priorities.
  * `candidate.pAccept` and `candidate.pNeed` come from the caller's own model.
  */
 export declare function utilityFloor(options: {
@@ -90,10 +118,29 @@ export declare function utilityFloor(options: {
     costMissedHelp: number;
 }): Check;
 /**
- * Bounded deferral (Horvitz): when the user is busy, wait t* = min(bound,
+ * Bounded deferral: when the user is busy, wait t* = min(bound,
  * lambda * interruptCost / (2 * staleness)), the optimum of a quadratic
  * staleness loss against the cost of interrupting a busy person, with the
  * user becoming free at rate lambda. Never rejects; only moves deliverAt.
+ *
+ * The derivation is Achlioptas and Horvitz, "Principles of Bounded Deferral
+ * for Balancing Information Awareness with Interruption", Microsoft Research
+ * (http://erichorvitz.com/Bounded_Deferral.pdf): the expected cost is
+ * stationary where f'(t0) = lambda * c with f''(t0) > 0, so a quadratic
+ * staleness f(t) = s * t^2 gives t* = lambda * c / (2 * s).
+ *
+ * `lambda` defaults to 1/43 from the same paper's field study: 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 duration 43.12 s with a standard deviation of 51.79 s. That
+ * spread matters: the same paper's two-subject Interruption Workbench analysis
+ * puts the mean time to a lower-cost state after an alert at 11 s for one
+ * person and 101 s for the other. Measure your own users before trusting it.
+ *
+ * `staleness` and `boundSeconds` are scale choices, not findings. Only the
+ * ratio interruptCost / staleness affects t*, so the pair below is one way to
+ * express "a few minutes"; nothing in the literature fixes either number.
  */
 export declare function boundedDeferral(options?: {
     lambda?: number;

package/dist/src/checks.js

@@ -132,6 +132,9 @@ export function quietHours(options = {}) {
  * For the first `days` after sign-up the user hears from the system only at
  * or above `minPriority`. A proactive assistant is least calibrated exactly
  * when the user is least forgiving.
+ *
+ * Seven days is a judgement, not a finding. No study sets this number, and
+ * none of the literature the package cites speaks to it.
  */
 export function trustRamp(options = {}) {
     const days = options.days ?? 7;
@@ -153,6 +156,10 @@ export function trustRamp(options = {}) {
  * When the user has dismissed `dismissals` candidates of a type within
  * `withinDays`, that type stays silent for `silenceDays`. Fed by
  * gate.record(userId, candidate, "dismissed").
+ *
+ * Three in thirty buying seven days is a judgement, not a finding. The shape
+ * is defensible, since a dismissal is the clearest signal a user gives; the
+ * three numbers are ours and no study sets them.
  */
 export function dismissalCooldown(options = {}) {
     const n = options.dismissals ?? 3;
@@ -235,11 +242,27 @@ const isoWeekKey = (day) => {
 };
 export const weeklyBudgetKey = (userId, now, timezone) => `weeklyBudget:${userId}:${isoWeekKey(localDay(now, timezone))}`;
 export const monthlyBudgetKey = (userId, now, timezone) => `monthlyBudget:${userId}:${localDay(now, timezone).slice(0, 7)}`;
-/** At most `limit` deliveries per user per local day. */
+/**
+ * At most `limit` deliveries per user per local day.
+ *
+ * Five is a judgement, not a finding. The direction has support: Pielot and
+ * Rello, "Productive, Anxious, Lonely: 24 Hours Without Push Notifications",
+ * MobileHCI 2017 (https://arxiv.org/abs/1612.02314), cite an in-situ log study
+ * (Pielot, Church and de Oliveira, MobileHCI 2014) in which participants
+ * received a median of 63.5 notifications a day, so a handful is far below the
+ * ambient load. Nothing in that work says five.
+ */
 export function dailyBudget(options = {}) {
     return budget({ id: "dailyBudget", label: "daily budget", defaultLimit: 5, keyFor: ({ user, now }) => budgetKey(user.id, now, user.timezone), ttlSeconds: 2 * DAY_SECONDS }, options);
 }
-/** At most `limit` deliveries per user per local ISO week. */
+/**
+ * At most `limit` deliveries per user per local ISO week.
+ *
+ * The week is the ISO week, so the counter resets on Monday morning in the
+ * user's zone. For a Sunday-to-Thursday working week that reset lands
+ * mid-week. Documented rather than fixed; changing it would move every
+ * existing key.
+ */
 export function weeklyBudget(options = {}) {
     return budget({ id: "weeklyBudget", label: "weekly budget", defaultLimit: 20, keyFor: ({ user, now }) => weeklyBudgetKey(user.id, now, user.timezone), ttlSeconds: 8 * DAY_SECONDS }, options);
 }
@@ -251,8 +274,13 @@ export function monthlyBudget(options = {}) {
 /* Optional, caller-fed checks. Off by default; the package ships no model.  */
 /* ------------------------------------------------------------------------ */
 /**
- * Horvitz's expected-utility rule with the PRISM threshold: act only when the
- * caller's estimate of acceptance clears tau = cFA / (cFA + pNeed * cFN).
+ * Expected-utility alerting: act only when the caller's estimate of acceptance
+ * clears tau = cFA / (cFA + pNeed * cFN). That threshold is the classical Bayes
+ * decision boundary between the cost of alerting when the user did not want it,
+ * (1 - p) * cFA, and the cost of staying silent when they did, p * cFN.
+ * The alerting application is Horvitz, Jacobs and Hovel, "Attention-Sensitive
+ * Alerting", UAI 1999 (https://arxiv.org/abs/1301.6707); the system in that
+ * paper is named Priorities.
  * `candidate.pAccept` and `candidate.pNeed` come from the caller's own model.
  */
 export function utilityFloor(options) {
@@ -270,10 +298,29 @@ export function utilityFloor(options) {
 }
 const round3 = (n) => Math.round(n * 1000) / 1000;
 /**
- * Bounded deferral (Horvitz): when the user is busy, wait t* = min(bound,
+ * Bounded deferral: when the user is busy, wait t* = min(bound,
  * lambda * interruptCost / (2 * staleness)), the optimum of a quadratic
  * staleness loss against the cost of interrupting a busy person, with the
  * user becoming free at rate lambda. Never rejects; only moves deliverAt.
+ *
+ * The derivation is Achlioptas and Horvitz, "Principles of Bounded Deferral
+ * for Balancing Information Awareness with Interruption", Microsoft Research
+ * (http://erichorvitz.com/Bounded_Deferral.pdf): the expected cost is
+ * stationary where f'(t0) = lambda * c with f''(t0) > 0, so a quadratic
+ * staleness f(t) = s * t^2 gives t* = lambda * c / (2 * s).
+ *
+ * `lambda` defaults to 1/43 from the same paper's field study: 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 duration 43.12 s with a standard deviation of 51.79 s. That
+ * spread matters: the same paper's two-subject Interruption Workbench analysis
+ * puts the mean time to a lower-cost state after an alert at 11 s for one
+ * person and 101 s for the other. Measure your own users before trusting it.
+ *
+ * `staleness` and `boundSeconds` are scale choices, not findings. Only the
+ * ratio interruptCost / staleness affects t*, so the pair below is one way to
+ * express "a few minutes"; nothing in the literature fixes either number.
  */
 export function boundedDeferral(options = {}) {
     const lambda = options.lambda ?? 1 / 43;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Decide whether a proactive AI agent may reach a user right now, and log why not. Ordered checks as code or JSON, a conformance spec, presets for platform and legal limits, adapters for AI SDK, Mastra, LangChain and OpenAI Agents, and a Python sibling.",
   "type": "module",
   "main": "./dist/src/index.js",