theorum 1.0.0 → 1.1.3

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

@@ -0,0 +1,51 @@
+/**
+ * Guardrail evaluation — measured detector quality, not asserted.
+ *
+ * Every detector in this facet is a pattern matcher, and pattern matchers fail on
+ * content nobody thought to write down. The point of this module is to make that
+ * failure visible against corpora the authors did not choose, rather than against
+ * hand-picked examples that flatter whatever was just built.
+ *
+ * Reached from `theorum/guardrails/testing`; never from the production entry.
+ *
+ * @command `deno task guardrails:eval`
+ * @module
+ */
+import { type DetectorScore, type EvalDetector } from './score.js';
+/**
+ * The detectors under evaluation, with what they do when they fire.
+ *
+ * `action` is not decoration: it sets how much a false positive costs. A `redact`
+ * silently rewrites a user's message, a `block` withholds a whole turn, and an
+ * `annotate` only adds a caution the model may disregard. The first two have to
+ * clear a far higher bar.
+ */
+declare const DETECTORS: readonly EvalDetector[];
+export interface EvalOptions {
+    /** Cache directory for fetched corpora. Gitignored; never published. */
+    cacheDir?: string;
+    /** Cap samples per source, for a quick local run. */
+    limit?: number;
+}
+export interface EvalReport {
+    scores: DetectorScore[];
+    /** Attribution for every corpus actually loaded. */
+    sources: {
+        id: string;
+        licence: string;
+        attribution: string;
+        samples: number;
+        /** Rows available upstream, so partial sampling is visible. */
+        upstreamRows?: number;
+    }[];
+    /** Corpora that could not be loaded, and why. */
+    skipped: {
+        id: string;
+        reason: string;
+    }[];
+}
+/** Fetch the corpora and score every detector against each source separately. */
+declare function runGuardrailEval(options?: EvalOptions): Promise<EvalReport>;
+/** Human-readable report, including the attribution the licences require. */
+declare function formatReport(report: EvalReport): string;
+export { DETECTORS, formatReport, runGuardrailEval };

package/esm/src/guardrails/eval/mod.js

