@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/guardrails/egress.js

@@ -1,29 +1,15 @@
-import { isRecord } from '../kernel/util/record.js';
-import { guardedEventTexts, scanTextForCanaryLeak } from './canary.js';
+import { canaryNoteMarker, guardedEventTexts, scanTextForCanaryLeak } from './canary.js';
 import { SYSTEM_BOUNDARY } from './egress-patterns.js';
-import { imageLeakSpans, linkLeakSpans } from './egress-urls.js';
-import { describeError } from './error.js';
-import { hitFromSpan } from './hits.js';
-import { injectionSpans } from './injection.js';
-import { lexiconText } from './lexicon.js';
+import { CANARY_HIT, PROMPT_ECHO_HIT } from './hits.js';
 import { scanTextForPromptEcho } from './prompt-echo.js';
-import { EGRESS_RULES } from './rules.js';
-import { anySensitive, resolveSensitive, SENSITIVE_GROUPS, sensitiveSpans, } from './sensitive.js';
-import { textForScan } from './serialize.js';
-import { SEVERITIES } from './types.js';
-function hitsFromSpans(text, spans, rule, severity) {
-    return spans.map((span) => hitFromSpan(text, span, rule, severity));
-}
+import { DETECT_RULES, EGRESS_RULES } from './rules.js';
 /** Why a reply was withheld, for the builder (`errorInternal`); the user reads `error.safety`. */
 const WITHHELD_REASON = {
     canary: 'canary leaked',
-    promptEcho: 'system prompt echoed', // lexicon-exempt: internal diagnostic — the user reads error.safety
-    providerToolLeak: 'a provider-side tool already sent the canary or system prompt', // lexicon-exempt: internal diagnostic — the user reads error.safety
-    egress: 'Turn withheld: egress disclosure violation', // lexicon-exempt: internal diagnostic — the user reads error.safety
+    promptEcho: 'system prompt echoed', // labels-exempt: internal diagnostic — the user reads error.safety
+    providerToolLeak: 'a provider-side tool already sent the canary or system prompt', // labels-exempt: internal diagnostic — the user reads error.safety
+    egress: 'Turn withheld: egress disclosure violation', // labels-exempt: internal diagnostic — the user reads error.safety
 };
-/** Never carries the live token, only a placeholder. */
-const CANARY_HIT = { rule: EGRESS_RULES.canary, severity: 'high', match: '[canary]' };
-const PROMPT_ECHO_HIT = { rule: EGRESS_RULES.promptEcho, severity: 'high' };
 function canaryHits(text, canary) {
     return canary && scanTextForCanaryLeak(text, canary) ? [CANARY_HIT] : [];
 }
@@ -33,9 +19,13 @@ function promptEchoHits(text, privateSystem, canary) {
         ? [PROMPT_ECHO_HIT]
         : [];
 }
