@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/guardrails/progressive-yield.js

@@ -0,0 +1,237 @@
+import { canaryOpeningFrom, createCanaryScanner, promptLeakCarry, RELEASED_LOOKBACK, } from './canary.js';
+import { CANARY_HIT, promptEchoHits, runEnforcer } from './egress.js';
+import { streamPlanOf } from './egress-stream.js';
+import { TheoremError } from './error.js';
+import { promptEchoHoldFrom, promptEchoScanFrom } from './prompt-echo.js';
+import { EGRESS_RULES } from './rules.js';
+/** Default lookback under a host `egress.enforce` the gate cannot read. */
+const DEFAULT_HOLDBACK = 256;
+/**
+ * Default lookback on Live under a host policy the gate cannot read, where the
+ * held transcript holds back audio too: the shortest that shows the host no
+ * character of any egress corpus match however the transcript is chunked
+ * (88), with a margin.
+ */
+const LIVE_DEFAULT_HOLDBACK = 96;
+const PEM_BEGIN = '-----BEGIN';
+/**
+ * Fixed lookback for a host policy the gate cannot read: `holdback`, or
+ * `DEFAULT_HOLDBACK`. The canary, the prompt echo and the bundled policy need
+ * none — each holds exactly the tail that could still start a match.
+ */
+function resolveHoldback(options, exact) {
+    if (exact) {
+        if (options.holdback !== undefined) {
+            throw new TheoremError('config', 'holdback applies only to a host egress.enforce; the bundled policy holds exactly');
+        }
+        return 0;
+    }
+    return options.holdback ?? (options.enforce ? DEFAULT_HOLDBACK : 0);
+}
+function holdbackForWindow(window, base) {
+    // Incomplete PEM bodies can be large; do not release past BEGIN until END/flush.
+    const begin = window.lastIndexOf(PEM_BEGIN);
+    if (begin < 0)
+        return base;
+    const fromBegin = window.slice(begin);
+    if (/-----END (?:RSA )?PRIVATE KEY-----/.test(fromBegin))
+        return base;
+    return Math.max(base, window.length - begin);
+}
+/**
+ * The verdict for a match the stream settled: the policy's own, run on the
+ * window. The stream only ever settles a match the policy finds, so a policy
+ * that does not block here is out of step with it: blocked anyway.
+ */
+async function streamHitVerdict(enforce, hit, window, context) {
+    const verdict = await runEnforcer(enforce, { text: window }, context);
+    if ((verdict.action === 'block' || verdict.action === 'redact') && verdict.hits.length > 0) {
+        return verdict.hits;
+    }
+    return [{ rule: hit.rule, severity: hit.severity }];
+}
+/** Call `flush` when the stream ends to release the held tail. */
+function createProgressiveYieldGate(options) {
+    const { context } = options;
+    const stream = options.enforce
+        ? streamPlanOf(options.enforce)?.(context)
+        : undefined;
+    const baseHoldback = resolveHoldback(options, stream !== undefined);
+    const carry = context.canary ? (options.carry ?? '') : '';
+    let accumulated = '';
+    let emitted = 0;
+    /** The window from `emitted` on. Each piece of the reply is kept apart, so no step rereads the whole. */
+    let held = '';
+    /** The carry and the released window, as far back as the canary hold rereads. */
+    let released = carry.slice(-RELEASED_LOOKBACK);
+    /** The carry and window from where the next prompt echo scan may reach back to. */
+    let echoed = carry;
+    /** Where `echoed` starts in the carry and window. */
+    let echoedFrom = 0;
+    /**
+     * The carry and window from `openingBase` on, for the canary hold. No
+     * opening of a leak starts before `openingFrom`: a point further back than
+     * `RELEASED_LOOKBACK` that does not open one by now never will. So each
+     * step reads from there, not the whole held text.
+     */
+    let opening = carry;
+    let openingBase = 0;
+    let openingFrom = 0;
+    /** Reads the carry, then the window as it grows. */
+    const scanner = context.canary ? createCanaryScanner(context.canary) : undefined;
+    scanner?.push(carry);
+    /**
+     * The system-prompt leak hits (canary, prompt echo) in the carry and this
+     * window. The canary scan reads each character once (`createCanaryScanner`)
+     * and the echo check rereads only its own short lookback
+     * (`promptEchoScanFrom`), so a long reply costs time in proportion to its
+     * length, not its square.
+     */
+    function canaryWindowHits(fresh) {
+        const scanned = echoed.length;
+        echoed += fresh;
+        const from = promptEchoScanFrom(echoed, scanned);
+        echoed = echoed.slice(from);
+        echoedFrom += from;
+        return [
+            ...(scanner?.push(fresh) ? [CANARY_HIT] : []),
+            ...(context.privateSystem
+                ? promptEchoHits(echoed, context.privateSystem, context.canary)
+                : []),
+        ];
+    }
+    /**
+     * The host policy's hits on the window. The bundled policy reads only the
+     * new fragment (`egress-stream.ts`) and runs whole only when a match
+     * settles; a policy the gate cannot read runs whole at every step. At the
+     * end (`fragment` unset) every policy runs whole.
+     */
+    async function policyHits(window, fragment) {
+        if (!options.enforce) {
+            return null;
+        }
+        if (stream && fragment !== undefined) {
+            const hit = stream.push(fragment);
+            return hit ? await streamHitVerdict(options.enforce, hit, window, context) : null;
+        }
+        // Mid-stream the gate can only release or stop: emitted prefixes cannot be
+        // rewritten, so `redact` stops here and end-of-attempt egress applies the
+        // full verdict. `flag` is advisory and keeps the stream flowing.
+        const verdict = await runEnforcer(options.enforce, { text: window }, context);
+        if (verdict.action === 'block' || verdict.action === 'redact') {
+            return verdict.hits.length > 0
+                ? verdict.hits
+                : [{ rule: EGRESS_RULES.blocked, severity: 'high' }];
+        }
+        return null;
+    }
+    async function scan(window, fragment) {
+        // The system-prompt leak checks always run, under a host policy too: it adds
+        // checks, it never replaces these (the guardrail invariant).
+        const leaks = context.canary ? canaryWindowHits(fragment ?? '') : [];
+        if (leaks.length > 0) {
+            return leaks;
+        }
+        return await policyHits(window, fragment);
+    }
+    /** Where the leak checks hold from: a canary opening, or words a prompt echo could grow from. */
+    function leakHoldFrom() {
+        if (!context.canary) {
+            return accumulated.length;
+        }
+        const echo = context.privateSystem
+            ? echoHoldFrom(context.privateSystem, context.canary)
+            : held.length;
+        return emitted + Math.min(canaryFrom(context.canary), echo);
+    }
+    /** `canaryHoldFrom` on the held text, read from where an opening could start. */
+    function canaryFrom(canary) {
+        const shownTo = carry.length + emitted;
+        const from = Math.max(shownTo, openingFrom);
+        const lead = Math.max(openingBase, from - RELEASED_LOOKBACK);
+        let at = lead + canaryOpeningFrom(opening.slice(lead - openingBase), canary);
+        if (at < from && from > shownTo) {
+            // An opening the bound rules out: read the held text whole, and from there on.
+            opening = released + held;
+            openingBase = shownTo - released.length;
+            at = openingBase + canaryOpeningFrom(opening, canary);
+        }
+        openingFrom = Math.min(at, carry.length + accumulated.length - RELEASED_LOOKBACK);
+        const base = Math.max(openingBase, Math.max(shownTo, openingFrom) - RELEASED_LOOKBACK);
+        opening = opening.slice(base - openingBase);
+        openingBase = base;
+        return Math.max(0, at - shownTo);
+    }
+    /** `promptEchoHoldFrom` on the held text, read from its last few words. */
+    function echoHoldFrom(privateSystem, canary) {
+        // Until this window releases anything, its opening may continue the carry.
+        const lead = emitted === 0 ? carry : '';
+        const leadFrom = carry.length + emitted - lead.length;
+        const [text, from] = echoedFrom >= leadFrom ? [echoed, echoedFrom] : [lead + held, leadFrom];
+        return Math.max(0, from + promptEchoHoldFrom(text, privateSystem, canary) - carry.length - emitted);
+    }
+    /** Where the host policy holds from: exactly for the bundled one, a fixed lookback otherwise. */
+    function policyHoldFrom() {
+        if (stream) {
+            return stream.holdFrom();
+        }
+        const hold = options.enforce ? holdbackForWindow(accumulated, baseHoldback) : baseHoldback;
+        return accumulated.length - hold;
+    }
+    async function release(fragment) {
+        const hits = await scan(accumulated, fragment);
+        if (hits) {
+            return { blocked: true, hits };
+        }
+        const end = fragment === undefined ? accumulated.length : Math.min(leakHoldFrom(), policyHoldFrom());
+        const emit = take(Math.max(0, end - emitted));
+        return { blocked: false, emit };
+    }
+    /** Release the first `length` characters held. */
+    function take(length) {
+        const emit = held.slice(0, length);
+        held = held.slice(length);
+        emitted += emit.length;
+        if (context.canary)
+            released = (released + emit).slice(-RELEASED_LOOKBACK);
+        return emit;
+    }
+    return {
+        async process(fragment) {
+            if (!fragment) {
+                return { blocked: false, emit: '' };
+            }
+            accumulated += fragment;
+            held += fragment;
+            if (context.canary)
+                opening += fragment;
+            return await release(fragment);
+        },
+        async flush() {
+            return await release();
+        },
+        accumulated: () => accumulated,
+        unreleased: () => held,
+        drainUnreleased: () => take(held.length),
+        carryOut: () => context.canary
+            ? promptLeakCarry(carry + accumulated, context.canary, context.privateSystem)
+            : '',
+    };
+}
+/**
+ * Shared constructor for runTurn + Live: gate when canary and/or egress.enforce
+ * is active. `context.canary` is set only when the profile enabled canary minting.
+ */
+function createOutboundProgressiveGate(policy, context, carry) {
+    const egress = policy.egress;
+    if (!egress?.enforce && !context.canary) {
+        return null;
+    }
+    return createProgressiveYieldGate({
+        context,
+        ...(egress?.enforce ? { enforce: egress.enforce } : {}),
+        ...(egress?.holdback === undefined ? {} : { holdback: egress.holdback }),
+        ...(carry ? { carry } : {}),
+    });
+}
+export { createOutboundProgressiveGate, createProgressiveYieldGate, DEFAULT_HOLDBACK, LIVE_DEFAULT_HOLDBACK, };

