@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -6,51 +6,42 @@
  *
  * @module
  */
-/** Injection phrasing or sensitive data stripped from text entering the turn. */
-export declare const SANITIZE_RULES: {
-    readonly injection: "sanitize.injection";
-    readonly sensitive: "sanitize.sensitive";
+/** What a detector found, the same id at every boundary; the event names the boundary. */
+export declare const DETECT_RULES: {
+    readonly ids: "detect.ids";
+    readonly financial: "detect.financial";
+    readonly network: "detect.network";
+    readonly credentials: "detect.credentials";
+    readonly injection: "detect.injection";
+    readonly tool_instructions: "detect.tool_instructions";
+    readonly canary_leak: "detect.canary_leak";
+    readonly prompt_leak: "detect.prompt_leak";
+    readonly marker_leak: "detect.marker_leak";
+    readonly ungiven_images: "detect.ungiven_images";
+    readonly ungiven_links: "detect.ungiven_links";
+    readonly tool_leak: "detect.tool_leak";
 };
-/** What the bundled egress policy finds in the model's outbound text. */
+/** The rule a match of `key` reports: a detector of Theorem's, or the id of one of the host's own (`detect.acme.record`). */
+export declare function detectRule(key: string): string;
+/** What stops a reply besides a detector's match. */
 export declare const EGRESS_RULES: {
-    readonly canary: "egress.canary-leak";
-    /** The reply repeats the system prompt (`guardrails.promptEcho`). */
-    readonly promptEcho: "egress.prompt-echo";
     /**
      * A provider-side built-in tool carried the canary or the system prompt. It
      * ran before Theorem saw it: the data already left, so this is an incident.
      */
     readonly providerToolLeak: "egress.provider-tool-leak";
-    readonly sensitive: "egress.sensitive-echo";
-    readonly boundary: "egress.system-boundary";
-    readonly injection: "egress.injection-echo";
-    /** An image loads a URL the model was not given, from a host not allowed. */
-    readonly image: "egress.image-exfil";
-    /** A link goes to a URL the model was not given, on a host not allowed. */
-    readonly link: "egress.link-exfil";
     /** Payload could not be rendered for inspection — released output is unverified. */
     readonly unscannable: "egress.unscannable";
-    readonly enforcerError: "egress.enforcer-error";
-    /** The progressive gate stopped the stream on a host verdict that named no rule. */
-    readonly blocked: "egress.blocked";
 };
-/** Remote tool content behaving like an instruction to the agent. */
-export declare const DIRECTIVE_RULES: {
-    readonly toolName: "tool_result.names-callable-tool";
-    readonly imperative: "tool_result.imperative";
-    readonly authority: "tool_result.authority-claim";
-};
-/** The tool boundary: results and failures redacted, and calls flagged or blocked. */
+/** A tool call refused for what the turn read before it. */
 export declare const TOOL_RULES: {
-    readonly resultRedacted: "tool_result.redacted";
-    readonly failureRedacted: "tool_failure.redacted";
-    readonly sensitiveArgument: "tool_call.sensitive-argument";
     readonly taintedTurn: "tool_call.tainted-turn";
     readonly steeredTurn: "tool_call.steered-turn";
+    readonly remoteDestination: "tool_call.remote-destination";
 };
 /** A tool's network target refused before any request was made. */
 export declare const NETWORK_RULES: {
     readonly blocked: "network.blocked";
 };
 /** A rule id Theorem's own guardrails report. */
-export type GuardrailRule = (typeof SANITIZE_RULES)[keyof typeof SANITIZE_RULES] | (typeof EGRESS_RULES)[keyof typeof EGRESS_RULES] | (typeof DIRECTIVE_RULES)[keyof typeof DIRECTIVE_RULES] | (typeof TOOL_RULES)[keyof typeof TOOL_RULES] | (typeof NETWORK_RULES)[keyof typeof NETWORK_RULES];
+export type GuardrailRule = (typeof DETECT_RULES)[keyof typeof DETECT_RULES] | (typeof EGRESS_RULES)[keyof typeof EGRESS_RULES] | (typeof TOOL_RULES)[keyof typeof TOOL_RULES] | (typeof NETWORK_RULES)[keyof typeof NETWORK_RULES];

package/esm/src/guardrails/rules.js

@@ -6,47 +6,40 @@
  *
  * @module
  */
-/** Injection phrasing or sensitive data stripped from text entering the turn. */
-export const SANITIZE_RULES = {
-    injection: 'sanitize.injection',
-    sensitive: 'sanitize.sensitive',
+/** What a detector found, the same id at every boundary; the event names the boundary. */
+export const DETECT_RULES = {
+    ids: 'detect.ids',
+    financial: 'detect.financial',
+    network: 'detect.network',
+    credentials: 'detect.credentials',
+    injection: 'detect.injection',
+    tool_instructions: 'detect.tool_instructions',
+    canary_leak: 'detect.canary_leak',
+    prompt_leak: 'detect.prompt_leak',
+    marker_leak: 'detect.marker_leak',
+    ungiven_images: 'detect.ungiven_images',
+    ungiven_links: 'detect.ungiven_links',
+    tool_leak: 'detect.tool_leak',
 };
-/** What the bundled egress policy finds in the model's outbound text. */
+/** The rule a match of `key` reports: a detector of Theorem's, or the id of one of the host's own (`detect.acme.record`). */
+export function detectRule(key) {
+    return `detect.${key}`;
+}
+/** What stops a reply besides a detector's match. */
 export const EGRESS_RULES = {
-    canary: 'egress.canary-leak',
-    /** The reply repeats the system prompt (`guardrails.promptEcho`). */
-    promptEcho: 'egress.prompt-echo', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     /**
      * A provider-side built-in tool carried the canary or the system prompt. It
      * ran before Theorem saw it: the data already left, so this is an incident.
      */
-    providerToolLeak: 'egress.provider-tool-leak', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    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)
-    /** An image loads a URL the model was not given, from a host not allowed. */
-    image: 'egress.image-exfil', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    /** A link goes to a URL the model was not given, on a host not allowed. */
-    link: 'egress.link-exfil', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    providerToolLeak: 'egress.provider-tool-leak', // labels-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)
-    enforcerError: 'egress.enforcer-error', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    /** The progressive gate stopped the stream on a host verdict that named no rule. */
-    blocked: 'egress.blocked',
+    unscannable: 'egress.unscannable', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
 };
-/** Remote tool content behaving like an instruction to the agent. */
-export const DIRECTIVE_RULES = {
-    toolName: 'tool_result.names-callable-tool',
-    imperative: 'tool_result.imperative',
-    authority: 'tool_result.authority-claim',
-};
-/** The tool boundary: results and failures redacted, and calls flagged or blocked. */
+/** A tool call refused for what the turn read before it. */
 export const TOOL_RULES = {
-    resultRedacted: 'tool_result.redacted',
-    failureRedacted: 'tool_failure.redacted',
-    sensitiveArgument: 'tool_call.sensitive-argument',
     taintedTurn: 'tool_call.tainted-turn',
     steeredTurn: 'tool_call.steered-turn',
+    remoteDestination: 'tool_call.remote-destination',
 };
 /** A tool's network target refused before any request was made. */
 export const NETWORK_RULES = {

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

@@ -1,23 +1,40 @@
-import type { NormalizedTurnRequest, Profile, TurnEvent, TurnRequest } from '../kernel/types.js';
-import { type DetectionOptions } from './policy.js';
-import type { GuardrailHit, TrustLevel } from './types.js';
-declare function detectText(text: string, options?: Partial<DetectionOptions>): {
-    text: string;
-    hits: GuardrailHit[];
+import type { NormalizedTurnRequest, Profile, TurnContext, TurnEvent, TurnHistoryMessage, TurnRequest } from '../kernel/types.js';
+import { type Boundary } from './boundaries.js';
+import { type BoundaryReader } from './detect-at.js';
+import { TheoremError } from './theorem-error.js';
+import type { GuardrailEvent } from './types.js';
+/** A context package as the model reads it: text as written, anything else as JSON. */
+declare function contextText(value: unknown): string;
+/** Each sender's package read at the `context` boundary, with what was found there. */
+declare function sanitizeContext(context: TurnContext | undefined, readerFor: () => BoundaryReader): {
+    context: TurnContext | undefined;
+    events: GuardrailEvent[];
+    blocked: boolean;
 };
-declare function sanitizeText(text: string, options?: Partial<DetectionOptions>): string;
-declare function redactSensitiveOnly(text: string): string;
+/** The project id trimmed, or `undefined` when it is empty or has illegal characters. */
 declare function sanitizeProjectId(id: string | undefined): string | undefined;
 /**
  * Exported because every path that injects messages into a turn needs it — turn
  * history, and host steer injects mid-turn. A second copy would drift.
  */
-declare function sanitizeHistory(history: import('../kernel/types.js').TurnHistoryMessage[], options: DetectionOptions, hits?: GuardrailHit[]): import('../kernel/types.js').TurnHistoryMessage[];
-declare function detectionForProfile(profile: Profile, trust: TrustLevel): DetectionOptions;
-declare function sanitizeTurnRequest(req: TurnRequest, profile: Profile): NormalizedTurnRequest;
-/** Attachments and voice are validated but emit no guardrail events. */
-declare function sanitizeTurnRequestWithEvents(req: TurnRequest, profile: Profile): {
+declare function sanitizeHistory(history: TurnHistoryMessage[], reader: BoundaryReader): TurnHistoryMessage[];
+/** The error a turn ends on when a detector set to `block` matched at `boundary`. */
+declare function requestRefused(boundary: Boundary): TheoremError;
+/** A turn request read at each boundary it crosses. */
+interface SanitizedTurnRequest {
     request: NormalizedTurnRequest;
+    /** One guardrail event for each boundary where something matched. */
     events: TurnEvent[];
-};
-export { detectionForProfile, detectText, redactSensitiveOnly, sanitizeHistory, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, };
+    /** Set when a match blocks: the request does not reach the model, and the turn ends on this. */
+    refusal?: TheoremError;
+}
+/**
+ * `req.system` is host-assembled per turn — it interpolates retrieval and user
+ * data, so it is read at its own boundary. `identity.system` never reaches this
+ * path and stays verbatim.
+ */
+declare function sanitizeTurnRequestWithEvents(req: TurnRequest, profile: Profile): SanitizedTurnRequest;
+/** The turn request with its input cleaned under the profile's guardrails. Throws when a match blocks it. */
+declare function sanitizeTurnRequest(req: TurnRequest, profile: Profile): NormalizedTurnRequest;
+export type { SanitizedTurnRequest };
+export { contextText, requestRefused, sanitizeContext, sanitizeHistory, sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, };

package/esm/src/guardrails/sanitize.js

@@ -1,67 +1,71 @@
 import { sanitizeTurnBlobs } from '../kernel/registry/attachments.js';
+import { CONTEXT_SENDERS } from '../kernel/schema.js';
 import { mapSystemPrompt } from '../kernel/system-parts.js';
-import { applySpans } from '../observability/spans.js';
-import { guardrailFromHits } from './events.js';
-import { hitFromSpan } from './hits.js';
-import { injectionSpans } from './injection.js';
-import { detectionForTrust, resolveGuardrailPolicy } from './policy.js';
-import { SANITIZE_RULES } from './rules.js';
-import { anySensitive, resolveSensitive, sensitiveSpans } from './sensitive.js';
-function detectText(text, options) {
-    const sanitizeInput = options?.sanitizeInput ?? true;
-    const groups = resolveSensitive(options?.redactSensitive);
-    if (!sanitizeInput && !anySensitive(groups)) {
-        return { text, hits: [] };
-    }
-    const spans = [...(sanitizeInput ? injectionSpans(text) : []), ...sensitiveSpans(text, groups)];
-    const hits = spans.map((span) => hitFromSpan(text, span, span.kind === 'injection' ? SANITIZE_RULES.injection : SANITIZE_RULES.sensitive, 'high'));
-    return { text: applySpans(text, spans), hits };
-}
-function sanitizeText(text, options) {
-    return detectText(text, options).text;
-}
-function redactSensitiveOnly(text) {
-    return detectText(text, { sanitizeInput: false, redactSensitive: true }).text;
-}
-function appendHits(into, hits) {
-    for (const hit of hits) {
-        into.push(hit);
-    }
-}
-function sanitizeSlots(slots, options, hits) {
+import { recordOf } from './boundaries.js';
+import { boundaryReader, detectEvent } from './detect-at.js';
+import { guardrailTurnEvent } from './events.js';
+import { resolveGuardrailPolicy } from './policy.js';
+import { TheoremError } from './theorem-error.js';
+/** The boundaries one turn request crosses, in the order their events are reported. */
+const REQUEST_BOUNDARIES = [
+    'user',
+    'slots',
+    'repair',
+    'attachment',
+    'voice',
+    'history',
+    'system',
+];
+function sanitizeSlots(slots, reader) {
     if (!slots) {
         return slots;
     }
-    const out = {};
-    for (const [key, value] of Object.entries(slots)) {
-        const detected = detectText(value, options);
-        appendHits(hits, detected.hits);
-        out[key] = detected.text;
+    return Object.fromEntries(Object.entries(slots).map(([key, value]) => [key, reader.read(value)]));
+}
+/** The browser's context is the visitor's to change; the host's is built by its own code, like turn system text. */
+const CONTEXT_TRUST = {
+    client: 'untrusted',
+    server: 'assembled',
+};
+/** A context package as the model reads it: text as written, anything else as JSON. */
+function contextText(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/** Each sender's package read at the `context` boundary, with what was found there. */
+function sanitizeContext(context, readerFor) {
+    const events = [];
+    let blocked = false;
+    if (!context)
+        return { context, events, blocked };
+    const read = {};
+    for (const sender of CONTEXT_SENDERS) {
+        const value = context[sender];
+        if (value === undefined)
+            continue;
+        const reader = readerFor();
+        read[sender] = reader.read(contextText(value));
+        const found = reader.found();
+        const event = detectEvent('context', found);
+        if (event)
+            events.push({ ...event, trust: CONTEXT_TRUST[sender] });
+        blocked ||= found.action === 'block';
     }
-    return out;
+    return { context: read, events, blocked };
 }
 const PROJECT_ID_OK = /^[A-Za-z0-9._-]+$/;
+/** The project id trimmed, or `undefined` when it is empty or has illegal characters. */
 function sanitizeProjectId(id) {
     const trimmed = id?.trim();
     return trimmed && PROJECT_ID_OK.test(trimmed) ? trimmed : undefined;
 }
-function sanitizeRepair(repair, options, hits) {
+function sanitizeRepair(repair, reader) {
     if (!repair) {
         return repair;
     }
-    const previous = detectText(repair.previousOutput, options);
-    const rejection = detectText(repair.rejection, options);
-    appendHits(hits, previous.hits);
-    appendHits(hits, rejection.hits);
-    let guidance = repair.guidance;
-    if (guidance) {
-        const detected = detectText(guidance, options);
-        appendHits(hits, detected.hits);
-        guidance = detected.text;
-    }
+    const guidance = repair.guidance ? reader.read(repair.guidance) : undefined;
     return {
-        previousOutput: previous.text,
-        rejection: rejection.text,
+        previousOutput: reader.read(repair.previousOutput),
+        rejection: reader.read(repair.rejection),
         ...(guidance ? { guidance } : {}),
     };
 }
@@ -69,25 +73,10 @@ function sanitizeRepair(repair, options, hits) {
  * Exported because every path that injects messages into a turn needs it — turn
  * history, and host steer injects mid-turn. A second copy would drift.
  */
-function sanitizeHistory(history, options, hits = []) {
+function sanitizeHistory(history, reader) {
     return history.map((m) => {
-        let content = m.content;
-        if (content !== undefined) {
-            const detected = detectText(content, options);
-            appendHits(hits, detected.hits);
-            content = detected.text;
-        }
-        let parts = m.parts;
-        if (parts) {
-            parts = parts.map((p) => {
-                if (p.type !== 'text') {
-                    return p;
-                }
-                const detected = detectText(p.text, options);
-                appendHits(hits, detected.hits);
-                return { ...p, text: detected.text };
-            });
-        }
+        const content = m.content === undefined ? undefined : reader.read(m.content);
+        const parts = m.parts?.map((p) => p.type === 'text' ? { ...p, text: reader.read(p.text) } : p);
         return {
             role: m.role,
             ...(content !== undefined ? { content } : {}),
@@ -96,53 +85,51 @@ function sanitizeHistory(history, options, hits = []) {
             ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {}),
             ...(m.name ? { name: m.name } : {}),
             ...(m.metadata ? { metadata: m.metadata } : {}),
+            // why: Google refuses a call from the current turn replayed without its thought signature, so a reply resumed after a gate needs it.
+            ...(m.reasoning ? { reasoning: m.reasoning } : {}),
         };
     });
 }
-function detectionForProfile(profile, trust) {
-    return detectionForTrust(resolveGuardrailPolicy(profile.guardrails), trust);
-}
-function pushStageEvent(events, stage, trust, hits) {
-    const event = guardrailFromHits(stage, trust, hits, 'redact');
-    if (event) {
-        events.push(event);
-    }
+/** The error a turn ends on when a detector set to `block` matched at `boundary`. */
+function requestRefused(boundary) {
+    // labels-exempt: developer contract / internal diagnostic — the user's wording is `detect.blocked`
+    return new TheoremError('input', `guardrails.detect blocked the request at ${boundary}`, {
+        copy: { key: 'detect.blocked' },
+    });
 }
 /**
  * `req.system` is host-assembled per turn — it interpolates retrieval and user
- * data, so it is treated as `assembled`, not trusted. `identity.system` never
- * reaches this path and stays verbatim.
+ * data, so it is read at its own boundary. `identity.system` never reaches this
+ * path and stays verbatim.
  */
-function sanitizeTurnRequestText(req, profile) {
-    const untrusted = detectionForProfile(profile, 'untrusted');
-    const assembled = detectionForProfile(profile, 'assembled');
+function sanitizeTurnRequestWithEvents(req, profile) {
+    const { detect } = resolveGuardrailPolicy(profile.guardrails);
+    const at = recordOf(REQUEST_BOUNDARIES, (boundary) => boundaryReader(boundary, detect));
     const input = req.input ?? {};
-    const events = [];
-    const inputHits = [];
-    const historyHits = [];
-    const systemHits = [];
-    const { text: rawText } = input;
-    let text = rawText;
-    if (rawText !== undefined) {
-        const detected = detectText(rawText, untrusted);
-        appendHits(inputHits, detected.hits);
-        text = detected.text;
-    }
+    const text = input.text === undefined ? undefined : at.user.read(input.text);
     const system = req.system === undefined
         ? undefined
-        : mapSystemPrompt(req.system, 'TurnRequest.system', (part) => {
-            const detected = detectText(part, assembled);
-            appendHits(systemHits, detected.hits);
-            return detected.text;
-        });
-    const slots = sanitizeSlots(input.slots, untrusted, inputHits);
-    const repair = sanitizeRepair(input.repair, untrusted, inputHits);
-    const history = input.history
-        ? sanitizeHistory(input.history, untrusted, historyHits)
-        : undefined;
-    pushStageEvent(events, 'input', 'untrusted', inputHits);
-    pushStageEvent(events, 'history', 'untrusted', historyHits);
-    pushStageEvent(events, 'system', 'assembled', systemHits);
+        : mapSystemPrompt(req.system, 'TurnRequest.system', (part) => at.system.read(part));
+    const slots = sanitizeSlots(input.slots, at.slots);
+    const told = sanitizeContext(input.context, () => boundaryReader('context', detect));
+    const repair = sanitizeRepair(input.repair, at.repair);
+    const history = input.history ? sanitizeHistory(input.history, at.history) : undefined;
+    const { attachments, voice } = input.attachments?.length || input.voice?.length
+        ? sanitizeTurnBlobs(profile, input.attachments, input.voice, at)
+        : input;
+    const events = [];
+    let refusal;
+    for (const boundary of REQUEST_BOUNDARIES) {
+        const found = at[boundary].found();
+        const event = detectEvent(boundary, found);
+        if (event)
+            events.push(guardrailTurnEvent(event));
+        if (found.action === 'block')
+            refusal ??= requestRefused(boundary);
+    }
+    events.push(...told.events.map(guardrailTurnEvent));
+    if (told.blocked)
+        refusal ??= requestRefused('context');
     return {
         request: {
             ...req,
@@ -152,33 +139,22 @@ function sanitizeTurnRequestText(req, profile) {
                 ...input,
                 text,
                 slots,
+                ...(told.context ? { context: told.context } : {}),
                 repair,
                 history,
-            },
-        },
-        events,
-    };
-}
-function sanitizeTurnRequest(req, profile) {
-    return sanitizeTurnRequestWithEvents(req, profile).request;
-}
-/** Attachments and voice are validated but emit no guardrail events. */
-function sanitizeTurnRequestWithEvents(req, profile) {
-    const { request: textSafe, events } = sanitizeTurnRequestText(req, profile);
-    const input = textSafe.input ?? {};
-    const { attachments, voice } = input.attachments?.length || input.voice?.length
-        ? sanitizeTurnBlobs(profile, input.attachments, input.voice)
-        : input;
-    return {
-        request: {
-            ...textSafe,
-            input: {
-                ...input,
                 attachments,
                 voice,
             },
         },
         events,
+        ...(refusal ? { refusal } : {}),
     };
 }
-export { detectionForProfile, detectText, redactSensitiveOnly, sanitizeHistory, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, };
+/** The turn request with its input cleaned under the profile's guardrails. Throws when a match blocks it. */
+function sanitizeTurnRequest(req, profile) {
+    const { request, refusal } = sanitizeTurnRequestWithEvents(req, profile);
+    if (refusal)
+        throw refusal;
+    return request;
+}
+export { contextText, requestRefused, sanitizeContext, sanitizeHistory, sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, };

package/esm/src/guardrails/sensitive-groups.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The names of the sensitive-data groups and how a profile switches them, apart from the patterns
+ * that find them: what reads or shows a profile's settings has no need of the patterns.
+ *
+ * @module
+ */
+/**
+ * The families of sensitive data, each switched on its own: a profile can
+ * redact credentials and card numbers but leave network addresses alone.
+ */
+declare const SENSITIVE_GROUPS: readonly ["ids", "financial", "network", "credentials"];
+/** A group of sensitive-value checks: ids, financial, network, or credentials. */
+type SensitiveGroup = (typeof SENSITIVE_GROUPS)[number];
+/** Per group, whether it runs. A group left out keeps its default. */
+type SensitiveSwitches = Partial<Record<SensitiveGroup, boolean>>;
+/** `true` runs every group, `false` none; an object switches the groups it names. */
+type SensitiveSelection = boolean | SensitiveSwitches;
+/** Every group's switch, defaults applied. */
+type SensitiveGroups = Readonly<Record<SensitiveGroup, boolean>>;
+export type { SensitiveGroup, SensitiveGroups, SensitiveSelection, SensitiveSwitches };
+export { SENSITIVE_GROUPS };

package/esm/src/guardrails/sensitive-groups.js

@@ -0,0 +1,12 @@
+/**
+ * The names of the sensitive-data groups and how a profile switches them, apart from the patterns
+ * that find them: what reads or shows a profile's settings has no need of the patterns.
+ *
+ * @module
+ */
+/**
+ * The families of sensitive data, each switched on its own: a profile can
+ * redact credentials and card numbers but leave network addresses alone.
+ */
+const SENSITIVE_GROUPS = ['ids', 'financial', 'network', 'credentials'];
+export { SENSITIVE_GROUPS };

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

@@ -1,29 +1,22 @@
 import { type RedactSpan } from '../observability/spans.js';
+import type { SensitiveGroup, SensitiveSelection } from './sensitive-groups.js';
 declare const CARD_CANDIDATE: RegExp;
-/**
- * The families of sensitive data, each switched on its own: a profile can
- * redact credentials and card numbers but leave network addresses alone.
- */
-declare const SENSITIVE_GROUPS: readonly ["ids", "financial", "network", "credentials"];
-type SensitiveGroup = (typeof SENSITIVE_GROUPS)[number];
-/** Per group, whether it runs. A group left out keeps its default. */
-type SensitiveSwitches = Partial<Record<SensitiveGroup, boolean>>;
-/** `true` runs every group, `false` none; an object switches the groups it names. */
-type SensitiveSelection = boolean | SensitiveSwitches;
-/** Every group's switch, defaults applied. */
-type SensitiveGroups = Readonly<Record<SensitiveGroup, boolean>>;
-/** Every pattern, with its group. */
-declare const SENSITIVE_PATTERNS: readonly {
+interface SensitivePattern {
     group: SensitiveGroup;
     pattern: RegExp;
-}[];
-/** `selection` with the groups it leaves out taken from `defaults`. */
-declare function resolveSensitive(selection: SensitiveSelection | undefined, defaults?: SensitiveGroups): SensitiveGroups;
-/** Whether any group runs. */
-declare function anySensitive(groups: SensitiveGroups): boolean;
-/** A card-number candidate that is a card: 13–19 digits passing the Luhn check. */
-declare function cardHit(blob: string): boolean;
+    /** Whether a match at `at` of `text` counts. */
+    hit?: (match: string, text: string, at: number) => boolean;
+}
+/** Every pattern, with its group. */
+declare const SENSITIVE_PATTERNS: readonly SensitivePattern[];
+/**
+ * A card-number candidate at `at` of `text` that is a card: digits a card
+ * network issues, passing the Luhn check, outside a web address. A run of
+ * digits in an address is the address's own identifier: one random 19-digit
+ * identifier in a hundred passes the first two tests.
+ */
+declare function cardHit(blob: string, text: string, at: number): boolean;
 /** Sensitive-data spans in `text`, from the groups `selection` runs (every group by default). */
 declare function sensitiveSpans(text: string, selection?: SensitiveSelection): RedactSpan[];
-export type { SensitiveGroup, SensitiveGroups, SensitiveSelection, SensitiveSwitches };
-export { anySensitive, CARD_CANDIDATE, cardHit, resolveSensitive, SENSITIVE_GROUPS, SENSITIVE_PATTERNS, sensitiveSpans, };
+export type { SensitivePattern };
+export { CARD_CANDIDATE, cardHit, SENSITIVE_PATTERNS, sensitiveSpans };