@@ -0,0 +1,133 @@
+/**
+ * Guardrail evaluation — measured detector quality, not asserted.
+ *
+ * Every detector in this facet is a pattern matcher, and pattern matchers fail on
+ * content nobody thought to write down. The point of this module is to make that
+ * failure visible against corpora the authors did not choose, rather than against
+ * hand-picked examples that flatter whatever was just built.
+ *
+ * Reached from `theorum/guardrails/testing`; never from the production entry.
+ *
+ * @command `deno task guardrails:eval`
+ * @module
+ */
+/** lexicon-exempt-file: evaluation runner — not runtime user or model copy (P2) */
+import { injectionSpans } from '../injection.js';
+import { sensitiveSpans } from '../sensitive.js';
+import { directiveHits } from '../tool-directives.js';
+import { createCorpusCache, SOURCES } from './corpus.js';
+import { formatScores, scoreAll } from './score.js';
+/** Tool names used for the callable-tool signal when scoring tool-result content. */
+const EVAL_TOOLS = ['send_email', 'send_money', 'read_inbox', 'get_channel_messages'];
+/**
+ * The detectors under evaluation, with what they do when they fire.
+ *
+ * `action` is not decoration: it sets how much a false positive costs. A `redact`
+ * silently rewrites a user's message, a `block` withholds a whole turn, and an
+ * `annotate` only adds a caution the model may disregard. The first two have to
+ * clear a far higher bar.
+ */
+const DETECTORS = [
+    {
+        id: 'injection.spans',
+        action: 'redact',
+        accountableFor: [
+            'prompt-injection-prompts',
+            'deepset-prompts',
+            'spml-chatbot',
+            'agent-app-attacks',
+            'nvidia-agentic-ipi',
+            'llmail-adaptive',
+            'llmail-evaded-defense',
+            'multilingual-prompts',
+            'nvidia-jailbreak',
+            'wildjailbreak',
+        ],
+        fires: (text) => injectionSpans(text).length > 0,
+    },
+    {
+        id: 'sensitive.spans',
+        action: 'redact',
+        // `pii-spans` is the one corpus that labels what this detector hunts.
+        accountableFor: ['pii-spans'],
+        fires: (text) => sensitiveSpans(text).length > 0,
+    },
+    {
+        id: 'tool-directives',
+        // Indirect injection inside tool output. The prompt corpora are user-text
+        // shaped; the agent-app attacks are the closest available match.
+        action: 'annotate',
+        accountableFor: [
+            'agent-app-attacks',
+            'nvidia-agentic-ipi',
+            'llmail-adaptive',
+            'llmail-evaded-defense',
+        ],
+        fires: (text) => directiveHits(text, EVAL_TOOLS).length > 0,
+    },
+];
+function corpusSkipReason(source, kind, err) {
+    if (kind === 'error') {
+        if (source.requiresToken)
+            return 'gated upstream — set HF_TOKEN to include it';
+        return err instanceof Error ? err.message : String(err);
+    }
+    return source.requiresToken
+        ? 'no rows returned — gated, or upstream rate-limited'
+        : 'no rows returned — upstream rate-limited or schema changed';
+}
+async function loadEvalSource(source, cache, limit) {
+    let samples;
+    try {
+        samples = await source.load(cache, limit ?? source.sampleLimit);
+    }
+    catch (err) {
+        return { ok: false, skip: { id: source.id, reason: corpusSkipReason(source, 'error', err) } };
+    }
+    if (samples.length === 0 && (source.upstreamRows ?? 0) > 0) {
+        return { ok: false, skip: { id: source.id, reason: corpusSkipReason(source, 'empty') } };
+    }
+    return {
+        ok: true,
+        samples,
+        meta: {
+            id: source.id,
+            licence: source.licence,
+            attribution: source.attribution,
+            samples: samples.length,
+            ...(source.upstreamRows !== undefined ? { upstreamRows: source.upstreamRows } : {}),
+        },
+    };
+}
+/** Fetch the corpora and score every detector against each source separately. */
+async function runGuardrailEval(options = {}) {
+    const cache = createCorpusCache(options.cacheDir ?? '.guardrail-corpus');
+    const bySource = new Map();
+    const sources = [];
+    const skipped = [];
+    for (const source of SOURCES) {
+        const loaded = await loadEvalSource(source, cache, options.limit);
+        if (!loaded.ok) {
+            skipped.push(loaded.skip);
+            continue;
+        }
+        bySource.set(source.id, loaded.samples);
+        sources.push(loaded.meta);
+    }
+    return { scores: scoreAll(DETECTORS, bySource), sources, skipped };
+}
+/** Human-readable report, including the attribution the licences require. */
+function formatReport(report) {
+    const header = report.sources
+        .map((s) => {
+        // Say plainly when a figure rests on a slice of a much larger corpus.
+        const of = s.upstreamRows !== undefined && s.samples < s.upstreamRows ? ` of ${s.upstreamRows}` : '';
+        return `  ${s.id.padEnd(24)} ${String(s.samples).padStart(6)}${of.padEnd(12)} samples  ${s.licence}  ${s.attribution}`;
+    })
+        .join('\n');
+    const skipped = report.skipped.length === 0
+        ? ''
+        : `\n\nNot loaded\n${report.skipped.map((s) => `  ${s.id.padEnd(24)} ${s.reason}`).join('\n')}`;
+    return `Corpora\n${header}${skipped}\n${formatScores(report.scores)}`;
+}
+export { DETECTORS, formatReport, runGuardrailEval };

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