package/esm/src/guardrails/prompt-echo.d.ts

@@ -0,0 +1,38 @@
+/**
+ * System-prompt echo — the leak the canary cannot see.
+ *
+ * The canary proves the token leaked; a reply that restates the system prompt
+ * while leaving the token out trips nothing. This check reads the reply for a
+ * run of `PROMPT_ECHO_WORDS` consecutive words of one private stretch of the
+ * system prompt (`BoundSystem.private`); text the host marked shareable is
+ * not read, and no run reaches across it. Words are
+ * compared case-folded after Unicode compatibility folding, punctuation and
+ * markup between them ignored, and bare numbers skipped, so reformatting a
+ * dump as a numbered or bulleted list does not hide it. Where the prompt has
+ * the canary, any one word or none continues a run: a model told to hide the
+ * canary echoes the prompt around a stand-in for it. A streamed reply holds
+ * the words an echo could still grow from (`promptEchoHoldFrom`), so none of
+ * an echo reaches the host.
+ *
+ * @module
+ */
+/** Consecutive system-prompt words that make a reply an echo of it. */
+declare const PROMPT_ECHO_WORDS = 12;
+/**
+ * Where an echo still being written could start: the first word of the
+ * longest run of words ending `text` that the system prompt also has, or the
+ * word still being written when that is earlier and could become a prompt
+ * word. Any echo that completes later starts there or after.
+ */
+declare function promptEchoHoldFrom(text: string, stretches: readonly string[], canary?: string): number;
+/** Offsets `[start, end)` of `text` that repeat a private stretch, ordered by start. */
+declare function promptEchoRanges(text: string, stretches: readonly string[], canary?: string): Array<[number, number]>;
+/** Whether `text` repeats `PROMPT_ECHO_WORDS` consecutive words of a private stretch. */
+declare function scanTextForPromptEcho(text: string, stretches: readonly string[], canary?: string): boolean;
+/**
+ * Where a scan of `text` must start when everything before `from` was
+ * already scanned clean: at the word an echo run ending past `from` could
+ * start in.
+ */
+declare function promptEchoScanFrom(text: string, from: number): number;
+export { PROMPT_ECHO_WORDS, promptEchoHoldFrom, promptEchoRanges, promptEchoScanFrom, scanTextForPromptEcho, };

