proactive-gate 0.4.1 → 0.6.0

package/dist/src/simulate-report.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The simulation as a table. Rendering only: every number here was computed in simulate.ts,
+ * and nothing in this file recounts anything, so the terminal output and `--json` cannot
+ * disagree with each other.
+ */
+import { DEMO_WEEK_NOTE } from "./demo-week.js";
+import type { SimResult } from "./simulate.js";
+export interface ReportOptions {
+    /** How many timeline rows to print. 0 prints all of them. */
+    limit?: number;
+    /** Print only the candidates the policies disagreed about. */
+    disagreementsOnly?: boolean;
+    /** Print each held candidate's sentence under its row. */
+    why?: boolean;
+    /** Which run the sentences and the stopped-by table describe; the last policy by default. */
+    reasonsFor?: number;
+    night?: {
+        start: number;
+        end: number;
+    };
+    /** Appended under the tables, for a generated stream that has to say so. */
+    note?: string;
+    /** One line per user, for a generated stream whose people were chosen for a reason. */
+    people?: string[];
+}
+export declare function formatSimulation(result: SimResult, options?: ReportOptions): string;
+export { DEMO_WEEK_NOTE };

package/dist/src/simulate-report.js

@@ -0,0 +1,128 @@
+/**
+ * The simulation as a table. Rendering only: every number here was computed in simulate.ts,
+ * and nothing in this file recounts anything, so the terminal output and `--json` cannot
+ * disagree with each other.
+ */
+import { DEMO_WEEK_NOTE } from "./demo-week.js";
+const VERDICT = {
+    sent: "sent",
+    held: "held",
+    deferred: "deferred",
+    expired: "expired",
+    lostAtCommit: "lost at commit",
+    spentNotDelivered: "spent, not delivered",
+};
+/** Outcome plus the check that produced it, which is the whole verdict in one cell. */
+const verdictOf = (cell) => {
+    if (!cell)
+        return "";
+    const word = VERDICT[cell.outcome] ?? cell.outcome;
+    return cell.check && cell.outcome !== "sent" ? `${word} ${cell.check}` : word;
+};
+const pad = (s, w) => (s.length > w ? `${s.slice(0, Math.max(0, w - 1))}…` : s.padEnd(w));
+/** The widest cell in a column, so nothing is truncated that would have fitted. */
+const widthOf = (values, min) => Math.max(min, ...values.map((v) => v.length));
+function timelineTable(result, rows, why) {
+    const labels = result.runs.map((r) => r.label);
+    const cols = labels.map((label, i) => ({
+        label,
+        width: widthOf([label, ...rows.map((r) => verdictOf(r.cells[i]))], 8),
+    }));
+    const userW = widthOf(["user", ...rows.map((r) => r.userId)], 4);
+    const typeW = widthOf(["type", ...rows.map((r) => r.type)], 4);
+    const priW = widthOf(["pri", ...rows.map((r) => r.priority)], 3);
+    const head = `${pad("when (local)", 13)}  ${pad("user", userW)}  ${pad("type", typeW)}  ${pad("pri", priW)}  ${cols.map((c) => pad(c.label, c.width)).join("  ")}`;
+    const out = [head, "-".repeat(head.length)];
+    for (const row of rows) {
+        const cells = cols.map((c, i) => pad(verdictOf(row.cells[i]), c.width)).join("  ");
+        out.push(`${pad(row.localTime, 13)}  ${pad(row.userId, userW)}  ${pad(row.type, typeW)}  ${pad(row.priority, priW)}  ${cells}`.trimEnd());
+        // --why prints the sentence explain() already produces, under the row it belongs to.
+        const cell = why === null ? undefined : row.cells[why];
+        if (cell && cell.outcome !== "sent" && cell.sentence)
+            out.push(`               ${cell.sentence}`);
+    }
+    return out;
+}
+function summaryTable(runs, night) {
+    const labels = runs.map((r) => r.label);
+    const nightLabel = `delivered ${String(night.start).padStart(2, "0")}:00-${String(night.end).padStart(2, "0")}:00 local`;
+    const quietLabel = "delivered inside their own quiet hours";
+    const rows = [
+        ["delivered", runs.map((r) => String(r.counts.sent))],
+        ["held", runs.map((r) => String(r.counts.held))],
+        ["deferred, then delivered", runs.map((r) => String(r.counts.sentAfterDeferral))],
+        ["moved to a later moment", runs.map((r) => String(r.counts.sentAtALaterMoment))],
+        ["deferred, then expired", runs.map((r) => String(r.counts.expired))],
+        ["lost at commit", runs.map((r) => String(r.counts.lostAtCommit))],
+        ["spent, not delivered", runs.map((r) => String(r.counts.spentNotDelivered))],
+        [quietLabel, runs.map((r) => String(r.counts.sentInQuietHours))],
+        ["  of those, critical (what the floor lets through)", runs.map((r) => String(r.counts.sentInQuietHoursByFloor))],
+        [`${nightLabel} (a fixed window)`, runs.map((r) => String(r.counts.sentAtNight))],
+        ["most one person got in a day", runs.map((r) => String(r.counts.busiestUserDay))],
+    ];
+    const labelW = widthOf(["", ...rows.map((r) => r[0])], 12);
+    const colW = labels.map((l, i) => widthOf([l, ...rows.map((r) => r[1][i] ?? "")], 6));
+    const out = [
+        `${pad("", labelW)}  ${labels.map((l, i) => pad(l, colW[i] ?? 6)).join("  ")}`,
+        "-".repeat(labelW + 2 + colW.reduce((n, w) => n + w + 2, 0)),
+    ];
+    for (const [label, values] of rows) {
+        if (values.every((v) => v === "0"))
+            continue;
+        out.push(`${pad(label, labelW)}  ${values.map((v, i) => pad(v, colW[i] ?? 6)).join("  ")}`.trimEnd());
+    }
+    return out;
+}
+function stoppedTable(run) {
+    if (!run.counts.stoppedBy.length)
+        return [];
+    const checkW = widthOf(["check", ...run.counts.stoppedBy.map((s) => s.check)], 5);
+    const out = [
+        `${pad("check", checkW)}  ${pad("stopped", 7)}  example`,
+        "-".repeat(checkW + 2 + 7 + 2 + 40),
+    ];
+    for (const s of run.counts.stoppedBy)
+        out.push(`${pad(s.check, checkW)}  ${String(s.count).padStart(7)}  ${s.example}`);
+    return out;
+}
+export function formatSimulation(result, options = {}) {
+    const limit = options.limit ?? 20;
+    const night = options.night ?? { start: 22, end: 8 };
+    const users = new Set(result.timeline.map((r) => r.userId)).size;
+    const source = options.disagreementsOnly ? result.disagreements : result.timeline;
+    const rows = limit > 0 ? source.slice(0, limit) : source;
+    const reasonsFor = options.reasonsFor ?? result.runs.length - 1;
+    const out = [
+        `proactive-gate simulate  ·  seed ${result.seed}  ·  ${result.events} candidates, ${users} users`,
+        `policies: ${result.runs.map((r) => r.label).join("  |  ")}`,
+        "rows are in the order a server produced them; the time is the recipient's own clock",
+        "",
+        ...timelineTable(result, rows, options.why ? reasonsFor : null),
+    ];
+    if (rows.length < source.length) {
+        out.push(`${source.length - rows.length} more ${options.disagreementsOnly ? "disagreements" : "candidates"} not shown; --limit 0 prints every row, --json prints everything`);
+    }
+    out.push("", `the policies disagreed about ${result.disagreements.length} of ${result.events} candidates`, "");
+    out.push(...summaryTable(result.runs, night));
+    const subject = result.runs[reasonsFor];
+    if (subject && subject.counts.stoppedBy.length) {
+        out.push("", `why ${subject.label} did not send`, "");
+        out.push(...stoppedTable(subject));
+    }
+    const budget = subject?.budget ?? [];
+    if (budget.length) {
+        const busiest = [...budget].sort((a, b) => b.used - a.used || a.userId.localeCompare(b.userId)).slice(0, 5);
+        out.push("", `budget spent, read back out of the store (top ${busiest.length} of ${budget.length} user-days)`, "");
+        for (const row of busiest)
+            out.push(`  ${pad(row.userId, 10)} ${row.localDay}  ${row.used}`);
+    }
+    if (options.people?.length) {
+        out.push("", "who is in the week, and why each one is here", "");
+        for (const line of options.people)
+            out.push(`  ${line}`);
+    }
+    if (options.note)
+        out.push("", options.note);
+    return out.join("\n");
+}
+export { DEMO_WEEK_NOTE };