@@ -0,0 +1,66 @@
+/**
+ * Scoring for guardrail evaluation.
+ *
+ * Reports per detector, per source, and per benign category. Never a single
+ * pooled number: pooling hides which kind of content a detector misfires on, and
+ * "security documentation" and "work email" fail for different reasons.
+ *
+ * The false-positive rate is the number that decides whether a detector ships. A
+ * detector that fires on legitimate content does not make an agent careful; it
+ * makes it unreliable in ways a user cannot see the reason for.
+ *
+ * @module
+ */
+import type { CorpusSample } from './corpus.js';
+/** One detector under evaluation. */
+export interface EvalDetector {
+    id: string;
+    /** What the detector does when it fires — determines how costly a miss is. */
+    action: 'redact' | 'block' | 'annotate';
+    /**
+     * Sources whose attack label this detector is answerable for.
+     *
+     * A credential detector scored against a corpus of prompt injections would
+     * report near-zero recall and look broken, when in fact it was asked the wrong
+     * question. Recall is reported only where the corpus labels the thing the
+     * detector exists to find; false-positive rate is always reported, because
+     * benign is benign whatever the detector is looking for.
+     */
+    accountableFor: readonly string[];
+    fires: (text: string) => boolean;
+}
+export interface CategoryScore {
+    category: string;
+    samples: number;
+    fired: number;
+    /** Rate at which the detector fired on this category. */
+    rate: number;
+}
+export interface DetectorScore {
+    detector: string;
+    action: EvalDetector['action'];
+    source: string;
+    attacks: number;
+    attacksCaught: number;
+    /** Undefined when the source carries no attacks. */
+    recall?: number;
+    benign: number;
+    falsePositives: number;
+    /** Undefined when the source carries no benign samples. */
+    falsePositiveRate?: number;
+    /** Benign breakdown, so one bad category cannot hide inside an average. */
+    byCategory: CategoryScore[];
+}
+/** Score one detector against one source's samples. */
+declare function scoreDetector(detector: EvalDetector, source: string, samples: readonly CorpusSample[]): DetectorScore;
+/**
+ * Score every detector against every source, keeping sources apart.
+ *
+ * Sources are never merged. A detector tuned on one corpus routinely collapses on
+ * another, and a combined figure would report the average of a good result and a
+ * bad one as though it were a single fact.
+ */
+declare function scoreAll(detectors: readonly EvalDetector[], bySource: ReadonlyMap<string, readonly CorpusSample[]>): DetectorScore[];
+/** Render scores as a report, marking any figure too small to be a claim. */
+declare function formatScores(scores: readonly DetectorScore[]): string;
+export { formatScores, scoreAll, scoreDetector };

package/esm/src/guardrails/eval/score.js