package/esm/src/guardrails/prompt-echo.js

@@ -0,0 +1,225 @@
+/**
+ * System-prompt echo — the leak the canary cannot see.
+ *
+ * The canary proves the token leaked; a reply that restates the system prompt
+ * while leaving the token out trips nothing. This check reads the reply for a
+ * run of `PROMPT_ECHO_WORDS` consecutive words of one private stretch of the
+ * system prompt (`BoundSystem.private`); text the host marked shareable is
+ * not read, and no run reaches across it. Words are
+ * compared case-folded after Unicode compatibility folding, punctuation and
+ * markup between them ignored, and bare numbers skipped, so reformatting a
+ * dump as a numbered or bulleted list does not hide it. Where the prompt has
+ * the canary, any one word or none continues a run: a model told to hide the
+ * canary echoes the prompt around a stand-in for it. A streamed reply holds
+ * the words an echo could still grow from (`promptEchoHoldFrom`), so none of
+ * an echo reaches the host.
+ *
+ * @module
+ */
+/** Consecutive system-prompt words that make a reply an echo of it. */
+const PROMPT_ECHO_WORDS = 12;
+/** Words a scan rereads before new text: an echo run ending in it starts no earlier. */
+const ECHO_LOOKBACK_WORDS = PROMPT_ECHO_WORDS;
+const WORD = /[\p{L}\p{N}]+/gu;
+const WORD_CHAR = /[\p{L}\p{N}]/u;
+const NUMBER = /^\p{N}+$/u;
+const ASCII = /^\p{ASCII}*$/u;
+/** Most letters compatibility folding joins into one (a Hangul syllable from its jamo). */
+const MAX_FOLD = 3;
+/** The words a text is compared by, with the offsets each came from. */
+function echoWords(text) {
+    const words = [];
+    for (const match of text.matchAll(WORD)) {
+        const word = match[0].normalize('NFKC').toLowerCase();
+        if (!NUMBER.test(word)) {
+            words.push({ word, at: match.index, to: match.index + match[0].length });
+        }
+    }
+    return words;
+}
+/** Where the canary stood in the prompt's words: any one word or none matches it. */
+const SLOT = '\u0000';
+/**
+ * The private stretches' words as a run can repeat them: as written, with the
+ * canary left out, and with the canary as `SLOT`.
+ */
+function promptReadings(stretches, canary) {
+    const token = canary ? echoWords(canary).map((entry) => entry.word) : [];
+    const readings = { plain: [], slotted: [] };
+    for (const stretch of stretches) {
+        const words = echoWords(stretch).map((entry) => entry.word);
+        readings.plain.push(words);
+        if (token.length === 0)
+            continue;
+        const slotted = [];
+        for (let at = 0; at < words.length;) {
+            if (token.every((word, k) => words[at + k] === word)) {
+                slotted.push(SLOT);
+                at += token.length;
+            }
+            else {
+                slotted.push(words[at]);
+                at++;
+            }
+        }
+        if (!slotted.includes(SLOT))
+            continue;
+        readings.plain.push(slotted.filter((word) => word !== SLOT));
+        readings.slotted.push(slotted);
+    }
+    return readings;
+}
+/** A run with a slot, keyed by where the slot is and the words around it. */
+function slotKey(run, slot) {
+    // Bare numbers are never words here, so the slot's index leads unambiguously.
+    return [slot, ...run.filter((_, k) => k !== slot)].join(' ');
+}
+/** A run may not start on the canary's place unless `leading`: a stand-in for it is not prompt text. */
+function addRuns(set, readings, lengths, leading) {
+    for (const words of readings.plain) {
+        for (const length of lengths) {
+            for (let from = 0; from + length <= words.length; from++) {
+                set.plain.add(words.slice(from, from + length).join(' '));
+            }
+        }
+    }
+    for (const slotted of readings.slotted) {
+        for (const length of lengths) {
+            for (let from = 0; from + length <= slotted.length; from++) {
+                const run = slotted.slice(from, from + length);
+                const slot = run.indexOf(SLOT);
+                if (slot === -1 || (slot === 0 && !leading))
+                    continue;
+                set.slotted.add(slotKey(run, slot));
+                set.slots.add(slot);
+            }
+        }
+    }
+}
+/** Where in `run` the canary's place fell when `set` has it: -1 for nowhere, undefined when not a run. */
+function matchRun(set, run) {
+    if (set.plain.has(run.join(' ')))
+        return -1;
+    for (const slot of set.slots) {
+        if (slot < run.length && set.slotted.has(slotKey(run, slot)))
+            return slot;
+    }
+    return undefined;
+}
+function sameStretches(a, b) {
+    return a === b || (a.length === b.length && a.every((stretch, k) => stretch === b[k]));
+}
+let gramsCache;
+/** Every run of `PROMPT_ECHO_WORDS` words in a private stretch. */
+function promptGrams(stretches, canary) {
+    if (gramsCache &&
+        gramsCache.canary === canary &&
+        sameStretches(gramsCache.stretches, stretches)) {
+        return gramsCache.grams;
+    }
+    const grams = { plain: new Set(), slotted: new Set(), slots: new Set() };
+    addRuns(grams, promptReadings(stretches, canary), [PROMPT_ECHO_WORDS], true);
+    gramsCache = { stretches, canary, grams };
+    return grams;
+}
+let shapeCache;
+function promptShape(stretches, canary) {
+    if (shapeCache &&
+        shapeCache.canary === canary &&
+        sameStretches(shapeCache.stretches, stretches)) {
+        return shapeCache.shape;
+    }
+    const readings = promptReadings(stretches, canary);
+    const shape = {
+        runs: { plain: new Set(), slotted: new Set(), slots: new Set() },
+        prefixes: new Set(),
+        longest: 0,
+    };
+    for (const word of readings.plain.flat()) {
+        shape.longest = Math.max(shape.longest, word.length);
+        for (let end = 1; end <= word.length && ASCII.test(word.charAt(end - 1)); end++) {
+            shape.prefixes.add(word.slice(0, end));
+        }
+    }
+    addRuns(shape.runs, readings, Array.from({ length: PROMPT_ECHO_WORDS - 1 }, (_, k) => k + 1), false);
+    shapeCache = { stretches, canary, shape };
+    return shape;
+}
+/**
+ * Whether a word still being written could end as a word of the system
+ * prompt. ASCII folds letter by letter, so it must start one; other
+ * scripts can fold several letters into one (Hangul jamo, up to three), so
+ * only a word too long to fold down to any of them is ruled out.
+ */
+function mayBecomePromptWord(partial, shape) {
+    if (ASCII.test(partial)) {
+        return shape.prefixes.has(partial.toLowerCase());
+    }
+    return partial.length <= MAX_FOLD * shape.longest;
+}
+/**
+ * Where an echo still being written could start: the first word of the
+ * longest run of words ending `text` that the system prompt also has, or the
+ * word still being written when that is earlier and could become a prompt
+ * word. Any echo that completes later starts there or after.
+ */
+function promptEchoHoldFrom(text, stretches, canary) {
+    const tail = promptEchoScanFrom(text, text.length);
+    const words = echoWords(text.slice(tail));
+    let writing = text.length;
+    while (writing > 0 && WORD_CHAR.test(text.charAt(writing - 1)))
+        writing--;
+    const complete = words.filter((entry) => tail + entry.to < text.length || writing === text.length);
+    const shape = promptShape(stretches, canary);
+    const hold = mayBecomePromptWord(text.slice(writing), shape) ? writing : text.length;
+    for (let from = Math.max(0, complete.length - (PROMPT_ECHO_WORDS - 1)); from < complete.length; from++) {
+        const run = complete.slice(from).map((entry) => entry.word);
+        if (matchRun(shape.runs, run) !== undefined) {
+            return Math.min(hold, tail + complete[from].at);
+        }
+    }
+    return hold;
+}
+/** Offsets `[start, end)` of `text` that repeat a private stretch, ordered by start. */
+function promptEchoRanges(text, stretches, canary) {
+    const grams = promptGrams(stretches, canary);
+    if (!text || grams.plain.size === 0) {
+        return [];
+    }
+    const words = echoWords(text);
+    const ranges = [];
+    for (let from = 0; from + PROMPT_ECHO_WORDS <= words.length; from++) {
+        const run = words.slice(from, from + PROMPT_ECHO_WORDS).map((entry) => entry.word);
+        const slot = matchRun(grams, run);
+        if (slot === undefined)
+            continue;
+        // A stand-in for the canary at either end is the model's, not the prompt's.
+        const first = slot === 0 ? from + 1 : from;
+        const last = slot === PROMPT_ECHO_WORDS - 1 ? from + slot - 1 : from + PROMPT_ECHO_WORDS - 1;
+        ranges.push([words[first]?.at ?? 0, words[last]?.to ?? 0]);
+    }
+    return ranges;
+}
+/** Whether `text` repeats `PROMPT_ECHO_WORDS` consecutive words of a private stretch. */
+function scanTextForPromptEcho(text, stretches, canary) {
+    return promptEchoRanges(text, stretches, canary).length > 0;
+}
+/**
+ * Where a scan of `text` must start when everything before `from` was
+ * already scanned clean: at the word an echo run ending past `from` could
+ * start in.
+ */
+function promptEchoScanFrom(text, from) {
+    let at = Math.min(from, text.length);
+    for (let counted = 0; counted < ECHO_LOOKBACK_WORDS && at > 0;) {
+        while (at > 0 && !WORD_CHAR.test(text.charAt(at - 1)))
+            at--;
+        const end = at;
+        while (at > 0 && WORD_CHAR.test(text.charAt(at - 1)))
+            at--;
+        if (end > at && !NUMBER.test(text.slice(at, end)))
+            counted++;
+    }
+    return at;
+}
+export { PROMPT_ECHO_WORDS, promptEchoHoldFrom, promptEchoRanges, promptEchoScanFrom, scanTextForPromptEcho, };

