proactive-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Efe Genc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# proactive-gate
+
+Decide whether a proactive AI agent may reach a user right now, and log why not.
+
+A proactive assistant has two halves. The generating half decides what is worth
+saying. The suppressing half decides whether to say it now, later, or never. Almost
+everything written about proactive AI is about the first half. This package is the
+second half: one gate, an ordered list of checks, and a reason for every rejection.
+
+```
+npm install proactive-gate
+```
+
+```ts
+import { createGate, defaultChecks, RedisStore } from "proactive-gate";
+
+const gate = createGate({
+  store: new RedisStore(redis),                  // MemoryStore() for one instance
+  checks: defaultChecks({ dailyLimit: 3, quietHoursFloor: "high" }),
+  onDecision: (d) => log.info("gate", d),        // every decision, allowed or not
+});
+
+const decision = await gate.evaluate({ user, candidate });
+if (decision.allowed && (await gate.commit(decision, { user, candidate }))) {
+  await send(decision.surfaces, candidate.payload);
+}
+```
+
+Zero dependencies. TypeScript. Node 20 or newer. Framework-agnostic: the gate sits
+between "the model produced something" and "the user's phone buzzed", whichever
+model or framework produced it.
+
+## What a decision looks like
+
+```ts
+{
+  allowed: false,
+  userId: "ayse",
+  candidateId: "a1",
+  rejectedBy: "quietHours",
+  reason: "quiet hours 22:00 to 08:00 Europe/Istanbul; priority normal is below the floor (high)",
+  surfaces: [],
+  trace: [
+    { id: "killSwitch", outcome: "pass", ms: 0.02 },
+    { id: "consent",    outcome: "pass", ms: 0.01 },
+    { id: "enabled",    outcome: "pass", ms: 0.01 },
+    { id: "mode",       outcome: "pass", ms: 0.01 },
+    { id: "snooze",     outcome: "pass", ms: 0.02 },
+    { id: "mute",       outcome: "pass", ms: 0.01 },
+    { id: "intensity",  outcome: "pass", ms: 0.02 },
+    { id: "quietHours", outcome: "reject", reason: "quiet hours 22:00 to 08:00 …", ms: 0.09 }
+  ],
+  evaluatedAt: 2026-09-04T03:00:00.000Z
+}
+```
+
+With one gate and a logged reason, "why was the user not told about this" has an
+answer. With checks scattered through a pipeline, the honest answer is "somewhere,
+something returned false".
+
+## The checks, in the order the default runs them
+
+| # | check | rejects when | notes |
+|---|---|---|---|
+| 1 | `killSwitch(isOn)` | your flag is on | production hard-stop; silences every producer at once |
+| 2 | `consent()` | `user.consent` is false | comes first, or you have evaluated preferences for someone who never agreed |
+| 3 | `enabled()` | `user.proactiveEnabled === false` | per-profile switch |
+| 4 | `mode({ allow })` | `user.mode` is not in the list | e.g. only `"normal"`, never `"focus"` |
+| 5 | `snooze()` | `user.snoozedUntil` is in the future | global pause |
+| 6 | `mute()` | `candidate.type` is in `user.mutedTypes` | per-type mute |
+| 7 | `intensity()` | priority is below the user's intensity floor | low hears only high, normal hears normal and up, high hears everything |
+| 8 | `quietHours({ priorityFloor })` | inside the user's local quiet window | IANA time zone, window may cross midnight, bypassed at or above the floor |
+| 9 | `trustRamp({ days, minPriority })` | user is newer than `days` and priority is below the floor | the system is least calibrated exactly when the user is least forgiving |
+| 10 | `dismissalCooldown({ dismissals, withinDays, silenceDays })` | the user dismissed that type `dismissals` times in the window | fed by `gate.record(user, candidate, "dismissed")`; every further dismissal restarts the silence |
+| 11 | `adaptiveTiming({ nextGoodMoment, surfacesFor })` | never | non-rejecting: moves `deliverAt` or narrows surfaces; a check marked `nonRejecting` cannot reject even if it tries |
+| 12 | `dailyBudget({ limit, bypassPriority })` | the user's local-day counter is at the limit | `evaluate` reads, `commit` increments atomically and can still refuse |
+
+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
+consumes a delivery it never made. Reorder freely; the trace will show what you did.
+
+```ts
+import { createGate, checks } from "proactive-gate";
+
+const gate = createGate({
+  checks: [
+    checks.consent(),
+    checks.quietHours({ priorityFloor: "high" }),
+    checks.dailyBudget({ limit: 3, bypassPriority: "critical" }),
+    myOwnCheck, // { id, run(ctx) => pass | reject | adjust | skip }
+  ],
+});
+```
+
+## The budget is enforced at commit, not at evaluate
+
+Two instances can both evaluate a candidate for the same user, both see four of
+five used, and both decide to send. The only race-safe place to enforce a cap is
+the atomic increment right before sending:
+
+```ts
+const decision = await gate.evaluate(input);        // reads the counter
+if (decision.allowed && await gate.commit(decision, input)) {   // INCR, returns false on the sixth
+  await send(...);
+}
+```
+
+`RedisStore` uses `INCR` and attaches the day's TTL on the first increment. The
+counter is keyed on the user's local day, so a budget resets at the user's midnight,
+not at UTC.
+
+## Fail open, on purpose
+
+When a store-backed check throws (Redis is down), the default lets the candidate
+through and records `outcome: "skip", reason: "check threw (…); failing open"` in the
+trace. A cache outage should not silence every user of a product whose whole point
+is to speak up. If your product would rather stay silent, pass `onStoreError:
+"closed"` and the same failure becomes a rejection that names the check.
+
+## Replay a day before you ship a policy
+
+The CLI takes a JSONL file of `{ user, candidate, now }` lines and reports what a
+policy would have done. `--commit` consumes the budget in order, as production would.
+
+```
+npx proactive-gate replay examples/day.jsonl --commit
+```
+
+```
+17 candidates  ·  7 allowed (41.2%)  ·  10 rejected
+
+check        rejected  example
+---------------------------------------------------------------
+intensity           3  priority low is below the "normal" intensity floor (normal)
+consent             3  user has not consented to proactive behaviour
+mode                2  operating mode "focus" does not allow proactive messages
+quietHours          1  quiet hours 22:00 to 08:00 Europe/Istanbul; priority normal is below the floor (critical)
+dailyBudget         1  daily budget of 5 used (5)
+```
+
+`--policy examples/policy.js` loads your own gate; `--json` prints one full decision
+per line for a notebook. Replay a week of real candidates against a proposed policy
+and you know its allow rate and its silence reasons before a single user does.
+
+## Learning from what happened
+
+```ts
+await gate.record(user, candidate, "dismissed");   // feeds dismissalCooldown
+await gate.record(user, candidate, "acted");       // recorded for you to extend
+await gate.inspect(user);                          // { budgetUsed, dismissals }
+```
+
+Silence has to be measurable or it becomes an excuse. Log every decision through
+`onDecision`; the allow rate, the top rejection reasons, and the dismissal rate of
+what was allowed are the three numbers that tell you whether the gate is tuned.
+
+## What this does not do
+
+- It does not decide what is worth saying. That is the generating half, and it
+  belongs to your model and your product.
+- It does not score value against attention. `adaptiveTiming` is a hook for your
+  own model of the user's next good moment; the package ships no such model.
+- It does not coordinate across products. If three agents each respect a budget of
+  three, the user still gets nine. A cross-agent layer is a different problem.
+- It does not replace consent law. `consent()` checks a boolean you set; how you
+  obtained it is on you.
+
+## Where it comes from
+
+This is the delivery gate from [LILA](https://efe-genc-portfolio.vercel.app/projects/lila/),
+a proactive assistant I have been building alone since February 2026, extracted and
+made framework-agnostic. The order of the twelve checks, the trust ramp, the
+three-in-thirty cooldown and the fail-open budget are all decisions that were made
+in production and defended in
+[The hardest part of a proactive assistant is knowing when not to speak](https://efe-genc-portfolio.vercel.app/writing/knowing-when-not-to-speak/).
+Tian Pan's
+[notification budget](https://tianpan.co/blog/2026-05-13-background-agents-notification-budget-attention-economy)
+essay argues the same case from the product side and suggests a daily cap of three
+to five; `defaultChecks({ dailyLimit })` defaults to five.
+
+## Development
+
+```
+npm ci
+npm test        # tsc build, then node:test over dist/test
+```
+
+MIT.

package/dist/src/checks.d.ts

@@ -0,0 +1,81 @@
+import type { Check, CheckContext, Priority, Surface } from "./types.js";
+export declare const DAY_SECONDS: number;
+/** Local "HH:MM" and calendar day for an instant in an IANA zone, using Intl only. */
+export declare function localClock(now: Date, timezone: string): {
+    minutes: number;
+    day: string;
+};
+/** True when `minutes` falls inside [start, end), where the window may cross midnight. */
+export declare function inWindow(minutes: number, start: number, end: number): boolean;
+/** A production hard-stop that silences every producer at once. */
+export declare function killSwitch(isOn: () => boolean | Promise<boolean>): Check;
+/** Consent comes before everything, or you have evaluated preferences for someone who never agreed. */
+export declare function consent(): Check;
+/** Proactive behaviour switched on for this profile. Defaults to on when undefined. */
+export declare function enabled(): Check;
+/** Only these operating modes may receive proactive messages. Undefined mode passes. */
+export declare function mode(options: {
+    allow: string[];
+}): Check;
+/** A global pause until an instant. */
+export declare function snooze(): Check;
+/** Per-type mute. */
+export declare function mute(): Check;
+/**
+ * The user's intensity setting maps to a priority floor:
+ * low hears only high priority, normal hears normal and up, high hears everything.
+ */
+export declare function intensity(floors?: Record<"low" | "normal" | "high", Priority>): Check;
+/** Timezone-aware quiet hours, bypassed only at or above the priority floor. */
+export declare function quietHours(options?: {
+    priorityFloor?: Priority;
+}): Check;
+/**
+ * For the first `days` after sign-up the user hears from the system only at
+ * or above `minPriority`. A proactive assistant is least calibrated exactly
+ * when the user is least forgiving.
+ */
+export declare function trustRamp(options?: {
+    days?: number;
+    minPriority?: Priority;
+}): Check;
+/**
+ * When the user has dismissed `dismissals` candidates of a type within
+ * `withinDays`, that type stays silent for `silenceDays`. Fed by
+ * gate.record(userId, candidate, "dismissed").
+ */
+export declare function dismissalCooldown(options?: {
+    dismissals?: number;
+    withinDays?: number;
+    silenceDays?: number;
+}): Check;
+export declare const dismissalKey: (userId: string, type: string) => string;
+/**
+ * Never rejects. Moves a delivery to the user's next good moment when the
+ * caller supplies one, and can narrow surfaces. The default keeps the
+ * candidate where it is; pass `nextGoodMoment` to plug in your own model.
+ */
+export declare function adaptiveTiming(options?: {
+    nextGoodMoment?: (ctx: CheckContext) => Promise<Date | null> | Date | null;
+    surfacesFor?: (ctx: CheckContext) => Surface[] | null;
+}): Check;
+/**
+ * At most `limit` deliveries per user per local day. The check reads the
+ * counter; gate.commit() increments it atomically and can still refuse when
+ * two instances race, which is the only race-safe place to enforce a cap.
+ */
+export interface BudgetCheck extends Check {
+    limit: number;
+}
+export declare function dailyBudget(options?: {
+    limit?: number;
+    bypassPriority?: Priority;
+}): BudgetCheck;
+export declare const budgetKey: (userId: string, now: Date, timezone?: string) => string;
+/** The LILA order, as a starting point. Replace, reorder, or drop checks freely. */
+export declare function defaultChecks(options?: {
+    killSwitch?: () => boolean | Promise<boolean>;
+    modes?: string[];
+    dailyLimit?: number;
+    quietHoursFloor?: Priority;
+}): Check[];

package/dist/src/checks.js

@@ -0,0 +1,230 @@
+import { PRIORITY_RANK } from "./types.js";
+const pass = { kind: "pass" };
+const reject = (reason) => ({ kind: "reject", reason });
+const skip = (reason) => ({ kind: "skip", reason });
+const atLeast = (priority, floor) => PRIORITY_RANK[priority] >= PRIORITY_RANK[floor];
+const toDate = (value) => {
+    if (value === null || value === undefined)
+        return null;
+    const d = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+};
+export const DAY_SECONDS = 24 * 60 * 60;
+/** Local "HH:MM" and calendar day for an instant in an IANA zone, using Intl only. */
+export function localClock(now, timezone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+    }).formatToParts(now);
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? "00";
+    const hour = Number(get("hour")) % 24;
+    return { minutes: hour * 60 + Number(get("minute")), day: `${get("year")}-${get("month")}-${get("day")}` };
+}
+const parseHHMM = (text) => {
+    const [h, m] = text.split(":").map(Number);
+    if (h === undefined || m === undefined || Number.isNaN(h) || Number.isNaN(m))
+        throw new Error(`bad time "${text}", expected HH:MM`);
+    return h * 60 + m;
+};
+/** True when `minutes` falls inside [start, end), where the window may cross midnight. */
+export function inWindow(minutes, start, end) {
+    if (start === end)
+        return false;
+    return start < end ? minutes >= start && minutes < end : minutes >= start || minutes < end;
+}
+/* ------------------------------------------------------------------------ */
+/* The checks, in the order LILA runs them. Compose your own order freely.  */
+/* ------------------------------------------------------------------------ */
+/** A production hard-stop that silences every producer at once. */
+export function killSwitch(isOn) {
+    return {
+        id: "killSwitch",
+        async run() {
+            return (await isOn()) ? reject("engine kill switch is on") : pass;
+        },
+    };
+}
+/** Consent comes before everything, or you have evaluated preferences for someone who never agreed. */
+export function consent() {
+    return {
+        id: "consent",
+        run: ({ user }) => (user.consent ? pass : reject("user has not consented to proactive behaviour")),
+    };
+}
+/** Proactive behaviour switched on for this profile. Defaults to on when undefined. */
+export function enabled() {
+    return {
+        id: "enabled",
+        run: ({ user }) => (user.proactiveEnabled === false ? reject("proactive behaviour is disabled on this profile") : pass),
+    };
+}
+/** Only these operating modes may receive proactive messages. Undefined mode passes. */
+export function mode(options) {
+    return {
+        id: "mode",
+        run: ({ user }) => user.mode !== undefined && !options.allow.includes(user.mode)
+            ? reject(`operating mode "${user.mode}" does not allow proactive messages`)
+            : pass,
+    };
+}
+/** A global pause until an instant. */
+export function snooze() {
+    return {
+        id: "snooze",
+        run: ({ user, now }) => {
+            const until = toDate(user.snoozedUntil);
+            return until && until > now ? reject(`snoozed until ${until.toISOString()}`) : pass;
+        },
+    };
+}
+/** Per-type mute. */
+export function mute() {
+    return {
+        id: "mute",
+        run: ({ user, candidate }) => user.mutedTypes?.includes(candidate.type) ? reject(`type "${candidate.type}" is muted by the user`) : pass,
+    };
+}
+/**
+ * The user's intensity setting maps to a priority floor:
+ * low hears only high priority, normal hears normal and up, high hears everything.
+ */
+export function intensity(floors = { low: "high", normal: "normal", high: "low" }) {
+    return {
+        id: "intensity",
+        run: ({ user, priority }) => {
+            const floor = floors[user.intensity ?? "normal"];
+            return atLeast(priority, floor) ? pass : reject(`priority ${priority} is below the "${user.intensity ?? "normal"}" intensity floor (${floor})`);
+        },
+    };
+}
+/** Timezone-aware quiet hours, bypassed only at or above the priority floor. */
+export function quietHours(options = {}) {
+    const floor = options.priorityFloor ?? "critical";
+    return {
+        id: "quietHours",
+        run: ({ user, now, priority }) => {
+            if (!user.quietHours)
+                return pass;
+            if (!user.timezone)
+                return skip("quiet hours set but no timezone on the user; cannot evaluate");
+            const { minutes } = localClock(now, user.timezone);
+            const start = parseHHMM(user.quietHours.start);
+            const end = parseHHMM(user.quietHours.end);
+            if (!inWindow(minutes, start, end))
+                return pass;
+            if (atLeast(priority, floor))
+                return pass;
+            return reject(`quiet hours ${user.quietHours.start} to ${user.quietHours.end} ${user.timezone}; priority ${priority} is below the floor (${floor})`);
+        },
+    };
+}
+/**
+ * For the first `days` after sign-up the user hears from the system only at
+ * or above `minPriority`. A proactive assistant is least calibrated exactly
+ * when the user is least forgiving.
+ */
+export function trustRamp(options = {}) {
+    const days = options.days ?? 7;
+    const floor = options.minPriority ?? "high";
+    return {
+        id: "trustRamp",
+        run: ({ user, now, priority }) => {
+            const created = toDate(user.createdAt);
+            if (!created)
+                return skip("no createdAt on the user; ramp cannot be evaluated");
+            const age = (now.getTime() - created.getTime()) / (DAY_SECONDS * 1000);
+            if (age >= days)
+                return pass;
+            return atLeast(priority, floor) ? pass : reject(`trust ramp: day ${Math.floor(age) + 1} of ${days}, priority ${priority} is below ${floor}`);
+        },
+    };
+}
+/**
+ * When the user has dismissed `dismissals` candidates of a type within
+ * `withinDays`, that type stays silent for `silenceDays`. Fed by
+ * gate.record(userId, candidate, "dismissed").
+ */
+export function dismissalCooldown(options = {}) {
+    const n = options.dismissals ?? 3;
+    const withinDays = options.withinDays ?? 30;
+    const silenceDays = options.silenceDays ?? 7;
+    return {
+        id: "dismissalCooldown",
+        async run({ user, candidate, now, store }) {
+            const key = dismissalKey(user.id, candidate.type);
+            const raw = await store.get(key);
+            const stamps = raw ? JSON.parse(raw) : [];
+            const windowStart = now.getTime() - withinDays * DAY_SECONDS * 1000;
+            const recent = stamps.filter((t) => t >= windowStart).sort((a, b) => a - b);
+            if (recent.length < n)
+                return pass;
+            // Silence runs from the most recent dismissal; every further dismissal restarts it.
+            const latest = recent[recent.length - 1];
+            const silentUntil = latest + silenceDays * DAY_SECONDS * 1000;
+            if (now.getTime() >= silentUntil)
+                return pass;
+            return reject(`${recent.length} dismissals of "${candidate.type}" in ${withinDays} days; silent until ${new Date(silentUntil).toISOString()}`);
+        },
+    };
+}
+export const dismissalKey = (userId, type) => `cooldown:${userId}:${type}`;
+/**
+ * Never rejects. Moves a delivery to the user's next good moment when the
+ * caller supplies one, and can narrow surfaces. The default keeps the
+ * candidate where it is; pass `nextGoodMoment` to plug in your own model.
+ */
+export function adaptiveTiming(options = {}) {
+    return {
+        id: "adaptiveTiming",
+        nonRejecting: true,
+        async run(ctx) {
+            const at = options.nextGoodMoment ? await options.nextGoodMoment(ctx) : null;
+            const surfaces = options.surfacesFor ? options.surfacesFor(ctx) : null;
+            if (!at && !surfaces)
+                return pass;
+            const parts = [];
+            if (at)
+                parts.push(`deliver at ${at.toISOString()}`);
+            if (surfaces)
+                parts.push(`surfaces ${surfaces.join(",")}`);
+            return { kind: "adjust", reason: parts.join("; "), ...(at ? { deliverAt: at } : {}), ...(surfaces ? { surfaces } : {}) };
+        },
+    };
+}
+export function dailyBudget(options = {}) {
+    const limit = options.limit ?? 5;
+    return {
+        id: "dailyBudget",
+        limit,
+        async run({ user, now, store, priority }) {
+            if (options.bypassPriority && atLeast(priority, options.bypassPriority))
+                return pass;
+            const key = budgetKey(user.id, now, user.timezone);
+            const used = Number((await store.get(key)) ?? 0);
+            return used < limit ? pass : reject(`daily budget of ${limit} used (${used})`);
+        },
+    };
+}
+export const budgetKey = (userId, now, timezone) => `budget:${userId}:${timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10)}`;
+/** The LILA order, as a starting point. Replace, reorder, or drop checks freely. */
+export function defaultChecks(options = {}) {
+    return [
+        killSwitch(options.killSwitch ?? (() => false)),
+        consent(),
+        enabled(),
+        mode({ allow: options.modes ?? ["normal"] }),
+        snooze(),
+        mute(),
+        intensity(),
+        quietHours({ priorityFloor: options.quietHoursFloor ?? "critical" }),
+        trustRamp(),
+        dismissalCooldown(),
+        adaptiveTiming(),
+        dailyBudget({ limit: options.dailyLimit ?? 5 }),
+    ];
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import type { Gate } from "./gate.js";
+import type { Decision } from "./types.js";
+export declare function loadPolicy(path?: string): Promise<Gate>;
+export declare function replay(lines: string[], gate: Gate, commit: boolean): Promise<Decision[]>;
+export declare function summarize(decisions: Decision[]): string;

package/dist/src/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * proactive-gate replay <events.jsonl> [--policy <module>] [--json]
+ *
+ * Replays candidate messages through a gate and prints why each one was or
+ * was not allowed. Each JSONL line is an EvaluateInput: { user, candidate, now? }.
+ * The policy module must export `gate` (a Gate) or default-export one; without
+ * --policy the default check order runs against an in-memory store.
+ */
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+import { createGate } from "./gate.js";
+import { defaultChecks } from "./checks.js";
+const HELP = `usage: proactive-gate replay <events.jsonl> [--policy <module.js>] [--json] [--commit]
+
+Replays candidates through a gate and reports what was allowed and why not.
+
+  --policy <module>  ES module exporting \`gate\` (or default) built with createGate()
+  --json             one Decision per line instead of the summary table
+  --commit           also call gate.commit() for allowed decisions, so the daily
+                     budget is consumed in order, as it would be in production
+  -h, --help         this text
+
+Each line of the file is {"user": {...}, "candidate": {...}, "now": "ISO date"}.`;
+export async function loadPolicy(path) {
+    if (!path)
+        return createGate({ checks: defaultChecks() });
+    const mod = await import(pathToFileURL(resolve(path)).href);
+    const gate = mod.gate ?? mod.default;
+    if (!gate || typeof gate.evaluate !== "function")
+        throw new Error(`${path} must export a gate created with createGate()`);
+    return gate;
+}
+export async function replay(lines, gate, commit) {
+    const decisions = [];
+    for (const [i, line] of lines.entries()) {
+        if (!line.trim())
+            continue;
+        let input;
+        try {
+            const raw = JSON.parse(line);
+            input = { ...raw, ...(raw.now ? { now: new Date(raw.now) } : {}) };
+        }
+        catch (error) {
+            throw new Error(`line ${i + 1}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const decision = await gate.evaluate(input);
+        if (commit && decision.allowed) {
+            const ok = await gate.commit(decision, input);
+            if (!ok) {
+                decision.allowed = false;
+                decision.rejectedBy = "dailyBudget";
+                decision.reason = "daily budget exhausted at commit";
+            }
+        }
+        decisions.push(decision);
+    }
+    return decisions;
+}
+export function summarize(decisions) {
+    const allowed = decisions.filter((d) => d.allowed).length;
+    const byCheck = new Map();
+    const sample = new Map();
+    for (const d of decisions) {
+        if (d.allowed || !d.rejectedBy)
+            continue;
+        byCheck.set(d.rejectedBy, (byCheck.get(d.rejectedBy) ?? 0) + 1);
+        if (!sample.has(d.rejectedBy) && d.reason)
+            sample.set(d.rejectedBy, d.reason);
+    }
+    const deferred = decisions.filter((d) => d.allowed && d.deliverAt).length;
+    const lines = [
+        `${decisions.length} candidates  ·  ${allowed} allowed (${pct(allowed, decisions.length)})  ·  ${decisions.length - allowed} rejected${deferred ? `  ·  ${deferred} deferred to a later moment` : ""}`,
+        "",
+    ];
+    if (byCheck.size) {
+        const w = Math.max(...[...byCheck.keys()].map((k) => k.length), 5);
+        lines.push(`${"check".padEnd(w)}  ${"rejected".padStart(8)}  example`);
+        lines.push("-".repeat(w + 2 + 8 + 2 + 40));
+        for (const [id, n] of [...byCheck.entries()].sort((a, b) => b[1] - a[1])) {
+            lines.push(`${id.padEnd(w)}  ${String(n).padStart(8)}  ${sample.get(id) ?? ""}`);
+        }
+    }
+    else {
+        lines.push("nothing was rejected");
+    }
+    return lines.join("\n");
+}
+const pct = (n, total) => (total ? `${((100 * n) / total).toFixed(1)}%` : "0%");
+async function main(argv) {
+    if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+        console.log(HELP);
+        return;
+    }
+    const [command, file] = argv;
+    if (command !== "replay" || !file) {
+        console.error(HELP);
+        process.exit(2);
+    }
+    const policyIndex = argv.indexOf("--policy");
+    const policy = policyIndex >= 0 ? argv[policyIndex + 1] : undefined;
+    const gate = await loadPolicy(policy);
+    const text = await readFile(file, "utf8");
+    const decisions = await replay(text.split("\n"), gate, argv.includes("--commit"));
+    if (argv.includes("--json")) {
+        for (const d of decisions)
+            console.log(JSON.stringify(d));
+    }
+    else {
+        console.log(summarize(decisions));
+    }
+}
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (entry === import.meta.url || entry.endsWith("/proactive-gate")) {
+    main(process.argv.slice(2)).catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/src/gate.d.ts

@@ -0,0 +1,20 @@
+import type { Candidate, Check, Decision, EvaluateInput, GateOptions, OutcomeEvent, UserState } from "./types.js";
+export interface Gate {
+    /** Run every check in order. Never throws for a check failure; see the trace. */
+    evaluate(input: EvaluateInput): Promise<Decision>;
+    /**
+     * Call right before you actually send. Atomically consumes one unit of the
+     * user's daily budget when a dailyBudget check is configured, and returns
+     * false if the budget was exhausted by a concurrent delivery in the meantime.
+     */
+    commit(decision: Decision, input: EvaluateInput): Promise<boolean>;
+    /** Tell the gate what happened after delivery, so cooldowns can learn. */
+    record(user: Pick<UserState, "id">, candidate: Pick<Candidate, "type">, event: OutcomeEvent, at?: Date): Promise<void>;
+    /** Snapshot of the current counters for a user, for debugging and UIs. */
+    inspect(user: UserState, now?: Date): Promise<{
+        budgetUsed: number;
+        dismissals: Record<string, number>;
+    }>;
+    readonly checks: readonly Check[];
+}
+export declare function createGate(options: GateOptions): Gate;

package/dist/src/gate.js

@@ -0,0 +1,120 @@
+import { budgetKey, dismissalKey, DAY_SECONDS } from "./checks.js";
+import { MemoryStore } from "./stores.js";
+class PrefixedStore {
+    inner;
+    prefix;
+    constructor(inner, prefix) {
+        this.inner = inner;
+        this.prefix = prefix;
+    }
+    get(key) { return this.inner.get(this.prefix + key); }
+    set(key, value, ttl) { return this.inner.set(this.prefix + key, value, ttl); }
+    incr(key, ttl) { return this.inner.incr(this.prefix + key, ttl); }
+    del(key) { return this.inner.del(this.prefix + key); }
+}
+export function createGate(options) {
+    const store = new PrefixedStore(options.store ?? new MemoryStore(), options.keyPrefix ?? "pg:");
+    const onStoreError = options.onStoreError ?? "open";
+    const checks = [...options.checks];
+    const budgetCheck = checks.find((c) => c.id === "dailyBudget");
+    const evaluate = async (input) => {
+        const now = input.now ?? new Date();
+        const priority = input.candidate.priority ?? "normal";
+        const trace = [];
+        let surfaces = pickSurfaces(input.user, input.candidate);
+        let deliverAt;
+        const finish = (partial) => {
+            const decision = {
+                allowed: false,
+                userId: input.user.id,
+                candidateId: input.candidate.id,
+                surfaces: [],
+                trace,
+                evaluatedAt: now,
+                ...partial,
+            };
+            options.onDecision?.(decision);
+            return decision;
+        };
+        for (const check of checks) {
+            const ctx = { user: input.user, candidate: input.candidate, now, priority, store, surfaces };
+            const started = performance.now();
+            let outcome;
+            try {
+                outcome = await check.run(ctx);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (onStoreError === "closed") {
+                    trace.push({ id: check.id, outcome: "reject", reason: `check threw (${message}); failing closed`, ms: elapsed(started) });
+                    return finish({ rejectedBy: check.id, reason: `check "${check.id}" failed and the gate fails closed: ${message}` });
+                }
+                trace.push({ id: check.id, outcome: "skip", reason: `check threw (${message}); failing open`, ms: elapsed(started) });
+                continue;
+            }
+            if (check.nonRejecting && outcome.kind === "reject") {
+                // A non-rejecting check that tries to reject is a bug in the check, not a decision about the user.
+                trace.push({ id: check.id, outcome: "skip", reason: `non-rejecting check returned reject (${outcome.reason}); ignored`, ms: elapsed(started) });
+                continue;
+            }
+            trace.push({ id: check.id, outcome: outcome.kind, ...(("reason" in outcome && outcome.reason) ? { reason: outcome.reason } : {}), ms: elapsed(started) });
+            if (outcome.kind === "reject") {
+                return finish({ rejectedBy: check.id, reason: outcome.reason });
+            }
+            if (outcome.kind === "adjust") {
+                if (outcome.deliverAt)
+                    deliverAt = outcome.deliverAt;
+                if (outcome.surfaces)
+                    surfaces = outcome.surfaces;
+            }
+        }
+        return finish({ allowed: true, surfaces, ...(deliverAt ? { deliverAt } : {}) });
+    };
+    const commit = async (decision, input) => {
+        if (!decision.allowed)
+            return false;
+        if (!budgetCheck)
+            return true;
+        const now = input.now ?? new Date();
+        const limit = readLimit(budgetCheck);
+        try {
+            const used = await store.incr(budgetKey(input.user.id, now, input.user.timezone), 2 * DAY_SECONDS);
+            return limit === undefined || used <= limit;
+        }
+        catch {
+            return onStoreError === "open";
+        }
+    };
+    const record = async (user, candidate, event, at = new Date()) => {
+        if (event !== "dismissed")
+            return;
+        const key = dismissalKey(user.id, candidate.type);
+        const raw = await store.get(key);
+        const stamps = raw ? JSON.parse(raw) : [];
+        const keepFrom = at.getTime() - 90 * DAY_SECONDS * 1000;
+        const next = [...stamps.filter((t) => t >= keepFrom), at.getTime()];
+        await store.set(key, JSON.stringify(next), 90 * DAY_SECONDS);
+    };
+    const inspect = async (user, now = new Date()) => {
+        const budgetUsed = Number((await store.get(budgetKey(user.id, now, user.timezone))) ?? 0);
+        const dismissals = {};
+        for (const type of user.mutedTypes ?? []) {
+            const raw = await store.get(dismissalKey(user.id, type));
+            dismissals[type] = raw ? JSON.parse(raw).length : 0;
+        }
+        return { budgetUsed, dismissals };
+    };
+    return { evaluate, commit, record, inspect, checks };
+}
+function pickSurfaces(user, candidate) {
+    const wanted = candidate.surfaces ?? ["feed"];
+    if (!user.surfaces)
+        return wanted;
+    const allowed = new Set(user.surfaces);
+    return wanted.filter((s) => allowed.has(s));
+}
+const elapsed = (started) => Math.round((performance.now() - started) * 1000) / 1000;
+/** dailyBudget() closes over its limit; expose it through a well-known property for commit(). */
+function readLimit(check) {
+    return typeof check.limit === "number" ? check.limit : undefined;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export { createGate } from "./gate.js";
+export type { Gate } from "./gate.js";
+export { MemoryStore, RedisStore } from "./stores.js";
+export type { RedisLike } from "./stores.js";
+export * as checks from "./checks.js";
+export { defaultChecks, localClock, inWindow, budgetKey, dismissalKey } from "./checks.js";
+export { PRIORITY_RANK } from "./types.js";
+export type { Candidate, Check, CheckContext, CheckOutcome, Decision, EvaluateInput, GateOptions, OutcomeEvent, Priority, Store, Surface, TraceEntry, UserState, } from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { createGate } from "./gate.js";
+export { MemoryStore, RedisStore } from "./stores.js";
+export * as checks from "./checks.js";
+export { defaultChecks, localClock, inWindow, budgetKey, dismissalKey } from "./checks.js";
+export { PRIORITY_RANK } from "./types.js";

package/dist/src/stores.d.ts

@@ -0,0 +1,38 @@
+import type { Store } from "./types.js";
+/** In-process store. Correct for one instance, wrong the moment you scale out. */
+export declare class MemoryStore implements Store {
+    private readonly clock;
+    private readonly data;
+    constructor(clock?: () => number);
+    private live;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    incr(key: string, ttlSeconds?: number): Promise<number>;
+    del(key: string): Promise<void>;
+    /** Test helper. */
+    size(): number;
+}
+/**
+ * The subset of a Redis client the gate needs. Both ioredis and node-redis
+ * satisfy it (node-redis names are upper-case; pass a small adapter).
+ */
+export interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: any[]): Promise<unknown>;
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+}
+/**
+ * Redis-backed store. `incr` is atomic on the server, which is what makes the
+ * daily budget safe across many instances; the TTL is attached on the first
+ * increment so a day's counter disappears on its own.
+ */
+export declare class RedisStore implements Store {
+    private readonly client;
+    constructor(client: RedisLike);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    incr(key: string, ttlSeconds?: number): Promise<number>;
+    del(key: string): Promise<void>;
+}

package/dist/src/stores.js

@@ -0,0 +1,67 @@
+/** In-process store. Correct for one instance, wrong the moment you scale out. */
+export class MemoryStore {
+    clock;
+    data = new Map();
+    constructor(clock = () => Date.now()) {
+        this.clock = clock;
+    }
+    live(key) {
+        const entry = this.data.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== null && entry.expiresAt <= this.clock()) {
+            this.data.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    async get(key) {
+        return this.live(key)?.value ?? null;
+    }
+    async set(key, value, ttlSeconds) {
+        this.data.set(key, { value, expiresAt: ttlSeconds ? this.clock() + ttlSeconds * 1000 : null });
+    }
+    async incr(key, ttlSeconds) {
+        const current = this.live(key);
+        const next = (current ? Number(current.value) : 0) + 1;
+        const expiresAt = current ? current.expiresAt : ttlSeconds ? this.clock() + ttlSeconds * 1000 : null;
+        this.data.set(key, { value: String(next), expiresAt });
+        return next;
+    }
+    async del(key) {
+        this.data.delete(key);
+    }
+    /** Test helper. */
+    size() {
+        return this.data.size;
+    }
+}
+/**
+ * Redis-backed store. `incr` is atomic on the server, which is what makes the
+ * daily budget safe across many instances; the TTL is attached on the first
+ * increment so a day's counter disappears on its own.
+ */
+export class RedisStore {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async get(key) {
+        return this.client.get(key);
+    }
+    async set(key, value, ttlSeconds) {
+        if (ttlSeconds)
+            await this.client.set(key, value, "EX", ttlSeconds);
+        else
+            await this.client.set(key, value);
+    }
+    async incr(key, ttlSeconds) {
+        const next = await this.client.incr(key);
+        if (next === 1 && ttlSeconds)
+            await this.client.expire(key, ttlSeconds);
+        return next;
+    }
+    async del(key) {
+        await this.client.del(key);
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,129 @@
+/** Priority of a candidate message. Higher priorities may bypass some checks. */
+export type Priority = "low" | "normal" | "high" | "critical";
+export declare const PRIORITY_RANK: Record<Priority, number>;
+/** Where a delivery may land. Free-form so callers can add their own. */
+export type Surface = "feed" | "push" | "chat" | "voice" | "email" | (string & {});
+/** Everything the gate knows about the person it might interrupt. */
+export interface UserState {
+    id: string;
+    /** Has the user agreed to proactive behaviour at all? */
+    consent: boolean;
+    /** Is proactive behaviour switched on for this profile right now? */
+    proactiveEnabled?: boolean;
+    /** Operating mode of the assistant for this user, e.g. "normal", "focus", "vacation". */
+    mode?: string;
+    /** Global pause until this instant. */
+    snoozedUntil?: Date | string | null;
+    /** Candidate types the user has muted. */
+    mutedTypes?: string[];
+    /** How much the user wants to hear from the assistant. */
+    intensity?: "low" | "normal" | "high";
+    /** IANA time zone, required for quiet hours. */
+    timezone?: string;
+    /** Quiet hours in local time, "HH:MM". May cross midnight. */
+    quietHours?: {
+        start: string;
+        end: string;
+    } | null;
+    /** When the user joined. Drives the trust ramp. */
+    createdAt?: Date | string;
+    /** Surfaces the user allows, in preference order. Defaults to the candidate's surfaces. */
+    surfaces?: Surface[];
+}
+/** The thing the agent wants to say. */
+export interface Candidate {
+    id: string;
+    /** A stable category such as "reminder", "insight", "follow_up". Used by mute and cooldown. */
+    type: string;
+    priority?: Priority;
+    /** Surfaces this candidate can be delivered on, in preference order. */
+    surfaces?: Surface[];
+    /** Free-form payload; the gate never reads it. */
+    payload?: unknown;
+}
+export interface EvaluateInput {
+    user: UserState;
+    candidate: Candidate;
+    /** Injected clock for tests and replays. */
+    now?: Date;
+}
+/** What a single check may say. */
+export type CheckOutcome = {
+    kind: "pass";
+} | {
+    kind: "reject";
+    reason: string;
+} | {
+    kind: "adjust";
+    reason: string;
+    deliverAt?: Date;
+    surfaces?: Surface[];
+} | {
+    kind: "skip";
+    reason: string;
+};
+export interface CheckContext {
+    user: UserState;
+    candidate: Candidate;
+    now: Date;
+    priority: Priority;
+    store: Store;
+    /** Surfaces still on the table after earlier checks. */
+    surfaces: Surface[];
+}
+export interface Check {
+    id: string;
+    /** True when the check can never reject; it only adjusts timing or surfaces. */
+    nonRejecting?: boolean;
+    run(ctx: CheckContext): Promise<CheckOutcome> | CheckOutcome;
+}
+export interface TraceEntry {
+    id: string;
+    outcome: CheckOutcome["kind"];
+    reason?: string;
+    ms: number;
+}
+export interface Decision {
+    allowed: boolean;
+    userId: string;
+    candidateId: string;
+    /** Surfaces to route to when allowed. Empty when rejected. */
+    surfaces: Surface[];
+    /** Set when a non-rejecting check asked for a later delivery. */
+    deliverAt?: Date;
+    /** The check that rejected, when rejected. */
+    rejectedBy?: string;
+    /** Human-readable reason, when rejected. */
+    reason?: string;
+    /** Every check that ran, in order, with what it said. */
+    trace: TraceEntry[];
+    evaluatedAt: Date;
+}
+/** Outcome events the gate learns from. */
+export type OutcomeEvent = "delivered" | "dismissed" | "acted" | "ignored";
+/**
+ * Minimal key-value contract. MemoryStore ships with the package; wrap a Redis
+ * client with RedisStore. Every method may throw; the gate decides per check
+ * whether a store failure fails open or closed.
+ */
+export interface Store {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    /** Atomic increment. Returns the new value. */
+    incr(key: string, ttlSeconds?: number): Promise<number>;
+    del(key: string): Promise<void>;
+}
+export interface GateOptions {
+    checks: Check[];
+    store?: Store;
+    /**
+     * What to do when a store-backed check throws. "open" lets the candidate
+     * through and records the failure in the trace; "closed" rejects.
+     * Default "open": a Redis outage should not silence every user.
+     */
+    onStoreError?: "open" | "closed";
+    /** Receives every decision. Wire this to your logger. */
+    onDecision?: (decision: Decision) => void;
+    /** Key prefix for everything the gate writes to the store. */
+    keyPrefix?: string;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export const PRIORITY_RANK = { low: 0, normal: 1, high: 2, critical: 3 };

package/dist/test/gate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/gate.test.js

@@ -0,0 +1,192 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createGate, MemoryStore, defaultChecks, checks, localClock, inWindow } from "../src/index.js";
+import { replay, summarize } from "../src/cli.js";
+const user = (overrides = {}) => ({
+    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",
+    ...overrides,
+});
+const candidate = (overrides = {}) => ({ id: "c1", type: "reminder", priority: "normal", surfaces: ["push", "feed"], ...overrides });
+const noon = new Date("2026-09-04T09:00:00Z"); // 12:00 in Istanbul (UTC+3)
+const night = new Date("2026-09-04T20:30:00Z"); // 23:30 in Istanbul
+test("happy path: every check passes, surfaces are returned, trace lists all twelve", async () => {
+    const gate = createGate({ checks: defaultChecks() });
+    const d = await gate.evaluate({ user: user(), candidate: candidate(), now: noon });
+    assert.equal(d.allowed, true);
+    assert.deepEqual(d.surfaces, ["push", "feed"]);
+    assert.equal(d.trace.length, 12);
+    assert.deepEqual(d.trace.map((t) => t.id), ["killSwitch", "consent", "enabled", "mode", "snooze", "mute", "intensity", "quietHours", "trustRamp", "dismissalCooldown", "adaptiveTiming", "dailyBudget"]);
+});
+test("order is visible: consent rejects before quiet hours gets a chance", async () => {
+    const gate = createGate({ checks: defaultChecks() });
+    const d = await gate.evaluate({ user: user({ consent: false }), candidate: candidate(), now: night });
+    assert.equal(d.allowed, false);
+    assert.equal(d.rejectedBy, "consent");
+    assert.equal(d.trace.length, 2);
+});
+test("kill switch silences everything and says so", async () => {
+    const gate = createGate({ checks: defaultChecks({ killSwitch: () => true }) });
+    const d = await gate.evaluate({ user: user(), candidate: candidate({ priority: "critical" }), now: noon });
+    assert.equal(d.rejectedBy, "killSwitch");
+    assert.match(d.reason, /kill switch/);
+});
+test("quiet hours: rejects at 23:30 local, passes at noon, crosses midnight, bypassed at the floor", async () => {
+    const gate = createGate({ checks: [checks.quietHours({ priorityFloor: "high" })] });
+    const late = await gate.evaluate({ user: user(), candidate: candidate(), now: night });
+    assert.equal(late.rejectedBy, "quietHours");
+    assert.match(late.reason, /22:00 to 08:00 Europe\/Istanbul/);
+    const early = await gate.evaluate({ user: user(), candidate: candidate(), now: new Date("2026-09-05T03:30:00Z") }); // 06:30 local
+    assert.equal(early.allowed, false);
+    const day = await gate.evaluate({ user: user(), candidate: candidate(), now: noon });
+    assert.equal(day.allowed, true);
+    const urgent = await gate.evaluate({ user: user(), candidate: candidate({ priority: "high" }), now: night });
+    assert.equal(urgent.allowed, true);
+    const noTz = await gate.evaluate({ user: user({ timezone: undefined }), candidate: candidate(), now: night });
+    assert.equal(noTz.allowed, true);
+    assert.equal(noTz.trace[0]?.outcome, "skip");
+});
+test("localClock and inWindow handle zones and midnight", () => {
+    assert.equal(localClock(new Date("2026-09-04T20:30:00Z"), "Europe/Istanbul").minutes, 23 * 60 + 30);
+    assert.equal(localClock(new Date("2026-09-04T20:30:00Z"), "America/Los_Angeles").minutes, 13 * 60 + 30);
+    assert.equal(localClock(new Date("2026-09-04T23:30:00Z"), "Europe/Istanbul").day, "2026-09-05");
+    assert.equal(inWindow(23 * 60, 22 * 60, 8 * 60), true);
+    assert.equal(inWindow(7 * 60, 22 * 60, 8 * 60), true);
+    assert.equal(inWindow(12 * 60, 22 * 60, 8 * 60), false);
+    assert.equal(inWindow(12 * 60, 9 * 60, 17 * 60), true);
+    assert.equal(inWindow(12 * 60, 12 * 60, 12 * 60), false);
+});
+test("trust ramp: new users hear only high priority for seven days", async () => {
+    const gate = createGate({ checks: [checks.trustRamp()] });
+    const fresh = user({ createdAt: "2026-09-02T00:00:00Z" });
+    const normal = await gate.evaluate({ user: fresh, candidate: candidate(), now: noon });
+    assert.equal(normal.rejectedBy, "trustRamp");
+    assert.match(normal.reason, /day 3 of 7/);
+    const high = await gate.evaluate({ user: fresh, candidate: candidate({ priority: "high" }), now: noon });
+    assert.equal(high.allowed, true);
+    const old = await gate.evaluate({ user: user(), candidate: candidate(), now: noon });
+    assert.equal(old.allowed, true);
+});
+test("intensity maps to a priority floor", async () => {
+    const gate = createGate({ checks: [checks.intensity()] });
+    assert.equal((await gate.evaluate({ user: user({ intensity: "low" }), candidate: candidate(), now: noon })).rejectedBy, "intensity");
+    assert.equal((await gate.evaluate({ user: user({ intensity: "low" }), candidate: candidate({ priority: "high" }), now: noon })).allowed, true);
+    assert.equal((await gate.evaluate({ user: user({ intensity: "high" }), candidate: candidate({ priority: "low" }), now: noon })).allowed, true);
+});
+test("snooze, mute, mode and enabled each reject with a specific reason", async () => {
+    const gate = createGate({ checks: defaultChecks() });
+    const cases = [
+        [{ snoozedUntil: "2026-09-04T12:00:00Z" }, "snooze"],
+        [{ mutedTypes: ["reminder"] }, "mute"],
+        [{ mode: "focus" }, "mode"],
+        [{ proactiveEnabled: false }, "enabled"],
+    ];
+    for (const [overrides, expected] of cases) {
+        const d = await gate.evaluate({ user: user(overrides), candidate: candidate(), now: noon });
+        assert.equal(d.rejectedBy, expected, `expected ${expected} to reject`);
+    }
+});
+test("dismissal cooldown: three dismissals in thirty days buy a week of silence for that type only", async () => {
+    const store = new MemoryStore();
+    const gate = createGate({ store, checks: [checks.dismissalCooldown()] });
+    const u = user();
+    for (const day of [1, 2, 3])
+        await gate.record(u, { type: "reminder" }, "dismissed", new Date(`2026-09-0${day}T10:00:00Z`));
+    const silenced = await gate.evaluate({ user: u, candidate: candidate(), now: new Date("2026-09-05T10:00:00Z") });
+    assert.equal(silenced.rejectedBy, "dismissalCooldown");
+    assert.match(silenced.reason, /silent until 2026-09-10T10:00:00.000Z/);
+    const otherType = await gate.evaluate({ user: u, candidate: candidate({ type: "insight" }), now: new Date("2026-09-05T10:00:00Z") });
+    assert.equal(otherType.allowed, true);
+    const later = await gate.evaluate({ user: u, candidate: candidate(), now: new Date("2026-09-11T10:00:00Z") });
+    assert.equal(later.allowed, true);
+    await gate.record(u, { type: "reminder" }, "acted");
+    const acted = await gate.evaluate({ user: u, candidate: candidate(), now: new Date("2026-09-11T10:00:00Z") });
+    assert.equal(acted.allowed, true);
+});
+test("daily budget: evaluate reads, commit consumes atomically and refuses the sixth delivery", async () => {
+    const store = new MemoryStore();
+    const gate = createGate({ store, checks: [checks.dailyBudget({ limit: 5 })] });
+    const input = { user: user(), candidate: candidate(), now: noon };
+    for (let i = 0; i < 5; i++) {
+        const d = await gate.evaluate(input);
+        assert.equal(d.allowed, true, `delivery ${i + 1} should be allowed`);
+        assert.equal(await gate.commit(d, input), true);
+    }
+    const sixth = await gate.evaluate(input);
+    assert.equal(sixth.rejectedBy, "dailyBudget");
+    assert.match(sixth.reason, /5 used \(5\)/);
+    // Two instances that both evaluated before either committed: only one wins.
+    const store2 = new MemoryStore();
+    const gate2 = createGate({ store: store2, checks: [checks.dailyBudget({ limit: 1 })] });
+    const a = await gate2.evaluate(input);
+    const b = await gate2.evaluate(input);
+    assert.equal(a.allowed && b.allowed, true);
+    assert.equal(await gate2.commit(a, input), true);
+    assert.equal(await gate2.commit(b, input), false);
+    // The budget resets on the user's local day, not UTC.
+    const nextLocalDay = new Date("2026-09-04T21:30:00Z"); // 00:30 next day in Istanbul
+    assert.equal((await gate.evaluate({ ...input, now: nextLocalDay })).allowed, true);
+    assert.equal((await gate.inspect(user(), noon)).budgetUsed, 5);
+});
+test("adaptive timing never rejects; it defers and can narrow surfaces", async () => {
+    const later = new Date("2026-09-04T15:00:00Z");
+    const gate = createGate({
+        checks: [
+            checks.adaptiveTiming({ nextGoodMoment: () => later, surfacesFor: () => ["feed"] }),
+            { id: "rogue", nonRejecting: true, run: () => ({ kind: "reject", reason: "should be ignored" }) },
+        ],
+    });
+    const d = await gate.evaluate({ user: user(), candidate: candidate(), now: noon });
+    assert.equal(d.allowed, true);
+    assert.equal(d.deliverAt?.toISOString(), later.toISOString());
+    assert.deepEqual(d.surfaces, ["feed"]);
+    assert.equal(d.trace[1]?.outcome, "skip");
+});
+test("store failure fails open by default and closed on request, and the trace says which", async () => {
+    const broken = {
+        get: async () => { throw new Error("redis down"); },
+        set: async () => { throw new Error("redis down"); },
+        incr: async () => { throw new Error("redis down"); },
+        del: async () => { throw new Error("redis down"); },
+    };
+    const open = createGate({ store: broken, checks: [checks.dailyBudget({ limit: 1 })] });
+    const d1 = await open.evaluate({ user: user(), candidate: candidate(), now: noon });
+    assert.equal(d1.allowed, true);
+    assert.match(d1.trace[0]?.reason ?? "", /failing open/);
+    assert.equal(await open.commit(d1, { user: user(), candidate: candidate(), now: noon }), true);
+    const closed = createGate({ store: broken, onStoreError: "closed", checks: [checks.dailyBudget({ limit: 1 })] });
+    const d2 = await closed.evaluate({ user: user(), candidate: candidate(), now: noon });
+    assert.equal(d2.allowed, false);
+    assert.equal(d2.rejectedBy, "dailyBudget");
+});
+test("user surfaces filter candidate surfaces; onDecision sees every decision", async () => {
+    const seen = [];
+    const gate = createGate({ checks: defaultChecks(), onDecision: (d) => seen.push(`${d.candidateId}:${d.allowed}`) });
+    const d = await gate.evaluate({ user: user({ surfaces: ["feed"] }), candidate: candidate({ surfaces: ["push", "feed", "voice"] }), now: noon });
+    assert.deepEqual(d.surfaces, ["feed"]);
+    await gate.evaluate({ user: user({ consent: false }), candidate: candidate({ id: "c2" }), now: noon });
+    assert.deepEqual(seen, ["c1:true", "c2:false"]);
+});
+test("replay summarises a day of candidates and consumes the budget in order", async () => {
+    const gate = createGate({ checks: defaultChecks({ dailyLimit: 2 }) });
+    const lines = [
+        JSON.stringify({ user: user(), candidate: candidate({ id: "a" }), now: noon }),
+        JSON.stringify({ user: user(), candidate: candidate({ id: "b" }), now: noon }),
+        JSON.stringify({ user: user(), candidate: candidate({ id: "c" }), now: noon }),
+        JSON.stringify({ user: user(), candidate: candidate({ id: "d" }), now: night }),
+        JSON.stringify({ user: user({ consent: false }), candidate: candidate({ id: "e" }), now: noon }),
+    ];
+    const decisions = await replay(lines, gate, true);
+    assert.deepEqual(decisions.map((d) => d.allowed), [true, true, false, false, false]);
+    const text = summarize(decisions);
+    assert.match(text, /5 candidates {2}· {2}2 allowed \(40\.0%\)/);
+    assert.match(text, /dailyBudget/);
+    assert.match(text, /quietHours/);
+    assert.match(text, /consent/);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "proactive-gate",
+  "version": "0.1.0",
+  "description": "Decide whether a proactive AI agent may reach a user right now, and log why not. Ordered checks: kill switch, consent, quiet hours, trust ramp, dismissal cooldown, daily budget.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "proactive-gate": "dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/gate.test.js",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "proactive",
+    "notifications",
+    "rate-limit",
+    "quiet-hours",
+    "consent",
+    "budget",
+    "llm"
+  ],
+  "author": "Efe Genc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bubblegunn/proactive-gate.git"
+  },
+  "homepage": "https://github.com/Bubblegunn/proactive-gate#readme",
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.0"
+  }
+}