@@ -0,0 +1,114 @@
+/**
+ * Scoring for guardrail evaluation.
+ *
+ * Reports per detector, per source, and per benign category. Never a single
+ * pooled number: pooling hides which kind of content a detector misfires on, and
+ * "security documentation" and "work email" fail for different reasons.
+ *
+ * The false-positive rate is the number that decides whether a detector ships. A
+ * detector that fires on legitimate content does not make an agent careful; it
+ * makes it unreliable in ways a user cannot see the reason for.
+ *
+ * @module
+ */
+function rate(n, of) {
+    return of === 0 ? undefined : n / of;
+}
+/** Score one detector against one source's samples. */
+function scoreDetector(detector, source, samples) {
+    const attacks = samples.filter((s) => s.attack);
+    const benign = samples.filter((s) => !s.attack);
+    const accountable = detector.accountableFor.includes(source);
+    const caught = attacks.filter((s) => detector.fires(s.text)).length;
+    const falsePositives = benign.filter((s) => detector.fires(s.text)).length;
+    const categories = new Map();
+    for (const sample of benign) {
+        const entry = categories.get(sample.category) ?? { samples: 0, fired: 0 };
+        entry.samples++;
+        if (detector.fires(sample.text)) {
+            entry.fired++;
+        }
+        categories.set(sample.category, entry);
+    }
+    return {
+        detector: detector.id,
+        action: detector.action,
+        source,
+        attacks: accountable ? attacks.length : 0,
+        attacksCaught: accountable ? caught : 0,
+        recall: accountable ? rate(caught, attacks.length) : undefined,
+        benign: benign.length,
+        falsePositives,
+        falsePositiveRate: rate(falsePositives, benign.length),
+        byCategory: [...categories.entries()]
+            .map(([category, entry]) => ({
+            category,
+            samples: entry.samples,
+            fired: entry.fired,
+            rate: entry.samples === 0 ? 0 : entry.fired / entry.samples,
+        }))
+            .sort((a, b) => b.rate - a.rate),
+    };
+}
+/**
+ * Score every detector against every source, keeping sources apart.
+ *
+ * Sources are never merged. A detector tuned on one corpus routinely collapses on
+ * another, and a combined figure would report the average of a good result and a
+ * bad one as though it were a single fact.
+ */
+function scoreAll(detectors, bySource) {
+    const out = [];
+    for (const detector of detectors) {
+        for (const [source, samples] of bySource) {
+            if (samples.length > 0) {
+                out.push(scoreDetector(detector, source, samples));
+            }
+        }
+    }
+    return out;
+}
+function pct(value) {
+    return value === undefined ? '   —  ' : `${(value * 100).toFixed(1).padStart(5)}%`;
+}
+/** Sample count below which a rate is noise rather than a measurement. */
+const MEANINGFUL_N = 200;
+function groupScoresByDetector(scores) {
+    const byDetector = new Map();
+    for (const score of scores) {
+        byDetector.set(score.detector, [...(byDetector.get(score.detector) ?? []), score]);
+    }
+    return byDetector;
+}
+function formatRecall(score) {
+    if (score.recall === undefined) {
+        return 'recall     n/a        ';
+    }
+    return `recall ${pct(score.recall)} (${score.attacksCaught}/${score.attacks})`;
+}
+function formatSourceLine(score) {
+    const thin = score.benign > 0 && score.benign < MEANINGFUL_N ? '  [n too small]' : '';
+    return (`  ${score.source.padEnd(24)} ${formatRecall(score)}` +
+        `   false+ ${pct(score.falsePositiveRate)} (${score.falsePositives}/${score.benign})${thin}`);
+}
+function formatFiredCategories(score) {
+    const lines = [];
+    for (const category of score.byCategory) {
+        if (category.fired <= 0)
+            continue;
+        lines.push(`      ${category.category.padEnd(22)} ${pct(category.rate)} (${category.fired}/${category.samples})`);
+    }
+    return lines;
+}
+/** Render scores as a report, marking any figure too small to be a claim. */
+function formatScores(scores) {
+    const lines = [];
+    for (const [detector, group] of groupScoresByDetector(scores)) {
+        lines.push(`\n${detector}  (on fire: ${group[0]?.action ?? 'unknown'})`);
+        for (const score of group) {
+            lines.push(formatSourceLine(score), ...formatFiredCategories(score));
+        }
+    }
+    return lines.join('\n');
+}
+export { formatScores, scoreAll, scoreDetector };

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

@@ -0,0 +1,25 @@
+/**
+ * Turn-event constructors for guardrail decisions.
+ *
+ * Keeps `{ type: 'guardrail', guardrail }` shaping in one place so sanitize,
+ * egress, tools, network, and live paths cannot drift.
+ *
+ * @module
+ */
+import type { TurnEvent } from '../kernel/types.js';
+import type { GuardrailAction, GuardrailEvent, GuardrailHit, GuardrailStage, Provenance, TrustLevel, Verdict } from './types.js';
+/** Wrap a GuardrailEvent as a turn stream event. */
+declare function guardrailTurnEvent(guardrail: GuardrailEvent): TurnEvent;
+/**
+ * Build a turn event from a Verdict. `allow` yields nothing (clean = silence).
+ * `flag` / `redact` / `block` all emit so hosts and traces can count hits.
+ */
+declare function guardrailFromVerdict(stage: GuardrailStage, trust: TrustLevel, verdict: Verdict, provenance?: Provenance): TurnEvent | undefined;
+/** Build a turn event from a hit list. Empty hits → undefined. */
+declare function guardrailFromHits(stage: GuardrailStage, trust: TrustLevel, hits: GuardrailHit[], action?: GuardrailAction, provenance?: Provenance): TurnEvent | undefined;
+/**
+ * Project a guardrail turn event for host/trace: strip `hit.match` unless opted in.
+ * Non-guardrail events pass through unchanged.
+ */
+declare function projectGuardrailTurnEvent(event: TurnEvent, includeMatch: boolean): TurnEvent;
+export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent };

