proactive-gate 0.2.2 → 0.2.3

package/README.md

@@ -132,7 +132,8 @@ Passing a single window is unchanged and remains the common case; a schedule who
 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.
@@ -374,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
@@ -597,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

@@ -342,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

@@ -127,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
@@ -214,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

@@ -327,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.  */
 /* ------------------------------------------------------------------------ */
@@ -480,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

@@ -89,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.2",
+  "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",