proactive-gate 0.2.4 → 0.3.0

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
@@ -433,6 +436,23 @@ 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.
 
+**Writing your own store?** `proactive-gate/store-contract` exports the same suite these three are
+held to, so you can prove yours behaves rather than hope:
+
+```ts
+import { storeContract } from "proactive-gate/store-contract";
+storeContract("PostgresStore", (clock) => new PostgresStore({ clock }));
+```
+
+It checks `get`, `set` and `del`, `incr` from an absent key, concurrent `incr` atomicity, the
+expiry boundary, and that a TTL given to `set` and one given to `incr` agree, then replays a
+seeded random operation sequence against `MemoryStore`. A store whose backend owns the clock
+passes `expiry: "skip"` and those cases are reported as skipped rather than quietly dropped. It
+was contributed by [@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) in
+[#24](https://github.com/Bubblegunn/proactive-gate/pull/24), and lives on its own subpath so
+importing the package never pulls `node:test` into your bundle. See
+[docs/store-contract.md](docs/store-contract.md).
+
 ## Fail open, on purpose
 
 When a store-backed check throws (Redis is down), the default lets the candidate
@@ -550,8 +570,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
@@ -719,7 +741,20 @@ before. [@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) wrote `
 ([#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.
+every release since, including the one you install today. @aaqib-hafeez-khan-in came back for a
+second one and wrote the store contract suite in [#24](https://github.com/Bubblegunn/proactive-gate/pull/24).
+
+## 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/dist/src/store-contract.d.ts

@@ -0,0 +1,11 @@
+import type { Store } from "./types.js";
+export interface StoreContractHandle {
+    store: Store;
+    teardown?: () => void | Promise<void>;
+}
+export type StoreContractFactory = (clock?: () => number) => Store | StoreContractHandle | Promise<Store | StoreContractHandle>;
+export interface StoreContractOptions {
+    expiry?: "injected" | "skip";
+    skip?: string;
+}
+export declare function storeContract(name: string, factory: StoreContractFactory, options?: StoreContractOptions): void;

package/dist/src/store-contract.js

@@ -0,0 +1,118 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { MemoryStore } from "./stores.js";
+function asHandle(value) {
+    return "store" in value ? value : { store: value };
+}
+export function storeContract(name, factory, options = {}) {
+    const expiry = options.expiry ?? "injected";
+    const skip = options.skip;
+    const testOptions = skip ? { skip } : {};
+    const expiryOptions = expiry === "skip" ? { skip: "expiry cases skipped: this store does not accept an injected clock" } : testOptions;
+    const withStore = async (clock, run) => {
+        const handle = asHandle(await factory(clock));
+        try {
+            return await run(handle.store);
+        }
+        finally {
+            await handle.teardown?.();
+        }
+    };
+    test(`${name}: get, set and del`, testOptions, async () => {
+        await withStore(undefined, async (store) => {
+            assert.equal(await store.get("missing"), null);
+            await store.set("key", "value");
+            assert.equal(await store.get("key"), "value");
+            await store.del("key");
+            assert.equal(await store.get("key"), null);
+        });
+    });
+    test(`${name}: incr from absent starts at one`, testOptions, async () => {
+        await withStore(undefined, async (store) => {
+            assert.equal(await store.incr("counter"), 1);
+            assert.equal(await store.incr("counter"), 2);
+        });
+    });
+    test(`${name}: incr is atomic`, testOptions, async () => {
+        await withStore(undefined, async (store) => {
+            const results = await Promise.all(Array.from({ length: 100 }, () => store.incr("counter")));
+            assert.deepEqual([...results].sort((a, b) => a - b), Array.from({ length: 100 }, (_, i) => i + 1));
+            assert.equal(await store.get("counter"), "100");
+        });
+    });
+    test(`${name}: set and incr TTLs expire at the same boundary`, expiryOptions, async () => {
+        let now = 0;
+        const clock = () => now;
+        await withStore(clock, async (store) => {
+            await store.set("set", "value", 2);
+            await store.incr("incr", 2);
+            now = 1999;
+            assert.equal(await store.get("set"), "value");
+            assert.equal(await store.get("incr"), "1");
+            now = 2000;
+            assert.equal(await store.get("set"), null);
+            assert.equal(await store.get("incr"), null);
+        });
+    });
+    test(`${name}: expiry is inclusive at the boundary`, expiryOptions, async () => {
+        let now = 1000;
+        const clock = () => now;
+        await withStore(clock, async (store) => {
+            await store.set("key", "value", 1);
+            assert.equal(await store.get("key"), "value");
+            now = 1999;
+            assert.equal(await store.get("key"), "value");
+            now = 2000;
+            assert.equal(await store.get("key"), null);
+        });
+    });
+    test(`${name}: random operations match MemoryStore`, testOptions, async () => {
+        for (let seed = 1; seed <= 40; seed++) {
+            let now = 0;
+            const clock = () => now;
+            await withStore(expiry === "injected" ? clock : undefined, async (store) => {
+                const reference = new MemoryStore(clock);
+                const keys = ["a", "b", "c"];
+                let state = 0x6d2b79f5 ^ seed;
+                const random = () => {
+                    state = (Math.imul(state ^ (state >>> 16), 2246822507) + 3266489909) >>> 0;
+                    return state / 4294967296;
+                };
+                try {
+                    for (let step = 0; step < 40; step++) {
+                        const key = keys[Math.floor(random() * keys.length)];
+                        const ttl = expiry === "injected" && random() > 0.5 ? 1 + Math.floor(random() * 3) : undefined;
+                        const op = Math.floor(random() * 5);
+                        if (op === 0) {
+                            const value = String(Math.floor(random() * 100));
+                            await reference.set(key, value, ttl);
+                            await store.set(key, value, ttl);
+                        }
+                        else if (op === 1) {
+                            assert.equal(await store.incr(key, ttl), await reference.incr(key, ttl), `seed ${seed} step ${step}: incr disagreed`);
+                        }
+                        else if (op === 2) {
+                            await reference.del(key);
+                            await store.del(key);
+                        }
+                        else if (op === 3) {
+                            if (expiry === "injected")
+                                now += Math.floor(random() * 3000);
+                        }
+                        else {
+                            assert.equal(await store.get(key), await reference.get(key), `seed ${seed} step ${step}: get disagreed on ${key}`);
+                        }
+                    }
+                    for (const key of keys) {
+                        assert.equal(await store.get(key), await reference.get(key), `seed ${seed}: final state disagreed on ${key}`);
+                    }
+                }
+                finally {
+                    await reference.del("a");
+                    await reference.del("b");
+                    await reference.del("c");
+                }
+            });
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "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",
@@ -14,6 +14,10 @@
       "types": "./dist/src/presets.d.ts",
       "import": "./dist/src/presets.js"
     },
+    "./store-contract": {
+      "types": "./dist/src/store-contract.d.ts",
+      "import": "./dist/src/store-contract.js"
+    },
     "./ai-sdk": {
       "types": "./dist/src/adapters/ai-sdk.d.ts",
       "import": "./dist/src/adapters/ai-sdk.js"
@@ -65,9 +69,9 @@
     "agents",
     "proactive",
     "notifications",
-    "rate-limit",
     "quiet-hours",
     "consent",
+    "rate-limit",
     "budget",
     "llm",
     "policy",