package/esm/src/guardrails/events.js

@@ -0,0 +1,56 @@
+/**
+ * Turn-event constructors for guardrail decisions.
+ *
+ * Keeps `{ type: 'guardrail', guardrail }` shaping in one place so sanitize,
+ * egress, tools, network, and live paths cannot drift.
+ *
+ * @module
+ */
+import { projectGuardrailEvent } from './hits.js';
+/** Wrap a GuardrailEvent as a turn stream event. */
+function guardrailTurnEvent(guardrail) {
+    return { type: 'guardrail', guardrail };
+}
+/**
+ * Build a turn event from a Verdict. `allow` yields nothing (clean = silence).
+ * `flag` / `redact` / `block` all emit so hosts and traces can count hits.
+ */
+function guardrailFromVerdict(stage, trust, verdict, provenance) {
+    if (verdict.action === 'allow') {
+        return undefined;
+    }
+    return guardrailTurnEvent({
+        stage,
+        trust,
+        action: verdict.action,
+        hits: verdict.hits,
+        ...(provenance ? { provenance } : {}),
+    });
+}
+/** Build a turn event from a hit list. Empty hits → undefined. */
+function guardrailFromHits(stage, trust, hits, action = 'redact', provenance) {
+    if (hits.length === 0) {
+        return undefined;
+    }
+    return guardrailTurnEvent({
+        stage,
+        trust,
+        action,
+        hits,
+        ...(provenance ? { provenance } : {}),
+    });
+}
+/**
+ * Project a guardrail turn event for host/trace: strip `hit.match` unless opted in.
+ * Non-guardrail events pass through unchanged.
+ */
+function projectGuardrailTurnEvent(event, includeMatch) {
+    if (event.type !== 'guardrail' || !event.guardrail) {
+        return event;
+    }
+    return {
+        ...event,
+        guardrail: projectGuardrailEvent(event.guardrail, includeMatch),
+    };
+}
+export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent };

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

@@ -0,0 +1,24 @@
+/**
+ * Guardrail hit helpers — match previews and host/trace projection.
+ *
+ * Detectors may attach `match` (the exact substring). Projection strips it unless
+ * the host opted into `observability.include.guardrailMatchPreview`.
+ *
+ * @module
+ */
+import type { GuardrailEvent, GuardrailHit, Severity } from './types.js';
+/** Cap for `GuardrailHit.match` so PEM / long blobs do not explode logs. */
+declare const GUARDRAIL_MATCH_PREVIEW_MAX = 512;
+/** Slice + cap the matched substring for debugging. */
+declare function matchPreview(text: string, start: number, end: number): string;
+/** Build a span hit with an optional match preview from the inspected text. */
+declare function hitFromSpan(text: string, span: {
+    start: number;
+    end: number;
+}, rule: string, severity: Severity): GuardrailHit;
+/**
+ * Strip or keep `match` on hits.
+ * Default host/trace posture is strip — opt in via profile observability.
+ */
+declare function projectGuardrailEvent(event: GuardrailEvent, includeMatch: boolean): GuardrailEvent;
+export { GUARDRAIL_MATCH_PREVIEW_MAX, hitFromSpan, matchPreview, projectGuardrailEvent };

package/esm/src/guardrails/hits.js