package/dist/src/simulate.d.ts

@@ -0,0 +1,118 @@
+import type { Check, EvaluateInput, Policy } from "./types.js";
+/** What became of one candidate under one policy. */
+export type SimOutcome = "sent" | "held" | "deferred" | "expired" | "lostAtCommit" | "spentNotDelivered";
+export interface SimRecord {
+    candidateId: string;
+    userId: string;
+    /** The instant this attempt was evaluated at, which for a retry is the deferral's own time. */
+    at: string;
+    /** 1 for the first evaluation, 2 and up for re-evaluations after a deferral. */
+    attempt: number;
+    outcome: SimOutcome;
+    rejectedBy?: string;
+    deferredBy?: string;
+    retryAt?: string;
+    /** Set when a non-rejecting check asked for the send to happen at a later moment. */
+    deliverAt?: string;
+    /** The check's own reason, as the library words it. */
+    reason?: string;
+    /** The whole decision as one sentence, from `explain()`. */
+    sentence?: string;
+}
+export interface SimCounts {
+    candidates: number;
+    /**
+     * Every count below is over final outcomes, one per candidate: a candidate deferred and then
+     * sent is one send, not a deferral and a send. `deferredAtLeastOnce` and `sentAfterDeferral`
+     * are how the holding shows up, and they are the argument that a deferral is not a drop.
+     */
+    sent: number;
+    held: number;
+    expired: number;
+    lostAtCommit: number;
+    spentNotDelivered: number;
+    deferredAtLeastOnce: number;
+    sentAfterDeferral: number;
+    /** Sends a non-rejecting check moved to a later moment, which is neither a hold nor a drop. */
+    sentAtALaterMoment: number;
+    /**
+     * Sends that landed inside the recipient's **own** quiet hours. This is the number that says
+     * whether a stated preference was honoured; a fixed curfew would punish `hana`, who asked for
+     * no quiet hours at all, and would miss a user whose window is 18:00 to 09:00.
+     */
+    sentInQuietHours: number;
+    /** Of those, the ones the documented priority floor lets through on purpose. */
+    sentInQuietHoursByFloor: number;
+    /** Sends inside a fixed 22:00 to 08:00 local window, which is nobody's preference. */
+    sentAtNight: number;
+    /** The most sends one person received in one of their own local days. */
+    busiestUserDay: number;
+    /** How many candidates each check stopped, deferrals included, highest first. */
+    stoppedBy: Array<{
+        check: string;
+        count: number;
+        example: string;
+    }>;
+}
+export interface SimRun {
+    label: string;
+    records: SimRecord[];
+    counts: SimCounts;
+    /** Budget units spent, read back out of the store rather than counted in a local variable. */
+    budget: Array<{
+        userId: string;
+        localDay: string;
+        used: number;
+    }>;
+}
+export interface SimTimelineRow {
+    candidateId: string;
+    userId: string;
+    at: string;
+    /** Month-day and time in the recipient's own zone, which is the clock that judges a message. */
+    localTime: string;
+    type: string;
+    priority: string;
+    /** One cell per policy, in the order the policies were given. */
+    cells: Array<{
+        outcome: SimOutcome;
+        check?: string;
+        sentence?: string;
+        retryAt?: string;
+    }>;
+}
+export interface SimResult {
+    seed: number;
+    events: number;
+    runs: SimRun[];
+    timeline: SimTimelineRow[];
+    /** The candidates the policies disagreed about: the whole argument, in one list. */
+    disagreements: SimTimelineRow[];
+}
+/** A policy to run. Leave both `policy` and `checks` out for the no-gate baseline. */
+export interface SimPolicy {
+    label: string;
+    policy?: Policy;
+    checks?: Check[];
+}
+export interface SimOptions {
+    events: EvaluateInput[];
+    policies: SimPolicy[];
+    /** Seeds the simulated transport, and nothing else. */
+    seed?: number;
+    /** Fraction of simulated sends the fake transport fails. 0 keeps the run about the policy. */
+    transportFailureRate?: number;
+    /** How long a deferred candidate stays worth sending before this scheduler drops it. */
+    expirySeconds?: number;
+    /** The local window counted as night in `sentAtNight`. */
+    night?: {
+        start: number;
+        end: number;
+    };
+}
+export declare const DEFAULT_NIGHT: {
+    start: number;
+    end: number;
+};
+export declare const DEFAULT_EXPIRY_SECONDS: number;
+export declare function simulate(options: SimOptions): Promise<SimResult>;

