proactive-gate 0.2.3 → 0.2.4

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.3",
+  "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,6 +37,7 @@
   },
   "files": [
     "dist/src",
+    "spec",
     "README.md",
     "LICENSE"
   ],
@@ -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

package/spec/fixtures/adaptive-timing/placeholder.json

@@ -0,0 +1,58 @@
+{
+  "spec_version": "1.2.0",
+  "since": "1.0.0",
+  "name": "adaptive-timing/placeholder",
+  "description": "A JSON policy cannot carry a next-good-moment function; the placeholder passes and keeps the trace shape.",
+  "policy": {
+    "specVersion": "1.0.0",
+    "checks": [
+      {
+        "id": "consent"
+      },
+      {
+        "id": "adaptiveTiming"
+      },
+      {
+        "id": "dailyBudget"
+      }
+    ]
+  },
+  "tests": [
+    {
+      "description": "passes",
+      "input": {
+        "user": {
+          "id": "u1",
+          "consent": true,
+          "proactiveEnabled": true,
+          "mode": "normal",
+          "intensity": "normal",
+          "timezone": "Europe/Istanbul",
+          "quietHours": {
+            "start": "22:00",
+            "end": "08:00"
+          },
+          "createdAt": "2026-01-01T00:00:00Z"
+        },
+        "candidate": {
+          "id": "c1",
+          "type": "reminder",
+          "priority": "normal",
+          "surfaces": [
+            "push",
+            "feed"
+          ]
+        },
+        "now": "2026-09-04T09:00:00Z"
+      },
+      "expect": {
+        "allowed": true,
+        "trace": [
+          "consent",
+          "adaptiveTiming",
+          "dailyBudget"
+        ]
+      }
+    }
+  ]
+}

package/spec/fixtures/budget/bypass-priority.json

@@ -0,0 +1,100 @@
+{
+  "spec_version": "1.2.0",
+  "since": "1.0.0",
+  "name": "budget/bypass-priority",
+  "description": "A bypass priority passes the budget without reading or consuming it.",
+  "policy": {
+    "specVersion": "1.0.0",
+    "checks": [
+      {
+        "id": "consent"
+      },
+      {
+        "id": "dailyBudget",
+        "limit": 1,
+        "bypassPriority": "critical"
+      }
+    ]
+  },
+  "store_seed": {
+    "budget:u1:2026-09-04": "1"
+  },
+  "tests": [
+    {
+      "description": "critical passes a full budget and commit consumes nothing",
+      "input": {
+        "user": {
+          "id": "u1",
+          "consent": true,
+          "proactiveEnabled": true,
+          "mode": "normal",
+          "intensity": "normal",
+          "timezone": "Europe/Istanbul",
+          "quietHours": {
+            "start": "22:00",
+            "end": "08:00"
+          },
+          "createdAt": "2026-01-01T00:00:00Z"
+        },
+        "candidate": {
+          "id": "c1",
+          "type": "reminder",
+          "priority": "critical",
+          "surfaces": [
+            "push",
+            "feed"
+          ]
+        },
+        "now": "2026-09-04T09:00:00Z"
+      },
+      "commit": true,
+      "expect": {
+        "allowed": true,
+        "trace": [
+          "consent",
+          "dailyBudget"
+        ],
+        "commit": true,
+        "store_after": {
+          "budget:u1:2026-09-04": "1"
+        }
+      }
+    },
+    {
+      "description": "normal is rejected",
+      "input": {
+        "user": {
+          "id": "u1",
+          "consent": true,
+          "proactiveEnabled": true,
+          "mode": "normal",
+          "intensity": "normal",
+          "timezone": "Europe/Istanbul",
+          "quietHours": {
+            "start": "22:00",
+            "end": "08:00"
+          },
+          "createdAt": "2026-01-01T00:00:00Z"
+        },
+        "candidate": {
+          "id": "c2",
+          "type": "reminder",
+          "priority": "normal",
+          "surfaces": [
+            "push",
+            "feed"
+          ]
+        },
+        "now": "2026-09-04T09:00:00Z"
+      },
+      "expect": {
+        "allowed": false,
+        "rejectedBy": "dailyBudget",
+        "trace": [
+          "consent",
+          "dailyBudget"
+        ]
+      }
+    }
+  ]
+}

