proactive-gate 0.2.2 → 0.2.4

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
@@ -543,6 +595,69 @@ Python tests both run all of them; `npx proactive-gate replay --fixtures spec/fi
 them from the command line. A third implementation starts from the fixtures, not from this
 source.
 
+The suite is an artifact, not a folder in this package. It is versioned by
+[`spec/SPEC_VERSION`](spec/SPEC_VERSION) and tagged `spec/vX.Y.Z`, a series separate from the
+package's release tags, so an implementation in any language can pin it without depending on npm
+or PyPI:
+
+```sh
+git clone --depth 1 --branch spec/v1.2.0 https://github.com/Bubblegunn/proactive-gate
+```
+
+The npm package also ships it, so `node_modules/proactive-gate/spec/fixtures` exists after an
+install. [`spec/CONFORMANCE.md`](spec/CONFORMANCE.md) states what passing means field by field,
+and how to declare a skip: silence about a failing fixture is the one thing that makes a
+conformance claim worthless.
+
+<!-- conformance:start -->
+Generated by `npm run conformance-table`; CI fails when it is stale.
+
+| implementation | spec version | fixtures passed | declared skips |
+|---|---|---:|---|
+| TypeScript | 1.2.0 | 32 of 32 | none |
+| Python | 1.2.0 | 32 of 32 | none |
+<!-- conformance:end -->
+
+### What made this work elsewhere, and why it might not here
+
+The [JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) is the
+working example of a language-neutral fixture set becoming common ground: JSON files, a directory
+per draft, consumed as "a git submodule or git subtree", an `optional/` directory for cases
+implementations may decline, and validators in more than twenty languages held to it. What made it
+work is that people were already implementing JSON Schema and already disagreeing about edge cases.
+The suite settled arguments that existed.
+
+This suite has no such argument to settle. Almost nobody has implemented notification gating twice,
+so there is no disagreement waiting for a referee, and being early to a contract nobody adopts is
+indistinguishable from being wrong. What the suite is worth today is narrower and still worth
+having: it is why the Python package behaves like the TypeScript one, and it is what a third
+implementation would be measured against rather than argued with.
+
+Two implementations pass it and the same person wrote both, hours apart. That is a consistency
+check, not independent verification, and the honest test is a third implementation written from
+`SPEC.md` by someone who has not read this source. The method is in
+[`docs/superpowers/specs/2026-09-05-proactive-gate-conformance-design.md`](docs/superpowers/specs/2026-09-05-proactive-gate-conformance-design.md).
+
+### Where this sits next to MCP and A2A
+
+Neither protocol answers the question this library answers, and both were read at the source rather
+than summarised.
+
+MCP's [elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation) is
+the closest mechanism and it is complementary. It "provides a standardized way for servers to
+request additional information from users through the client during interactions", and those
+requests "occur *nested* inside other MCP server features". The user already started something and
+the server needs input to finish it. Nothing there concerns being approached by an agent that
+nobody asked: no quiet hours, no budget, no dismissal cooldown, no consent to be contacted.
+
+A2A's [push notifications](https://a2a-protocol.org/latest/specification/) are transport. The
+specification scopes them to server-to-server integrations, long-running tasks and event-driven
+architectures, delivered by HTTP POST to client-registered webhook endpoints. Quiet hours, rate
+limits and notification budgets do not appear in it.
+
+Both answer how a message moves. Neither answers whether it should be sent now. That is the whole
+claim, and it is all the reading supports.
+
 ## Performance
 
 `npm run bench` runs `gate.evaluate()` ten thousand times with the default twelve checks and
@@ -597,6 +712,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.4",
   "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",
@@ -37,13 +37,14 @@
   },
   "files": [
     "dist/src",
+    "spec",
     "README.md",
     "LICENSE"
   ],
   "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",
@@ -53,7 +54,8 @@
     "release": "node scripts/release.mjs",
     "release-gate": "npm run build && node scripts/release-gate.mjs",
     "trace-svg": "npm run build && node scripts/trace-svg.mjs",
-    "bench:compare": "npm run build && node bench/compare.mjs"
+    "bench:compare": "npm run build && node bench/compare.mjs",
+    "conformance-table": "node scripts/conformance-table.mjs"
   },
   "engines": {
     "node": ">=20"

package/spec/CONFORMANCE.md

@@ -0,0 +1,83 @@
+# Claiming conformance
+
+This directory is the contract. `SPEC.md` states the behaviour as numbered requirements and
+`fixtures/` holds the cases that decide whether an implementation meets them. Both are
+language-neutral: an implementation in any language can run them, and none of it depends on the
+npm or PyPI packages.
+
+## Getting the suite
+
+The suite is versioned by `SPEC_VERSION`, and each version is tagged `spec/vX.Y.Z`, a series
+separate from the package's own `vX.Y.Z` release tags.
+
+```sh
+git clone --depth 1 --branch spec/v1.2.0 https://github.com/Bubblegunn/proactive-gate
+# or, to keep it beside your own source and update it deliberately
+git subtree add --prefix spec https://github.com/Bubblegunn/proactive-gate spec/v1.2.0 --squash
+```
+
+A JavaScript implementation can also read the fixtures from an install, because the npm package
+ships this directory: `node_modules/proactive-gate/spec/fixtures`. The Python wheel does not ship
+it; use git there.
+
+## What passing means
+
+An implementation conforms at version X when, for every fixture whose `spec_version` is X, every
+assertion in every test's `expect` holds.
+
+A fixture is a JSON document described by `schema/fixture.schema.json`. For each test, evaluate the
+policy against the input at the given `now` and compare:
+
+| Field | Comparison |
+|---|---|
+| `allowed` | exact |
+| `trace` | exact, the ordered list of check ids that ran |
+| `rejectedBy`, `deferredBy` | exact, including absent |
+| `retryAt`, `deliverAt` | exact, as an ISO instant ending `Z` |
+| `surfaces`, `shadowed`, `nearLimit` | exact, when the fixture asserts them |
+| `reason_pattern` | a regular expression that must match the decision's reason |
+| `commit` | the boolean returned by committing the decision, when the test sets `commit` |
+| `store_after` | exact, each key read from the store after the test, with the policy's key prefix |
+
+`ms` on a trace entry is informative and is never asserted (`SPEC.md` 8.1). A fixture's
+`store_seed` is written to the store before the tests run, with the same prefix.
+
+Both existing runners work exactly this way, so this table describes the suite rather than adding a
+second rule to it: see `src/conformance.ts` and `python/src/proactive_gate/conformance.py`.
+
+## Declaring what you skip
+
+Silence about a failing fixture is the one thing that makes a conformance claim worthless. Declare
+skips in `skip/<impl>.txt`, one fixture name per line, with the reason after a `#`:
+
+```
+quiet-hours/apia   # no IANA time zone database on this platform
+```
+
+`SPEC.md` requires that file to be empty at a stable release. Before then, the honest form of a
+partial claim is "conforms to 1.2.0 except these fixtures, for these reasons", stated where a
+reader will see it.
+
+## Declaring the version you target
+
+State the spec version in your own metadata, and assert in your continuous integration that it
+equals the `SPEC_VERSION` in the suite you vendored. Both implementations here do that, and it is
+what stops a suite from being updated underneath a claim.
+
+## Adding to the suite
+
+A fixture is a contract for every implementation, not only this one. So a change lands in
+`SPEC.md`, in `fixtures/`, and in both implementations, or it does not land. New fixtures carry
+`since` set to the version that introduced them, and `spec_version` set to the current one, which
+`test/spec-lint.mjs` checks.
+
+Versioning follows `SPEC.md`: a patch adds fixtures existing implementations already pass, a minor
+adds a check or a field, a major changes an expectation.
+
+## The honest status of this suite
+
+Two implementations pass it, and the same person wrote both within hours of each other. That is
+weaker evidence than it looks: agreement between two implementations by one author is closer to a
+consistency check than to independent verification. A third implementation, written from `SPEC.md`
+by someone who has not read the source, is what would test whether this document is enough. Until
+that exists, treat the suite as a contract that has been used twice, not as a proven standard.

