proactive-gate 0.2.0 → 0.2.2

package/README.md

@@ -100,18 +100,59 @@ something returned false".
 | 5 | `snooze()` | `user.snoozedUntil` is in the future | global pause |
 | 6 | `mute()` | `candidate.type` is in `user.mutedTypes` | per-type mute |
 | 7 | `intensity()` | priority is below the user's intensity floor | low hears only high, normal hears normal and up, high hears everything |
-| 8 | `quietHours({ priorityFloor })` | inside the user's local quiet window | IANA time zone, window may cross midnight, bypassed at or above the floor |
+| 8 | `quietHours({ priorityFloor })` | inside the user's local quiet window | IANA time zone, window may cross midnight, bypassed at or above the floor; one window every day or [a schedule per day](#quiet-hours-that-differ-by-day) |
 | 9 | `trustRamp({ days, minPriority })` | user is newer than `days` and priority is below the floor | the system is least calibrated exactly when the user is least forgiving |
 | 10 | `dismissalCooldown({ dismissals, withinDays, silenceDays })` | the user dismissed that type `dismissals` times in the window | fed by `gate.record(user, candidate, "dismissed")`; every further dismissal restarts the silence |
 | 11 | `adaptiveTiming({ nextGoodMoment, surfacesFor })` | never | non-rejecting: moves `deliverAt` or narrows surfaces; a check marked `nonRejecting` cannot reject even if it tries |
 | 12 | `dailyBudget({ limit, bypassPriority })` | the user's local-day counter is at the limit | `evaluate` reads, `commit` increments atomically and can still refuse |
 
+### Quiet hours that differ by day
+
+A working week is not Monday to Friday everywhere, and a holiday is not a weekday at all.
+`quietHours` takes a schedule as well as a single window:
+
+```ts
+quietHours: {
+  default: { start: "22:00", end: "08:00" },
+  days: { fri: { start: "00:00", end: "23:59" }, sat: { start: "00:00", end: "23:59" }, sun: null },
+  dates: { "2026-12-25": { start: "00:00", end: "23:59" } },
+}
+```
+
+A date beats a weekday beats the default, and `null` means the day has no quiet hours, which is
+how a working day is carved out of a default. A window belongs to the day it opens on, so one
+that crosses midnight silences the next morning and the reason names the day it came from.
+
+Two things this deliberately does not do. There is no bundled holiday calendar: the dates you
+observe are yours to supply, and a bundled one goes stale without anyone noticing. And one row
+cannot express more than 24 hours, so a Friday evening to Saturday evening silence is two rows,
+`fri: 18:00 to 00:00` and `sat: 00:00 to 20:00`.
+
+Passing a single window is unchanged and remains the common case; a schedule whose every day
+resolves to the same window behaves identically to that window.
+
 `weeklyBudget({ limit, bypassPriority })` is the same shape keyed on the user's local ISO
 week; `defaultChecks({ weeklyLimit })` places it just before the daily one. Budgets are
 consumed in check order at commit, so when a weekly check passes and the daily one then
 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 +249,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 +338,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
@@ -390,6 +497,10 @@ preset) still refuses. Both are part of `npm run examples` and of the test suite
 pip install proactive-gate
 ```
 
+To run an unreleased state, install from the repository instead: `pip install "proactive-gate @
+git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`. The published release was
+uploaded from a local build with a token, so unlike the npm package it carries no build provenance.
+
 ```python
 from proactive_gate import Gate
 gate = Gate.from_policy(policy)          # the same policy.json

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 |
@@ -234,6 +309,10 @@ kurmak gerekmez. Her biri kapının gerekçesiyle reddeder ve onayda bütçeyi t
 pip install proactive-gate
 ```
 
+Yayınlanmamış bir durumu denemek için depodan kurulur: `pip install "proactive-gate @
+git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`. Yayınlanan sürüm yerel bir
+derlemeden token ile yüklendi; npm paketinin aksine derleme kanıtı taşımıyor.
+
 `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).

package/dist/src/checks.d.ts

