proactive-gate 0.2.3 → 0.2.5

package/README.md

@@ -9,6 +9,7 @@ English | [Türkçe](README.tr.md)
   <img src="https://img.shields.io/bundlephobia/minzip/proactive-gate?style=flat-square&color=111111" alt="minzipped size">
   <img src="https://img.shields.io/github/stars/Bubblegunn/proactive-gate?style=flat-square&color=111111" alt="stars">
   <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT">
+  <a href="https://doi.org/10.5281/zenodo.22393512"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22393512-111111?style=flat-square" alt="DOI"></a>
 </p>
 
 Decide whether a proactive AI agent may reach a user right now, and log why not.
@@ -138,21 +139,23 @@ consumed in check order at commit, so when a weekly check passes and the daily o
 refuses, that weekly unit is spent without a delivery. It only happens when two commits
 race after a shared evaluate.
 
-### Two limits you should know before you adopt this
+### One limit you should know before you adopt this
 
-Neither is a bug, and both are pinned by tests so a future change has to be deliberate.
+It is not a bug, and it is pinned by tests so a future change has to be deliberate.
 
-**The week is the ISO week, so the weekly budget refills on Monday.** Where the working
-week runs Sunday to Thursday, that refill lands one day in: a user who spends the budget on
-Sunday has it back on Monday, with four working days still to run. Changing the key would
-move every counter already in your store, so it is documented rather than quietly altered.
-Pass your own budget check keyed how you like if the ISO week is wrong for your users.
-
-**Quiet hours are a single window, the same on every day of the week.** A user carries one
-`start` and one `end`, so a Friday window, a Shabbat window or a public holiday cannot be
-expressed. The day of the week is never read. If you need one, write a check: it is an
-object with an `id` and a `run`, it composes in the order you choose, and the trace will
-show it firing beside the built-in ones.
+**The week is the ISO week, so the weekly budget refills on Monday.** Monday is not where
+the week starts for most people: of the twenty most populous countries, CLDR gives Monday
+to seven, Sunday to eleven and Saturday to two, which you can read yourself with
+`new Intl.Locale("und-EG").getWeekInfo().firstDay`. Where the working week runs Sunday to
+Thursday, an ISO refill lands one day in: a user who spends the budget on Sunday has it back
+on Monday with four working days still to run. The key is ISO anyway, for two reasons. A
+counter already in your store is keyed by it, and moving the key silently resets every user
+mid-week. And the day the counter turns over is not the day the user is protected on: quiet
+hours already read the user's own weekday, including a Friday or a Shabbat window, and they
+are what decides when a notification is allowed. The budget only decides how many. If the ISO
+week is wrong for your users, pass your own budget check keyed how you like; it is an object
+with an `id` and a `run`, it composes in the order you choose, and the trace will show it
+firing beside the built-in ones.
 
 Order is a design decision and it should be visible. Consent has to come before
 everything. Quiet hours have to come before the budget, or a rejected candidate
@@ -550,8 +553,10 @@ 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.
+git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`. The Python package is published by
+the same workflow as the npm one, so it carries PyPI publish attestations naming the repository
+and the workflow that built each file. Releases before 0.2.2 were uploaded from a local build with
+a token and carry none.
 
 ```python
 from proactive_gate import Gate
@@ -595,6 +600,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
@@ -658,6 +726,18 @@ before. [@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) wrote `
 ([#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.
 
+## Cite this
+
+Every release is archived on Zenodo with a DOI, so a paper or a report can point at the
+exact code it ran.
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22393512.svg)](https://doi.org/10.5281/zenodo.22393512)
+
+That is the **concept** DOI: it always resolves to the newest version. To cite the exact
+version you ran, open that page, pick the version in the sidebar, and use the DOI shown
+there. `CITATION.cff` in this repository carries the same identifier, so GitHub's "Cite this
+repository" button produces correct BibTeX and APA without any copying by hand.
+
 ## Development
 
 ```

package/README.tr.md