-/** The system-prompt leak hits: the canary, and the prompt's own words when guarded. */
-function promptLeakHits(text, canary, privateSystem) {
-    return [...canaryHits(text, canary), ...promptEchoHits(text, privateSystem, canary)];
+/** The system-prompt leak hits: the canary unless it was given, and the prompt's own words when guarded. */
+function promptLeakHits(text, scope) {
+    const { canary, canaryGiven, privateSystem } = scope;
+    return [
+        ...canaryHits(text, canaryGiven ? undefined : canary),
+        ...promptEchoHits(text, privateSystem, canary),
+    ];
 }
 const PROVIDER_TOOL_LEAK_HIT = {
     rule: EGRESS_RULES.providerToolLeak,
@@ -61,19 +51,50 @@ function isProviderToolReport(event) {
  * (`guardedEventTexts`). In the report of a provider-side tool they are one
  * `egress.provider-tool-leak`: the call already ran.
  */
-function eventPromptLeakHits(event, canary, privateSystem) {
-    const hits = guardedEventTexts(event).flatMap((text) => promptLeakHits(text, canary, privateSystem));
+function eventPromptLeakHits(event, scope) {
+    const hits = guardedEventTexts(event).flatMap((text) => promptLeakHits(text, scope));
     if (hits.length > 0 && isProviderToolReport(event)) {
         return [PROVIDER_TOOL_LEAK_HIT];
     }
     return [...new Map(hits.map((hit) => [hit.rule, hit])).values()];
 }
+/**
+ * What the detectors of what is ours find in an event's host content
+ * (`guardedEventTexts`) under their actions at `boundary`, as the event goes
+ * to the host with the reply. `flag` reports it; `redact` and `block` stop the
+ * turn, as an event has no text to replace. The report of a provider-side tool
+ * is read whatever the actions are and always stops: the call already ran.
+ */
+function eventLeak(event, scope, detect, boundary) {
+    if (isProviderToolReport(event)) {
+        const hits = eventPromptLeakHits(event, scope);
+        return hits.length > 0 ? { stop: true, hits } : undefined;
+    }
+    const texts = guardedEventTexts(event);
+    const found = [];
+    const canary = scope.canaryGiven ? undefined : scope.canary;
+    const canaryAction = detect.canary_leak[boundary];
+    if (canaryAction !== 'ignore' && texts.some((text) => canaryHits(text, canary).length > 0)) {
+        found.push([canaryAction, CANARY_HIT]);
+    }
+    const promptAction = detect.prompt_leak[boundary];
+    if (promptAction !== 'ignore' &&
+        texts.some((text) => promptEchoHits(text, scope.privateSystem, scope.canary).length > 0)) {
+        found.push([promptAction, PROMPT_ECHO_HIT]);
+    }
+    if (found.length === 0)
+        return undefined;
+    return {
+        stop: found.some(([action]) => action !== 'flag'),
+        hits: found.map(([, hit]) => hit),
+    };
+}
 const PROMPT_LEAK_RULES = new Set([
-    EGRESS_RULES.canary,
-    EGRESS_RULES.promptEcho,
+    DETECT_RULES.canary_leak,
+    DETECT_RULES.prompt_leak,
     EGRESS_RULES.providerToolLeak,
 ]);
-/** Whether a hit is a system-prompt leak: a hard stop under any host policy. */
+/** Whether a hit is a system-prompt leak. */
 function isPromptLeakHit(hit) {
     return PROMPT_LEAK_RULES.has(hit.rule);
 }
@@ -82,293 +103,22 @@ function promptLeakReason(hits) {
     if (hits.some((hit) => hit.rule === EGRESS_RULES.providerToolLeak)) {
         return WITHHELD_REASON.providerToolLeak;
     }
-    return hits.some((hit) => hit.rule === EGRESS_RULES.canary)
+    return hits.some((hit) => hit.rule === DETECT_RULES.canary_leak)
         ? WITHHELD_REASON.canary
         : WITHHELD_REASON.promptEcho;
 }
-const EGRESS_SENSITIVE_DEFAULT = {
-    ids: true,
-    financial: true,
-    network: false,
-    credentials: true,
-};
-function resolveUrlCheck(check, byDefault) {
-    if (check === undefined)
-        return byDefault ? {} : undefined;
-    if (typeof check === 'boolean')
-        return check ? {} : undefined;
-    return check;
-}
-function resolveEgressChecks(checks = {}) {
-    const images = resolveUrlCheck(checks.images, true);
-    const resolved = resolveUrlCheck(checks.links, false);
-    // A host images load from already takes data with no click, so a link there opens nothing new.
-    const links = resolved && images?.hosts
-        ? { ...resolved, hosts: [...new Set([...(resolved.hosts ?? []), ...images.hosts])] }
-        : resolved;
-    return {
-        sensitive: resolveSensitive(checks.sensitive, EGRESS_SENSITIVE_DEFAULT),
-        boundary: checks.boundary ?? true,
-        injection: checks.injection ?? true,
-        ...(images ? { images } : {}),
-        ...(links ? { links } : {}),
-    };
-}
-/** Every check off: the system-prompt leak checks alone. */
-const NO_CHECKS = resolveEgressChecks({
-    sensitive: false,
-    boundary: false,
-    injection: false,
-    images: false,
-});
-const DEFAULT_CHECKS = resolveEgressChecks();
-function urlScope(check, given) {
-    return { ...check, ...(given ? { given } : {}) };
-}
-/** The bundled policy's hits in `text`, from the checks `checks` runs. */
-function collectEgressHits(text, scope = {}, checks = DEFAULT_CHECKS) {
-    const hits = promptLeakHits(text, scope.canary, scope.privateSystem);
-    if (anySensitive(checks.sensitive)) {
-        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        hits.push(...hitsFromSpans(text, sensitiveSpans(text, checks.sensitive), EGRESS_RULES.sensitive, 'high'));
-    }
-    const boundary = checks.boundary ? SYSTEM_BOUNDARY.exec(text) : null;
-    if (boundary && boundary.index !== undefined) {
-        hits.push(hitFromSpan(text, { start: boundary.index, end: boundary.index + boundary[0].length }, EGRESS_RULES.boundary, 'medium'));
-    }
-    if (checks.injection) {
-        hits.push(...hitsFromSpans(text, injectionSpans(text), EGRESS_RULES.injection, 'medium')); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    }
-    if (checks.images) {
-        const spans = imageLeakSpans(text, urlScope(checks.images, scope.given));
-        hits.push(...hitsFromSpans(text, spans, EGRESS_RULES.image, 'high'));
-    }
-    if (checks.links) {
-        const spans = linkLeakSpans(text, urlScope(checks.links, scope.given), Boolean(checks.images));
-        hits.push(...hitsFromSpans(text, spans, EGRESS_RULES.link, 'high'));
-    }
-    return hits;
-}
+/** The distinct rule names among the hits. */
 function hitRules(hits) {
     return [...new Set(hits.map((hit) => hit.rule))];
 }
-function isGuardrailHit(value) {
-    if (!isRecord(value) ||
-        typeof value.rule !== 'string' ||
-        !value.rule.trim() ||
-        !SEVERITIES.includes(value.severity)) {
-        return false;
-    }
-    for (const key of ['match', 'label', 'doc']) {
-        if (value[key] !== undefined && typeof value[key] !== 'string')
-            return false;
-    }
-    if (value.span !== undefined) {
-        if (!isRecord(value.span) ||
-            typeof value.span.start !== 'number' ||
-            !Number.isFinite(value.span.start) ||
-            typeof value.span.end !== 'number' ||
-            !Number.isFinite(value.span.end)) {
-            return false;
-        }
-    }
-    return true;
-}
-function isGuardrailHits(value) {
-    return Array.isArray(value) && value.every(isGuardrailHit);
-}
-function isVerdict(value) {
-    if (!isRecord(value))
-        return false;
-    switch (value.action) {
-        case 'allow':
-            return true;
-        case 'redact':
-            return typeof value.text === 'string' && isGuardrailHits(value.hits);
-        case 'flag':
-            return isGuardrailHits(value.hits);
-        case 'block':
-            return (isGuardrailHits(value.hits) &&
-                typeof value.rejection === 'string' &&
-                (value.errorInternal === undefined || typeof value.errorInternal === 'string'));
-        default:
-            return false;
-    }
-}
-function legacyHits(value) {
-    if (!Array.isArray(value)) {
-        return [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }];
-    }
-    const hits = value
-        .map((hit) => {
-        if (typeof hit === 'string' && hit.trim()) {
-            return { rule: hit, severity: 'high' };
-        }
-        if (isRecord(hit) && typeof hit.rule === 'string' && hit.rule.trim()) {
-            const severity = SEVERITIES.includes(hit.severity)
-                ? hit.severity
-                : 'high';
-            return {
-                rule: hit.rule,
-                severity,
-                ...(typeof hit.label === 'string' ? { label: hit.label } : {}),
-                ...(typeof hit.doc === 'string' ? { doc: hit.doc } : {}),
-            };
-        }
-        return undefined;
-    })
-        .filter((hit) => Boolean(hit));
-    return hits.length ? hits : [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }];
-}
-function normalizeVerdict(value, context) {
-    if (isVerdict(value)) {
-        return value;
-    }
-    if (isRecord(value) && typeof value.blocked === 'boolean') {
-        if (!value.blocked) {
-            return { action: 'allow' };
-        }
-        const hits = legacyHits(value.hits);
-        const rejection = typeof value.rejectionMessage === 'string' && value.rejectionMessage.trim()
-            ? value.rejectionMessage
-            : lexiconText('egress.rejection', { rules: hitRules(hits).join(', ') }, context.lexicon);
-        return { action: 'block', hits, rejection };
-    }
-    return {
-        action: 'block',
-        hits: [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }],
-        rejection: lexiconText('egress.invalid_verdict', {}, context.lexicon),
-    };
-}
-/** An enforce that blocks on `collect`'s hits in the reply and in any structured output. */
-function hitsEnforcer(collect) {
-    return (payload, context) => {
-        const hits = collect(payload.text, context);
-        if (payload.structured !== undefined) {
-            const structured = textForScan(payload.structured);
-            if (structured.unscannable) {
-                // Cannot inspect it, so cannot vouch for it. Fail closed.
-                hits.push({ rule: EGRESS_RULES.unscannable, severity: 'high' }); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            }
-            else {
-                hits.push(...collect(structured.text, context));
-            }
-        }
-        if (hits.length === 0) {
-            return { action: 'allow' };
-        }
-        return {
-            action: 'block',
-            hits,
-            rejection: lexiconText('egress.rejection', { rules: hitRules(hits).join(', ') }, context.lexicon),
-        };
-    };
-}
-/** What the bundled policy reads from a gate's context. */
-function egressScope(context) {
-    return {
-        ...(context.canary ? { canary: context.canary } : {}),
-        ...(context.privateSystem ? { privateSystem: context.privateSystem } : {}),
-        ...(context.givenUrls ? { given: context.givenUrls } : {}),
-    };
-}
-/** Default egress enforce: every bundled check at its default (`EgressChecks`). */
-const standardEgressEnforce = hitsEnforcer((text, context) => collectEgressHits(text, egressScope(context)));
-/** The bundled checks each enforce runs, for the enforces built from them. */
-const KNOWN_CHECKS = new WeakMap([
-    [standardEgressEnforce, DEFAULT_CHECKS],
-]);
-function registerEgressChecks(enforce, checks) {
-    KNOWN_CHECKS.set(enforce, checks);
-}
-/** The bundled checks `enforce` runs; undefined for a host enforce, whose checks are its own. */
-function egressChecksOf(enforce) {
-    return enforce && KNOWN_CHECKS.get(enforce);
-}
-const CHECK_NAMES = new Set(['sensitive', 'boundary', 'injection', 'images', 'links']);
-const URL_CHECK_NAMES = new Set(['hosts', 'fromTools']);
-const GROUP_NAMES = new Set(SENSITIVE_GROUPS);
-/** A hostname is all a URL check's host is: a scheme, port or path would never match one. */
-function urlCheckProblem(path, check) {
-    if (check === undefined || typeof check === 'boolean')
-        return undefined;
-    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    if (typeof check !== 'object' || check === null)
-        return `${path} must be a boolean or an object`;
-    const unknown = Object.keys(check).find((key) => !URL_CHECK_NAMES.has(key));
-    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    if (unknown !== undefined)
-        return `${path} has no option ${JSON.stringify(unknown)}`;
-    const { hosts, fromTools } = check;
-    if (fromTools !== undefined && typeof fromTools !== 'boolean') {
-        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        return `${path}.fromTools must be a boolean`;
-    }
-    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    if (hosts !== undefined && !Array.isArray(hosts))
-        return `${path}.hosts must be a list`;
-    const bad = (hosts ?? []).find((host) => typeof host !== 'string' || !/^[a-z0-9.-]+$/i.test(host) || host.startsWith('.'));
-    return bad === undefined
-        ? undefined
-        : // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            `${path}.hosts lists ${JSON.stringify(bad)}, which is not a hostname`;
-}
-/** A misspelt check or group would leave the check it meant at its default, silently. */
-function egressChecksProblem(path, checks) {
-    if (typeof checks === 'boolean')
-        return undefined;
-    if (typeof checks !== 'object' || checks === null)
-        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        return `${path} must be a boolean or an object`;
-    const unknown = Object.keys(checks).find((key) => !CHECK_NAMES.has(key));
-    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    if (unknown !== undefined)
-        return `${path} has no check ${JSON.stringify(unknown)}`;
-    const { sensitive, boundary, injection, images, links } = checks;
-    for (const [name, value] of [
-        ['boundary', boundary],
-        ['injection', injection],
-    ]) {
-        if (value !== undefined && typeof value !== 'boolean')
-            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            return `${path}.${name} must be a boolean`;
-    }
-    if (sensitive !== undefined && typeof sensitive !== 'boolean') {
-        if (typeof sensitive !== 'object' || sensitive === null) {
-            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            return `${path}.sensitive must be a boolean or an object`;
-        }
-        const unknownGroup = Object.keys(sensitive).find((group) => !GROUP_NAMES.has(group));
-        if (unknownGroup !== undefined) {
-            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            return `${path}.sensitive has no group ${JSON.stringify(unknownGroup)} (${SENSITIVE_GROUPS.join(', ')})`;
-        }
-        const bad = Object.entries(sensitive).find(([, on]) => typeof on !== 'boolean');
-        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        if (bad !== undefined)
-            return `${path}.sensitive.${bad[0]} must be a boolean`;
-    }
-    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    return urlCheckProblem(`${path}.images`, images) ?? urlCheckProblem(`${path}.links`, links);
-}
 /**
- * A policy that throws has reached no decision, so it cannot vouch for the output:
- * the failure becomes a `block`, not a pass. The turn then follows the profile's
- * ordinary `onBlock` handling instead of surfacing a raw host stack trace. The
- * thrown message may carry host internals, so it goes to the builder only
- * (`errorInternal`); the model reads the lexicon's `egress.policy_failed`.
+ * The words of the canary note a turn binds, when the profile's labels
+ * rewords it so that `SYSTEM_BOUNDARY` no longer reads them.
  */
-async function runEnforcer(enforce, payload, context) {
-    try {
-        return normalizeVerdict(await enforce(payload, context), context);
-    }
-    catch (err) {
-        return {
-            action: 'block',
-            hits: [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }],
-            rejection: lexiconText('egress.policy_failed', {}, context.lexicon),
-            errorInternal: describeError(err),
-        };
-    }
+function boundaryNote({ canary, labels, }) {
+    if (!canary)
+        return undefined;
+    const marker = canaryNoteMarker(labels);
+    return marker && !SYSTEM_BOUNDARY.test(marker) ? marker : undefined;
 }
-export { CANARY_HIT, collectEgressHits, DEFAULT_CHECKS, egressChecksOf, egressChecksProblem, egressScope, eventPromptLeakHits, hitRules, hitsEnforcer, isPromptLeakHit, NO_CHECKS, PROMPT_ECHO_HIT, promptEchoHits, promptLeakReason, registerEgressChecks, resolveEgressChecks, runEnforcer, standardEgressEnforce, WITHHELD_REASON, };
+export { boundaryNote, eventLeak, eventPromptLeakHits, hitRules, isPromptLeakHit, promptEchoHits, promptLeakReason, WITHHELD_REASON, };

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

@@ -1,26 +1,31 @@
 import type { TurnEventOf } from '../kernel/turn-events.js';
 import type { TurnEvent } from '../kernel/types.js';
-import { type LexiconOverrides } from './lexicon.js';
-import { type ErrorKind, TheoremError } from './theorem-error.js';
+import { type LabelOverrides } from './labels.js';
+import { type ErrorCopies, type ErrorKind, TheoremError } from './theorem-error.js';
+/** True when the value is an error named `AbortError`. */
 declare function isAbortError(err: unknown): boolean;
 /** `AbortSignal.timeout` rejects with a `TimeoutError`, not an `AbortError`. */
 declare function isTimeoutError(err: unknown): boolean;
+/** Throws when the signal has aborted: its framework, abort or timeout reason, else an `AbortError`. */
 declare function throwIfAborted(signal?: AbortSignal): void;
 /** Anything that is not a `TheoremError` or an abort escaped every boundary that names kinds: a THEOREM bug. */
 declare function errorKind(err: unknown): ErrorKind;
+/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 429 `rate_limit`; 503 and 529 (overloaded) `busy`; 500 and above `unavailable`; the rest `unsupported`. */
 declare function kindOfHttpStatus(status: number): ErrorKind;
-/** Pass the profile's `lexicon`, or the profile's wording is skipped. */
-declare function publicError(err: unknown, lexicon?: LexiconOverrides): string;
-/** Raw diagnostic for hosts, traces and logs; never shown to end users. */
+/** The named reasons an error carries, one line each, in the profile's wording. */
+declare function errorCopyText(copy: ErrorCopies, labels?: LabelOverrides): string;
+/** Pass the profile's `labels`, or the profile's wording is skipped. */
+declare function publicError(err: unknown, labels?: LabelOverrides): string;
+/** Raw diagnostic for hosts, traces, and logs; never shown to end users. */
 declare function describeError(err: unknown): string;
 type ProducedError = TurnEventOf<'error'> & {
     errorInternal: string;
 };
-/** No user wording yet: `withPublicWording` adds it where the event reaches the host, the one place that knows the profile. */
+/** No user wording yet: `withPublicLabels` adds it where the event reaches the host, the one place that knows the profile. */
 declare function toErrorEvent(err: unknown): ProducedError;
 /** Wording already set (host copy) is kept. */
-declare function withPublicWording(event: TurnEvent, lexicon?: LexiconOverrides): TurnEvent;
+declare function withPublicLabels(event: TurnEvent, labels?: LabelOverrides): TurnEvent;
 export type { ErrorCopies, ErrorCopy, ErrorKind, TheoremErrorOptions } from './theorem-error.js';
 export { ERROR_KINDS } from './theorem-error.js';
 export type { ProducedError };
-export { describeError, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicWording, };
+export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };

package/esm/src/guardrails/error.js

@@ -1,5 +1,6 @@
-import { lexiconText } from './lexicon.js';
+import { labelText } from './labels.js';
 import { TheoremError } from './theorem-error.js';
+/** True when the value is an error named `AbortError`. */
 function isAbortError(err) {
     return errorName(err) === 'AbortError';
 }
@@ -10,15 +11,16 @@ function isTimeoutError(err) {
 function errorName(err) {
     return err && typeof err === 'object' ? err.name : undefined;
 }
+/** Throws when the signal has aborted: its framework, abort or timeout reason, else an `AbortError`. */
 function throwIfAborted(signal) {
     if (!signal?.aborted) {
         return;
     }
     const { reason } = signal;
-    if (isAbortError(reason) || isTimeoutError(reason)) {
+    if (reason instanceof TheoremError || isAbortError(reason) || isTimeoutError(reason)) {
         throw reason;
     }
-    throw new DOMException('The operation was aborted.', 'AbortError'); // lexicon-exempt: DOM AbortError fingerprint
+    throw new DOMException('The operation was aborted.', 'AbortError'); // labels-exempt: DOM AbortError fingerprint
 }
 /** Anything that is not a `TheoremError` or an abort escaped every boundary that names kinds: a THEOREM bug. */
 function errorKind(err) {
@@ -30,6 +32,7 @@ function errorKind(err) {
         return 'cancelled';
     return 'internal';
 }
+/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 429 `rate_limit`; 503 and 529 (overloaded) `busy`; 500 and above `unavailable`; the rest `unsupported`. */
 function kindOfHttpStatus(status) {
     if (status === 401 || status === 402 || status === 403)
         return 'auth';
@@ -37,24 +40,28 @@ function kindOfHttpStatus(status) {
         return 'timeout';
     if (status === 429)
         return 'rate_limit';
+    if (status === 503 || status === 529)
+        return 'busy';
     if (status >= 500)
         return 'unavailable';
     return 'unsupported';
 }
-function kindText(kind, lexicon, params) {
-    return lexiconText(`error.${kind}`, params, lexicon);
+function kindText(kind, labels, params) {
+    return labelText(`error.${kind}`, params, labels);
 }
-function wording(kind, copy, lexicon) {
-    if (!copy)
-        return kindText(kind, lexicon);
+function wording(kind, copy, labels) {
+    return copy ? errorCopyText(copy, labels) : kindText(kind, labels);
+}
+/** The named reasons an error carries, one line each, in the profile's wording. */
+function errorCopyText(copy, labels) {
     const lines = 'key' in copy ? [copy] : copy;
-    return lines.map((line) => lexiconText(line.key, line.params, lexicon)).join('\n');
+    return lines.map((line) => labelText(line.key, line.params, labels)).join('\n');
 }
-/** Pass the profile's `lexicon`, or the profile's wording is skipped. */
-function publicError(err, lexicon) {
-    return wording(errorKind(err), err instanceof TheoremError ? err.copy : undefined, lexicon);
+/** Pass the profile's `labels`, or the profile's wording is skipped. */
+function publicError(err, labels) {
+    return wording(errorKind(err), err instanceof TheoremError ? err.copy : undefined, labels);
 }
-/** Raw diagnostic for hosts, traces and logs; never shown to end users. */
+/** Raw diagnostic for hosts, traces, and logs; never shown to end users. */
 function describeError(err) {
     if (typeof err === 'string') {
         return err;
@@ -64,7 +71,7 @@ function describeError(err) {
     }
     return String(err);
 }
-/** No user wording yet: `withPublicWording` adds it where the event reaches the host, the one place that knows the profile. */
+/** No user wording yet: `withPublicLabels` adds it where the event reaches the host, the one place that knows the profile. */
 function toErrorEvent(err) {
     return {
         type: 'error',
@@ -74,18 +81,18 @@ function toErrorEvent(err) {
     };
 }
 /** Wording already set (host copy) is kept. */
-function withPublicWording(event, lexicon) {
+function withPublicLabels(event, labels) {
     if (event.type === 'error' && event.error === undefined) {
-        return { ...event, error: wording(event.errorKind, event.errorCopy, lexicon) };
+        return { ...event, error: wording(event.errorKind, event.errorCopy, labels) };
     }
     if (event.type === 'tool' &&
         event.tool.phase === 'error' &&
         event.tool.failure.error === undefined) {
         const { tool } = event;
-        const error = kindText(tool.failure.kind, lexicon, { tool: tool.name });
+        const error = kindText(tool.failure.kind, labels, { tool: tool.name });
         return { ...event, tool: { ...tool, failure: { ...tool.failure, error } } };
     }
     return event;
 }
 export { ERROR_KINDS } from './theorem-error.js';
-export { describeError, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicWording, };
+export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };

package/esm/src/guardrails/event-schemas.d.ts

@@ -1,15 +1,18 @@
 import { z } from 'zod';
-import { type LexiconKey } from './lexicon.js';
+import { type Boundary } from './boundaries.js';
+import { type LabelKey } from './labels.js';
 import { type ErrorKind } from './theorem-error.js';
 import { type GuardrailAction, type GuardrailStage, type Severity, type ToolOrigin, type TrustLevel } from './types.js';
+/** The schema an error kind parses against. */
 export declare const errorKindSchema: z.ZodType<ErrorKind>;
-/** Wording for the user more specific than its kind's: a lexicon key and its parameters. */
+/** Wording for the user more specific than its kind's: a label key and its parameters. */
 export interface ErrorCopy {
-    key: LexiconKey;
+    key: LabelKey;
     params?: Record<string, string | number>;
 }
 /** One line of wording, or one per problem found. */
 export type ErrorCopies = ErrorCopy | readonly ErrorCopy[];
+/** The schema error wording parses against. */
 export declare const errorCopiesSchema: z.ZodType<ErrorCopies>;
 /**
  * `depth` is hops from the user's turn: a direct tool call is 1; a tool result
@@ -22,6 +25,18 @@ export interface Provenance {
     tool: string;
     depth: number;
 }
+export declare const provenance: z.ZodObject<{
+    origin: z.ZodEnum<{
+        http: "http";
+        mcp: "mcp";
+        builtin: "builtin";
+        local: "local";
+        delegated: "delegated";
+    }>;
+    tool: z.ZodString;
+    depth: z.ZodNumber;
+}, z.core.$strip>;
+/** One rule match: the rule id, its severity, where it matched and, when kept, the matched text. */
 export interface GuardrailHit {
     /** Stable rule id, e.g. `egress.canary-leak`. */
     rule: string;
@@ -40,13 +55,40 @@ export interface GuardrailHit {
     label?: string;
     /** Why a match matters, in a sentence, for a host's own rule. */
     doc?: string;
+    /** The name of the host's pattern that matched; unset for a match of Theorem's own patterns. */
+    pattern?: string;
+    /**
+     * What about the match made it one, for `tool_instructions`: `override`, `tool_name`, `order`
+     * or `authority`. For a host's `find` that failed, how: `find_threw` or `find_result`.
+     */
+    signal?: string;
 }
+export declare const guardrailHit: z.ZodObject<{
+    rule: z.ZodString;
+    severity: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        info: "info";
+    }>;
+    span: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strip>>;
+    match: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    doc: z.ZodOptional<z.ZodString>;
+    pattern: z.ZodOptional<z.ZodString>;
+    signal: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /**
  * Matched text rides only under `observability.include.guardrailMatchPreview`, so by default a
  * trace sink can count and locate hits without becoming a second copy of the secret.
  */
 export interface GuardrailEvent {
     stage: GuardrailStage;
+    /** Where the text was crossing, when a detector read it there. */
+    boundary?: Boundary;
     trust: TrustLevel;
     action: GuardrailAction;
     hits: GuardrailHit[];
@@ -54,4 +96,5 @@ export interface GuardrailEvent {
     /** The block verdict's `errorInternal`: builder-only, stripped by `forClient`. */
     errorInternal?: string;
 }
+/** The schema a guardrail event parses against. */
 export declare const guardrailEventSchema: z.ZodType<GuardrailEvent>;