@@ -0,0 +1,45 @@
+/**
+ * Guardrail hit helpers — match previews and host/trace projection.
+ *
+ * Detectors may attach `match` (the exact substring). Projection strips it unless
+ * the host opted into `observability.include.guardrailMatchPreview`.
+ *
+ * @module
+ */
+/** Cap for `GuardrailHit.match` so PEM / long blobs do not explode logs. */
+const GUARDRAIL_MATCH_PREVIEW_MAX = 512;
+/** Slice + cap the matched substring for debugging. */
+function matchPreview(text, start, end) {
+    const raw = text.slice(start, end);
+    if (raw.length <= GUARDRAIL_MATCH_PREVIEW_MAX) {
+        return raw;
+    }
+    return `${raw.slice(0, GUARDRAIL_MATCH_PREVIEW_MAX)}…`;
+}
+/** Build a span hit with an optional match preview from the inspected text. */
+function hitFromSpan(text, span, rule, severity) {
+    return {
+        rule,
+        severity,
+        span: { start: span.start, end: span.end },
+        match: matchPreview(text, span.start, span.end),
+    };
+}
+/**
+ * Strip or keep `match` on hits.
+ * Default host/trace posture is strip — opt in via profile observability.
+ */
+function projectGuardrailEvent(event, includeMatch) {
+    if (includeMatch) {
+        return event;
+    }
+    return {
+        ...event,
+        hits: event.hits.map(({ rule, severity, span }) => ({
+            rule,
+            severity,
+            ...(span ? { span } : {}),
+        })),
+    };
+}
+export { GUARDRAIL_MATCH_PREVIEW_MAX, hitFromSpan, matchPreview, projectGuardrailEvent };

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

@@ -0,0 +1,39 @@
+/**
+ * Kernel lexicon — the registered defaults for every English string the kernel
+ * may emit toward a user or a model.
+ *
+ * "Host decides, Theorum runs": the kernel may ship overridable defaults for
+ * mechanism text, never unreplaceable copy. Every kernel emit-site imports its
+ * string from here, so a host can replace all of them in one place
+ * (`overrideLexicon`), and the copy-manifest lint
+ * (`scripts/docs-truth/copy-lint.mjs`) fails the build when prose appears
+ * anywhere else in `src/kernel`, `src/guardrails`, or `src/interface`.
+ *
+ * Imports `TheorumError` from `./theorum-error.ts` (not `./error.ts`) to avoid
+ * a cycle — `error.ts` resolves public-safe copy through this module.
+ *
+ * @module
+ */
+/** Substitution parameters for a lexicon template. */
+export type LexiconParams = Record<string, string | number>;
+/** Registered default strings the kernel can emit. Keys are stable API. */
+export declare const LEXICON_KEYS: readonly ["continue.instruction", "canary.bind_note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "advisory.notice_elevated", "advisory.notice_high", "attachments.too_many_files", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "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", "repair.default_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "egress.default_repair_guidance", "session.abandon_gated", "session.tool_denied", "tool.awaiting_user", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.output_invalid", "tool.not_wired_t1", "tool.not_loaded_t2", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type"];
+export type LexiconKey = (typeof LEXICON_KEYS)[number];
+/** Host-supplied replacement templates, `{param}` placeholders included. */
+export type LexiconOverrides = Partial<Record<LexiconKey, string>>;
+/**
+ * Replace registered defaults with host copy. Follows the
+ * `registerTraceDestination` pattern: process-level registration owned by the
+ * host. Templates keep `{param}` placeholders; mechanism-critical placeholders
+ * (the canary token) are validated here.
+ */
+export declare function overrideLexicon(entries: LexiconOverrides): void;
+/** Drop all host overrides (tests / host teardown). */
+export declare function resetLexicon(): void;
+/**
+ * Resolve one string: explicit host template (per call site, e.g. a profile
+ * field) → process override → registered default.
+ */
+export declare function lexiconText(key: LexiconKey, params?: LexiconParams, hostTemplate?: string): string;
+/** The registered default for a key, rendered with `params`. Ignores overrides. */
+export declare function lexiconDefault(key: LexiconKey, params?: LexiconParams): string;