package/spec/SPEC.md

@@ -0,0 +1,140 @@
+# proactive-gate behaviour contract
+
+Version: see `SPEC_VERSION`. The key words MUST, MUST NOT, SHOULD and MAY are to be read as in
+RFC 2119. An implementation conforms when it passes every fixture under `fixtures/` for its
+declared spec version, minus the fixtures listed in its `skip/<impl>.txt` file, which MUST be
+empty at a stable release.
+
+Versioning: patch releases add fixtures that existing implementations already pass; minor
+releases add a check or field and mark it with `since`; major releases change an expectation.
+An implementation declares the spec version it targets, and its CI MUST assert that the value
+equals `SPEC_VERSION`.
+
+## 1. Inputs
+
+1.1 An evaluation input is a user, a candidate and an instant `now`. `now` MUST be supplied by
+the caller in fixtures and MAY default to the current instant in library use.
+
+1.2 A user has at least `id` and `consent`. Optional fields: `proactiveEnabled`, `mode`,
+`snoozedUntil`, `mutedTypes`, `intensity` (low, normal, high), `timezone` (IANA), `quietHours`
+(a window, or a schedule; see 6.3), `createdAt`, `surfaces`, `consents` (map of
+name to boolean), `lastInboundAt`, `minor`, `existingCustomer`.
+
+1.3 A candidate has at least `id` and `type`. Optional: `priority` (low, normal, high,
+critical; default normal), `surfaces`, `channel`, `busy`, `pAccept`, `pNeed`, `payload`.
+
+1.4 An implementation MUST NOT read `payload`.
+
+## 2. Evaluation order and short circuit
+
+2.1 An implementation MUST run checks in policy order and MUST stop at the first check whose
+outcome is `reject` or `defer` and which is not in shadow mode.
+
+2.2 The trace MUST list every check that ran, in order, with its outcome kind. Checks after the
+stopping check MUST NOT appear.
+
+2.3 The surfaces of an allowed decision start as the candidate's surfaces (default `["feed"]`)
+filtered by the user's allowed surfaces when the user lists any, and MAY be narrowed by
+`adjust` outcomes.
+
+## 3. Outcomes
+
+3.1 A check returns exactly one of `pass`, `reject` (with a reason), `adjust` (reason, optional
+`deliverAt`, optional `surfaces`), `skip` (reason), or `defer` (reason and `retryAt`).
+
+3.2 A check marked non-rejecting that returns `reject` MUST be recorded as `skip` and MUST NOT
+stop evaluation.
+
+3.3 `defer` produces a decision with `allowed` false, `deferredBy` set to the check id and
+`retryAt` set to the instant the check supplied. `rejectedBy` MUST be absent.
+
+3.4 A `pass` MAY carry `nearLimit` with `used` and `limit`; the decision lists every such entry
+in order.
+
+3.5 A check that throws MUST be recorded as `skip` and evaluation continues when the gate fails
+open, or as `reject` and evaluation stops when it fails closed. The default is open.
+
+## 4. Shadow mode
+
+4.1 A check with `shadow` true that returns `reject` or `defer` MUST be recorded in the trace
+with its real outcome kind and `shadow` true, its id MUST be appended to `shadowed`, and
+evaluation MUST continue as if it had passed.
+
+## 5. Store keys and atomic commit
+
+5.1 Keys, before the implementation's prefix (default `pg:`):
+`budget:<userId>:<YYYY-MM-DD>` local day, `weeklyBudget:<userId>:<YYYY>-W<WW>` ISO week of the
+local day, `monthlyBudget:<userId>:<YYYY-MM>`, `cooldown:<userId>:<type>` (JSON array of epoch
+milliseconds), `rate:<scope>:<window>` for rate limits, `windowBudget:<userId>:<epochSeconds of
+lastInboundAt>`, `commit:<decisionId>`.
+
+5.2 Budget checks read the counter at evaluate and MUST NOT increment it. `commit` MUST
+increment atomically, in check order, and return false when a counter exceeds its limit.
+
+5.3 `commit` MUST be idempotent on the decision id: a second call returns the first result
+without incrementing.
+
+5.4 `commit` on a decision that is not allowed MUST return false without touching the store.
+
+5.5 `dedupe` keys as `dedupe:<userId>:<candidate.dedupeKey>`. With no `dedupeKey` on the
+candidate it MUST skip, not pass silently: a deduplication keyed on something unique per
+attempt does nothing, and an implementation that guessed a key would hide that.
+
+5.6 `dedupe` MUST NOT claim at evaluate. It reads the key at evaluate and rejects when the key
+is present; it claims at commit with the same atomic increment the budgets use, and only the
+caller receiving the first increment may deliver. Two callers evaluating the same event
+concurrently therefore both pass the check and exactly one commit succeeds. A read-then-write
+claim is non-conforming.
+
+5.7 Where `dedupe` and a budget are both present, `dedupe` MUST consume first, so a suppressed
+duplicate does not spend a budget unit. The consequence, which implementations MUST NOT hide:
+an event that clears `dedupe` and is then refused by an exhausted budget has claimed its key
+for the remainder of the window.
+
+5.8 The deduplication window is fixed from the first claim, not sliding. Incrementing an
+existing key MUST NOT extend its expiry.
+
+## 6. Clock and time zones
+
+6.1 `now` is an instant. Local day, minutes and ISO week are derived from `now` in the user's
+IANA zone; without a zone, UTC.
+
+6.2 A check MUST NOT read a wall clock. Fixtures with `now` far in the future only pass when
+`now` is honoured.
+
+6.3 Quiet hours use `[start, end)` and may cross midnight; `start == end` is an empty window.
+
+6.4 `quietHours` is either a window (`start`, `end` as `HH:MM`) or a schedule (since 1.1.0) with
+optional `default` (a window or null), `days` (a map of `sun` to `sat` to a window or null) and
+`dates` (a map of `YYYY-MM-DD` in the user's zone to a window or null). A window applies on every
+day; a schedule resolves one window per local date, and an implementation MUST resolve it as
+`dates[date]`, else `days[weekday(date)]`, else `default`, else none, where a present key whose
+value is null means the day has no quiet hours.
+
+6.5 A window belongs to the day it opens on. An implementation MUST treat a local time as quiet
+when the window resolved for that local date contains it, or when the window resolved for the
+previous local date crosses midnight and the time is before its `end`. The day resolved for the
+current date takes precedence when both apply. A schedule whose every day resolves to the same
+window MUST behave identically to that window given directly.
+
+6.6 The weekday of a local date MUST be derived from the local calendar date, not from an
+instant, so that a zone with an offset that is not a whole hour and a daylight-saving transition
+cannot change it.
+
+6.7 An implementation MUST NOT ship a calendar of holidays. `dates` is supplied by the caller.
+
+## 7. Policy document
+
+7.1 A policy is JSON with `specVersion`, optional `onStoreError`, optional `keyPrefix` and an
+ordered `checks` array. An entry is `{ "id": <check>, ...options, "shadow"?: bool }` or
+`{ "preset": <name>, ...options, "shadow"?: bool }`.
+
+7.2 A preset entry expands in place to the preset's ordered checks.
+
+7.3 An unknown check id or preset name MUST be rejected when the policy is compiled, naming the
+known ids.
+
+## 8. Trace
+
+8.1 Each trace entry has `id`, `outcome`, optional `reason`, `ms`, optional `shadow`. `ms` is
+informative and MUST NOT appear in fixtures.

package/spec/SPEC_VERSION

@@ -0,0 +1 @@
+1.2.0