@@ -1,4 +1,4 @@
-import type { Check, CheckContext, Priority, Surface } from "./types.js";
+import type { Check, CheckContext, Priority, QuietSchedule, QuietWindow, Surface, Weekday } from "./types.js";
 export declare const DAY_SECONDS: number;
 /** Local "HH:MM" and calendar day for an instant in an IANA zone, using Intl only. */
 export declare function localClock(now: Date, timezone: string): {
@@ -7,6 +7,30 @@ export declare function localClock(now: Date, timezone: string): {
 };
 /** True when `minutes` falls inside [start, end), where the window may cross midnight. */
 export declare function inWindow(minutes: number, start: number, end: number): boolean;
+/**
+ * The weekday of a local calendar date, and the date before it.
+ *
+ * Both are pure calendar arithmetic on the "YYYY-MM-DD" that `localClock` already
+ * resolved through Intl, never arithmetic on an instant. That is what keeps zones
+ * with a 45-minute offset (Kathmandu, Chatham, Eucla) and every daylight-saving
+ * transition out of this: the offset was applied before we got here.
+ */
+export declare function weekdayOf(day: string): Weekday;
+export declare function dayBefore(day: string): string;
+/** The window in force on one local date: a date beats a weekday beats the default. */
+export declare function windowFor(quiet: QuietWindow | QuietSchedule, day: string): QuietWindow | null;
+/**
+ * Whether a local time is inside quiet hours, and which day's window says so.
+ *
+ * A window that crosses midnight belongs to the day it opens on, so a time can be
+ * quiet because of yesterday: Friday 18:00 to 00:00 silences Saturday 00:00 too.
+ * With one window every day this reduces exactly to `inWindow`, which is why the
+ * single-window form keeps behaving as it did.
+ */
+export declare function quietAt(quiet: QuietWindow | QuietSchedule, day: string, minutes: number): {
+    window: QuietWindow;
+    day: string;
+} | null;
 /** A production hard-stop that silences every producer at once. */
 export declare function killSwitch(isOn: () => boolean | Promise<boolean>): Check;
 /** Consent comes before everything, or you have evaluated preferences for someone who never agreed. */
@@ -36,6 +60,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 +72,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 +105,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 +142,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

@@ -39,6 +39,61 @@ export function inWindow(minutes, start, end) {
     return start < end ? minutes >= start && minutes < end : minutes >= start || minutes < end;
 }
 const localDay = (now, timezone) => (timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10));
+const WEEKDAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+/**
+ * The weekday of a local calendar date, and the date before it.
+ *
+ * Both are pure calendar arithmetic on the "YYYY-MM-DD" that `localClock` already
+ * resolved through Intl, never arithmetic on an instant. That is what keeps zones
+ * with a 45-minute offset (Kathmandu, Chatham, Eucla) and every daylight-saving
+ * transition out of this: the offset was applied before we got here.
+ */
+export function weekdayOf(day) {
+    const [y, m, d] = day.split("-").map(Number);
+    return WEEKDAYS[new Date(Date.UTC(y, m - 1, d)).getUTCDay()];
+}
+export function dayBefore(day) {
+    const [y, m, d] = day.split("-").map(Number);
+    return new Date(Date.UTC(y, m - 1, d - 1)).toISOString().slice(0, 10);
+}
+const isSchedule = (q) => !("start" in q);
+/** The window in force on one local date: a date beats a weekday beats the default. */
+export function windowFor(quiet, day) {
+    if (!isSchedule(quiet))
+        return quiet;
+    const byDate = quiet.dates?.[day];
+    if (byDate !== undefined)
+        return byDate;
+    const byDay = quiet.days?.[weekdayOf(day)];
+    if (byDay !== undefined)
+        return byDay;
+    return quiet.default ?? null;
+}
+/**
+ * Whether a local time is inside quiet hours, and which day's window says so.
+ *
+ * A window that crosses midnight belongs to the day it opens on, so a time can be
+ * quiet because of yesterday: Friday 18:00 to 00:00 silences Saturday 00:00 too.
+ * With one window every day this reduces exactly to `inWindow`, which is why the
+ * single-window form keeps behaving as it did.
+ */
+export function quietAt(quiet, day, minutes) {
+    const today = windowFor(quiet, day);
+    if (today) {
+        const start = parseHHMM(today.start);
+        const end = parseHHMM(today.end);
+        if (start !== end && (start < end ? minutes >= start && minutes < end : minutes >= start))
+            return { window: today, day };
+    }
+    const yesterday = windowFor(quiet, dayBefore(day));
+    if (yesterday) {
+        const start = parseHHMM(yesterday.start);
+        const end = parseHHMM(yesterday.end);
+        if (start > end && minutes < end)
+            return { window: yesterday, day: dayBefore(day) };
+    }
+    return null;
+}
 /* ------------------------------------------------------------------------ */
 /* The checks, in the order LILA runs them. Compose your own order freely.  */
 /* ------------------------------------------------------------------------ */
