proactive-gate 0.3.1 → 0.4.0

package/README.md

@@ -252,6 +252,29 @@ a hook that throws is routed to `error` and never changes the decision. `example
 turns them into one span per check. Every decision has an `id`, and `commit` is idempotent on
 it: a retry after a timeout does not consume a second unit.
 
+## A rejection reason a product manager can read
+
+`decision.reason` is written for the engineer holding the trace. `explain(decision)` renders
+the same decision as sentences for the person who decides whether the assistant is too chatty:
+
+```ts
+import { explain } from "proactive-gate";
+
+explain(decision).summary;
+// "Held until 08:00 because the user's quiet hours run 22:00 to 08:00 Europe/Istanbul and
+//  normal priority is below the critical floor needed to override them."
+```
+
+It answers "why did this go out at 22:30" too: an allowed decision explains itself, and
+`explanation.checks` carries one sentence per check that ran, in order. The renderer is a
+pure function of the decision; it invents nothing, and a check whose reason matches nothing
+known is quoted verbatim rather than guessed. `language` is a parameter: English ships as
+`en`, and any other language is a `Partial<Sentences>` in `catalogs`, merged over English so
+a partial translation still renders. The Python sibling ships the same sentences, and CI
+compares both renderings of every fixture decision on each push. It was contributed by
+[@LouisDeconinck](https://github.com/LouisDeconinck) in
+[#28](https://github.com/Bubblegunn/proactive-gate/pull/28), in TypeScript and Python together.
+
 ## Optional checks, fed by your own model
 
 Both ship off. They read numbers the caller puts on the candidate.
@@ -762,7 +785,7 @@ before. [@Aaqibhafeezkhan](https://github.com/Aaqibhafeezkhan) wrote `SqliteStor
 every release since, including the one you install today. @Aaqibhafeezkhan came back for a
 second one and wrote the store contract suite in [#24](https://github.com/Bubblegunn/proactive-gate/pull/24).
 
-A third person arrived from the other direction. [@LouisDeconinck](https://github.com/LouisDeconinck) took [#26](https://github.com/Bubblegunn/proactive-gate/issues/26), an issue this project filed against itself to admit that expired rows were never cleaned up, and twelve minutes later sent the fix in both languages with the test that would have caught the original bug ([#27](https://github.com/Bubblegunn/proactive-gate/pull/27), in 0.3.1).
+A third person arrived from the other direction. [@LouisDeconinck](https://github.com/LouisDeconinck) took [#26](https://github.com/Bubblegunn/proactive-gate/issues/26), an issue this project filed against itself to admit that expired rows were never cleaned up, and twelve minutes later sent the fix in both languages with the test that would have caught the original bug ([#27](https://github.com/Bubblegunn/proactive-gate/pull/27), in 0.3.1). He then took [#23](https://github.com/Bubblegunn/proactive-gate/issues/23), the issue asking for a rejection reason a product manager could read, and wrote its sixty-seven sentence templates in both languages ([#28](https://github.com/Bubblegunn/proactive-gate/pull/28), in 0.4.0). That is the work in this library that is hardest to review and easiest to get wrong, because it lives in the wording rather than in the code.
 
 ## Cite this
 

package/README.tr.md

@@ -209,6 +209,31 @@ fırlatan bir kanca `error` kancasına yönlendirilir ve kararı asla değiştir
 `commit` bu id üzerinde tekrarlanabilir: zaman aşımından sonraki bir yeniden deneme ikinci
 bir birim tüketmez.
 
+## Bir ürün yöneticisinin okuyabileceği ret gerekçesi
+
+`decision.reason` izi elinde tutan mühendis için yazılmıştır. `explain(decision)` aynı kararı,
+asistanın fazla konuşkan olup olmadığına karar veren kişi için cümlelere çevirir; aynı izden,
+hiçbir şey eklemeden:
+
+```ts
+import { explain } from "proactive-gate";
+
+explain(decision).summary;
+// "Held until 08:00 because the user's quiet hours run 22:00 to 08:00 Europe/Istanbul and
+//  normal priority is below the critical floor needed to override them."
+```
+
+"Bu mesaj 22:30'da neden gitti" sorusunun da bir yanıtı olur: izin verilen karar da kendini
+anlatır, `explanation.checks` ise çalışan her kontrol için sırayla bir cümle taşır. Renderer
+kararın saf bir fonksiyonudur: saat okumaz, adaya da kullanıcıya da bakmaz, dolayısıyla
+gate'in vermediği bir kararı anlatamaz. Hiçbir şablona uymayan bir gerekçe tahmin edilmez,
+olduğu gibi alıntılanır ve söyleyen kontrolün adıyla verilir. `language` bir parametredir:
+İngilizce `en` olarak gelir, başka bir dil `catalogs` içinde İngilizcenin üzerine birleşen bir
+`Partial<Sentences>`'tır, böylece yarım bir çeviri de görüntülenir. Python kardeşi aynı
+cümleleri yollar, CI her push'ta iki uygulamanın her fixture kararını karşılaştırır. Bu bölümü
+[@LouisDeconinck](https://github.com/LouisDeconinck)
+[#28](https://github.com/Bubblegunn/proactive-gate/pull/28) ile iki dilde birden yazdı.
+
 ## İsteğe bağlı, kendi modelinizin beslediği kontroller
 
 İkisi de kapalı gelir; adayın üzerine çağıranın koyduğu sayıları okurlar.

package/dist/src/explain.d.ts

@@ -0,0 +1,130 @@
+/**
+ * explain(): a decision rendered as sentences a non-engineer can read.
+ *
+ * The renderer is a pure function of the decision. Every fact in a sentence
+ * comes from a trace entry's own reason or from a decision field, so it can
+ * only describe a decision the gate actually made; a check that never ran has
+ * no sentence. The machine reasons are the contract both implementations pin
+ * word for word, which is what makes them safe to read back here. When a
+ * reason does not match what a check emits, the sentence quotes it verbatim
+ * rather than guessing.
+ *
+ * `decision.reason` is unchanged: the plain sentence and the machine reason
+ * sit side by side and neither replaces the other.
+ */
+import type { Decision, TraceEntry } from "./types.js";
+/** Fields a parser pulled out of a machine reason; a template reads them. */
+export type SentenceFacts = Record<string, string | undefined>;
+export type SentenceTemplate = (facts: SentenceFacts) => string;
+/**
+ * Every sentence the renderer can emit, as one flat template table. A new
+ * language is a `Partial<Sentences>` merged over English, so a partial
+ * translation still renders. Keys are `check.outcome` plus the summary,
+ * note, gate and fallback entries.
+ */
+export interface Sentences {
+    /** A catalog may define keys beyond this table; explain() only reads the named ones. */
+    [key: string]: SentenceTemplate | undefined;
+    /** Whole-decision line for a reject or defer. `until` is set when the trace names the instant the hold lifts. */
+    "summary.held": SentenceTemplate;
+    /** Whole-decision line for an allowed decision. `notes` is pre-joined, leading semicolon included. */
+    "summary.allowed": SentenceTemplate;
+    /** Allowed with an empty trace. */
+    "summary.allowedEmpty": SentenceTemplate;
+    /** Not allowed but no stopping entry found; the decision was built by hand. */
+    "summary.heldUnknown": SentenceTemplate;
+    "note.deliverAt": SentenceTemplate;
+    "note.nearLimit": SentenceTemplate;
+    "note.shadowed": SentenceTemplate;
+    /** Wraps a shadowed stop: `body` is the clause the check would have produced. */
+    "entry.shadow": SentenceTemplate;
+    "killSwitch.pass": SentenceTemplate;
+    "killSwitch.reject": SentenceTemplate;
+    "consent.pass": SentenceTemplate;
+    "consent.reject": SentenceTemplate;
+    "enabled.pass": SentenceTemplate;
+    "enabled.reject": SentenceTemplate;
+    "mode.pass": SentenceTemplate;
+    "mode.reject": SentenceTemplate;
+    "snooze.pass": SentenceTemplate;
+    "snooze.reject": SentenceTemplate;
+    "mute.pass": SentenceTemplate;
+    "mute.reject": SentenceTemplate;
+    "intensity.pass": SentenceTemplate;
+    "intensity.reject": SentenceTemplate;
+    "quietHours.pass": SentenceTemplate;
+    "quietHours.reject": SentenceTemplate;
+    "quietHours.skip": SentenceTemplate;
+    "trustRamp.pass": SentenceTemplate;
+    "trustRamp.reject": SentenceTemplate;
+    "trustRamp.skip": SentenceTemplate;
+    "dismissalCooldown.pass": SentenceTemplate;
+    "dismissalCooldown.reject": SentenceTemplate;
+    "adaptiveTiming.pass": SentenceTemplate;
+    "adaptiveTiming.adjust": SentenceTemplate;
+    "dedupe.pass": SentenceTemplate;
+    "dedupe.reject": SentenceTemplate;
+    "dedupe.skip": SentenceTemplate;
+    "dailyBudget.pass": SentenceTemplate;
+    "dailyBudget.reject": SentenceTemplate;
+    "weeklyBudget.pass": SentenceTemplate;
+    "weeklyBudget.reject": SentenceTemplate;
+    "monthlyBudget.pass": SentenceTemplate;
+    "monthlyBudget.reject": SentenceTemplate;
+    "windowBudget.pass": SentenceTemplate;
+    "windowBudget.reject": SentenceTemplate;
+    "rateLimit.pass": SentenceTemplate;
+    "rateLimit.reject": SentenceTemplate;
+    "budget.pass": SentenceTemplate;
+    "budget.reject": SentenceTemplate;
+    "utilityFloor.pass": SentenceTemplate;
+    "utilityFloor.reject": SentenceTemplate;
+    "utilityFloor.skip": SentenceTemplate;
+    "boundedDeferral.pass": SentenceTemplate;
+    "boundedDeferral.adjust": SentenceTemplate;
+    "allowedWindow.pass": SentenceTemplate;
+    "allowedWindow.reject": SentenceTemplate;
+    "allowedWindow.skip": SentenceTemplate;
+    "requiresConsent.pass": SentenceTemplate;
+    "requiresConsent.reject": SentenceTemplate;
+    "requiresConsent.skip": SentenceTemplate;
+    "recentInteraction.pass": SentenceTemplate;
+    "recentInteraction.reject": SentenceTemplate;
+    /** The gate's own trace reasons, not any check's: store failures and ignored non-rejecting stops. */
+    "gate.failOpen": SentenceTemplate;
+    "gate.failClosed": SentenceTemplate;
+    "gate.nonRejecting": SentenceTemplate;
+    /** Unknown check ids and reasons that match nothing: quote the trace, invent nothing. */
+    "fallback.stop": SentenceTemplate;
+    "fallback.pass": SentenceTemplate;
+    "fallback.skip": SentenceTemplate;
+    "fallback.adjust": SentenceTemplate;
+}
+/** One trace entry rendered: which check, what it said, and the sentence for it. */
+export interface CheckSentence {
+    id: string;
+    outcome: TraceEntry["outcome"];
+    shadow?: boolean;
+    sentence: string;
+}
+export interface Explanation {
+    /** The decision as one sentence: "held until 08:00 because ...", "allowed because ...". */
+    summary: string;
+    /** One sentence per check that ran, in the order it ran. */
+    checks: CheckSentence[];
+}
+export interface ExplainOptions {
+    /**
+     * Language of the sentences. Only "en" ships with the package; any other
+     * code needs a matching entry in `catalogs`, which is merged over English
+     * so a partial translation still renders.
+     */
+    language?: string;
+    catalogs?: Record<string, Partial<Sentences>>;
+}
+export declare const en: Sentences;
+/**
+ * Render a decision as sentences. Deterministic: the same decision always
+ * produces the same explanation, and nothing outside the decision is read.
+ */
+export declare function explain(decision: Decision, options?: ExplainOptions): Explanation;

package/dist/src/explain.js

@@ -0,0 +1,336 @@
+/* English ---------------------------------------------------------------- */
+const plural = (n, unit) => `${n} ${unit}${n === 1 ? "" : "s"}`;
+/** "1d" to "within the last day", "24h" to "within the last 24 hours": the dedupe window, said long. */
+const spanWords = (label) => {
+    const m = /^(\d+)([dhms])$/.exec(label);
+    if (!m)
+        return `within the last ${label}`;
+    const unit = { d: "day", h: "hour", m: "minute", s: "second" }[m[2]];
+    const n = Number(m[1]);
+    return n === 1 ? `within the last ${unit}` : `within the last ${plural(n, unit)}`;
+};
+/** "86400" to "day", "7200" to "2 hours": a rate-limit period in seconds, said long. */
+const secondsWords = (text) => {
+    const n = Number(text);
+    if (!Number.isFinite(n))
+        return `${text} seconds`;
+    // "per hour", not "per 1 hour": the same singular spanWords already says as "the last day".
+    const period = (count, unit) => (count === 1 ? unit : plural(count, unit));
+    if (n % 86400 === 0)
+        return period(n / 86400, "day");
+    if (n % 3600 === 0)
+        return period(n / 3600, "hour");
+    if (n % 60 === 0)
+        return period(n / 60, "minute");
+    return period(n, "second");
+};
+/** The spend note is true only when the pass really read the counter: a bypassed budget returns a bare pass, a near-limit pass cannot be a bypass. */
+const budgetPass = (label) => (f) => f.used !== undefined
+    ? `the ${label} had room, but only just: ${f.used} of ${f.limit} already used; the unit is spent when the message actually goes out`
+    : `the ${label} did not stop it`;
+const budgetReject = (label) => (f) => `the ${label} of ${f.limit} was already spent (${f.used} used)`;
+export const en = {
+    "summary.held": (f) => `held${f.until ? ` until ${f.until}` : ""} because ${f.clause}`,
+    "summary.allowed": (f) => `allowed at ${f.at} because no check stopped it${f.notes ?? ""}`,
+    "summary.allowedEmpty": () => "allowed; no checks ran",
+    "summary.heldUnknown": () => "held; the trace does not name the check that stopped it",
+    "note.deliverAt": (f) => `delivery waits until ${f.at}`,
+    "note.nearLimit": (f) => `${f.check} was close to its limit (${f.used} of ${f.limit} used)`,
+    "note.shadowed": (f) => `${f.check} would have stopped it but ran in shadow mode`,
+    "entry.shadow": (f) => `it would have stopped the message (${f.body}), but the check ran in shadow mode so evaluation continued`,
+    "killSwitch.pass": () => "the kill switch was off",
+    "killSwitch.reject": () => "the kill switch is on, which stops every message",
+    "consent.pass": () => "the user has agreed to proactive messages",
+    "consent.reject": () => "the user has not agreed to proactive messages",
+    "enabled.pass": () => "proactive messages are switched on for this profile",
+    "enabled.reject": () => "proactive messages are switched off on this user's profile",
+    "mode.pass": () => "the user's operating mode did not block it",
+    "mode.reject": (f) => `the user's operating mode is "${f.mode}", which does not allow proactive messages`,
+    "snooze.pass": () => "no snooze was in effect",
+    "snooze.reject": (f) => `the user has snoozed the assistant until ${f.until}`,
+    "mute.pass": () => "this type of message is not muted",
+    "mute.reject": (f) => `the user has muted "${f.type}" messages`,
+    "intensity.pass": () => "the message's priority satisfied the user's intensity setting",
+    "intensity.reject": (f) => `the message was ${f.priority} priority, and the user's "${f.level}" intensity setting allows only ${f.floor} and above`,
+    "quietHours.pass": () => "quiet hours did not block it",
+    "quietHours.reject": (f) => `the user's quiet hours run ${f.start} to ${f.end} ${f.tz}${f.from ? `, a window belonging to ${f.from},` : ""} and ${f.priority} priority is below the ${f.floor} floor needed to override them`,
+    "quietHours.skip": () => "the user has quiet hours but no time zone, so the check could not run",
+    "trustRamp.pass": () => "the new-user trust period did not block it",
+    "trustRamp.reject": (f) => `the user is on day ${f.day} of a ${f.days}-day trust period for new users, which allows only ${f.floor} priority and above, and the message was ${f.priority}`,
+    "trustRamp.skip": () => "the user's sign-up date is not on record, so the new-user trust period could not be checked",
+    "dismissalCooldown.pass": () => "the user has not dismissed this type enough to silence it",
+    "dismissalCooldown.reject": (f) => `the user has dismissed "${f.type}" messages ${f.count} times in ${f.within} days, so this type stays silent until ${f.until}`,
+    "adaptiveTiming.pass": () => "the timing check left the message as it was",
+    "adaptiveTiming.adjust": (f) => f.at && f.surfaces
+        ? `delivery was moved to ${f.at} and narrowed to ${f.surfaces.split(",").join(", ")}`
+        : f.at
+            ? `delivery was moved to ${f.at}`
+            : `delivery was narrowed to ${(f.surfaces ?? "").split(",").join(", ")}`,
+    "dedupe.pass": () => "this event had not already produced a message; the event is claimed when the message actually goes out",
+    "dedupe.reject": (f) => `the same event already produced a message ${spanWords(f.window ?? "")}`,
+    "dedupe.skip": () => "the candidate carried no event key, so duplicate detection could not run",
+    "dailyBudget.pass": budgetPass("daily budget"),
+    "dailyBudget.reject": budgetReject("user's daily budget"),
+    "weeklyBudget.pass": budgetPass("weekly budget"),
+    "weeklyBudget.reject": budgetReject("user's weekly budget"),
+    "monthlyBudget.pass": budgetPass("monthly budget"),
+    "monthlyBudget.reject": budgetReject("user's monthly budget"),
+    "windowBudget.pass": budgetPass("window budget"),
+    "windowBudget.reject": (f) => `the budget for the window opened by the user's last message was already spent (${f.used} of ${f.limit} used)`,
+    "rateLimit.pass": () => "the rate limit did not stop it",
+    "rateLimit.reject": (f) => `the rate limit of ${f.limit} messages per ${secondsWords(f.per ?? "")} was already reached (${f.used} used)`,
+    "budget.pass": (f) => `the budget had room, but only just: ${f.used} of ${f.limit} already used; the unit is spent when the message actually goes out`,
+    "budget.reject": (f) => `the ${f.label} was already used up (${f.used} of ${f.limit} used)`,
+    "utilityFloor.pass": () => "the estimated acceptance chance cleared the utility floor",
+    "utilityFloor.reject": (f) => `the estimated chance the user would accept this message was ${f.pAccept}, below the utility floor of ${f.tau}`,
+    "utilityFloor.skip": () => "the candidate carried no acceptance estimate, so the utility floor could not run",
+    "boundedDeferral.pass": () => "the user did not look busy",
+    "boundedDeferral.adjust": (f) => `the user looked busy, so delivery was deferred ${f.tStar} seconds to ${f.at}`,
+    "allowedWindow.pass": (f) => (f.name ? `the "${f.name}" allowed window did not block it` : "the allowed window did not block it"),
+    "allowedWindow.reject": (f) => `messages may only go out between ${f.start} and ${f.end} (${f.zone}), and the local time was outside that window`,
+    "allowedWindow.skip": () => "the user has no time zone, so the allowed window could not be checked",
+    "requiresConsent.pass": (f) => (f.name ? `the "${f.name}" consent the check needs was in place` : "the consent the check needs was in place"),
+    "requiresConsent.reject": (f) => `the user has not given the required "${f.name}" consent${f.start ? `, which applies between ${f.start} and ${f.end}` : ""}`,
+    "requiresConsent.skip": () => "the user has no time zone, so the hours this consent applies could not be checked",
+    "recentInteraction.pass": () => "the user had written to the assistant recently enough",
+    "recentInteraction.reject": (f) => f.age ? `the user's last message to the assistant was ${f.age} h ago, outside the ${f.within} h window` : "the user has never written to the assistant, and this rule allows messages only after they do",
+    "gate.failOpen": (f) => `the "${f.id}" check failed with "${f.error}", and the gate is set to let messages through when a check fails`,
+    "gate.failClosed": (f) => `the "${f.id}" check failed with "${f.error}", and the gate is set to stop messages when a check fails`,
+    "gate.nonRejecting": (f) => `the "${f.id}" check tried to ${f.kind} ("${f.reason}") but is marked non-rejecting, so the gate ignored it`,
+    "fallback.stop": (f) => `the "${f.id}" check stopped it: ${f.reason}`,
+    "fallback.pass": (f) => `the "${f.id}" check let it through${f.reason ? ` (${f.reason})` : ""}`,
+    "fallback.skip": (f) => `the "${f.id}" check did not weigh in: ${f.reason}`,
+    "fallback.adjust": (f) => `the "${f.id}" check adjusted it: ${f.reason}`,
+};
+const match = (pattern, keys) => (reason) => {
+    const m = pattern.exec(reason);
+    if (!m)
+        return null;
+    const facts = {};
+    keys.forEach((key, i) => {
+        const value = m[i + 1];
+        if (value !== undefined)
+            facts[key] = value;
+    });
+    return facts;
+};
+const fixed = (text) => (reason) => (reason === text ? {} : null);
+const first = (...parsers) => (reason) => {
+    for (const parse of parsers) {
+        const facts = parse(reason);
+        if (facts)
+            return facts;
+    }
+    return null;
+};
+const BUDGET_STOP = match(/^.* of (\d+) used \((\d+)\)$/, ["limit", "used"]);
+const BUDGET_NEAR = match(/^(\d+) of (\d+) used$/, ["used", "limit"]);
+const parseQuietHours = (reason) => {
+    const m = /^quiet hours (\S+) to (\S+)(?: \((\w+) (\S+)\))? (\S+); priority (\w+) is below the floor \((\w+)\)$/.exec(reason);
+    if (!m)
+        return null;
+    // holdUntil is the fact the summary headlines ("held until 08:00"); checks
+    // whose clause already says the instant (snooze, cooldown) leave it unset.
+    const facts = { start: m[1], end: m[2], tz: m[5], priority: m[6], floor: m[7], holdUntil: m[2] };
+    if (m[3] !== undefined)
+        facts.from = `${m[3]} ${m[4]}`;
+    return facts;
+};
+const PARSERS = {
+    killSwitch: { stop: fixed("engine kill switch is on") },
+    consent: { stop: fixed("user has not consented to proactive behaviour") },
+    enabled: { stop: fixed("proactive behaviour is disabled on this profile") },
+    mode: { stop: match(/^operating mode "(.+)" does not allow proactive messages$/, ["mode"]) },
+    snooze: { stop: match(/^snoozed until (.+)$/, ["until"]) },
+    mute: { stop: match(/^type "(.+)" is muted by the user$/, ["type"]) },
+    intensity: { stop: match(/^priority (\w+) is below the "(\w+)" intensity floor \((\w+)\)$/, ["priority", "level", "floor"]) },
+    quietHours: { stop: parseQuietHours, skip: fixed("quiet hours set but no timezone on the user; cannot evaluate") },
+    trustRamp: { stop: match(/^trust ramp: day (\d+) of (\S+), priority (\w+) is below (\w+)$/, ["day", "days", "priority", "floor"]), skip: fixed("no createdAt on the user; ramp cannot be evaluated") },
+    dismissalCooldown: { stop: match(/^(\d+) dismissals of "(.+)" in (\S+) days; silent until (.+)$/, ["count", "type", "within", "until"]) },
+    adaptiveTiming: { adjust: first(match(/^deliver at (\S+); surfaces (.+)$/, ["at", "surfaces"]), match(/^deliver at (\S+)$/, ["at"]), match(/^surfaces (.+)$/, ["surfaces"])) },
+    dedupe: { stop: match(/^already delivered within the last (.+)$/, ["window"]), skip: fixed("no dedupeKey on the candidate; deduplication cannot be evaluated") },
+    dailyBudget: { stop: BUDGET_STOP, passReason: BUDGET_NEAR },
+    weeklyBudget: { stop: BUDGET_STOP, passReason: BUDGET_NEAR },
+    monthlyBudget: { stop: BUDGET_STOP, passReason: BUDGET_NEAR },
+    windowBudget: { stop: BUDGET_STOP, passReason: BUDGET_NEAR },
+    rateLimit: { stop: match(/^rate limit (\d+) per (\d+) s of \d+ used \((\d+)\)$/, ["limit", "per", "used"]), passReason: BUDGET_NEAR },
+    utilityFloor: { stop: match(/^pAccept (\S+) < tau (\S+)$/, ["pAccept", "tau"]), skip: fixed("no pAccept on the candidate; utility floor cannot be evaluated") },
+    boundedDeferral: { adjust: match(/^user busy; deliver at (\S+) \(t\* (\d+) s\)$/, ["at", "tStar"]) },
+    allowedWindow: {
+        stop: match(/^outside the allowed window (\S+) to (\S+) (.+)$/, ["start", "end", "zone"]),
+        idFacts: (id) => (id.startsWith("window:") ? { name: id.slice("window:".length) } : {}),
+        skip: fixed("no timezone on the user; window cannot be evaluated"),
+    },
+    requiresConsent: {
+        stop: match(/^consent "(.+)" is missing(?: \(required (\S+) to (\S+)\))?$/, ["name", "start", "end"]),
+        idFacts: (id) => (id.startsWith("consent:") ? { name: id.slice("consent:".length) } : {}),
+        skip: fixed("no timezone on the user; consent window cannot be evaluated"),
+    },
+    recentInteraction: {
+        stop: first(fixed("no inbound message from the user on record"), match(/^last inbound message (\d+) h ago, window is (\S+) h$/, ["age", "within"])),
+    },
+};
+/** The ids the package itself emits: the fixed check ids, plus consent:<name>, rate:<limit>/<period>s and window:<name>. */
+const keyForId = (id) => {
+    if (id in PARSERS)
+        return id;
+    if (id.startsWith("consent:"))
+        return "requiresConsent";
+    if (id.startsWith("rate:"))
+        return "rateLimit";
+    if (id.startsWith("window:"))
+        return "allowedWindow";
+    return undefined;
+};
+/** The gate's own trace entries: a store failure, or a non-rejecting check that tried to stop evaluation anyway. */
+const GATE_ENTRIES = [
+    { key: "gate.failOpen", parse: match(/^check threw \((.*)\); failing open$/, ["error"]) },
+    { key: "gate.failClosed", parse: match(/^check threw \((.*)\); failing closed$/, ["error"]) },
+    { key: "gate.nonRejecting", parse: match(/^non-rejecting check returned (\w+) \((.*)\); ignored$/, ["kind", "reason"]) },
+];
+/**
+ * Custom ids (a preset's "window:kakao", a caller's own wrapper) still emit the
+ * check's reason, so an unmatched id falls back to recognizing the reason's
+ * shape. Order is distinctiveness: each pattern names the check it sounds like.
+ */
+const STOP_SCAN = ["quietHours", "allowedWindow", "requiresConsent", "rateLimit", "dismissalCooldown", "snooze", "mute", "mode", "intensity", "trustRamp", "dedupe", "utilityFloor", "recentInteraction", "killSwitch", "consent", "enabled"];
+const SKIP_SCAN = ["quietHours", "trustRamp", "dedupe", "utilityFloor", "allowedWindow", "requiresConsent"];
+const ADJUST_SCAN = ["adaptiveTiming", "boundedDeferral"];
+const BUDGET_LABELS = { "daily budget": "dailyBudget", "weekly budget": "weeklyBudget", "monthly budget": "monthlyBudget", "window budget": "windowBudget" };
+/** A "label of N used (M)" reason from a budget whose id we do not know. */
+const scanBudget = (reason) => {
+    const m = /^(.+) of (\d+) used \((\d+)\)$/.exec(reason);
+    if (!m)
+        return null;
+    const known = BUDGET_LABELS[m[1]];
+    const facts = { label: m[1], limit: m[2], used: m[3] };
+    return { key: known ?? "budget", facts };
+};
+const cap = (text) => (text ? text[0].toUpperCase() + text.slice(1) : text);
+const sentenceOf = (fragment) => `${cap(fragment)}.`;
+const t = (s, key, facts) => s[key]?.(facts) ?? en[key]?.(facts) ?? facts.reason ?? "";
+/** The stopping entry's clause and, when the trace names it, the instant the hold lifts. */
+function stopFacts(entry) {
+    const reason = entry.reason ?? "";
+    for (const g of GATE_ENTRIES) {
+        const facts = g.parse(reason);
+        if (facts)
+            return { template: g.key, facts: { id: entry.id, ...facts } };
+    }
+    const key = keyForId(entry.id);
+    if (key && PARSERS[key]?.stop) {
+        const facts = PARSERS[key].stop(reason);
+        if (facts)
+            return { template: `${key}.reject`, facts };
+    }
+    for (const k of STOP_SCAN) {
+        const facts = PARSERS[k]?.stop?.(reason);
+        if (facts)
+            return { template: `${k}.reject`, facts };
+    }
+    const budget = scanBudget(reason);
+    if (budget)
+        return { template: `${budget.key}.reject`, facts: budget.facts };
+    return { template: "fallback.stop", facts: { id: entry.id, reason } };
+}
+function entryBody(entry, s) {
+    const reason = entry.reason ?? "";
+    const key = keyForId(entry.id);
+    switch (entry.outcome) {
+        case "reject":
+        case "defer": {
+            const stop = stopFacts(entry);
+            return t(s, stop.template, stop.facts);
+        }
+        case "pass": {
+            if (reason) {
+                const facts = key ? PARSERS[key]?.passReason?.(reason) : BUDGET_NEAR(reason);
+                if (facts)
+                    return t(s, `${key ?? "budget"}.pass`, facts);
+                return t(s, "fallback.pass", { id: entry.id, reason });
+            }
+            const facts = key ? (PARSERS[key]?.idFacts?.(entry.id) ?? {}) : {};
+            return t(s, key ? `${key}.pass` : "fallback.pass", { id: entry.id, ...facts });
+        }
+        case "skip": {
+            for (const g of GATE_ENTRIES) {
+                const facts = g.parse(reason);
+                if (facts)
+                    return t(s, g.key, { id: entry.id, ...facts });
+            }
+            if (key && PARSERS[key]?.skip) {
+                const facts = PARSERS[key].skip(reason);
+                if (facts)
+                    return t(s, `${key}.skip`, facts);
+            }
+            for (const k of SKIP_SCAN) {
+                const facts = PARSERS[k]?.skip?.(reason);
+                if (facts)
+                    return t(s, `${k}.skip`, facts);
+            }
+            return t(s, "fallback.skip", { id: entry.id, reason });
+        }
+        case "adjust": {
+            if (key && PARSERS[key]?.adjust) {
+                const facts = PARSERS[key].adjust(reason);
+                if (facts)
+                    return t(s, `${key}.adjust`, facts);
+            }
+            for (const k of ADJUST_SCAN) {
+                const facts = PARSERS[k]?.adjust?.(reason);
+                if (facts)
+                    return t(s, `${k}.adjust`, facts);
+            }
+            return t(s, "fallback.adjust", { id: entry.id, reason });
+        }
+    }
+}
+function explainEntry(entry, s) {
+    const body = entryBody(entry, s);
+    // Shadow is only a would-have-stopped when the outcome could have stopped.
+    const shadowedStop = entry.shadow === true && (entry.outcome === "reject" || entry.outcome === "defer");
+    return {
+        id: entry.id,
+        outcome: entry.outcome,
+        ...(entry.shadow ? { shadow: true } : {}),
+        sentence: sentenceOf(shadowedStop ? t(s, "entry.shadow", { body }) : body),
+    };
+}
+function summarize(decision, s) {
+    if (decision.allowed) {
+        if (!decision.trace.length)
+            return sentenceOf(t(s, "summary.allowedEmpty", {}));
+        const notes = [];
+        if (decision.deliverAt)
+            notes.push(t(s, "note.deliverAt", { at: decision.deliverAt.toISOString() }));
+        for (const n of decision.nearLimit)
+            notes.push(t(s, "note.nearLimit", { check: n.check, used: String(n.used), limit: String(n.limit) }));
+        for (const id of decision.shadowed)
+            notes.push(t(s, "note.shadowed", { check: id }));
+        return sentenceOf(t(s, "summary.allowed", { at: decision.evaluatedAt.toISOString(), notes: notes.length ? `; ${notes.join("; ")}` : "" }));
+    }
+    const stopId = decision.rejectedBy ?? decision.deferredBy;
+    const entry = stopId ? [...decision.trace].reverse().find((e) => e.id === stopId && (e.outcome === "reject" || e.outcome === "defer")) : undefined;
+    if (!entry)
+        return sentenceOf(t(s, "summary.heldUnknown", {}));
+    const stop = stopFacts(entry);
+    const clause = t(s, stop.template, stop.facts);
+    // For a deferral the hold ends at retryAt; when the clause already names the
+    // instant (snooze's reason is "snoozed until X"), naming it twice reads worse.
+    const clauseSaysWhen = stop.facts.until !== undefined;
+    const until = stop.facts.holdUntil ?? (!clauseSaysWhen && decision.deferredBy ? decision.retryAt?.toISOString() : undefined);
+    return sentenceOf(t(s, "summary.held", { clause, ...(until ? { until } : {}) }));
+}
+/**
+ * Render a decision as sentences. Deterministic: the same decision always
+ * produces the same explanation, and nothing outside the decision is read.
+ */
+export function explain(decision, options = {}) {
+    const language = options.language ?? "en";
+    const overlay = options.catalogs?.[language];
+    if (language !== "en" && !overlay) {
+        throw new Error(`no sentence catalog for language "${language}"; pass one with the catalogs option`);
+    }
+    const s = { ...en, ...overlay };
+    return { summary: summarize(decision, s), checks: decision.trace.map((entry) => explainEntry(entry, s)) };
+}

package/dist/src/index.d.ts

@@ -1,5 +1,7 @@
 export { createGate } from "./gate.js";
 export type { Gate, PolicyGateOptions } from "./gate.js";
+export { explain, en } from "./explain.js";
+export type { CheckSentence, Explanation, ExplainOptions, SentenceFacts, Sentences, SentenceTemplate } from "./explain.js";
 export { compilePolicy, KNOWN_CHECKS } from "./policy.js";
 export { presets } from "./presets.js";
 export type { Preset } from "./presets.js";

package/dist/src/index.js

@@ -1,4 +1,5 @@
 export { createGate } from "./gate.js";
+export { explain, en } from "./explain.js";
 export { compilePolicy, KNOWN_CHECKS } from "./policy.js";
 export { presets } from "./presets.js";
 export { MemoryStore, RedisStore, SqliteStore } from "./stores.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.3.1",
+  "version": "0.4.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 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/explain.test.js test/release.test.mjs test/examples.test.mjs test/example-imports.test.mjs test/naive.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",
@@ -60,6 +60,7 @@
     "trace-svg": "npm run build && node scripts/trace-svg.mjs",
     "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"
   },
   "engines": {