theorum 0.1.2

package/docs/SECRETS.md

@@ -0,0 +1,55 @@
+# Theorum Provider Configuration Guide
+
+Theorum does not own secrets and does not read environment variables.
+
+Host applications own credentials, runtime configuration, and secret storage. Theorum receives provider configuration as explicit function arguments.
+
+## 1. Package Boundary
+
+- Do not create `.env` files in this repository.
+- Do not commit key templates to this repository.
+- Do not teach Theorum to discover keys from the shell or process environment.
+- Business applications pass credentials into provider constructors or transport objects.
+
+## 2. OpenRouter
+
+```ts
+import { createOpenRouterProvider } from 'theorum/openrouter';
+
+const provider = createOpenRouterProvider({
+  apiKey: hostResolvedOpenRouterKey,
+});
+```
+
+## 3. Google Interactions
+
+```ts
+import { createInteractionsProvider } from 'theorum/providers';
+
+const provider = createInteractionsProvider({
+  vault: {
+    freeA: hostResolvedFreeAKey,
+    freeB: hostResolvedFreeBKey,
+    freeC: hostResolvedFreeCKey,
+    paid: hostResolvedPaidKey,
+  },
+});
+```
+
+## 4. Tracing
+
+Tracing is silent by default. Hosts opt in by passing a sink to `runTurn`.
+
+```ts
+import { jsonlSink, runTurn } from 'theorum';
+
+for await (const event of runTurn(request, provider, jsonlSink(hostTraceDir))) {
+  // stream events
+}
+```
+
+For live verification, pass credentials explicitly:
+
+```bash
+deno run --allow-net scripts/verify-live.ts --api-key "<host-resolved-key>"
+```

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,11 @@
+declare global {
+    interface Object {
+        /**
+         * Determines whether an object has a property with the specified name.
+         * @param o An object.
+         * @param v A property name.
+         */
+        hasOwn(o: object, v: PropertyKey): boolean;
+    }
+}
+export {};

package/esm/_dnt.polyfills.js

@@ -0,0 +1,15 @@
+// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
+if (!Object.hasOwn) {
+    Object.defineProperty(Object, "hasOwn", {
+        value: function (object, property) {
+            if (object == null) {
+                throw new TypeError("Cannot convert undefined or null to object");
+            }
+            return Object.prototype.hasOwnProperty.call(Object(object), property);
+        },
+        configurable: true,
+        enumerable: false,
+        writable: true,
+    });
+}
+export {};

package/esm/_dnt.shims.d.ts

@@ -0,0 +1,5 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+export declare const dntGlobalThis: Omit<typeof globalThis, "Deno"> & {
+    Deno: typeof Deno;
+};

package/esm/_dnt.shims.js

@@ -0,0 +1,61 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+const dntGlobals = {
+    Deno,
+};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/esm/mod.d.ts