@@ -117,14 +172,16 @@ export function quietHours(options = {}) {
                 return pass;
             if (!user.timezone)
                 return skip("quiet hours set but no timezone on the user; cannot evaluate");
-            const { minutes } = localClock(now, user.timezone);
-            const start = parseHHMM(user.quietHours.start);
-            const end = parseHHMM(user.quietHours.end);
-            if (!inWindow(minutes, start, end))
+            const { minutes, day } = localClock(now, user.timezone);
+            const hit = quietAt(user.quietHours, day, minutes);
+            if (!hit)
                 return pass;
             if (atLeast(priority, floor))
                 return pass;
-            return reject(`quiet hours ${user.quietHours.start} to ${user.quietHours.end} ${user.timezone}; priority ${priority} is below the floor (${floor})`);
+            // Name the day the window came from: when it crossed midnight the reason is
+            // yesterday's setting, and a reader looking at today's would not find it.
+            const whose = hit.day === day ? "" : ` (${weekdayOf(hit.day)} ${hit.day})`;
+            return reject(`quiet hours ${hit.window.start} to ${hit.window.end}${whose} ${user.timezone}; priority ${priority} is below the floor (${floor})`);
         },
     };
 }
@@ -132,6 +189,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 +213,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 +299,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 +331,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 +355,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/dist/src/types.d.ts

@@ -3,6 +3,27 @@ export type Priority = "low" | "normal" | "high" | "critical";
 export declare const PRIORITY_RANK: Record<Priority, number>;
 /** Where a delivery may land. Free-form so callers can add their own. */
 export type Surface = "feed" | "push" | "chat" | "voice" | "email" | (string & {});
+/** A quiet window in local time, "HH:MM" to "HH:MM". `start` after `end` crosses midnight. */
+export type QuietWindow = {
+    start: string;
+    end: string;
+};
+/** Weekday keys for a quiet-hours schedule, Sunday first to match `Date#getUTCDay`. */
+export type Weekday = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+/**
+ * Quiet hours that differ by day. A working week is not Monday to Friday everywhere,
+ * and a holiday is not a weekday at all, so the window is resolved per day: a calendar
+ * date first, then the weekday, then the default. `null` at any level means the day has
+ * no quiet hours.
+ *
+ * There is no bundled holiday calendar and there will not be one: the dates a caller
+ * observes are the caller's to supply, and a bundled calendar goes stale silently.
+ */
+export type QuietSchedule = {
+    default?: QuietWindow | null;
+    days?: Partial<Record<Weekday, QuietWindow | null>>;
+    dates?: Record<string, QuietWindow | null>;
+};
 /** Everything the gate knows about the person it might interrupt. */
 export interface UserState {
     id: string;
@@ -20,11 +41,25 @@ export interface UserState {
     intensity?: "low" | "normal" | "high";
     /** IANA time zone, required for quiet hours. */
     timezone?: string;
-    /** Quiet hours in local time, "HH:MM". May cross midnight. */
-    quietHours?: {
-        start: string;
-        end: string;
-    } | null;
+    /**
+     * Quiet hours in local time, "HH:MM". May cross midnight.
+     *
+     * One window applies every day. A schedule gives a window per weekday, and per
+     * calendar date for the days a weekday cannot express, such as a public holiday:
+     *
+     * ```ts
+     * quietHours: {
+     *   default: { start: "22:00", end: "08:00" },
+     *   days: { fri: { start: "18:00", end: "00:00" }, sat: { start: "00:00", end: "20:00" } },
+     *   dates: { "2026-12-25": { start: "00:00", end: "23:59" } },
+     * }
+     * ```
+     *
+     * `null` for a weekday or a date means no quiet hours that day, which is how you
+     * carve a working day out of a default. A date beats a weekday, a weekday beats
+     * the default. Dates are the user's local calendar dates, "YYYY-MM-DD".
+     */
+    quietHours?: QuietWindow | QuietSchedule | null;
     /** When the user joined. Drives the trust ramp. */
     createdAt?: Date | string;
     /** Surfaces the user allows, in preference order. Defaults to the candidate's surfaces. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",