proactive-gate 0.2.1 → 0.2.3

package/README.md

@@ -100,14 +100,40 @@ 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
+week; `defaultChecks({ weeklyLimit })` places it just before the daily one. It was contributed by
+[@edwardsong08](https://github.com/edwardsong08) in [#9](https://github.com/Bubblegunn/proactive-gate/pull/9). 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.
@@ -349,11 +375,62 @@ if (decision.allowed && await gate.commit(decision, input)) {   // INCR, returns
 counter is keyed on the user's local day, so a budget resets at the user's midnight,
 not at UTC.
 
+## One message per event, when the transport delivers twice
+
+Message transports deliver at least once. A webhook that does not get its `200`
+quickly enough is sent again; a queue hands the same event to two workers; a retry
+after a timeout arrives after the first attempt already succeeded. The user sees the
+same message twice and reads it as a broken assistant.
+
+`dedupe` is the check for it, and it is off unless you ask for it:
+
+```ts
+const gate = createGate({ checks: defaultChecks({ dedupe: true }), store });
+
+await gate.evaluate({
+  user,
+  candidate: { id: crypto.randomUUID(), type: "shipping", dedupeKey: "order:42:shipped" },
+});
+```
+
+The key is yours because only you know what makes two attempts the same event.
+Derive it from the event, `order:42:shipped`, not from a fresh identifier per attempt
+and not from the message text, which usually carries a timestamp and so differs on
+every retry. Without a `dedupeKey` the check skips and says so, rather than guessing a
+key and silently doing nothing.
+
+Three things about it are worth stating, because they are what a hand-rolled version
+usually gets wrong.
+
+**The claim is atomic and happens at commit.** Two workers holding the same event both
+evaluate before either has recorded anything, so a check that only reads cannot tell
+them apart. `dedupe` reads at evaluate and claims at commit with the same increment the
+budgets use; only the caller that receives the first increment may send. A
+read-then-write claim lets both through, and the spec calls that non-conforming.
+
+**A suppressed duplicate does not cost a message.** `dedupe` consumes before the
+budgets, so when it loses the race the gate stops there and the counter is never
+incremented. The cost of that ordering, which is real: an event that clears `dedupe`
+and is then refused by an exhausted budget has claimed its key for the rest of the
+window.
+
+**The window is fixed from the first claim, not sliding.** A stream of duplicates does
+not push the expiry further out; every store here keeps the original expiry when a key
+is incremented again.
+
+The default window is 24 hours, which is the common retry horizon rather than a number
+of ours: Stripe prunes an idempotency key ["after they're at least 24 hours
+old"](https://docs.stripe.com/api/idempotent_requests), and Nylas gives the same figure
+as the safe default for [webhook
+deduplication](https://developer.nylas.com/docs/cookbook/agent-accounts/prevent-duplicate-replies/).
+Set `windowSeconds` from your own transport's retry horizon.
+
 ## Stores
 
 `MemoryStore` keeps values in process memory and is useful for a single instance. `RedisStore`
 shares values across instances. `SqliteStore` persists values in a SQLite database without
-adding a package dependency. `SqliteStore` requires Node.js 22.5 or newer; the SQLite module
+adding a package dependency. It was contributed by
+[@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) in [#3](https://github.com/Bubblegunn/proactive-gate/pull/3). `SqliteStore` requires Node.js 22.5 or newer; the SQLite module
 is loaded only when the store is constructed so the package can still be used on Node.js 20. On Node 22 the module prints an ExperimentalWarning on first use; it is stable from Node 24.
 
 ## Fail open, on purpose
@@ -472,6 +549,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
@@ -568,6 +649,15 @@ per-type switch and a priority floor that bypasses quiet time. Horvitz's work on
 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.
 
+## Thanks
+
+Two people sent pull requests on the day this was published, neither of whom I had spoken to
+before. [@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) wrote `SqliteStore`
+([#3](https://github.com/Bubblegunn/proactive-gate/pull/3)) and
+[@edwardsong08](https://github.com/edwardsong08) wrote the weekly budget
+([#9](https://github.com/Bubblegunn/proactive-gate/pull/9)). Both shipped in 0.1.2 and are in
+every release since, including the one you install today.
+
 ## Development
 
 ```

package/README.tr.md

@@ -309,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).
@@ -338,6 +342,54 @@ if (decision.allowed && await gate.commit(decision, input)) {   // INCR, returns
 `RedisStore`, `INCR` kullanır ve günün TTL'sini ilk artırmada ekler. Sayaç kullanıcının yerel
 gününe göre anahtarlanır, bu yüzden bütçe UTC'de değil kullanıcının gece yarısında sıfırlanır.
 
+## Taşıma iki kez ilettiğinde tek mesaj
+
+Mesaj taşımaları en az bir kez iletir. `200` yanıtını yeterince hızlı alamayan bir
+webhook yeniden gönderilir, bir kuyruk aynı olayı iki işçiye verir, zaman aşımından
+sonraki bir deneme ilki çoktan başarılı olmuşken gelir. Kullanıcı aynı mesajı iki kez
+görür ve bunu bozuk bir asistan diye okur.
+
+`dedupe` bunun için, ve istemediğiniz sürece kapalıdır:
+
+```ts
+const gate = createGate({ checks: defaultChecks({ dedupe: true }), store });
+
+await gate.evaluate({
+  user,
+  candidate: { id: crypto.randomUUID(), type: "shipping", dedupeKey: "order:42:shipped" },
+});
+```
+
+Anahtar sizin, çünkü iki denemeyi aynı olay yapan şeyi yalnızca siz bilirsiniz. Onu
+olaydan türetin, `order:42:shipped` gibi; her deneme için yeni üretilen bir kimlikten
+ya da mesaj metninden değil, çünkü metin genellikle bir zaman damgası taşır ve her
+denemede farklı olur. `dedupeKey` yoksa kontrol bunu söyleyerek kenara çekilir, bir
+anahtar uydurup sessizce hiçbir şey yapmaz.
+
+Elle yazılmış sürümlerin genellikle yanlış yaptığı üç nokta var.
+
+**Talep atomiktir ve commit anında olur.** Aynı olayı tutan iki işçi, henüz hiçbir şey
+kaydedilmeden değerlendirir; yalnızca okuyan bir kontrol onları ayıramaz. `dedupe`
+evaluate'te okur, commit'te bütçelerin kullandığı artırmayla talep eder ve yalnızca ilk
+artırmayı alan gönderebilir. Önce oku sonra yaz biçiminde bir talep ikisini de geçirir
+ve şartname bunu uygunsuz sayar.
+
+**Bastırılan bir kopya mesaj hakkı harcamaz.** `dedupe` bütçelerden önce tüketir, bu
+yüzden yarışı kaybettiğinde kapı orada durur ve sayaç hiç artmaz. Bu sıralamanın bedeli
+de gerçek: `dedupe`'u geçip ardından tükenmiş bir bütçeye takılan bir olay, pencerenin
+kalanı için anahtarını yakmış olur.
+
+**Pencere ilk talepten itibaren sabittir, kaymaz.** Arka arkaya gelen kopyalar bitiş
+zamanını ileri itmez; buradaki her mağaza, bir anahtar yeniden artırıldığında ilk
+bitiş zamanını korur.
+
+Varsayılan pencere 24 saat, ve bu bizim seçtiğimiz bir sayı değil, yaygın yeniden
+deneme ufku: Stripe bir idempotency anahtarını ["en az 24 saatlik olduktan
+sonra"](https://docs.stripe.com/api/idempotent_requests) siliyor, Nylas da webhook
+[tekilleştirmesi](https://developer.nylas.com/docs/cookbook/agent-accounts/prevent-duplicate-replies/)
+için aynı rakamı güvenli varsayılan olarak veriyor. `windowSeconds` değerini kendi
+taşımanızın yeniden deneme ufkundan seçin.
+
 ## Bilerek açık başarısız olur
 
 Depoya bağlı bir kontrol hata fırlattığında (Redis düştü), varsayılan adayı geçirir ve ize

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. */
@@ -103,6 +127,42 @@ export declare function dailyBudget(options?: BudgetOptions): BudgetCheck;
 export declare function weeklyBudget(options?: BudgetOptions): BudgetCheck;
 /** At most `limit` deliveries per user per local calendar month. */
 export declare function monthlyBudget(options?: BudgetOptions): BudgetCheck;
+export declare const dedupeKeyFor: (userId: string, key: string) => string;
+/**
+ * One delivery per event per window, claimed atomically at commit time.
+ *
+ * Message transports deliver at least once. A webhook that does not get its 200
+ * quickly enough arrives again, and two workers can pick up the same event at the
+ * same moment. Both attempts then evaluate against a store where nothing has been
+ * recorded yet, so a check that only reads cannot separate them: it has to claim.
+ * `consume()` claims with an atomic increment, the same primitive the budgets use,
+ * and only the caller that gets the first increment may send.
+ *
+ * Order matters and is the reason this check consumes before the budgets: when it
+ * loses the race the gate stops there, so the duplicate never spends one of the
+ * user's messages for the day. The cost of that ordering, stated rather than hidden:
+ * the key is claimed before a later budget check runs, so an event that clears
+ * dedupe and is then refused by an exhausted budget has burnt its key for the rest
+ * of the window.
+ *
+ * The window is fixed from the first claim rather than sliding; every store here
+ * keeps the original expiry when a key is incremented again.
+ *
+ * `candidate.dedupeKey` is the caller's, because only the caller knows what makes
+ * two attempts the same event. Without it the check skips rather than guessing: a
+ * dedupe keyed on something unique per attempt silently does nothing, which is
+ * worse than not running.
+ *
+ * The 24-hour default is the common convention for how long a retry may arrive:
+ * Stripe prunes an idempotency key "after they're at least 24 hours old"
+ * (https://docs.stripe.com/api/idempotent_requests), and Nylas gives the same
+ * figure as the safe default for webhook deduplication
+ * (https://developer.nylas.com/docs/cookbook/agent-accounts/prevent-duplicate-replies/).
+ * Pick your own from your transport's retry horizon.
+ */
+export declare function dedupe(options?: {
+    windowSeconds?: number;
+}): Check;
 /**
  * Expected-utility alerting: act only when the caller's estimate of acceptance
  * clears tau = cFA / (cFA + pNeed * cFN). That threshold is the classical Bayes
@@ -190,4 +250,11 @@ export declare function defaultChecks(options?: {
     dailyLimit?: number;
     weeklyLimit?: number;
     quietHoursFloor?: Priority;
+    /**
+     * Add `dedupe` before the budgets. Off by default because it adds an entry to
+     * every trace; on, it costs nothing until a candidate carries a `dedupeKey`.
+     */
+    dedupe?: boolean | {
+        windowSeconds?: number;
+    };
 }): Check[];

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})`);
         },
     };
 }
@@ -270,6 +327,67 @@ export function weeklyBudget(options = {}) {
 export function monthlyBudget(options = {}) {
     return budget({ id: "monthlyBudget", label: "monthly budget", defaultLimit: 60, keyFor: ({ user, now }) => monthlyBudgetKey(user.id, now, user.timezone), ttlSeconds: 32 * DAY_SECONDS }, options);
 }
+export const dedupeKeyFor = (userId, key) => `dedupe:${userId}:${key}`;
+const humanWindow = (seconds) => {
+    if (seconds % DAY_SECONDS === 0)
+        return `${seconds / DAY_SECONDS}d`;
+    if (seconds % 3600 === 0)
+        return `${seconds / 3600}h`;
+    if (seconds % 60 === 0)
+        return `${seconds / 60}m`;
+    return `${seconds}s`;
+};
+/**
+ * One delivery per event per window, claimed atomically at commit time.
+ *
+ * Message transports deliver at least once. A webhook that does not get its 200
+ * quickly enough arrives again, and two workers can pick up the same event at the
+ * same moment. Both attempts then evaluate against a store where nothing has been
+ * recorded yet, so a check that only reads cannot separate them: it has to claim.
+ * `consume()` claims with an atomic increment, the same primitive the budgets use,
+ * and only the caller that gets the first increment may send.
+ *
+ * Order matters and is the reason this check consumes before the budgets: when it
+ * loses the race the gate stops there, so the duplicate never spends one of the
+ * user's messages for the day. The cost of that ordering, stated rather than hidden:
+ * the key is claimed before a later budget check runs, so an event that clears
+ * dedupe and is then refused by an exhausted budget has burnt its key for the rest
+ * of the window.
+ *
+ * The window is fixed from the first claim rather than sliding; every store here
+ * keeps the original expiry when a key is incremented again.
+ *
+ * `candidate.dedupeKey` is the caller's, because only the caller knows what makes
+ * two attempts the same event. Without it the check skips rather than guessing: a
+ * dedupe keyed on something unique per attempt silently does nothing, which is
+ * worse than not running.
+ *
+ * The 24-hour default is the common convention for how long a retry may arrive:
+ * Stripe prunes an idempotency key "after they're at least 24 hours old"
+ * (https://docs.stripe.com/api/idempotent_requests), and Nylas gives the same
+ * figure as the safe default for webhook deduplication
+ * (https://developer.nylas.com/docs/cookbook/agent-accounts/prevent-duplicate-replies/).
+ * Pick your own from your transport's retry horizon.
+ */
+export function dedupe(options = {}) {
+    const windowSeconds = options.windowSeconds ?? DAY_SECONDS;
+    const label = humanWindow(windowSeconds);
+    return {
+        id: "dedupe",
+        async run({ user, candidate, store }) {
+            if (!candidate.dedupeKey)
+                return skip("no dedupeKey on the candidate; deduplication cannot be evaluated");
+            const seen = await store.get(dedupeKeyFor(user.id, candidate.dedupeKey));
+            return seen === null ? pass : reject(`already delivered within the last ${label}`);
+        },
+        async consume({ user, candidate, store }) {
+            if (!candidate.dedupeKey)
+                return true;
+            const claims = await store.incr(dedupeKeyFor(user.id, candidate.dedupeKey), windowSeconds);
+            return claims === 1;
+        },
+    };
+}
 /* ------------------------------------------------------------------------ */
 /* Optional, caller-fed checks. Off by default; the package ships no model.  */
 /* ------------------------------------------------------------------------ */
@@ -423,6 +541,7 @@ export function defaultChecks(options = {}) {
         trustRamp(),
         dismissalCooldown(),
         adaptiveTiming(),
+        ...(options.dedupe ? [dedupe(typeof options.dedupe === "object" ? options.dedupe : {})] : []),
         ...(options.weeklyLimit === undefined ? [] : [weeklyBudget({ limit: options.weeklyLimit })]),
         dailyBudget({ limit: options.dailyLimit ?? 5 }),
     ];

package/dist/src/policy.js

@@ -20,6 +20,7 @@ export const KNOWN_CHECKS = {
     trustRamp: (o) => checks.trustRamp({ ...opt(num(o, "days"), "days"), ...opt(prio(o, "minPriority"), "minPriority") }),
     dismissalCooldown: (o) => checks.dismissalCooldown({ ...opt(num(o, "dismissals"), "dismissals"), ...opt(num(o, "withinDays"), "withinDays"), ...opt(num(o, "silenceDays"), "silenceDays") }),
     adaptiveTiming: () => checks.adaptiveTiming(),
+    dedupe: (o) => checks.dedupe({ ...opt(num(o, "windowSeconds"), "windowSeconds") }),
     dailyBudget: (o) => checks.dailyBudget(budgetOptions(o)),
     weeklyBudget: (o) => checks.weeklyBudget(budgetOptions(o)),
     monthlyBudget: (o) => checks.monthlyBudget(budgetOptions(o)),

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. */
@@ -54,6 +89,16 @@ export interface Candidate {
     pAccept?: number;
     /** Caller-estimated probability the user needs it; utilityFloor reads it, default 1. */
     pNeed?: number;
+    /**
+     * Identity of the underlying event, not of this attempt. `dedupe` claims it once
+     * per window, so a webhook redelivered by an at-least-once transport, or the same
+     * event picked up by two workers, produces one message rather than two.
+     *
+     * Derive it from what makes the event the same event: `order:42:shipped`, not a
+     * fresh UUID per attempt and not the message text, which usually carries a
+     * timestamp and so differs on every retry.
+     */
+    dedupeKey?: string;
     /** Free-form payload; the gate never reads it. */
     payload?: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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",
@@ -43,7 +43,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node test/spec-lint.mjs && node --test dist/test/gate.test.js dist/test/conformance.test.js dist/test/presets.test.js dist/test/adapters.test.js dist/test/init.test.js dist/test/properties.test.js test/release.test.mjs test/examples.test.mjs test/naive.test.mjs",
+    "test": "npm run build && node test/spec-lint.mjs && node --test dist/test/gate.test.js dist/test/conformance.test.js dist/test/presets.test.js dist/test/adapters.test.js dist/test/init.test.js dist/test/properties.test.js dist/test/dedupe.test.js test/release.test.mjs test/examples.test.mjs test/naive.test.mjs test/suite.test.mjs",
     "lint": "tsc -p tsconfig.json --noEmit",
     "spec-lint": "node test/spec-lint.mjs",
     "conformance": "npm run build && node dist/src/cli.js replay --fixtures spec/fixtures",