theorum 0.1.15 → 1.1.3

package/esm/src/cli/matrix/synthesizer.js

@@ -1,87 +1,41 @@
 /**
  * Stress / matrix turn synthesis for the THEORUM CLI.
  *
- * Tool enabling walks the profile allowlist and registered catalog metadata
- * (`conflictsWith`). Google `--search` / `--map` flags remain as convenience
- * aliases for `googleSearch` / `googleMaps` when those ids are allowed.
+ * Custom tools come from `profile.tools.allow` (visibility via loadTier).
+ * Provider builtins come from `models.*.builtInTools`. `--search` /
+ * `--map` only verify those ids are listed on the selected model.
  *
  * @module
  */
-import { getTool } from '../../kernel/registry/catalog.js';
 import { FIXTURE_PNG_BASE64, FIXTURE_WAV_BASE64, getFixtureForMime } from './fixtures.js';
+function defaultModelId(profile) {
+    const ids = Object.keys(profile.models);
+    return profile.defaultModel ?? ids[0] ?? '';
+}
 export function synthesizeLiteCombo(profile) {
-    const select = profile.model.select?.fast ? 'fast' : undefined;
+    const model = profile.allowModelSelect && profile.models.fast ? 'fast' : undefined;
     return {
         profile: profile.id,
-        select,
-        tools: {},
+        model,
         input: {
             text: `Ping test for profile ${profile.id}. Respond concisely with confirmation.`,
         },
     };
 }
