theorum 1.0.0 → 1.1.3

package/esm/src/guardrails/egress.js

@@ -4,33 +4,84 @@
  * @module
  */
 import { scanTextForCanaryLeak } from './canary.js';
+import { hitFromSpan } from './hits.js';
 import { injectionSpans } from './injection.js';
 import { sensitiveSpans } from './sensitive.js';
-const SYSTEM_BOUNDARY = /This turn's canary is|<\/?user_data>|Untrusted user content is inside/i;
-/** Default egress enforce — canary leak, sensitive echo, fence markers, injection echo. */
-function standardEgressEnforce(context) {
-    const { text, canary } = context;
+import { textForScan } from './serialize.js';
+const SYSTEM_BOUNDARY = /This turn's canary is|<\/?user_data>/i; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+/** Rule ids emitted by the bundled outbound policy. */
+export const EGRESS_RULES = {
+    canary: 'egress.canary-leak',
+    sensitive: 'egress.sensitive-echo',
+    boundary: 'egress.system-boundary',
+    injection: 'egress.injection-echo', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    /** Payload could not be rendered for inspection — released output is unverified. */
+    unscannable: 'egress.unscannable', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    /** The host policy threw instead of returning a verdict. */
+    enforcerError: 'egress.enforcer-error', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+};
+function hitsFromSpans(text, spans, rule, severity) {
+    return spans.map((span) => hitFromSpan(text, span, rule, severity));
+}
+/** Hits from the bundled outbound policy (canary / sensitive / boundary / injection). */
+function collectEgressHits(text, canary) {
     const hits = [];
     if (canary && scanTextForCanaryLeak(text, canary)) {
-        hits.push('canary');
+        // Never put the live canary token into match — placeholder only.
+        hits.push({ rule: EGRESS_RULES.canary, severity: 'high', match: '[canary]' });
+    }
+    hits.push(...hitsFromSpans(text, sensitiveSpans(text), EGRESS_RULES.sensitive, 'high')); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    const boundary = SYSTEM_BOUNDARY.exec(text);
+    if (boundary && boundary.index !== undefined) {
+        hits.push(hitFromSpan(text, { start: boundary.index, end: boundary.index + boundary[0].length }, EGRESS_RULES.boundary, 'medium'));
     }
-    if (sensitiveSpans(text).length > 0) {
-        hits.push('sensitive');
+    hits.push(...hitsFromSpans(text, injectionSpans(text), EGRESS_RULES.injection, 'medium')); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    return hits;
+}
+/** Distinct rule ids in a hit list, in first-seen order — for rejection copy. */
+function hitRules(hits) {
+    return [...new Set(hits.map((hit) => hit.rule))];
+}
+/** Default egress enforce — canary leak, sensitive echo, fence markers, injection echo. */
+function standardEgressEnforce(payload, context) {
+    const hits = collectEgressHits(payload.text, context.canary);
+    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(...collectEgressHits(structured.text, context.canary));
+        }
     }
-    if (SYSTEM_BOUNDARY.test(text)) {
-        hits.push('system_boundary');
+    if (hits.length === 0) {
+        return { action: 'allow' };
     }
-    if (injectionSpans(text).length > 0) {
-        hits.push('injection_echo');
+    return {
+        action: 'block', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        hits,
+        rejection: `Egress blocked: ${hitRules(hits).join(', ')}`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    };
+}
+/**
+ * Run a host policy without letting it break the turn.
+ *
+ * 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.
+ */
+async function runEnforcer(enforce, payload, context) {
+    try {
+        return await enforce(payload, context);
     }
-    if (hits.length > 0) {
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
         return {
-            blocked: true,
-            text: '',
-            hits,
-            rejectionMessage: `Egress blocked: ${hits.join(', ')}`,
+            action: 'block',
+            hits: [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }],
+            rejection: `Egress policy failed to reach a decision: ${detail}`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         };
     }
-    return { blocked: false, text };
 }
-export { standardEgressEnforce };
+export { collectEgressHits, hitRules, runEnforcer, standardEgressEnforce };

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

@@ -2,34 +2,25 @@
  * Public-safe error mapping for THEORUM.
  *
  * Kernel internals may contain provider status text, tool names, or exception
- * details. This module maps those failures to stable user-safe strings.
+ * details. This module maps those failures to stable user-safe strings from the
+ * kernel lexicon (`public.*` keys) so hosts can override them via
+ * `overrideLexicon`.
  *
  * @module
  */
-/** Error class used for expected THEORUM contract failures. */
-declare class TheorumError extends Error {
-    constructor(message?: string, options?: ErrorOptions);
-}
+import { TheorumError } from './theorum-error.js';
 /** Internal marker for provider or transport failure. */
 declare const UPSTREAM_FAILED = "upstream failed";
-/** Generic safe fallback shown when details must not be surfaced. */
-declare const PUBLIC_GENERIC = "Something went wrong. Try again.";
-/** Safe copy for transient provider unavailability. */
-declare const PUBLIC_UNAVAILABLE = "The model is unavailable. Try again.";
-/** Safe copy for canary or egress disclosure violations. */
-declare const PUBLIC_CANARY = "That reply wasn't safe to show. Try again.";
-/** Safe copy for tool or permission denials. */
-declare const PUBLIC_ACTION = "That action isn't available.";
-/** Safe copy for unsupported MIME types. */
-declare const PUBLIC_FILE_TYPE = "That file type isn't supported.";
-/** Safe copy for oversized files. */
-declare const PUBLIC_FILE_SIZE = "That file is too large.";
-/** Safe copy for too many files in one turn. */
-declare const PUBLIC_FILE_COUNT = "Too many files for one message.";
-/** Safe copy for unsupported generated image dimensions. */
-declare const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
-/** Safe copy when the host aborts a turn. */
-declare const PUBLIC_CANCELLED = "Cancelled.";
+/** Snapshot of the registered default (ignores host overrides). Stable for tests. */
+declare const PUBLIC_GENERIC: string;
+declare const PUBLIC_UNAVAILABLE: string;
+declare const PUBLIC_CANARY: string;
+declare const PUBLIC_ACTION: string;
+declare const PUBLIC_FILE_TYPE: string;
+declare const PUBLIC_FILE_SIZE: string;
+declare const PUBLIC_FILE_COUNT: string;
+declare const PUBLIC_IMAGE_SIZE: string;
+declare const PUBLIC_CANCELLED: string;
 /** True when `err` is an abort (DOMException or Error named AbortError). */
 declare function isAbortError(err: unknown): boolean;
 /** Throw if `signal` is already aborted. */

package/esm/src/guardrails/error.js

@@ -2,37 +2,26 @@
  * Public-safe error mapping for THEORUM.
  *
  * Kernel internals may contain provider status text, tool names, or exception
- * details. This module maps those failures to stable user-safe strings.
+ * details. This module maps those failures to stable user-safe strings from the
+ * kernel lexicon (`public.*` keys) so hosts can override them via
+ * `overrideLexicon`.
  *
  * @module
  */
-/** Error class used for expected THEORUM contract failures. */
-class TheorumError extends Error {
-    constructor(message = '', options) {
-        super(message, options);
-        this.name = 'TheorumError';
-    }
-}
+import { lexiconDefault, lexiconText } from './lexicon.js';
+import { TheorumError } from './theorum-error.js';
 /** Internal marker for provider or transport failure. */
 const UPSTREAM_FAILED = 'upstream failed';
-/** Generic safe fallback shown when details must not be surfaced. */
-const PUBLIC_GENERIC = 'Something went wrong. Try again.';
-/** Safe copy for transient provider unavailability. */
-const PUBLIC_UNAVAILABLE = 'The model is unavailable. Try again.';
-/** Safe copy for canary or egress disclosure violations. */
-const PUBLIC_CANARY = "That reply wasn't safe to show. Try again.";
-/** Safe copy for tool or permission denials. */
-const PUBLIC_ACTION = "That action isn't available.";
-/** Safe copy for unsupported MIME types. */
-const PUBLIC_FILE_TYPE = "That file type isn't supported.";
-/** Safe copy for oversized files. */
-const PUBLIC_FILE_SIZE = 'That file is too large.';
-/** Safe copy for too many files in one turn. */
-const PUBLIC_FILE_COUNT = 'Too many files for one message.';
-/** Safe copy for unsupported generated image dimensions. */
-const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
-/** Safe copy when the host aborts a turn. */
-const PUBLIC_CANCELLED = 'Cancelled.';
+/** Snapshot of the registered default (ignores host overrides). Stable for tests. */
+const PUBLIC_GENERIC = lexiconDefault('public.generic');
+const PUBLIC_UNAVAILABLE = lexiconDefault('public.unavailable');
+const PUBLIC_CANARY = lexiconDefault('public.canary');
+const PUBLIC_ACTION = lexiconDefault('public.action');
+const PUBLIC_FILE_TYPE = lexiconDefault('public.file_type');
+const PUBLIC_FILE_SIZE = lexiconDefault('public.file_size');
+const PUBLIC_FILE_COUNT = lexiconDefault('public.file_count');
+const PUBLIC_IMAGE_SIZE = lexiconDefault('public.image_size');
+const PUBLIC_CANCELLED = lexiconDefault('public.cancelled');
 /** True when `err` is an abort (DOMException or Error named AbortError). */
 function isAbortError(err) {
     if (!err || typeof err !== 'object') {
@@ -50,103 +39,123 @@ function throwIfAborted(signal) {
     if (isAbortError(reason)) {
         throw reason;
     }
-    throw new DOMException('The operation was aborted.', 'AbortError');
+    throw new DOMException('The operation was aborted.', 'AbortError'); // lexicon-exempt: DOM AbortError fingerprint
+}
+/** Resolve public copy at call time so `overrideLexicon` takes effect. */
+function publicCopy(key) {
+    return lexiconText(key);
 }
+/** Upstream/internal message fingerprints → public lexicon keys (not emit copy). */
 const EXACT = {
-    [UPSTREAM_FAILED]: PUBLIC_UNAVAILABLE,
-    'empty Gemini stream': PUBLIC_UNAVAILABLE,
-    'canary leaked': PUBLIC_CANARY,
-    'The operation was aborted.': PUBLIC_CANCELLED,
-    'This operation was aborted': PUBLIC_CANCELLED,
-    'Turn withheld: egress disclosure violation': PUBLIC_CANARY,
-    'expected JSON object': 'Something was wrong with that request.',
-    'structured output was not valid JSON': 'Something was wrong with that request.',
-    'malformed Gemini Live message': PUBLIC_UNAVAILABLE,
-    'malformed Gemini Live message during setup': PUBLIC_UNAVAILABLE,
-    'user input cannot be placed in the system block': PUBLIC_GENERIC,
-    'attachment data must be base64': PUBLIC_FILE_TYPE,
-    'attachment is too large': PUBLIC_FILE_SIZE,
-    'attachments exceed the per-turn budget': PUBLIC_FILE_SIZE,
-    'Tool input validation failed': "That question isn't valid.",
-    'This profile does not accept text input': PUBLIC_ACTION,
+    [UPSTREAM_FAILED]: 'public.unavailable', // lexicon-exempt: internal marker
+    'empty Gemini stream': 'public.unavailable', // lexicon-exempt: upstream fingerprint
+    'canary leaked': 'public.canary', // lexicon-exempt: internal marker
+    'The operation was aborted.': 'public.cancelled', // lexicon-exempt: AbortError fingerprint
+    'This operation was aborted': 'public.cancelled', // lexicon-exempt: AbortError fingerprint
+    'Turn withheld: egress disclosure violation': 'public.canary', // lexicon-exempt: internal marker
+    'expected JSON object': 'public.bad_request', // lexicon-exempt: upstream fingerprint
+    'structured output was not valid JSON': 'public.bad_request', // lexicon-exempt: upstream fingerprint
+    'malformed Gemini Live message': 'public.unavailable', // lexicon-exempt: upstream fingerprint
+    'malformed Gemini Live message during setup': 'public.unavailable', // lexicon-exempt: upstream fingerprint
+    'user input cannot be placed in the system block': 'public.generic', // lexicon-exempt: internal marker
+    'attachment data must be base64': 'public.file_type', // lexicon-exempt: internal marker
+    'attachment is too large': 'public.file_size', // lexicon-exempt: internal marker
+    'attachments exceed the per-turn budget': 'public.file_size', // lexicon-exempt: internal marker
+    'Tool input validation failed': 'public.invalid_question', // lexicon-exempt: internal marker
+    'This profile does not accept text input': 'public.action', // lexicon-exempt: internal marker
 };
 const RULES = [
     {
         match: (t) => /^(Gemini|OpenRouter|TTS|OpenRouter TTS|Speech) HTTP/.test(t) ||
             t.includes('TTS HTTP') ||
             t.includes('Speech HTTP'),
-        resolve: () => PUBLIC_UNAVAILABLE,
+        resolve: () => publicCopy('public.unavailable'),
     },
     {
-        match: (t) => t.includes('not enabled on this turn') ||
+        match: (t) => 
+        // lexicon-exempt: substring fingerprints against internal TheorumError messages
+        t.includes('not enabled on this turn') ||
             t.includes('not allowed') ||
             t.includes('not registered') ||
-            t.includes('Unknown model select') ||
-            t.includes('Grounding tools'),
-        resolve: () => PUBLIC_ACTION,
+            t.includes('Unknown model select') || // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            t.includes('Grounding tools') ||
+            (t.includes('live.ingress.') && t.includes('is disabled')),
+        resolve: () => publicCopy('public.action'),
     },
     {
-        match: (t) => t.includes('MIME') ||
-            t.includes('does not accept attachments') ||
-            t.includes('does not accept voice'),
-        resolve: () => PUBLIC_FILE_TYPE,
+        match: (t) => 
+        // lexicon-exempt: substring fingerprints against internal TheorumError messages
+        t.includes('MIME') ||
+            t.includes('does not accept attachments') || // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            t.includes('does not accept voice'), // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        resolve: () => publicCopy('public.file_type'),
     },
     {
         match: (t) => t.startsWith('At most'),
-        resolve: () => PUBLIC_FILE_COUNT,
+        resolve: () => publicCopy('public.file_count'),
     },
     {
-        match: (t) => (t.startsWith('Only ') && t.includes('file')) ||
-            t.startsWith('Each file must be') ||
-            t.startsWith('Those files together'),
+        match: (t) => 
+        // lexicon-exempt: match already-lexicon attachment copy before remapping
+        (t.startsWith('Only ') && t.includes('file')) ||
+            t.startsWith('Each file must be') || // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            t.startsWith('Those files together'), // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         resolve: (t) => t,
     },
     {
         match: (t) => t.includes('attachment'),
-        resolve: () => PUBLIC_FILE_SIZE,
+        resolve: () => publicCopy('public.file_size'),
     },
     {
+        // lexicon-exempt: substring fingerprint against internal TheorumError messages
         match: (t) => t.includes('aspect or size'),
-        resolve: () => PUBLIC_IMAGE_SIZE,
+        resolve: () => publicCopy('public.image_size'),
     },
     {
-        match: (t) => t.includes('must pin thinking') || t.includes('has no models'),
-        resolve: () => PUBLIC_GENERIC,
+        match: (t) => 
+        // lexicon-exempt: substring fingerprints against internal TheorumError messages
+        t.includes('must pin thinking') || t.includes('has no models'),
+        resolve: () => publicCopy('public.generic'),
     },
 ];
-const ALREADY_PUBLIC = new Set([
-    PUBLIC_GENERIC,
-    PUBLIC_UNAVAILABLE,
-    PUBLIC_CANARY,
-    PUBLIC_ACTION,
-    PUBLIC_FILE_TYPE,
-    PUBLIC_FILE_SIZE,
-    PUBLIC_FILE_COUNT,
-    PUBLIC_IMAGE_SIZE,
-    PUBLIC_CANCELLED,
-]);
+const PUBLIC_KEYS = [
+    'public.generic',
+    'public.unavailable',
+    'public.canary',
+    'public.action',
+    'public.file_type',
+    'public.file_size',
+    'public.file_count',
+    'public.image_size',
+    'public.cancelled',
+    'public.bad_request',
+    'public.invalid_question',
+];
+function isAlreadyPublic(text) {
+    return PUBLIC_KEYS.some((key) => lexiconText(key) === text || lexiconDefault(key) === text);
+}
 function publicText(text) {
     if (/aborted/i.test(text)) {
-        return PUBLIC_CANCELLED;
+        return publicCopy('public.cancelled');
     }
-    if (ALREADY_PUBLIC.has(text)) {
+    if (isAlreadyPublic(text)) {
         return text;
     }
     const exact = EXACT[text];
     if (exact) {
-        return exact;
+        return publicCopy(exact);
     }
     for (const rule of RULES) {
         if (rule.match(text)) {
             return rule.resolve(text);
         }
     }
-    return PUBLIC_GENERIC;
+    return publicCopy('public.generic');
 }
 /** Convert an unknown thrown value or internal message to user-safe text. */
 function publicError(err) {
     if (isAbortError(err)) {
-        return PUBLIC_CANCELLED;
+        return publicCopy('public.cancelled');
     }
     if (typeof err === 'string') {
         return publicText(err);
@@ -154,7 +163,7 @@ function publicError(err) {
     if (err instanceof TheorumError) {
         return publicText(err.message);
     }
-    return PUBLIC_UNAVAILABLE;
+    return publicCopy('public.unavailable');
 }
 /** Raw diagnostic text for hosts, traces, and logs (never shown to end users). */
 function describeError(err) {

package/esm/src/guardrails/eval/corpus.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Corpus acquisition for guardrail evaluation.
+ *
+ * Nothing is vendored. Corpora are fetched on demand and cached locally, so the
+ * published package carries no third-party data and no licence obligations beyond
+ * attribution here.
+ *
+ * Two sources, deliberately different in shape:
+ *
+ * - **S-Labs/prompt-injection-dataset** (MIT) — ~11k labelled prompts whose benign
+ *   half deliberately includes security-adjacent questions ("explain output
+ *   validation best practices", "how do I implement stress testing"). This is
+ *   where user-text detectors are most likely to misfire.
+ *
+ *   Chosen over `prodnull/prompt-injection-repo-dataset`, which has richer hard
+ *   negatives but is gated: licence and access are separate axes, and a gated
+ *   corpus cannot be fetched by an unattended run.
+ * - **AgentDojo** (MIT, ETH Zurich) — simulated environments for a tool-using
+ *   agent. Its fixtures are read directly; the benchmark is never run, so no model
+ *   or API key is involved. This supplies benign output in the shape a *tool*
+ *   returns, which the repo dataset does not cover.
+ *
+ * The two are kept separate on purpose. Pooling sources and reporting one number
+ * hides the domain shift between them, and that shift is the thing most likely to
+ * make a detector look better than it is.
+ *
+ * @module
+ */
+export interface CorpusSample {
+    text: string;
+    /** True when the sample is an attack. */
+    attack: boolean;
+    /** Source dataset id, kept so results are never pooled silently. */
+    source: string;
+    /** Benign sub-category, so "security docs" never averages into "work email". */
+    category: string;
+}
+export interface CorpusSource {
+    id: string;
+    licence: string;
+    attribution: string;
+    /**
+     * Rows fetched by default.
+     *
+     * Several of these corpora are far larger than a fast run wants. The cap is
+     * declared rather than buried in the loader so a report can say what fraction
+     * was actually sampled — a rate over 1% of a corpus is not a rate over the
+     * corpus.
+     */
+    sampleLimit: number;
+    /** Rows available upstream, when known, so sampling is visible in the report. */
+    upstreamRows?: number;
+    /** Set when the dataset is gated and needs `HF_TOKEN` to fetch. */
+    requiresToken?: boolean;
+    load: (cache: CorpusCache, limit: number) => Promise<CorpusSample[]>;
+}
+/** Local cache directory for fetched corpora; gitignored, never published. */
+export interface CorpusCache {
+    dir: string;
+    fetchText: (url: string, key: string) => Promise<string>;
+}
+/**
+ * Page through a dataset via the rows API.
+ *
+ * Pages are fetched in batches rather than one at a time: a full corpus here runs
+ * to thousands of pages, and a serial walk is slow enough that it pressures whoever
+ * runs it into sampling a slice and quoting the result as if it covered the whole.
+ */
+/** Paging options. An object rather than more positionals, which had reached five. */
+export interface FetchRowsOptions {
+    split?: string;
+    config?: string;
+    /** Base retry delay. Seconds in production; tests pass milliseconds. */
+    retryBaseMs?: number;
+}
+declare function fetchRows(cache: CorpusCache, dataset: string, limit: number, options?: FetchRowsOptions): Promise<Record<string, unknown>[]>;
+/** Create a cache that reads from disk when present and fetches when not. */
+declare function createCorpusCache(dir: string): CorpusCache;
+/**
+ * Parse a two-column `text,label` CSV.
+ *
+ * Hand-rolled because the corpus text is adversarial by construction: it contains
+ * quotes, commas, and embedded newlines, and a naive split would shred exactly the
+ * samples that matter most.
+ */
+declare function parseLabelledCsv(input: string): {
+    text: string;
+    label: number;
+}[];
+declare function recordsFromYaml(yaml: string): string[];
+/**
+ * Corpora evaluated and deliberately not enabled, with the reason.
+ *
+ * Kept in the repo so the search does not have to be repeated, and so a later
+ * decision to include one starts from the objection rather than from scratch.
+ */
+/**
+ * Corpora evaluated and deliberately left out of SOURCES, with the objection.
+ * See docs/contracts/guardrails.md.
+ */
+export declare const REVIEWED_SOURCES: readonly {
+    dataset: string;
+    rows: number;
+    licence: string;
+    verdict: string;
+}[];
+declare const SOURCES: readonly CorpusSource[];
+export { createCorpusCache, fetchRows, parseLabelledCsv, recordsFromYaml, SOURCES };