@@ -81,12 +81,37 @@ olurdu.
 | 5 | `snooze()` | `user.snoozedUntil` gelecekteyse | genel duraklatma |
 | 6 | `mute()` | `candidate.type`, `user.mutedTypes` içindeyse | tür bazlı susturma |
 | 7 | `intensity()` | öncelik, kullanıcının yoğunluk tabanının altındaysa | low yalnızca high duyar, normal normal ve üstünü, high her şeyi |
-| 8 | `quietHours({ priorityFloor })` | kullanıcının yerel sessiz penceresi içindeyse | IANA saat dilimi, pencere gece yarısını geçebilir, taban ve üstünde atlanır |
+| 8 | `quietHours({ priorityFloor })` | kullanıcının yerel sessiz penceresi içindeyse | IANA saat dilimi, pencere gece yarısını geçebilir, taban ve üstünde atlanır; her gün tek pencere ya da [güne göre bir çizelge](#güne-göre-değişen-sessiz-saatler) |
 | 9 | `trustRamp({ days, minPriority })` | kullanıcı `days` günden yeniyse ve öncelik tabanın altındaysa | sistem, kullanıcı en az bağışlayıcıyken en az kalibredir |
 | 10 | `dismissalCooldown({ dismissals, withinDays, silenceDays })` | kullanıcı o türü pencere içinde `dismissals` kez reddettiyse | `gate.record(user, candidate, "dismissed")` ile beslenir; her yeni ret sessizliği yeniden başlatır |
 | 11 | `adaptiveTiming({ nextGoodMoment, surfacesFor })` | asla | reddetmez: `deliverAt` değerini taşır ya da yüzeyleri daraltır; `nonRejecting` işaretli bir kontrol istese de reddedemez |
 | 12 | `dailyBudget({ limit, bypassPriority })` | kullanıcının yerel gün sayacı sınırdaysa | `evaluate` okur, `commit` atomik artırır ve yine de reddedebilir |
 
+### Güne göre değişen sessiz saatler
+
+Çalışma haftası her yerde pazartesiden cumaya değildir ve tatil günü zaten hafta içi
+değildir. `quietHours` tek bir pencerenin yanında bir çizelge de alır:
+
+```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" } },
+}
+```
+
+Tarih haftanın gününü, o da varsayılanı yener; `null` o günün sessiz saati yok demektir ve
+varsayılanın içinden bir iş günü böyle oyulur. Bir pencere açıldığı güne aittir, yani gece
+yarısını geçen bir pencere ertesi sabahı susturur ve gerekçe hangi günden geldiğini söyler.
+
+Bunun bilerek yapmadığı iki şey var. Gömülü bir tatil takvimi yok: hangi tarihleri
+tuttuğunuz size aittir, gömülü olan ise kimse fark etmeden bayatlar. Ve tek bir satır 24
+saatten fazlasını anlatamaz, yani cuma akşamından cumartesi akşamına uzanan bir sessizlik
+iki satırdır: `fri: 18:00 to 00:00` ve `sat: 00:00 to 20:00`.
+
+Tek pencere geçmek eskisi gibi çalışır ve yaygın durum olmayı sürdürür; her günü aynı
+pencereye çıkan bir çizelge, o pencereyle birebir aynı davranır.
+
 Sıra bir tasarım kararıdır ve görünür olmalıdır. Rıza her şeyden önce gelmelidir. Sessiz
 saatler bütçeden önce gelmelidir, yoksa reddedilen bir aday hiç yapmadığı bir teslimi
 tüketir. İstediğiniz gibi yeniden sıralayın; iz ne yaptığınızı gösterecektir.
@@ -227,22 +252,24 @@ işyerinde sürekli ulaşılabilir olmaları beklendiği için katılmayı redde
 seçmediği bir sessizliğin bir bedeli var ve o bedel bu kütüphanenin yazdığı hiçbir izde
 görünmüyor.
 
-## Benimsemeden önce bilmeniz gereken iki sınır
-
-İkisi de hata değil ve ikisi de testle sabitlendi, böylece ileride değişecekse bilerek değişir.
-
-**Hafta, ISO haftasıdır; haftalık bütçe pazartesi yenilenir.** Çalışma haftası pazardan
-perşembeye uzanan yerlerde bu yenilenme haftanın birinci gününe denk gelir: pazar günü
-bütçesini harcayan bir kullanıcı pazartesi sabahı bütçesini geri alır ve önünde hâlâ dört
-iş günü vardır. Anahtarı değiştirmek deponuzdaki bütün sayaçları kaydıracağı için bunu
-sessizce değiştirmek yerine yazıyoruz. ISO haftası sizin kullanıcılarınız için yanlışsa
-kendi bütçe kontrolünüzü istediğiniz anahtarla yazabilirsiniz.
-
-**Sessiz saatler tek bir penceredir ve haftanın her günü aynıdır.** Kullanıcıda tek bir
-`start` ve tek bir `end` vardır; cuma penceresi, Şabat penceresi veya resmî tatil
-tanımlanamaz. Haftanın günü hiç okunmaz. Böyle bir kurala ihtiyacınız varsa kendi
-kontrolünüzü yazın: `id` ve `run` taşıyan bir nesnedir, istediğiniz sırada dizilir ve izde
-yerleşik kontrollerin yanında görünür.
+## Benimsemeden önce bilmeniz gereken bir sınır
+
+Hata değil ve testle sabitlendi, böylece ileride değişecekse bilerek değişir.
+
+**Hafta, ISO haftasıdır; haftalık bütçe pazartesi yenilenir.** Pazartesi, çoğu insan için
+haftanın başladığı gün değildir: en kalabalık yirmi ülkeden CLDR'ye göre yedisinde
+pazartesi, on birinde pazar, ikisinde cumartesi başlar; bunu kendiniz
+`new Intl.Locale("und-EG").getWeekInfo().firstDay` ile okuyabilirsiniz. Çalışma haftası
+pazardan perşembeye uzanan yerlerde ISO yenilenmesi haftanın birinci gününe denk gelir:
+pazar günü bütçesini harcayan bir kullanıcı pazartesi sabahı bütçesini geri alır ve önünde
+hâlâ dört iş günü vardır. Anahtar yine de ISO, iki nedenle. Deponuzdaki sayaç bu anahtarla
+tutuluyor ve anahtarı taşımak her kullanıcıyı haftanın ortasında sessizce sıfırlar. Ayrıca
+sayacın döndüğü gün, kullanıcının korunduğu gün değildir: sessiz saatler kullanıcının kendi
+haftalık gününü zaten okuyor, cuma ya da Şabat penceresi dahil, ve bildirimin ne zaman
+verilebileceğine onlar karar veriyor. Bütçe yalnız kaç tane olacağına karar verir. ISO
+haftası sizin kullanıcılarınız için yanlışsa kendi bütçe kontrolünüzü istediğiniz anahtarla
+yazın: `id` ve `run` taşıyan bir nesnedir, istediğiniz sırada dizilir ve izde yerleşik
+kontrollerin yanında görünür.
 
 ## Hazır paketler: platform kotaları ve yasal sınırlar, kaynaklarıyla
 
@@ -463,6 +490,18 @@ başına bir anahtar ve sessiz saati aşan bir öncelik tabanı verir. Horvitz'i
 çalışmaları iki isteğe bağlı kontrolü sağladı. Bu paket o fikirleri izli tek bir listeye
 koyar ve onların dışarıda bıraktığı parçayı ekler: gönderim anında tüketilen bütçe.
 
+## Atıf
+
+Her sürüm Zenodo'da bir DOI ile arşivleniyor, böylece bir makale ya da rapor tam olarak
+çalıştırdığı koda işaret edebiliyor.
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22393512.svg)](https://doi.org/10.5281/zenodo.22393512)
+
+Bu **kavram** DOI'si: her zaman en yeni sürüme çözümlenir. Çalıştırdığınız sürümün kendisini
+atıflamak için o sayfayı açıp yan çubuktan sürümü seçin ve orada yazan DOI'yi kullanın.
+Depodaki `CITATION.cff` aynı tanımlayıcıyı taşıyor, bu yüzden GitHub'ın "Cite this repository"
+düğmesi elle kopyalama olmadan doğru BibTeX ve APA üretiyor.
+
 ## Geliştirme
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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"
+        ]
+      }
+    }
+  ]
+}