-function resolveStressReasoning(profile) {
-    if (profile.model.select?.smart) {
-        return 'smart';
+function resolveStressModel(profile) {
+    if (!profile.allowModelSelect) {
+        return undefined;
     }
-    if (profile.model.select) {
-        const keys = Object.keys(profile.model.select);
-        return keys[keys.length - 1];
-    }
-    return undefined;
-}
-function isEnabled(active, id) {
-    return active[id] === true;
-}
-/** Drop tools whose registered `conflictsWith` siblings are also enabled. */
-function applyRegisteredConflicts(allowed, active) {
-    for (const id of allowed) {
-        if (!isEnabled(active, id)) {
-            continue;
-        }
-        const conflicts = getTool(id)?.conflictsWith ?? [];
-        if (conflicts.some((other) => isEnabled(active, other))) {
-            active[id] = false;
-        }
-    }
-}
-/**
- * Enable allowlisted tools, optionally forcing one preferred tool and clearing
- * what it conflicts with (and tools that conflict with it).
- */
-function resolveStressTools(allowed, prefer) {
-    const active = {};
-    for (const t of allowed) {
-        active[t] = true;
-    }
-    if (prefer && allowed.includes(prefer)) {
-        active[prefer] = true;
-        for (const c of getTool(prefer)?.conflictsWith ?? []) {
-            if (allowed.includes(c)) {
-                active[c] = false;
-            }
-        }
-        for (const t of allowed) {
-            if (t === prefer) {
-                continue;
-            }
-            const otherConflicts = getTool(t)?.conflictsWith ?? [];
-            if (otherConflicts.includes(prefer)) {
-                active[t] = false;
-            }
-        }
+    if (profile.models.smart) {
+        return 'smart';
     }
-    applyRegisteredConflicts(allowed, active);
-    return active;
-}
-/** Builtins on the allowlist that declare conflicts (candidates for matrix variants). */
-function conflictingAllowlistedTools(allowed) {
-    return allowed.filter((id) => {
-        const entry = getTool(id);
-        return entry?.kind === 'builtin' && (entry.conflictsWith?.length ?? 0) > 0;
-    });
+    const ids = Object.keys(profile.models);
+    return ids.length > 1 ? ids[ids.length - 1] : undefined;
 }
 function resolveStressAttachments(profile) {
+    if (profile.type === 'speech' || profile.type === 'live' || !profile.inputs) {
+        return [];
+    }
     const attachments = [];
     const accept = profile.inputs.attachments?.accept;
     if (accept && accept.length > 0) {
@@ -98,22 +52,23 @@ function resolveStressAttachments(profile) {
     return attachments;
 }
 function resolveStressVoice(profile) {
+    if (profile.type === 'speech' || profile.type === 'live' || !profile.inputs) {
+        return [];
+    }
     const voice = [];
     if (profile.inputs.voice?.accept && profile.inputs.voice.accept.length > 0) {
         voice.push({ mimeType: 'audio/wav', data: FIXTURE_WAV_BASE64 });
     }
     return voice;
 }
-export function synthesizeStressCombo(profile, options = {}) {
-    const select = resolveStressReasoning(profile);
-    const activeTools = resolveStressTools(profile.tools.allow ?? [], options.preferTool);
+export function synthesizeStressCombo(profile) {
+    const model = resolveStressModel(profile);
     const attachments = resolveStressAttachments(profile);
     const voice = resolveStressVoice(profile);
     const promptText = `Execute comprehensive test turn for profile ${profile.id}. Validate all instructions and produce required outputs.`;
     return {
         profile: profile.id,
-        select,
-        tools: activeTools,
+        model,
         input: {
             text: promptText,
             attachments: attachments.length > 0 ? attachments : undefined,
@@ -122,55 +77,27 @@ export function synthesizeStressCombo(profile, options = {}) {
     };
 }
 export function synthesizeMatrixCombos(profile) {
-    const combos = [];
-    const allowed = profile.tools.allow ?? [];
-    combos.push({
-        name: 'Lite (connectivity)',
-        req: synthesizeLiteCombo(profile),
-    });
-    const primary = synthesizeStressCombo(profile);
-    combos.push({
-        name: 'Stress (all modalities + primary tools)',
-        req: primary,
-    });
-    // Variants: each allowlisted conflicting builtin that the primary pass dropped.
-    for (const id of conflictingAllowlistedTools(allowed)) {
-        if (primary.tools?.[id] === true) {
-            continue;
-        }
-        const variant = synthesizeStressCombo(profile, { preferTool: id });
-        if (variant.tools?.[id] !== true) {
-            continue;
-        }
-        combos.push({
-            name: `Conflict variant (${id} preferred)`,
-            req: variant,
-        });
-    }
-    return combos;
+    return [
+        {
+            name: 'Lite (connectivity)',
+            req: synthesizeLiteCombo(profile),
+        },
+        {
+            name: 'Stress (all modalities + primary tools)',
+            req: synthesizeStressCombo(profile),
+        },
+    ];
 }
-/** Map legacy Google CLI flags onto tool ids when the profile allowlists them. */
-function applyGoogleFlagAliases(active, allowed, options) {
-    if (options.search !== undefined && allowed.includes('googleSearch')) {
-        active.googleSearch = options.search;
+/** Ensure CLI grounding flags match model builtInTools. */
+function assertGroundingFlagsOnModel(profile, options) {
+    const modelId = options.mode && profile.models[options.mode] ? options.mode : defaultModelId(profile);
+    const builtins = new Set(profile.models[modelId]?.builtInTools ?? []);
+    if (options.search === true && !builtins.has('googleSearch')) {
+        throw new Error(`--search requires googleSearch on models.${modelId}.builtInTools`);
     }
-    if (options.map !== undefined && allowed.includes('googleMaps')) {
-        active.googleMaps = options.map;
-    }
-}
-function applyExplicitToolOverrides(base, profile, options) {
-    const allowed = profile.tools.allow ?? [];
-    base.tools = base.tools ?? {};
-    applyGoogleFlagAliases(base.tools, allowed, options);
-    // If map was explicitly requested on, prefer it against its registered conflicts.
-    if (options.map === true && allowed.includes('googleMaps')) {
-        const preferred = resolveStressTools(allowed, 'googleMaps');
-        for (const id of allowed) {
-            base.tools[id] = preferred[id] === true;
-        }
-        return;
+    if (options.map === true && !builtins.has('googleMaps')) {
+        throw new Error(`--map requires googleMaps on models.${modelId}.builtInTools`);
     }
-    applyRegisteredConflicts(allowed, base.tools);
 }
 export function buildCustomTurnRequest(profile, options) {
     if (options.lite) {
@@ -178,10 +105,10 @@ export function buildCustomTurnRequest(profile, options) {
     }
     const base = synthesizeStressCombo(profile);
     if (options.mode) {
-        base.select = options.mode;
+        base.model = options.mode;
     }
     if (options.search !== undefined || options.map !== undefined) {
-        applyExplicitToolOverrides(base, profile, options);
+        assertGroundingFlagsOnModel(profile, options);
     }
     return base;
 }

package/esm/src/guardrails/canary-gate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Canary-only batch helper for hosts that need stream lookback without full
+ * egress. Live production path: `live-outbound-gate.ts` (progressive yield).
+ *
+ * @module
+ */
+import type { TurnEvent } from '../kernel/types.js';
+import { type CanaryStreamGate } from './canary.js';
+export interface CanaryGateSession {
+    canary: string;
+    gate: CanaryStreamGate;
+    lastStreamType?: 'text' | 'thought';
+}
+declare function createCanaryGateSession(canary: string): CanaryGateSession;
+declare function filterCanaryGatedEvents(session: CanaryGateSession, events: TurnEvent[]): {
+    leaked: true;
+} | {
+    leaked: false;
+    events: TurnEvent[];
+};
+export { createCanaryGateSession, filterCanaryGatedEvents };

package/esm/src/guardrails/canary-gate.js

@@ -0,0 +1,32 @@
+/**
+ * Canary-only batch helper for hosts that need stream lookback without full
+ * egress. Live production path: `live-outbound-gate.ts` (progressive yield).
+ *
+ * @module
+ */
+import { createCanaryStreamGate, eventHasCanary, isStreamedCanaryEvent, } from './canary.js';
+function createCanaryGateSession(canary) {
+    return { canary, gate: createCanaryStreamGate(canary) };
+}
+function filterCanaryGatedEvents(session, events) {
+    const out = [];
+    for (const event of events) {
+        if (isStreamedCanaryEvent(event)) {
+            session.lastStreamType = event.type;
+            const result = session.gate.process(event.text ?? '');
+            if (result.leak) {
+                return { leaked: true };
+            }
+            if (result.emit) {
+                out.push({ ...event, text: result.emit });
+            }
+            continue;
+        }
+        if (eventHasCanary(event, session.canary)) {
+            return { leaked: true };
+        }
+        out.push(event);
+    }
+    return { leaked: false, events: out };
+}
+export { createCanaryGateSession, filterCanaryGatedEvents };

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

@@ -0,0 +1,34 @@
+import type { TurnEvent } from '../kernel/types.js';
+declare const USER_OPEN = "<user_data>";
+declare const USER_CLOSE = "</user_data>";
+declare const OMIT_CANARY = "[omitted - canary]";
+declare function mintCanary(): string;
+declare function wrapUserData(text: string): string;
+/**
+ * Append the canary bind note to the host's system prompt.
+ *
+ * The note is mechanism text with an overridable registered default
+ * (`canary.bind_note` in the lexicon) or a per-profile template
+ * (`guardrails.canary.bindNote`). Either way the template must contain the
+ * `{canary}` placeholder — a note without the token binds nothing.
+ */
+declare function bindCanary(system: string, canary: string, bindNote?: string): string;
+declare function scanTextForCanaryLeak(text: string, canary: string): boolean;
+declare function eventHasCanary(event: TurnEvent, canary: string): boolean;
+type CanaryGateResult = {
+    leak: true;
+} | {
+    leak: false;
+    emit: string;
+};
+interface CanaryStreamGate {
+    process: (fragment: string) => CanaryGateResult;
+    flush: () => CanaryGateResult;
+}
+declare function createCanaryStreamGate(canary: string): CanaryStreamGate;
+declare function isStreamedCanaryEvent(event: TurnEvent): event is TurnEvent & {
+    type: 'text' | 'thought';
+};
+declare function redactCanary(event: TurnEvent, canary: string): TurnEvent;
+export type { CanaryGateResult, CanaryStreamGate };
+export { bindCanary, createCanaryStreamGate, eventHasCanary, isStreamedCanaryEvent, mintCanary, OMIT_CANARY, redactCanary, scanTextForCanaryLeak, USER_CLOSE, USER_OPEN, wrapUserData, };

package/esm/src/guardrails/canary.js

@@ -0,0 +1,150 @@
+import { mapStrings } from '../kernel/engine/tree.js';
+import { TheorumError } from './error.js';
+import { lexiconText } from './lexicon.js';
+import { scanTextOf } from './serialize.js';
+const USER_OPEN = '<user_data>';
+const USER_CLOSE = '</user_data>';
+const CANARY_PREFIX = 'theo-';
+const CANARY_BYTES = 16;
+const HEX_RADIX = 16;
+const HEX_PAD = 2;
+const OMIT_CANARY = '[omitted - canary]';
+const FENCE = /<\/?user_data>/gi;
+/** Base64 prefix hint for the literal string "theo". */
+const B64_THEO_HINT = 'dGhlbw';
+function mintCanary() {
+    const bytes = new Uint8Array(CANARY_BYTES);
+    crypto.getRandomValues(bytes);
+    let hex = '';
+    for (const byte of bytes) {
+        hex += byte.toString(HEX_RADIX).padStart(HEX_PAD, '0');
+    }
+    return `${CANARY_PREFIX}${hex}`;
+}
+function stripUserFences(text) {
+    return text.replaceAll(FENCE, '').trim();
+}
+function wrapUserData(text) {
+    return `${USER_OPEN}\n${stripUserFences(text)}\n${USER_CLOSE}`;
+}
+/**
+ * Append the canary bind note to the host's system prompt.
+ *
+ * The note is mechanism text with an overridable registered default
+ * (`canary.bind_note` in the lexicon) or a per-profile template
+ * (`guardrails.canary.bindNote`). Either way the template must contain the
+ * `{canary}` placeholder — a note without the token binds nothing.
+ */
+function bindCanary(system, canary, bindNote) {
+    if (!canary) {
+        return system;
+    }
+    if (bindNote !== undefined && !bindNote.includes('{canary}')) {
+        throw new TheorumError('guardrails.canary.bindNote must contain the {canary} placeholder');
+    }
+    const note = lexiconText('canary.bind_note', { canary }, bindNote);
+    if (!system) {
+        return note;
+    }
+    return `${system}\n\n${note}`;
+}
+function scanTextForCanaryLeak(text, canary) {
+    if (!text || !canary) {
+        return false;
+    }
+    if (text.includes(canary)) {
+        return true;
+    }
+    try {
+        const encoded = btoa(canary);
+        if (text.includes(encoded)) {
+            return true;
+        }
+    }
+    catch {
+        /* ignore invalid btoa input */
+    }
+    if (!text.includes('theo') && !text.includes(B64_THEO_HINT)) {
+        return false;
+    }
+    const hex = canary.startsWith(CANARY_PREFIX) ? canary.slice(CANARY_PREFIX.length) : '';
+    if (hex.length > 0) {
+        const spaced = hex.split('').join(' ');
+        if (text.includes(spaced)) {
+            return true;
+        }
+    }
+    return false;
+}
+function eventHasCanary(event, canary) {
+    if (!canary) {
+        return false;
+    }
+    if (event.text && scanTextForCanaryLeak(event.text, canary)) {
+        return true;
+    }
+    if (event.error && scanTextForCanaryLeak(event.error, canary)) {
+        return true;
+    }
+    if (event.structured !== undefined &&
+        scanTextForCanaryLeak(scanTextOf(event.structured), canary)) {
+        return true;
+    }
+    if (event.tool !== undefined && scanTextForCanaryLeak(scanTextOf(event.tool), canary)) {
+        return true;
+    }
+    if (event.grounding !== undefined && scanTextForCanaryLeak(scanTextOf(event.grounding), canary)) {
+        return true;
+    }
+    if (event.evidence !== undefined && scanTextForCanaryLeak(scanTextOf(event.evidence), canary)) {
+        return true;
+    }
+    if (event.session !== undefined && scanTextForCanaryLeak(scanTextOf(event.session), canary)) {
+        return true;
+    }
+    if (event.sessionResumptionHandle &&
+        scanTextForCanaryLeak(event.sessionResumptionHandle, canary)) {
+        return true;
+    }
+    return false;
+}
+function createCanaryStreamGate(canary) {
+    const overlap = Math.max(0, canary.length - 1);
+    let pending = '';
+    function step(window) {
+        if (scanTextForCanaryLeak(window, canary)) {
+            return { leak: true };
+        }
+        const safeEnd = Math.max(0, window.length - overlap);
+        const emit = window.slice(0, safeEnd);
+        pending = window.slice(safeEnd);
+        return { leak: false, emit };
+    }
+    return {
+        process(fragment) {
+            if (!fragment) {
+                return { leak: false, emit: '' };
+            }
+            return step(pending + fragment);
+        },
+        flush() {
+            if (scanTextForCanaryLeak(pending, canary)) {
+                return { leak: true };
+            }
+            const emit = pending;
+            pending = '';
+            return { leak: false, emit };
+        },
+    };
+}
+function isStreamedCanaryEvent(event) {
+    return event.type === 'text' || event.type === 'thought';
+}
+function redactCanary(event, canary) {
+    const next = mapStrings(event, (text) => text.replaceAll(canary, OMIT_CANARY));
+    if (next && typeof next === 'object') {
+        return next;
+    }
+    return event;
+}
+export { bindCanary, createCanaryStreamGate, eventHasCanary, isStreamedCanaryEvent, mintCanary, OMIT_CANARY, redactCanary, scanTextForCanaryLeak, USER_CLOSE, USER_OPEN, wrapUserData, };

package/esm/src/guardrails/corpus/canary-egress-attacks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Synthetic canary egress attack catalog — events built at fuzz time from a canary token.
+ *
+ * @module
+ */
+/** lexicon-exempt-file: adversarial corpus fixture — not runtime user or model copy (P2) */
+import type { TurnEvent } from '../../kernel/types.js';
+import type { CanaryEgressCatalogEntry } from './types.js';
+/** Fixed token so canary fuzz reports are reproducible across runs. */
+export declare const FIXED_CANARY = "theo-0123456789abcdef0123456789abcdef";
+export interface CanaryEgressAttack extends CanaryEgressCatalogEntry {
+    events: TurnEvent[];
+}
+/** Build the full canary egress adversarial bank for a given token. */
+export declare function buildCanaryEgressAttacks(canary: string): CanaryEgressAttack[];
+/** Catalog metadata without event payloads (for docs / inventory). */
+export declare function canaryEgressCatalog(canary: string): CanaryEgressCatalogEntry[];

package/esm/src/guardrails/corpus/canary-egress-attacks.js

@@ -0,0 +1,151 @@
+/**
+ * Synthetic canary egress attack catalog — events built at fuzz time from a canary token.
+ *
+ * @module
+ */
+/** Fixed token so canary fuzz reports are reproducible across runs. */
+export const FIXED_CANARY = 'theo-0123456789abcdef0123456789abcdef';
+function splitTextChunks(canary, text) {
+    const idx = text.indexOf(canary);
+    if (idx < 0) {
+        return [{ type: 'text', text }];
+    }
+    const before = text.slice(0, idx + Math.ceil(canary.length / 2));
+    const after = text.slice(idx + Math.ceil(canary.length / 2));
+    return [
+        { type: 'text', text: before },
+        { type: 'text', text: after },
+    ];
+}
+function allSplitPoints(canary) {
+    const cases = [];
+    for (let i = 1; i < canary.length; i++) {
+        cases.push({
+            name: `split-at-${i}`,
+            category: 'split-stream',
+            shouldBlock: true,
+            events: [
+                { type: 'text', text: canary.slice(0, i) },
+                { type: 'text', text: canary.slice(i) },
+            ],
+        });
+    }
+    return cases;
+}
+function charByChar(canary) {
+    return {
+        name: 'char-by-char',
+        category: 'split-stream',
+        shouldBlock: true,
+        events: [...canary].map((ch) => ({ type: 'text', text: ch })),
+    };
+}
+/** Build the full canary egress adversarial bank for a given token. */
+export function buildCanaryEgressAttacks(canary) {
+    const hex = canary.slice('theo-'.length);
+    const spacedHex = hex.split('').join(' ');
+    const b64 = btoa(canary);
+    const attacks = [
+        {
+            name: 'literal-text',
+            category: 'literal',
+            shouldBlock: true,
+            events: [{ type: 'text', text: `Here is the token: ${canary}` }],
+        },
+        {
+            name: 'literal-thought',
+            category: 'literal',
+            shouldBlock: true,
+            events: [{ type: 'thought', text: `internal ${canary}` }],
+        },
+        {
+            name: 'literal-structured',
+            category: 'literal',
+            shouldBlock: true,
+            events: [{ type: 'structured', structured: { secret: canary } }],
+        },
+        {
+            name: 'literal-tool',
+            category: 'literal',
+            shouldBlock: true,
+            events: [{ type: 'tool', tool: { name: 'leak', arguments: { token: canary } } }],
+        },
+        {
+            name: 'literal-grounding',
+            category: 'literal',
+            shouldBlock: true,
+            events: [{ type: 'grounding', grounding: { sources: [], metadata: { canary } } }],
+        },
+        {
+            name: 'literal-evidence',
+            category: 'literal',
+            shouldBlock: true,
+            events: [{ type: 'evidence', evidence: { provider: 'google', raw: { canary } } }],
+        },
+        {
+            name: 'base64-text',
+            category: 'encoding',
+            shouldBlock: true,
+            events: [{ type: 'text', text: `decode: ${b64}` }],
+        },
+        {
+            name: 'spaced-hex-text',
+            category: 'encoding',
+            shouldBlock: true,
+            events: [{ type: 'text', text: `theo- ${spacedHex}` }],
+        },
+        {
+            name: 'split-wrapper',
+            category: 'split-stream',
+            shouldBlock: true,
+            events: splitTextChunks(canary, `prefix ${canary} suffix`),
+        },
+        charByChar(canary),
+        {
+            name: 'thought-then-text-split',
+            category: 'split-stream',
+            shouldBlock: true,
+            events: [
+                { type: 'thought', text: canary.slice(0, 20) },
+                { type: 'text', text: canary.slice(20) },
+            ],
+        },
+        {
+            name: 'benign-theorem',
+            category: 'benign',
+            shouldBlock: false,
+            events: [{ type: 'text', text: 'Welcome to theorem proving and theory.' }],
+        },
+        {
+            name: 'benign-prefix-only',
+            category: 'benign',
+            shouldBlock: false,
+            events: [{ type: 'text', text: 'theo-' }],
+        },
+        {
+            name: 'benign-random-hex',
+            category: 'benign',
+            shouldBlock: false,
+            events: [{ type: 'text', text: 'theo-deadbeeffeedfacecafebabecafebabe' }],
+        },
+        {
+            name: 'benign-safe-reply',
+            category: 'benign',
+            shouldBlock: false,
+            events: [
+                { type: 'text', text: 'Hello! How can I help you today?' },
+                { type: 'tokens', tokens: { input: 1, output: 2, total: 3 } },
+            ],
+        },
+    ];
+    attacks.push(...allSplitPoints(canary));
+    return attacks;
+}
+/** Catalog metadata without event payloads (for docs / inventory). */
+export function canaryEgressCatalog(canary) {
+    return buildCanaryEgressAttacks(canary).map(({ name, category, shouldBlock }) => ({
+        name,
+        category,
+        shouldBlock,
+    }));
+}

package/esm/src/guardrails/corpus/fuzz-inbound.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Inbound sanitize fuzz runner — exercises all sanitize channels against the corpus.
+ *
+ * @module
+ */
+/**
+ * Run inbound adversarial fuzz against the corpus. Returns false when expected catches are missed.
+ */
+export declare function runInboundGuardrailFuzz(options?: {
+    quiet?: boolean;
+}): boolean;