package/esm/src/guardrails/quota.d.ts

@@ -0,0 +1,20 @@
+import type { Profile } from '../kernel/types.js';
+import { TheoremError } from './theorem-error.js';
+type QuotaSlotStatus = 'ok' | 'busy' | 'quota' | 'not_configured';
+/** Returns whether a local request lacks the proxy header needed for quota identity. */
+declare function skipQuota(peer: string, req: Request): boolean;
+/** Resolves the client identity, preferring Cloudflare's header for local peers. */
+declare function clientIp(peer: string, req: Request): string;
+/**
+ * Reserves one profile-and-client daily quota slot. The reservation stays busy
+ * until `releaseSlot` is called, preventing concurrent turns from overspending.
+ */
+declare function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotStatus;
+/** Releases an active quota reservation without decrementing its daily count. */
+declare function releaseSlot(profile: Profile, ip: string): void;
+/** `undefined` when the profile has no quota configured. */
+declare function quotaExhausted(profile: Profile): TheoremError | undefined;
+/** Clears all process-local quota counters; intended for tests or host resets. */
+declare function resetSlots(): void;
+export type { QuotaSlotStatus };
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/guardrails/quota.js

@@ -0,0 +1,80 @@
+import { resolveGuardrailPolicy } from './policy.js';
+import { TheoremError } from './theorem-error.js';
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+const slots = new Map();
+function utcDay(now) {
+    return new Date(now).toISOString().slice(0, 10);
+}
+function isLoopback(peer) {
+    return LOOPBACK.has(peer);
+}
+function cfConnectingIp(req) {
+    return req.headers.get('cf-connecting-ip')?.trim() ?? '';
+}
+function slotKey(profileId, ip) {
+    return `${profileId}:${ip}`;
+}
+/** Returns whether a local request lacks the proxy header needed for quota identity. */
+function skipQuota(peer, req) {
+    return isLoopback(peer) && !cfConnectingIp(req);
+}
+/** Resolves the client identity, preferring Cloudflare's header for local peers. */
+function clientIp(peer, req) {
+    if (isLoopback(peer)) {
+        const cf = cfConnectingIp(req);
+        if (cf) {
+            return cf;
+        }
+    }
+    if (peer) {
+        return peer;
+    }
+    return 'unknown';
+}
+/**
+ * Reserves one profile-and-client daily quota slot. The reservation stays busy
+ * until `releaseSlot` is called, preventing concurrent turns from overspending.
+ */
+function takeSlot(profile, ip, now) {
+    const quota = resolveGuardrailPolicy(profile.guardrails).quota;
+    if (!quota) {
+        return 'not_configured';
+    }
+    const day = utcDay(now);
+    const key = slotKey(profile.id, ip);
+    let slot = slots.get(key);
+    if (!slot || slot.day !== day) {
+        slot = { day, count: 0, busy: false };
+        slots.set(key, slot);
+    }
+    if (slot.busy) {
+        return 'busy';
+    }
+    if (slot.count >= quota.perDay) {
+        return 'quota';
+    }
+    slot.busy = true;
+    slot.count += 1;
+    return 'ok';
+}
+/** Releases an active quota reservation without decrementing its daily count. */
+function releaseSlot(profile, ip) {
+    const slot = slots.get(slotKey(profile.id, ip));
+    if (slot) {
+        slot.busy = false;
+    }
+}
+/** `undefined` when the profile has no quota configured. */
+function quotaExhausted(profile) {
+    const quota = resolveGuardrailPolicy(profile.guardrails).quota;
+    if (!quota) {
+        return undefined;
+    }
+    return new TheoremError('rate_limit', `${profile.id} used its daily quota of ${quota.perDay} turns`, // lexicon-exempt: internal diagnostic; the user reads the copy key
+    { copy: { key: 'quota.exhausted', params: { perDay: quota.perDay } } });
+}
+/** Clears all process-local quota counters; intended for tests or host resets. */
+function resetSlots() {
+    slots.clear();
+}
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/guardrails/rules.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Every rule id Theorem's own guardrails report, in one place. The trace
+ * catalog describes each one, and its description map is keyed by
+ * {@link GuardrailRule}, so a new id fails typecheck until it is described.
+ * A host's egress `enforce` hook may report ids of its own; those are not here.
+ *
+ * @module
+ */
+/** Injection phrasing or sensitive data stripped from text entering the turn. */
+export declare const SANITIZE_RULES: {
+    readonly injection: "sanitize.injection";
+    readonly sensitive: "sanitize.sensitive";
+};
+/** What the bundled egress policy finds in the model's outbound text. */
+export declare const EGRESS_RULES: {
+    readonly canary: "egress.canary-leak";
+    /** The reply repeats the system prompt (`guardrails.promptEcho`). */
+    readonly promptEcho: "egress.prompt-echo";
+    /**
+     * A provider-side built-in tool carried the canary or the system prompt. It
+     * ran before Theorem saw it: the data already left, so this is an incident.
+     */
+    readonly providerToolLeak: "egress.provider-tool-leak";
+    readonly sensitive: "egress.sensitive-echo";
+    readonly boundary: "egress.system-boundary";
+    readonly injection: "egress.injection-echo";
+    /** An image loads a URL the model was not given, from a host not allowed. */
+    readonly image: "egress.image-exfil";
+    /** A link goes to a URL the model was not given, on a host not allowed. */
+    readonly link: "egress.link-exfil";
+    /** Payload could not be rendered for inspection — released output is unverified. */
+    readonly unscannable: "egress.unscannable";
+    readonly enforcerError: "egress.enforcer-error";
+    /** The progressive gate stopped the stream on a host verdict that named no rule. */
+    readonly blocked: "egress.blocked";
+};
+/** Remote tool content behaving like an instruction to the agent. */
+export declare const DIRECTIVE_RULES: {
+    readonly toolName: "tool_result.names-callable-tool";
+    readonly imperative: "tool_result.imperative";
+    readonly authority: "tool_result.authority-claim";
+};
+/** The tool boundary: results and failures redacted, and calls flagged or blocked. */
+export declare const TOOL_RULES: {
+    readonly resultRedacted: "tool_result.redacted";
+    readonly failureRedacted: "tool_failure.redacted";
+    readonly sensitiveArgument: "tool_call.sensitive-argument";
+    readonly taintedTurn: "tool_call.tainted-turn";
+    readonly steeredTurn: "tool_call.steered-turn";
+};
+/** A tool's network target refused before any request was made. */
+export declare const NETWORK_RULES: {
+    readonly blocked: "network.blocked";
+};
+/** A rule id Theorem's own guardrails report. */
+export type GuardrailRule = (typeof SANITIZE_RULES)[keyof typeof SANITIZE_RULES] | (typeof EGRESS_RULES)[keyof typeof EGRESS_RULES] | (typeof DIRECTIVE_RULES)[keyof typeof DIRECTIVE_RULES] | (typeof TOOL_RULES)[keyof typeof TOOL_RULES] | (typeof NETWORK_RULES)[keyof typeof NETWORK_RULES];