@@ -0,0 +1,37 @@
+/**
+ * THEORUM public API.
+ *
+ * Import this entrypoint when an application wants the complete kernel surface:
+ * profile registration, turn execution, provider constructors, guardrails,
+ * observability sinks, and public type contracts.
+ *
+ * @example
+ * ```ts
+ * import { defineProfile, registerProfile, runTurn } from "jsr:@theorum/core";
+ *
+ * const profile = defineProfile({
+ *   id: "assistant.basic",
+ *   model: { allow: ["gemini35FlashLite"] },
+ *   tools: { allow: [] },
+ *   inputs: { text: true },
+ *   outputs: {},
+ *   guardrails: { quota: { perDay: 100 } },
+ * });
+ *
+ * registerProfile(profile);
+ * ```
+ *
+ * @module
+ */
+import "./_dnt.polyfills.js";
+export { publicError, TheorumError } from './src/guardrails/error.js';
+export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
+export { runTurn } from './src/kernel/engine/runner.js';
+export { defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
+export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
+export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';
+export { executeTool } from './src/kernel/registry/tools.js';
+export type * from './src/kernel/types.js';
+export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './src/observability/trace.js';
+export type { TraceRecord } from './src/observability/trace-record.js';
+export { createInteractionsProvider, createOpenRouterProvider, createOpenRouterTtsProvider, resolveOpenRouterApiKey, resolveOpenRouterModel, streamOpenRouterTts, toOpenRouterPayload, wrapPcmAsWav, } from './src/providers/mod.js';

package/esm/mod.js

@@ -0,0 +1,35 @@
+/**
+ * THEORUM public API.
+ *
+ * Import this entrypoint when an application wants the complete kernel surface:
+ * profile registration, turn execution, provider constructors, guardrails,
+ * observability sinks, and public type contracts.
+ *
+ * @example
+ * ```ts
+ * import { defineProfile, registerProfile, runTurn } from "jsr:@theorum/core";
+ *
+ * const profile = defineProfile({
+ *   id: "assistant.basic",
+ *   model: { allow: ["gemini35FlashLite"] },
+ *   tools: { allow: [] },
+ *   inputs: { text: true },
+ *   outputs: {},
+ *   guardrails: { quota: { perDay: 100 } },
+ * });
+ *
+ * registerProfile(profile);
+ * ```
+ *
+ * @module
+ */
+import "./_dnt.polyfills.js";
+export { publicError, TheorumError } from './src/guardrails/error.js';
+export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
+export { runTurn } from './src/kernel/engine/runner.js';
+export { defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
+export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
+export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';
+export { executeTool } from './src/kernel/registry/tools.js';
+export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './src/observability/trace.js';
+export { createInteractionsProvider, createOpenRouterProvider, createOpenRouterTtsProvider, resolveOpenRouterApiKey, resolveOpenRouterModel, streamOpenRouterTts, toOpenRouterPayload, wrapPcmAsWav, } from './src/providers/mod.js';

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

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

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ *
+ * @module
+ */
+/** Error class used for expected THEORUM contract failures. */
+declare class TheorumError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/** 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.";
+/** Convert an unknown thrown value or internal message to user-safe text. */
+declare function publicError(err: unknown): string;
+/** Backwards-compatible alias for `publicError`. */
+declare function errorMessage(err: unknown): string;
+export { errorMessage, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, };

package/esm/src/guardrails/error.js

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ *
+ * @module
+ */
+/** Error class used for expected THEORUM contract failures. */
+class TheorumError extends Error {
+    constructor(message = '', options) {
+        super(message, options);
+        this.name = 'TheorumError';
+    }
+}
+/** 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.";
+const EXACT = {
+    [UPSTREAM_FAILED]: PUBLIC_UNAVAILABLE,
+    'empty Gemini stream': PUBLIC_UNAVAILABLE,
+    'canary leaked': PUBLIC_CANARY,
+    'Turn withheld: egress disclosure violation': PUBLIC_CANARY,
+    'expected JSON object': 'Something was wrong with that request.',
+    '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,
+    'askUser.kind must be confirm, choice, or text': "That question isn't valid.",
+    'askUser.prompt is required': 'That question needs a prompt.',
+    'This profile does not accept text input': PUBLIC_ACTION,
+};
+const RULES = [
+    {
+        match: (t) => /^(Gemini|OpenRouter|TTS|OpenRouter TTS) HTTP/.test(t) || t.includes('TTS HTTP'),
+        resolve: () => PUBLIC_UNAVAILABLE,
+    },
+    {
+        match: (t) => t.includes('not gated') ||
+            t.includes('not allowed') ||
+            t.includes('has no kernel executor') ||
+            t.includes('Unknown model select') ||
+            t.includes('Grounding tools'),
+        resolve: () => 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) => t.startsWith('At most'),
+        resolve: () => PUBLIC_FILE_COUNT,
+    },
+    {
+        match: (t) => (t.startsWith('Only ') && t.includes('file')) ||
+            t.startsWith('Each file must be') ||
+            t.startsWith('Those files together'),
+        resolve: (t) => t,
+    },
+    {
+        match: (t) => t.includes('attachment'),
+        resolve: () => PUBLIC_FILE_SIZE,
+    },
+    {
+        match: (t) => t.includes('aspect or size'),
+        resolve: () => PUBLIC_IMAGE_SIZE,
+    },
+    {
+        match: (t) => t.includes('must pin thinking') || t.includes('has no models'),
+        resolve: () => PUBLIC_GENERIC,
+    },
+];
+function publicText(text) {
+    const exact = EXACT[text];
+    if (exact) {
+        return exact;
+    }
+    for (const rule of RULES) {
+        if (rule.match(text)) {
+            return rule.resolve(text);
+        }
+    }
+    return PUBLIC_GENERIC;
+}
+/** Convert an unknown thrown value or internal message to user-safe text. */
+function publicError(err) {
+    if (typeof err === 'string') {
+        return publicText(err);
+    }
+    if (err instanceof TheorumError) {
+        return publicText(err.message);
+    }
+    return PUBLIC_UNAVAILABLE;
+}
+/** Backwards-compatible alias for `publicError`. */
+function errorMessage(err) {
+    return publicError(err);
+}
+export { errorMessage, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, };

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

@@ -0,0 +1,12 @@
+/**
+ * Prompt-injection span detection.
+ *
+ * These utilities return spans that can be redacted from untrusted user text
+ * before provider submission.
+ *
+ * @module
+ */
+import { type RedactSpan } from '../observability/spans.js';
+/** Detect prompt-injection spans in a string. */
+declare function injectionSpans(text: string): RedactSpan[];
+export { injectionSpans };

package/esm/src/guardrails/injection.js

@@ -0,0 +1,220 @@
+/**
+ * Prompt-injection span detection.
+ *
+ * These utilities return spans that can be redacted from untrusted user text
+ * before provider submission.
+ *
+ * @module
+ */
+import { blobAt, spansFromPatterns } from '../observability/spans.js';
+const IGNORE_PREVIOUS = /ignore\s+(all\s+)?(previous|prior)\s+((?:safety|security|system|operational|internal|core|original|initial|existing|given|stated|provided|defined|specified|established)\s+)?(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const DISREGARD_INSTRUCTIONS = /disregard\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const FORGET_INSTRUCTIONS = /forget\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const NEW_INSTRUCTIONS = /new\s+instructions?:/gi;
+const DO_NOT_FOLLOW = /do\s+not\s+follow\s+(the\s+)?(system|developer|previous|original)/gi;
+const SUPERSEDE_INSTRUCTIONS = /supersedes?\s+(all\s+)?(prior|previous)\s+(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const VOID_INSTRUCTIONS = /(all\s+)?(previous|prior)\s+instructions?\s+(are|is)\s+(void|invalid|null|obsolete|cancelled|revoked)/gi;
+const DEVELOPER_MODE = /you\s+are\s+now\s+(in\s+)?developer\s+mode/gi;
+const ENTER_SPECIAL_MODE = /enter\s+(developer|admin|debug|maintenance)\s+mode/gi;
+const ACTIVATE_SPECIAL_MODE = /activate\s+(developer|admin|debug|jailbreak)\s+mode/gi;
+const SYSTEM_OVERRIDE = /\bsystem\s+override\b/gi;
+const OVERRIDE_INSTRUCTIONS = /override\s+(your\s+)?(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const REVEAL_PROMPT = /reveal\s+((?:your?|yoru|yuor|the|my|its|his|her|our|their)\s+)?((?:(?:full|hidden|complete|internal|secret|original|entire|exact|actual|real)\s+){0,2})((?:system|systme|sysetm|systemp?)\s+)?prompt\b/gi;
+const SHOW_PROMPT = /show\s+(me\s+)?((?:your?|yoru|yuor|the|my|its|his|her|our|their)\s+)((?:system|systme|sysetm|systemp?)\s+)?prompt\b/gi;
+const WHAT_INSTRUCTIONS = /what\s+(are|were)\s+(your\s+)?(exact\s+)?instructions/gi;
+const REPEAT_INSTRUCTIONS = /repeat\s+(the\s+)?(text|instructions?)\s+(above|before)/gi;
+const OUTPUT_PROMPT = /output\s+(your\s+)?(initial|original|system)\s+(prompt|instructions?)/gi;
+const REMOVE_RESTRICTIONS = /you\s+are\s+no\s+longer\s+(bound|restricted|limited)/gi;
+const ACT_UNBOUND = /act\s+as\s+if\s+(you('re|\s+are)\s+)?not\s+bound/gi;
+const PRETEND_DIFFERENT = /pretend\s+(you('re|\s+are)\s+)?(a\s+)?different\s+(ai|assistant|model)/gi;
+const IDENTITY_HIJACK = /you\s+are\s+now\s+(?:(?:a|an)\s+)?\w+.{0,40}(without\s+(any\s+)?restrict|ignor\w*\s+(all|any|every|prev)|bypass|unrestrict|unlimit|obey\s+only|no\s+(rules|limits|restrict|boundari))/gi;
+const DAN_JAILBREAK = /\bDAN\b[\s\S]{0,120}\bdo\s+anything\s+now\b/g;
+const JAILBREAK_MODE = /jailbreak(ed)?\s+(mode|prompt)/gi;
+const DO_ANYTHING_NOW = /\bdo\s+anything\s+now\b/gi;
+const BYPASS_SAFETY = /bypass\s+(your\s+)?(safety|security|content|ethical)\s+(filters?|measures?|guidelines?|restrictions?)/gi;
+const DISABLE_SAFETY = /disable\s+(your\s+)?(safety|security|content)\s+(filters?|measures?)/gi;
+const IGNORE_SAFETY = /(ignore|disregard)\s+(all\s+)?(your\s+)?(safety|security|ethical|content)\s+(guidelines?|rules?|restrictions?|measures?|filters?|polic(?:y|ies)|protocols?)/gi;
+const SYSTEM_TAG = /<\s*\/?\s*system\s*\/?>/gi;
+const ROLE_TAG = /<\s*\/?\s*(assistant|developer|tool|function)\s*\/?>/gi;
+const ROLE_DELIMITER = /\]\s*\n\s*\[?(system|assistant|user)\]?:/gi;
+const BRACKETED_ROLE = /\[\s*(System\s*Message|System|Assistant|Internal)\s*\]/gi;
+const SYSTEM_YOU_ARE = /^\s*System:\s+(you\s+are|ignore|override)/gim;
+const CONTROL_TOKEN = /<\|(?:im_start|im_end|eot_id|start_header_id|end_header_id|endoftext)\|>/g;
+const DEEPSEEK_CONTROL = /<\uFF5C(?:end\u2581of\u2581sentence|begin\u2581of\u2581sentence)\uFF5C>/g;
+const LLAMA_INST = /\[\/?INST\]/gi;
+const IGNORE_YOUR_INSTRUCTIONS = /ignore\s+(all\s+)?(your\s+)?(instructions?|rules?)\b/gi;
+const UNRESTRICTED_MODE = /\bunrestricted\s+(ai|mode|model)\b/gi;
+const INJECTION_PATTERNS = [
+    IGNORE_PREVIOUS,
+    DISREGARD_INSTRUCTIONS,
+    FORGET_INSTRUCTIONS,
+    NEW_INSTRUCTIONS,
+    DO_NOT_FOLLOW,
+    SUPERSEDE_INSTRUCTIONS,
+    VOID_INSTRUCTIONS,
+    DEVELOPER_MODE,
+    ENTER_SPECIAL_MODE,
+    ACTIVATE_SPECIAL_MODE,
+    SYSTEM_OVERRIDE,
+    OVERRIDE_INSTRUCTIONS,
+    REVEAL_PROMPT,
+    SHOW_PROMPT,
+    WHAT_INSTRUCTIONS,
+    REPEAT_INSTRUCTIONS,
+    OUTPUT_PROMPT,
+    REMOVE_RESTRICTIONS,
+    ACT_UNBOUND,
+    PRETEND_DIFFERENT,
+    IDENTITY_HIJACK,
+    DAN_JAILBREAK,
+    JAILBREAK_MODE,
+    DO_ANYTHING_NOW,
+    BYPASS_SAFETY,
+    DISABLE_SAFETY,
+    IGNORE_SAFETY,
+    SYSTEM_TAG,
+    ROLE_TAG,
+    ROLE_DELIMITER,
+    BRACKETED_ROLE,
+    SYSTEM_YOU_ARE,
+    CONTROL_TOKEN,
+    DEEPSEEK_CONTROL,
+    LLAMA_INST,
+    IGNORE_YOUR_INSTRUCTIONS,
+    UNRESTRICTED_MODE,
+];
+const TYPO_TARGETS = [
+    'ignore',
+    'bypass',
+    'override',
+    'reveal',
+    'delete',
+    'system',
+    'prompt',
+    'instructions',
+];
+const BASE64_BLOB = /[A-Za-z0-9+/]{16,}={0,2}/g;
+const HEX_BLOB = /(?:[0-9a-f]{2}[\s]?){8,}/gi;
+const SPACED_LETTERS = /\b(?:[A-Za-z] ){3,}[A-Za-z]\b/g;
+const WORD = /\b[A-Za-z]{4,}\b/g;
+const PRINTABLE_MIN = 0.85;
+const CODE_TAB = 9;
+const CODE_LF = 10;
+const CODE_CR = 13;
+const CODE_SPACE = 32;
+const CODE_DEL = 127;
+const HEX_RADIX = 16;
+const HEX_STEP = 2;
+function injectionSpansOn(text) {
+    return spansFromPatterns(text, INJECTION_PATTERNS, 'injection');
+}
+function sortedLetters(value) {
+    return [...value].sort().join('');
+}
+function firstLast(word) {
+    return { first: word.at(0), last: word.at(-1) };
+}
+function isTypoglycemia(word, target) {
+    if (word.length !== target.length) {
+        return false;
+    }
+    const lower = word.toLowerCase();
+    if (lower === target) {
+        return false;
+    }
+    const wordEnds = firstLast(lower);
+    const targetEnds = firstLast(target);
+    if (wordEnds.first !== targetEnds.first || wordEnds.last !== targetEnds.last) {
+        return false;
+    }
+    return sortedLetters(lower.slice(1, -1)) === sortedLetters(target.slice(1, -1));
+}
+function typoNormalize(text) {
+    return text.replace(WORD, (word) => {
+        for (const target of TYPO_TARGETS) {
+            if (isTypoglycemia(word, target)) {
+                return target;
+            }
+        }
+        return word;
+    });
+}
+function isMostlyPrintable(value) {
+    if (!value) {
+        return false;
+    }
+    let ok = 0;
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        const control = code === CODE_TAB || code === CODE_LF || code === CODE_CR;
+        const visible = code >= CODE_SPACE && code < CODE_DEL;
+        if (control || visible) {
+            ok += 1;
+        }
+    }
+    return ok / value.length >= PRINTABLE_MIN;
+}
+function decodedHits(decoded) {
+    if (!isMostlyPrintable(decoded)) {
+        return false;
+    }
+    return injectionSpansOn(decoded).length > 0;
+}
+function tryBase64(blob) {
+    try {
+        return atob(blob);
+    }
+    catch {
+        return undefined;
+    }
+}
+function tryHex(blob) {
+    const hex = blob.replaceAll(/\s/g, '');
+    if (hex.length % HEX_STEP !== 0) {
+        return undefined;
+    }
+    let out = '';
+    for (let i = 0; i < hex.length; i += HEX_STEP) {
+        out += String.fromCodePoint(Number.parseInt(hex.slice(i, i + HEX_STEP), HEX_RADIX));
+    }
+    return out;
+}
+function encodedFrom(text, pattern, decode) {
+    const spans = [];
+    for (const match of text.matchAll(pattern)) {
+        const found = blobAt(match);
+        if (found) {
+            const decoded = decode(found.blob);
+            if (decoded && decodedHits(decoded)) {
+                spans.push({ start: found.index, end: found.index + found.blob.length, kind: 'injection' });
+            }
+        }
+    }
+    return spans;
+}
+function encodedSpans(text) {
+    return [...encodedFrom(text, BASE64_BLOB, tryBase64), ...encodedFrom(text, HEX_BLOB, tryHex)];
+}
+function spacedSpans(text) {
+    const spans = [];
+    for (const match of text.matchAll(SPACED_LETTERS)) {
+        const found = blobAt(match);
+        if (found) {
+            const collapsed = found.blob.replaceAll(' ', '');
+            if (injectionSpansOn(`${collapsed} previous instructions`).length > 0) {
+                spans.push({ start: found.index, end: found.index + found.blob.length, kind: 'injection' });
+            }
+        }
+    }
+    return spans;
+}
+/** Detect prompt-injection spans in a string. */
+function injectionSpans(text) {
+    const shadow = typoNormalize(text);
+    let typo = [];
+    if (shadow !== text) {
+        typo = injectionSpansOn(shadow);
+    }
+    return [...injectionSpansOn(text), ...typo, ...encodedSpans(text), ...spacedSpans(text)];
+}
+export { injectionSpans };

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

@@ -0,0 +1,12 @@
+import type { BuiltinToolId, GeminiBucket, GeminiFreeBucket, ModelId } from '../kernel/types.js';
+type GeminiVault = Record<GeminiBucket, string | undefined>;
+interface GeminiTransport {
+    vault: GeminiVault;
+    wait?: (ms: number) => Promise<void>;
+    fetch?: typeof fetch;
+}
+declare function resolveGeminiBucket(free: GeminiFreeBucket, model: ModelId, builtins: BuiltinToolId[]): GeminiBucket;
+declare function withGeminiKey<T>(bucket: GeminiBucket, run: (apiKey: string) => Promise<T>, transport: GeminiTransport): Promise<T>;
+declare function fetchGemini(url: string, init: RequestInit, bucket: GeminiBucket, transport: GeminiTransport): Promise<Response>;
+export type { GeminiTransport, GeminiVault };
+export { fetchGemini, resolveGeminiBucket, withGeminiKey };