package/spec/fixtures/budget/daily-atomic-commit.json

@@ -0,0 +1,140 @@
+{
+  "spec_version": "1.2.0",
+  "since": "1.0.0",
+  "name": "budget/daily-atomic-commit",
+  "description": "evaluate reads the counter, commit consumes it, the extra commit is refused.",
+  "policy": {
+    "specVersion": "1.0.0",
+    "checks": [
+      {
+        "id": "consent"
+      },
+      {
+        "id": "dailyBudget",
+        "limit": 2
+      }
+    ]
+  },
+  "store_seed": {
+    "budget:u1:2026-09-04": "1"
+  },
+  "tests": [
+    {
+      "description": "one used, one left",
+      "input": {
+        "user": {
+          "id": "u1",
+          "consent": true,
+          "proactiveEnabled": true,
+          "mode": "normal",
+          "intensity": "normal",
+          "timezone": "Europe/Istanbul",
+          "quietHours": {
+            "start": "22:00",
+            "end": "08:00"
+          },
+          "createdAt": "2026-01-01T00:00:00Z"
+        },
+        "candidate": {
+          "id": "c1",
+          "type": "reminder",
+          "priority": "normal",
+          "surfaces": [
+            "push",
+            "feed"
+          ]
+        },
+        "now": "2026-09-04T09:00:00Z"
+      },
+      "commit": true,
+      "expect": {
+        "allowed": true,
+        "trace": [
+          "consent",
+          "dailyBudget"
+        ],
+        "commit": true,
+        "store_after": {
+          "budget:u1:2026-09-04": "2"
+        }
+      }
+    },
+    {
+      "description": "two used: rejected at evaluate",
+      "input": {
+        "user": {
+          "id": "u1",
+          "consent": true,
+          "proactiveEnabled": true,
+          "mode": "normal",
+          "intensity": "normal",
+          "timezone": "Europe/Istanbul",
+          "quietHours": {
+            "start": "22:00",
+            "end": "08:00"
+          },
+          "createdAt": "2026-01-01T00:00:00Z"
+        },
+        "candidate": {
+          "id": "c2",
+          "type": "reminder",
+          "priority": "normal",
+          "surfaces": [
+            "push",
+            "feed"
+          ]
+        },
+        "now": "2026-09-04T09:00:00Z"
+      },
+      "expect": {
+        "allowed": false,
+        "rejectedBy": "dailyBudget",
+        "trace": [
+          "consent",
+          "dailyBudget"
+        ],
+        "reason_pattern": "2 used \\(2\\)"
+      }
+    },
+    {
+      "description": "next local day resets (00:30 Istanbul)",
+      "input": {
+        "user": {
+          "id": "u1",
+          "consent": true,
+          "proactiveEnabled": true,
+          "mode": "normal",
+          "intensity": "normal",
+          "timezone": "Europe/Istanbul",
+          "quietHours": {
+            "start": "22:00",
+            "end": "08:00"
+          },
+          "createdAt": "2026-01-01T00:00:00Z"
+        },
+        "candidate": {
+          "id": "c3",
+          "type": "reminder",
+          "priority": "normal",
+          "surfaces": [
+            "push",
+            "feed"
+          ]
+        },
+        "now": "2026-09-04T21:30:00Z"
+      },
+      "commit": true,
+      "expect": {
+        "allowed": true,
+        "trace": [
+          "consent",
+          "dailyBudget"
+        ],
+        "commit": true,
+        "store_after": {
+          "budget:u1:2026-09-05": "1"
+        }
+      }
+    }
+  ]
+}