package/dist/src/simulate.js

@@ -0,0 +1,269 @@
+/**
+ * One stream of candidates, two or more policies, every figure recomputed from the run.
+ *
+ * This adds no check and no store and does not touch the decision path: it runs the gate that
+ * already exists once per policy over the same events and records what happened to each
+ * candidate. The point is the difference between the columns, which is the only honest way this
+ * repository can answer "what would installing this change for me" without asking anyone to
+ * take a number on trust.
+ *
+ * Three distinctions the output keeps apart, because collapsing them is how a simulation lies:
+ *
+ * - **allowed is not sent.** `evaluate` says a message may go, `commit` takes the budget unit
+ *   and can still refuse when a concurrent delivery took the last one, and only then does a
+ *   transport run. `lostAtCommit` and `spentNotDelivered` are counted apart from `sent`.
+ * - **deferred is not rejected.** A deferral carries `retryAt`, and the candidate is
+ *   re-evaluated from scratch at that instant against the same store, so consent, the clock and
+ *   the budget are read again. An old allowed decision is never a standing permission to send.
+ *   A deferral nobody could still act on is counted as `expired` rather than quietly dropped.
+ * - **no gate is not a policy.** The baseline bypasses the gate entirely: every candidate is
+ *   sent. A policy with no checks is not expressible, and a rival built to lose would measure
+ *   nothing. The baseline is what a product does before this library is installed.
+ *
+ * Nothing here reads a wall clock. Every event carries its own `now`, the deferral scheduler
+ * runs on those same instants, and the simulated transport draws from a seeded generator, so a
+ * replay gives the same result on any machine on any day.
+ */
+import { createGate } from "./gate.js";
+import { budgetKey, localClock, quietAt } from "./checks.js";
+import { explain } from "./explain.js";
+import { MemoryStore } from "./stores.js";
+export const DEFAULT_NIGHT = { start: 22, end: 8 };
+export const DEFAULT_EXPIRY_SECONDS = 4 * 60 * 60;
+/** Small deterministic PRNG, so a seed is the whole definition of a run. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const iso = (d) => d.toISOString();
+/** The recipient's own clock, which is the only one a notification is judged by. */
+function localOf(timezone, at) {
+    const clock = localClock(at, timezone ?? "UTC");
+    const hour = Math.floor(clock.minutes / 60);
+    const minute = clock.minutes % 60;
+    return { hour, minute, day: clock.day, text: `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}` };
+}
+const inNight = (hour, night) => night.start <= night.end ? hour >= night.start && hour < night.end : hour >= night.start || hour < night.end;
+function countsOf(records, events, night) {
+    const zones = new Map(events.map((e) => [e.user.id, e.user.timezone]));
+    const quiet = new Map(events.map((e) => [e.user.id, e.user.quietHours]));
+    const floor = new Map(events.map((e) => [e.candidate.id, e.candidate.priority ?? "normal"]));
+    const perUserDay = new Map();
+    const stopped = new Map();
+    // One row per candidate, the last attempt, because that is what became of it. Counting every
+    // attempt would report a candidate that was held until morning as both a deferral and a send.
+    const finals = new Map();
+    for (const r of records)
+        finals.set(r.candidateId, r);
+    const deferredIds = new Set(records.filter((r) => r.outcome === "deferred").map((r) => r.candidateId));
+    let sentAtNight = 0;
+    let sentInQuietHours = 0;
+    let sentInQuietHoursByFloor = 0;
+    for (const r of finals.values()) {
+        if (r.outcome === "sent") {
+            const at = new Date(r.at);
+            const local = localOf(zones.get(r.userId), at);
+            if (inNight(local.hour, night))
+                sentAtNight += 1;
+            const window = quiet.get(r.userId);
+            if (window && quietAt(window, local.day, local.hour * 60 + local.minute)) {
+                sentInQuietHours += 1;
+                if (floor.get(r.candidateId) === "critical")
+                    sentInQuietHoursByFloor += 1;
+            }
+            const key = `${r.userId}:${local.day}`;
+            perUserDay.set(key, (perUserDay.get(key) ?? 0) + 1);
+            continue;
+        }
+        const by = r.rejectedBy ?? r.deferredBy;
+        if (!by)
+            continue;
+        const seen = stopped.get(by);
+        if (seen)
+            seen.count += 1;
+        else
+            stopped.set(by, { count: 1, example: r.reason ?? r.sentence ?? "" });
+    }
+    const finalRows = [...finals.values()];
+    const count = (outcome) => finalRows.filter((r) => r.outcome === outcome).length;
+    return {
+        candidates: finals.size,
+        sent: count("sent"),
+        held: count("held"),
+        expired: count("expired"),
+        lostAtCommit: count("lostAtCommit"),
+        spentNotDelivered: count("spentNotDelivered"),
+        deferredAtLeastOnce: deferredIds.size,
+        sentAfterDeferral: finalRows.filter((r) => r.outcome === "sent" && r.attempt > 1).length,
+        sentAtALaterMoment: finalRows.filter((r) => r.outcome === "sent" && r.deliverAt).length,
+        sentInQuietHours,
+        sentInQuietHoursByFloor,
+        sentAtNight,
+        busiestUserDay: perUserDay.size ? Math.max(...perUserDay.values()) : 0,
+        stoppedBy: [...stopped.entries()]
+            .map(([check, v]) => ({ check, count: v.count, example: v.example }))
+            .sort((a, b) => b.count - a.count || a.check.localeCompare(b.check)),
+    };
+}
+/**
+ * One stream through one gate, with a scheduler for deferrals that belongs to this simulation
+ * rather than to the library: the library never runs a queue. The queue is drained per user just
+ * before that user's next event and again at the end, because budgets are keyed per user and
+ * local day, so each user's own order is what keeps their counter honest.
+ */
+async function runGate(label, gate, store, events, send, expirySeconds, night) {
+    const records = [];
+    const pending = [];
+    const evaluateOnce = async (user, candidate, now, attempt) => {
+        const input = { user, candidate, now };
+        const decision = await gate.evaluate(input);
+        const record = {
+            candidateId: candidate.id,
+            userId: user.id,
+            at: iso(now),
+            attempt,
+            outcome: "held",
+            ...(decision.rejectedBy ? { rejectedBy: decision.rejectedBy } : {}),
+            ...(decision.deferredBy ? { deferredBy: decision.deferredBy } : {}),
+            ...(decision.retryAt ? { retryAt: iso(decision.retryAt) } : {}),
+            ...(decision.deliverAt ? { deliverAt: iso(decision.deliverAt) } : {}),
+            ...(decision.reason ? { reason: decision.reason } : {}),
+            sentence: explain(decision).summary,
+        };
+        if (decision.deferredBy) {
+            const due = decision.retryAt ?? now;
+            const stillWorthIt = due.getTime() <= now.getTime() + expirySeconds * 1000;
+            record.outcome = stillWorthIt ? "deferred" : "expired";
+            if (stillWorthIt)
+                pending.push({ user, candidate, due, attempt: attempt + 1 });
+            records.push(record);
+            return;
+        }
+        if (!decision.allowed) {
+            records.push(record);
+            return;
+        }
+        if (!(await gate.commit(decision, input))) {
+            record.outcome = "lostAtCommit";
+            record.rejectedBy = "commit";
+            record.reason = "a budget was exhausted at commit";
+            records.push(record);
+            return;
+        }
+        record.outcome = send() ? "sent" : "spentNotDelivered";
+        records.push(record);
+    };
+    /** Re-evaluate every deferral for this user due by `upTo`; both null drains what is left. */
+    const drain = async (userId, upTo) => {
+        for (;;) {
+            const index = pending.findIndex((p) => (userId === null || p.user.id === userId) && (upTo === null || p.due.getTime() <= upTo.getTime()));
+            if (index < 0)
+                return;
+            const [item] = pending.splice(index, 1);
+            if (!item)
+                return;
+            await evaluateOnce(item.user, item.candidate, item.due, item.attempt);
+        }
+    };
+    for (const event of events) {
+        const now = event.now ?? new Date(0);
+        await drain(event.user.id, now);
+        await evaluateOnce(event.user, event.candidate, now, 1);
+    }
+    await drain(null, null);
+    // Budget rows come out of the store, one per user and per local day, because that is how the
+    // key is shaped (spec/SPEC.md 5.1). One number per user would report a counter that has just
+    // rolled over and hide what the day before spent.
+    const zones = new Map(events.map((e) => [e.user.id, e.user.timezone]));
+    const wanted = new Map();
+    for (const r of records) {
+        const key = budgetKey(r.userId, new Date(r.at), zones.get(r.userId));
+        if (!wanted.has(key))
+            wanted.set(key, { userId: r.userId, localDay: key.slice(key.lastIndexOf(":") + 1), key });
+    }
+    const budget = [];
+    for (const row of [...wanted.values()].sort((a, b) => a.userId.localeCompare(b.userId) || a.localDay.localeCompare(b.localDay))) {
+        const used = Number((await store.get(`pg:${row.key}`)) ?? 0);
+        if (used > 0)
+            budget.push({ userId: row.userId, localDay: row.localDay, used });
+    }
+    return { label, records, counts: countsOf(records, events, night), budget };
+}
+/** Every candidate is sent. What a product does before this library is installed. */
+function runBaseline(label, events, send, night) {
+    const records = events.map((e) => ({
+        candidateId: e.candidate.id,
+        userId: e.user.id,
+        at: iso(e.now ?? new Date(0)),
+        attempt: 1,
+        outcome: send() ? "sent" : "spentNotDelivered",
+    }));
+    return { label, records, counts: countsOf(records, events, night), budget: [] };
+}
+/** The last attempt is what became of a candidate; earlier attempts are how it got there. */
+function finalOf(run, candidateId) {
+    const attempts = run.records.filter((r) => r.candidateId === candidateId);
+    return attempts.length ? attempts[attempts.length - 1] : undefined;
+}
+export async function simulate(options) {
+    const seed = options.seed ?? 1;
+    const failureRate = options.transportFailureRate ?? 0;
+    const expirySeconds = options.expirySeconds ?? DEFAULT_EXPIRY_SECONDS;
+    const night = options.night ?? DEFAULT_NIGHT;
+    const { events, policies } = options;
+    if (!events.length)
+        throw new Error("simulate: no events to run");
+    if (!policies.length)
+        throw new Error("simulate: no policies to run");
+    const runs = [];
+    for (const entry of policies) {
+        // A transport per run, seeded identically, so one run's failures cannot move another's.
+        const random = mulberry32(seed);
+        const send = () => random() >= failureRate;
+        if (!entry.policy && !entry.checks) {
+            runs.push(runBaseline(entry.label, events, send, night));
+            continue;
+        }
+        const store = new MemoryStore();
+        const gate = entry.policy
+            ? createGate({ policy: entry.policy, store })
+            : createGate({ checks: entry.checks ?? [], store });
+        runs.push(await runGate(entry.label, gate, store, events, send, expirySeconds, night));
+    }
+    const timeline = events.map((event) => {
+        const at = event.now ?? new Date(0);
+        const local = localOf(event.user.timezone, at);
+        return {
+            candidateId: event.candidate.id,
+            userId: event.user.id,
+            at: iso(at),
+            localTime: `${local.day.slice(5)} ${local.text}`,
+            type: event.candidate.type,
+            priority: event.candidate.priority ?? "normal",
+            cells: runs.map((run) => {
+                const record = finalOf(run, event.candidate.id);
+                if (!record)
+                    return { outcome: "held" };
+                const check = record.rejectedBy ?? record.deferredBy;
+                return {
+                    outcome: record.outcome,
+                    ...(check ? { check } : {}),
+                    ...(record.sentence ? { sentence: record.sentence } : {}),
+                    ...(record.retryAt ? { retryAt: record.retryAt } : {}),
+                };
+            }),
+        };
+    });
+    return {
+        seed,
+        events: events.length,
+        runs,
+        timeline,
+        disagreements: timeline.filter((row) => new Set(row.cells.map((c) => c.outcome)).size > 1),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.4.1",
+  "version": "0.6.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",
@@ -48,7 +48,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node test/spec-lint.mjs && node --test dist/test/gate.test.js dist/test/conformance.test.js dist/test/presets.test.js dist/test/adapters.test.js dist/test/init.test.js dist/test/properties.test.js dist/test/dedupe.test.js dist/test/explain.test.js test/release.test.mjs test/examples.test.mjs test/example-imports.test.mjs test/naive.test.mjs test/suite.test.mjs",
+    "test": "npm run build && node test/spec-lint.mjs && node --test dist/test/gate.test.js dist/test/conformance.test.js dist/test/presets.test.js dist/test/adapters.test.js dist/test/init.test.js dist/test/properties.test.js dist/test/dedupe.test.js dist/test/simulate.test.js dist/test/monotonicity.test.js dist/test/explain.test.js test/release.test.mjs test/examples.test.mjs test/example-imports.test.mjs test/naive.test.mjs test/playground-render.test.mjs test/playground-scenarios.test.mjs test/snippet.test.mjs test/suite.test.mjs",
     "lint": "tsc -p tsconfig.json --noEmit",
     "spec-lint": "node test/spec-lint.mjs",
     "conformance": "npm run build && node dist/src/cli.js replay --fixtures spec/fixtures",
@@ -61,7 +61,8 @@
     "bench:compare": "npm run build && node bench/compare.mjs",
     "conformance-table": "node scripts/conformance-table.mjs",
     "explain-parity": "node scripts/explain-parity.mjs",
-    "og": "npm run build && node scripts/og-image.mjs"
+    "og": "npm run build && node scripts/og-image.mjs",
+    "simulate": "npm run build && node dist/src/cli.js simulate"
   },
   "engines": {
     "node": ">=20"

package/spec/CONFORMANCE.md

@@ -11,9 +11,9 @@ The suite is versioned by `SPEC_VERSION`, and each version is tagged `spec/vX.Y.
 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
+git clone --depth 1 --branch spec/v1.3.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
+git subtree add --prefix spec https://github.com/Bubblegunn/proactive-gate spec/v1.3.0 --squash
 ```
 
 A JavaScript implementation can also read the fixtures from an install, because the npm package
@@ -72,7 +72,9 @@ A fixture is a contract for every implementation, not only this one. So a change
 `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.
+adds a check or a field, a major changes an expectation. A new preset is a minor for the same
+reason a new check is: 7.3 makes a policy that names an unknown preset a compile error, so nobody
+already passes the fixture that exercises it.
 
 ## The honest status of this suite
 
@@ -81,3 +83,47 @@ weaker evidence than it looks: agreement between two implementations by one auth
 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.
+
+## Implementing this in your language
+
+This is the one thing the project is actively asking for, and it is deliberately the last section
+of this document: everything above is what you need, and nothing below it is required of you.
+
+**The shape of the work.** A conforming implementation is a decision loop over an ordered list of
+checks and a key-value store with a counter. There is no network, no dependency, no framework and
+no content inspection anywhere in it. The TypeScript version is about 1,400 lines of source and the
+Python sibling about the same, and most of that is the twelve checks, each of which is a small pure
+function over a user, a candidate and an instant.
+
+**The order to do it in**, which is how both existing versions were built:
+
+1. Vendor the suite at a tag rather than a branch: `git clone --depth 1 --branch spec/vX.Y.Z` or a
+   subtree, and assert in your tests that the `SPEC_VERSION` you vendored is the one you claim.
+2. Write the fixture loader first. Each file under `fixtures/` is a policy plus a list of cases,
+   each case an input and an expectation, and the loader is the only part that touches JSON.
+3. Make one fixture pass, in this order: `consent`, then `quiet-hours/istanbul`, then
+   `budget/daily-atomic-commit`. Those three exercise the whole spine: ordering, a wall clock in a
+   named zone, and a counter that has to be atomic at commit.
+4. Then the rest, in whatever order the failures suggest. `spec/SPEC.md` is numbered, and every
+   fixture names the requirement it came from.
+
+**What passing means** is defined above and is not negotiable in one direction: a fixture you do
+not pass is declared in your skip file with a reason, in the open. Silence about a failing fixture
+is the one thing that makes a conformance claim worthless.
+
+**What you may leave out.** Presets, adapters, the JSON policy compiler, `explain()`, the CLI and
+the simulator are all optional; the fixtures that exercise them are the ones to declare as skipped.
+The twelve checks, the ordering rules, the store contract and the commit-time budget are not
+optional, because they are what the word conform refers to.
+
+**What we will do with it.** If you say it conforms and the fixtures agree, it goes in the README
+next to the other two implementations, under your name, with the version of the spec it targets.
+If it does not conform yet, say which fixtures and it goes in as a work in progress, because an
+honest partial claim is more useful to a reader than an absent one.
+
+**What we will not do.** We will not write it for you and then call it independent. The value of a
+third implementation is exactly that its author was not us, so a version written here would be
+worth less than the four days it took somebody else.
+
+Issue [#16](https://github.com/Bubblegunn/proactive-gate/issues/16) is the place to say you are
+starting, so two people do not write the same one.

package/spec/SPEC.md

@@ -7,6 +7,9 @@ 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.
+A preset added to the vocabulary is a minor, because 7.3 requires an implementation to reject a
+policy naming a preset it does not know, so a fixture that names the new preset is one no existing
+implementation can pass.
 An implementation declares the spec version it targets, and its CI MUST assert that the value
 equals `SPEC_VERSION`.
 

package/spec/SPEC_VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

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

@@ -1,5 +1,5 @@
 {
-  "spec_version": "1.2.0",
+  "spec_version": "1.3.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.",