@directive-run/ai 1.18.0 → 1.19.0

package/dist/guardrails.d.ts

@@ -1,618 +1,190 @@
-import { m as GuardrailFn, I as InputGuardrailData, O as OutputGuardrailData, aW as SchemaValidator, T as ToolCallGuardrailData } from './types-DJ09LjZX.js';
-import { a as Embedding } from './semantic-cache-DM7ev7NQ.js';
-export { B as BatchedEmbedder, C as CacheEntry, b as CacheLookupResult, c as CacheStats, E as EmbedderFn, S as SemanticCache, d as SemanticCacheConfig, e as SemanticCacheStorage, f as createBatchedEmbedder, g as createInMemoryStorage, h as createSemanticCache, i as createSemanticCacheGuardrail, j as createTestEmbedder } from './semantic-cache-DM7ev7NQ.js';
-import '@directive-run/core';
+export { A as ANNIndex, a as ANNSearchResult, D as DEFAULT_INJECTION_PATTERNS, b as DetectedPII, E as EnhancedPIIGuardrailOptions, I as InjectionDetectionResult, P as PIIDetectionResult, c as PIIDetector, d as PIIType, e as PromptInjectionGuardrailOptions, R as RateLimitGuardrail, f as RedactionStyle, S as STRICT_INJECTION_PATTERNS, V as VPTreeIndexConfig, g as createBruteForceIndex, h as createContentFilterGuardrail, i as createEnhancedPIIGuardrail, j as createLengthGuardrail, k as createModerationGuardrail, l as createOutputPIIGuardrail, m as createOutputSchemaGuardrail, n as createOutputTypeGuardrail, o as createPIIGuardrail, p as createPromptInjectionGuardrail, q as createRateLimitGuardrail, r as createToolGuardrail, s as createUntrustedContentGuardrail, t as createVPTreeIndex, u as detectAndRedactPII, v as detectPII, w as detectPromptInjection, x as markUntrustedContent, y as redactPII, z as sanitizeInjection } from './ann-index-27QV9tPC.js';
+import { Plugin } from '@directive-run/core';
+export { B as BatchedEmbedder, C as CacheEntry, a as CacheLookupResult, b as CacheStats, E as EmbedderFn, c as Embedding, S as SemanticCache, d as SemanticCacheConfig, e as SemanticCacheStorage, f as createBatchedEmbedder, g as createInMemoryStorage, h as createSemanticCache, i as createSemanticCacheGuardrail, j as createTestEmbedder } from './semantic-cache-Ba0-jEwb.js';
+import './types-CUp1N0uU.js';
 
 /**
- * Built-in guardrails for AI adapter — PII, moderation, rate limiting, tool allowlists, schema validation.
- */
-
-/**
- * Create a PII detection guardrail that scans input text for personally identifiable
- * information. Blocks input when PII is detected, or optionally redacts matches and
- * passes the sanitized text through.
- *
- * @param options - Configuration for PII detection: `patterns` sets the RegExp list (defaults to SSN, credit card, email), `redact` replaces matches instead of blocking, `redactReplacement` sets the replacement string (defaults to `"[REDACTED]"`).
- * @returns An input guardrail that blocks or redacts PII in user input.
- *
- * @example
- * ```typescript
- * const piiGuardrail = createPIIGuardrail({
- *   patterns: [
- *     /\b\d{3}-\d{2}-\d{4}\b/, // SSN
- *     /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i, // Email
- *   ],
- *   redact: true,
- * });
- * ```
- *
- * @public
- */
-declare function createPIIGuardrail(options: {
-    patterns?: RegExp[];
-    redact?: boolean;
-    redactReplacement?: string;
-}): GuardrailFn<InputGuardrailData>;
-/**
- * Create a content moderation guardrail that delegates to a user-supplied check function.
- * Works on both input and output data — the guardrail extracts the text content
- * automatically and passes it to {@link options.checkFn}.
- *
- * @param options - Configuration for content moderation: `checkFn` returns `true` when content should be flagged (supports async), `message` sets the rejection reason (defaults to `"Content flagged by moderation"`).
- * @returns A guardrail that blocks content flagged by the check function.
- *
- * @example
- * ```typescript
- * const moderationGuardrail = createModerationGuardrail({
- *   checkFn: async (text) => {
- *     const result = await openai.moderations.create({ input: text });
- *     return result.results[0].flagged;
+ * Fact-PII Guardrail — input guardrail at the fact-store boundary
+ *
+ * Closes the source → fact → agent prompt PII bypass surfaced by R5's
+ * red-team / privacy / AI-integration reviewers: `createPIIGuardrail`
+ * only inspects the `data.input` string at runStream entry, so PII that
+ * a source publishes into a fact (a Supabase realtime row carrying a
+ * customer email, a webhook payload with a SSN, an MCP server's
+ * resource notification with a card number) reaches the agent's
+ * prompt — via fact injection — without ever hitting the input
+ * guardrail chain.
+ *
+ * This plugin runs as a Directive plugin (`onFactSet` / `onFactsBatch`),
+ * scans every write to a pii-tagged fact against a sync regex matcher
+ * for the three highest-volume PII categories (SSN, credit card, email),
+ * and either **redacts** the value (the default — safe shipping posture)
+ * or **rejects** the write (throws so the source's publish handler can
+ * surface the violation). Operators wire it once at `createSystem`; no
+ * per-source / per-fact changes are required.
+ *
+ * The async PII detector from `pii-enhanced.ts` is unsuitable here:
+ * `onFactSet` is synchronous and a deferred detection would let the
+ * raw PII reach observers + breakpoints + audit-ledger before the
+ * redaction completed. Built-in matching is therefore inlined as
+ * synchronous regex. Consumers who need richer detection pass a
+ * synchronous `customDetector`.
+ *
+ * @example Defensive (redact PII writes into pii-tagged facts)
+ * ```ts
+ * import { createSystem, t } from '@directive-run/core';
+ * import { createFactPIIGuardrail } from '@directive-run/ai/guardrails';
+ *
+ * const customer = createModule('customer', {
+ *   schema: {
+ *     facts: {
+ *       email: t.string().meta({ tags: ['pii'] }),
+ *       ssn: t.string().meta({ tags: ['pii'] }),
+ *     },
  *   },
- * });
- * ```
- *
- * @public
- */
-declare function createModerationGuardrail(options: {
-    checkFn: (text: string) => boolean | Promise<boolean>;
-    message?: string;
-}): GuardrailFn<InputGuardrailData | OutputGuardrailData>;
-/** Rate limiter with reset capability for testing */
-interface RateLimitGuardrail extends GuardrailFn<InputGuardrailData> {
-    reset(): void;
-}
-/**
- * Create a rate limit guardrail that tracks token and request counts over a sliding
- * one-minute window. Returns a {@link RateLimitGuardrail} — a guardrail function with
- * an additional `reset()` method for testing.
- *
- * @param options - Configuration for rate limiting: `maxTokensPerMinute` caps tokens in the sliding window (defaults to `100000`), `maxRequestsPerMinute` caps requests (defaults to `60`).
- * @returns A rate limit guardrail with an attached `reset()` method.
- *
- * @example
- * ```typescript
- * const rateLimiter = createRateLimitGuardrail({
- *   maxTokensPerMinute: 50000,
- *   maxRequestsPerMinute: 30,
- * });
- * ```
- *
- * @public
- */
-declare function createRateLimitGuardrail(options: {
-    maxTokensPerMinute?: number;
-    maxRequestsPerMinute?: number;
-}): RateLimitGuardrail;
-/**
- * Create a tool-call guardrail that restricts which tools an agent may invoke.
- * Supports allowlist mode, denylist mode, or both — when both are provided, a tool
- * must appear in the allowlist and not appear in the denylist.
- *
- * @param options - Configuration for tool filtering: `allowlist` sets permitted tool names, `denylist` sets blocked tool names, `caseSensitive` controls case matching (defaults to `false`).
- * @returns A tool-call guardrail that enforces the allowlist/denylist rules.
- *
- * @example
- * ```typescript
- * const toolGuardrail = createToolGuardrail({
- *   allowlist: ["search", "calculate"],
- *   denylist: ["delete_account"],
- * });
- * ```
- *
- * @public
- */
-declare function createToolGuardrail(options: {
-    allowlist?: string[];
-    denylist?: string[];
-    /** @default false */
-    caseSensitive?: boolean;
-}): GuardrailFn<ToolCallGuardrailData>;
-/**
- * Create an output guardrail that validates agent output against a schema using
- * a user-supplied {@link SchemaValidator}. Compatible with any validation library
- * (Zod, Valibot, ArkType, etc.) via the adapter pattern.
- *
- * @param options - Configuration for schema validation: `validate` checks the output against the expected schema, `errorPrefix` is prepended to error messages (defaults to `"Output schema validation failed"`).
- * @returns An output guardrail that rejects output failing schema validation.
- *
- * @example
- * ```typescript
- * import { z } from "zod";
- *
- * const schemaGuardrail = createOutputSchemaGuardrail({
- *   validate: (value) => {
- *     const result = z.object({ answer: z.string() }).safeParse(value);
- *     return { valid: result.success, errors: result.error?.issues.map(i => i.message) };
+ *   sources: {
+ *     supabase: { attach: (publish) => subscribe(publish) },
  *   },
  * });
- * ```
  *
- * @public
- */
-declare function createOutputSchemaGuardrail<T = unknown>(options: {
-    validate: SchemaValidator<T>;
-    errorPrefix?: string;
-}): GuardrailFn<OutputGuardrailData>;
-/**
- * Create an output guardrail that performs lightweight runtime type checks without
- * requiring a schema library. Supports `"string"`, `"number"`, `"boolean"`, `"object"`,
- * and `"array"` with optional size and field constraints.
- *
- * @param options - Configuration for type checking: `type` sets the expected JS type, `requiredFields` lists object keys that must exist, `minLength`/`maxLength` constrain array size, `minStringLength`/`maxStringLength` constrain string length.
- * @returns An output guardrail that rejects output not matching the expected type or constraints.
- *
- * @example
- * ```typescript
- * const typeGuardrail = createOutputTypeGuardrail({
- *   type: "object",
- *   requiredFields: ["id", "name"],
- * });
- * ```
- *
- * @public
- */
-declare function createOutputTypeGuardrail(options: {
-    type: "string" | "number" | "boolean" | "object" | "array";
-    requiredFields?: string[];
-    minLength?: number;
-    maxLength?: number;
-    minStringLength?: number;
-    maxStringLength?: number;
-}): GuardrailFn<OutputGuardrailData>;
-/**
- * Create an output guardrail that enforces maximum length constraints on agent output,
- * measured in characters or estimated tokens.
- *
- * @param options - Configuration for length limits: `maxCharacters` caps character count, `maxTokens` caps estimated token count, `estimateTokens` provides a custom token estimator (defaults to `Math.ceil(text.length / 4)`).
- * @returns An output guardrail that rejects output exceeding the configured length limits.
- *
- * @example
- * ```typescript
- * const lengthGuardrail = createLengthGuardrail({
- *   maxCharacters: 5000,
- *   maxTokens: 1200,
- * });
- * ```
- *
- * @public
- */
-declare function createLengthGuardrail(options: {
-    /** Maximum characters in output */
-    maxCharacters?: number;
-    /** Maximum estimated tokens in output */
-    maxTokens?: number;
-    /** Custom token estimator (default: chars / 4) */
-    estimateTokens?: (text: string) => number;
-}): GuardrailFn<OutputGuardrailData>;
-/**
- * Create an output guardrail that blocks content matching any of the provided patterns.
- * String patterns are escaped and compiled to RegExp; RegExp patterns are used as-is.
- *
- * @remarks
- * A warning is logged when `blockedPatterns` is empty, since an empty list means no
- * content will ever be filtered.
- *
- * @param options - Configuration for content filtering: `blockedPatterns` lists strings or RegExps to match against output, `caseSensitive` controls case matching for string patterns (defaults to `false`).
- * @returns An output guardrail that rejects output containing any blocked pattern.
- *
- * @example
- * ```typescript
- * const contentFilter = createContentFilterGuardrail({
- *   blockedPatterns: [
- *     /\bpassword\b/i,
- *     /\bsecret\b/i,
- *     'internal-only',
+ * const system = createSystem({
+ *   module: customer,
+ *   plugins: [
+ *     createFactPIIGuardrail({
+ *       mode: 'redact',
+ *       onBlocked: (key, detected) => {
+ *         console.warn(`[fact-pii] redacted ${detected.length} match(es) in ${key}`);
+ *       },
+ *     }),
  *   ],
  * });
  * ```
  *
- * @public
- */
-declare function createContentFilterGuardrail(options: {
-    /** Patterns to block — strings or RegExp */
-    blockedPatterns: Array<string | RegExp>;
-    /** Case-sensitive matching for string patterns (default: false) */
-    caseSensitive?: boolean;
-}): GuardrailFn<OutputGuardrailData>;
-
-/**
- * Enhanced PII Detection Guardrail
- *
- * Provides comprehensive PII detection beyond basic regex patterns:
- * - Multiple PII types (SSN, credit cards, emails, phones, addresses, names)
- * - Pluggable detection backends (regex, custom, or external services)
- * - Context-aware detection (reduces false positives)
- * - Redaction with reversible or irreversible options
- *
- * @example
- * ```typescript
- * import { createEnhancedPIIGuardrail } from '@directive-run/ai';
- *
- * const guardrail = createEnhancedPIIGuardrail({
- *   types: ['ssn', 'credit_card', 'email'],
- *   redact: true,
- *   detector: 'regex', // or 'custom' with custom detector
- * });
- * ```
- */
-
-/** Supported PII types */
-type PIIType = "ssn" | "credit_card" | "email" | "phone" | "address" | "name" | "date_of_birth" | "passport" | "driver_license" | "ip_address" | "bank_account" | "medical_id" | "national_id";
-/** Detected PII instance */
-interface DetectedPII {
-    type: PIIType;
-    value: string;
-    position: {
-        start: number;
-        end: number;
-    };
-    confidence: number;
-    context?: string;
-}
-/** PII detection result */
-interface PIIDetectionResult {
-    detected: boolean;
-    items: DetectedPII[];
-    typeCounts: Partial<Record<PIIType, number>>;
-    /** Text with PII redacted (if requested) */
-    redactedText?: string;
-}
-/** Custom PII detector interface */
-interface PIIDetector {
-    detect(text: string, types: PIIType[]): Promise<DetectedPII[]>;
-    name: string;
-}
-/** Redaction style */
-type RedactionStyle = 
-/** Replace with [REDACTED] */
-"placeholder"
-/** Replace with type-specific placeholder like [EMAIL] */
- | "typed"
-/**
- * Replace with a fixed-width `****` mask plus the last 4 characters
- * (e.g. `****6789`). Does not preserve or reveal the original length.
- */
- | "masked"
-/**
- * Replace with a deterministic FNV-1a hash.
- *
- * **WARNING — this is PSEUDONYMIZATION, not anonymization.** FNV-1a is a
- * fast, non-cryptographic 32-bit hash. For low-entropy structured PII (SSNs,
- * card numbers, phone numbers) the output is trivially RE-IDENTIFIABLE via
- * brute force or a precomputed rainbow table. It MUST NOT be relied on for
- * GDPR / HIPAA de-identification. Use it only for referential integrity
- * (correlating the same value across audit logs).
- */
- | "hashed";
-/** Redact detected PII from text */
-declare function redactPII(text: string, items: DetectedPII[], style?: RedactionStyle): string;
-/** Options for enhanced PII guardrail */
-interface EnhancedPIIGuardrailOptions {
-    /** PII types to detect (default: all) */
-    types?: PIIType[];
-    /** Detection backend (default: 'regex') */
-    detector?: "regex" | PIIDetector;
-    /** Redact instead of blocking */
-    redact?: boolean;
-    /** Redaction style (default: 'typed') */
-    redactionStyle?: RedactionStyle;
-    /** Minimum confidence to flag (0-1, default: 0.7) */
-    minConfidence?: number;
-    /** Callback when PII is detected */
-    onDetected?: (items: DetectedPII[]) => void;
-    /** Allow specific values (whitelist) */
-    allowlist?: string[];
-    /** Block only if count exceeds threshold */
-    minItemsToBlock?: number;
-    /** Timeout for custom detector in milliseconds (default: 5000) */
-    detectorTimeout?: number;
-}
-/**
- * Create an enhanced PII detection guardrail.
- *
- * @example
- * ```typescript
- * // Basic usage
- * const guardrail = createEnhancedPIIGuardrail();
- *
- * // Redact instead of blocking
- * const redactGuardrail = createEnhancedPIIGuardrail({
- *   redact: true,
- *   redactionStyle: 'masked',
- * });
- *
- * // Custom detection with external service
- * const customGuardrail = createEnhancedPIIGuardrail({
- *   detector: myPresidioDetector,
- *   types: ['ssn', 'credit_card', 'medical_id'],
- * });
- * ```
- */
-declare function createEnhancedPIIGuardrail(options?: EnhancedPIIGuardrailOptions): GuardrailFn<InputGuardrailData>;
-/**
- * Create an output PII guardrail (for checking agent responses).
- *
- * @example
- * ```typescript
- * const outputGuardrail = createOutputPIIGuardrail({
- *   types: ['ssn', 'credit_card'],
- *   redact: true,
- * });
- * ```
- */
-declare function createOutputPIIGuardrail(options?: EnhancedPIIGuardrailOptions): GuardrailFn<OutputGuardrailData>;
-/**
- * Detect PII in text without using as a guardrail.
- * Useful for analysis and logging.
- *
- * @example
- * ```typescript
- * const result = await detectPII('My SSN is 123-45-6789');
- * console.log(result.items); // [{ type: 'ssn', value: '123-45-6789', ... }]
- *
- * // With custom detector and timeout
- * const result = await detectPII(text, {
- *   detector: myPresidioDetector,
- *   timeout: 10000, // 10 seconds
- * });
- * ```
- */
-declare function detectPII(text: string, options?: {
-    types?: PIIType[];
-    detector?: "regex" | PIIDetector;
-    minConfidence?: number;
-    /** Timeout for custom detectors in milliseconds (default: 5000) */
-    timeout?: number;
-}): Promise<PIIDetectionResult>;
-/**
- * Detect PII in text and return a result whose `redactedText` is populated.
- *
- * This composes {@link detectPII} and {@link redactPII} so callers do not have
- * to manually wire the two together (and do not have to mutate the detection
- * result). When no PII is detected, `redactedText` is left `undefined` — it is
- * deliberately NOT defaulted to the raw input.
- *
- * @example
- * ```typescript
- * const result = await detectAndRedactPII('My SSN is 123-45-6789', {
- *   types: ['ssn'],
- *   style: 'typed',
+ * @example Monitor-only (alert on every PII match; don't mutate the fact)
+ * ```ts
+ * createFactPIIGuardrail({
+ *   mode: 'alert',
+ *   onBlocked: (key) => Sentry.captureException(new Error(`pii match: ${key}`)),
  * });
- * console.log(result.detected);      // true
- * // ssn is a sensitive-category type, so `typed` emits a generic [REDACTED]
- * console.log(result.redactedText);  // 'My SSN is [REDACTED]'
- *
- * const clean = await detectAndRedactPII('nothing here', { types: ['ssn'] });
- * console.log(clean.detected);       // false
- * console.log(clean.redactedText);   // undefined
  * ```
- */
-declare function detectAndRedactPII(text: string, options?: {
-    types?: PIIType[];
-    detector?: "regex" | PIIDetector;
-    minConfidence?: number;
-    /** Timeout for custom detectors in milliseconds (default: 5000) */
-    timeout?: number;
-    /** Redaction style applied when PII is detected (default: 'typed') */
-    style?: RedactionStyle;
-}): Promise<PIIDetectionResult>;
-
-/**
- * Prompt Injection Detection Guardrail
- *
- * Detects and blocks prompt injection attacks including:
- * - Direct injection attempts ("ignore previous instructions")
- * - Jailbreak patterns ("DAN mode", "pretend you can")
- * - Indirect injection via external content
- * - Encoding-based evasion attempts
- *
- * @example
- * ```typescript
- * import { createPromptInjectionGuardrail } from '@directive-run/ai';
  *
- * const guardrail = createPromptInjectionGuardrail({
- *   strictMode: true,
- *   onBlocked: (input, patterns) => logSecurityEvent(input, patterns),
+ * @example Allow specific keys (not just by tag)
+ * ```ts
+ * createFactPIIGuardrail({
+ *   includeKeys: ['customer.email', 'customer.phone'],
  * });
  * ```
  */
 
-/** Pattern with metadata for better debugging */
-interface InjectionPattern {
-    pattern: RegExp;
-    name: string;
-    severity: "low" | "medium" | "high" | "critical";
-    category: InjectionCategory;
-}
-/** Categories of injection attacks */
-type InjectionCategory = "instruction_override" | "jailbreak" | "role_manipulation" | "encoding_evasion" | "delimiter_injection" | "context_manipulation" | "indirect_injection";
-/** Default injection patterns - well-tested and low false-positive rate */
-declare const DEFAULT_INJECTION_PATTERNS: InjectionPattern[];
-/** Strict patterns - more aggressive, may have higher false positives */
-declare const STRICT_INJECTION_PATTERNS: InjectionPattern[];
-/** Detailed detection result */
-interface InjectionDetectionResult {
-    detected: boolean;
-    patterns: Array<{
-        name: string;
-        category: InjectionCategory;
-        severity: InjectionPattern["severity"];
-        match: string;
-        position: number;
-    }>;
-    riskScore: number;
-    sanitizedInput?: string;
-}
 /**
- * Detect prompt injection patterns in text.
- * Returns detailed results about what was detected.
- *
- * @throws Error if input exceeds MAX_INJECTION_INPUT_LENGTH (100KB)
+ * Public match record for a single PII finding. Mirrors `DetectedPII` from
+ * `pii-enhanced.ts` so a downstream guardrail can normalize against either
+ * detection path.
  */
-declare function detectPromptInjection(text: string, patterns?: InjectionPattern[]): InjectionDetectionResult;
-/**
- * Sanitize text by removing detected injection patterns.
- * Warning: This is a best-effort sanitization, not a security guarantee.
- *
- * Uses a single-pass approach to prevent infinite loops where a replacement
- * could create a new pattern match.
- */
-declare function sanitizeInjection(text: string, patterns?: InjectionPattern[]): string;
-/** Options for prompt injection guardrail */
-interface PromptInjectionGuardrailOptions {
-    /** Additional patterns to check (added to defaults) */
-    additionalPatterns?: InjectionPattern[];
-    /** Replace default patterns entirely */
-    replacePatterns?: InjectionPattern[];
-    /** Use strict mode with more aggressive detection */
-    strictMode?: boolean;
-    /** Minimum risk score to block (0-100, default: 50) */
-    blockThreshold?: number;
-    /** Attempt to sanitize instead of blocking */
-    sanitize?: boolean;
-    /** Callback when injection is detected */
-    onBlocked?: (input: string, result: InjectionDetectionResult) => void;
-    /** Categories to ignore (e.g., allow 'role_manipulation' for roleplay apps) */
-    ignoreCategories?: InjectionCategory[];
-}
-/**
- * Create a prompt injection detection guardrail.
- *
- * @example
- * ```typescript
- * // Basic usage
- * const guardrail = createPromptInjectionGuardrail();
- *
- * // Strict mode for high-security applications
- * const strictGuardrail = createPromptInjectionGuardrail({
- *   strictMode: true,
- *   blockThreshold: 25,
- * });
- *
- * // Allow role manipulation for roleplay apps
- * const roleplayGuardrail = createPromptInjectionGuardrail({
- *   ignoreCategories: ['role_manipulation'],
- * });
- * ```
- */
-declare function createPromptInjectionGuardrail(options?: PromptInjectionGuardrailOptions): GuardrailFn<InputGuardrailData>;
-/**
- * Mark content as potentially untrusted (from external sources).
- * This wraps the content with markers that injection detection will scrutinize more closely.
- *
- * @example
- * ```typescript
- * const userUpload = await readFile(path);
- * const markedContent = markUntrustedContent(userUpload, 'user-upload');
- * const prompt = `Summarize this document: ${markedContent}`;
- * ```
- */
-declare function markUntrustedContent(content: string, source: string): string;
-/**
- * Create a guardrail that applies stricter checks to marked untrusted content.
- *
- * @example
- * ```typescript
- * const guardrail = createUntrustedContentGuardrail({
- *   baseGuardrail: createPromptInjectionGuardrail({ strictMode: true }),
- * });
- * ```
- */
-declare function createUntrustedContentGuardrail(options: {
-    /** Guardrail to apply to untrusted sections */
-    baseGuardrail?: GuardrailFn<InputGuardrailData>;
-    /** Block if untrusted content contains these patterns */
-    additionalPatterns?: InjectionPattern[];
-}): GuardrailFn<InputGuardrailData>;
-
-/**
- * Approximate Nearest Neighbor (ANN) Index for Semantic Cache
- *
- * Provides pluggable vector search backends for efficient similarity lookups.
- * Includes a brute-force exact search and a VP-tree (Vantage Point Tree) for
- * fast approximate nearest neighbor queries.
- *
- * @example
- * ```typescript
- * import { createSemanticCache } from '@directive-run/ai';
- * import { createVPTreeIndex } from '@directive-run/ai';
- *
- * const index = createVPTreeIndex();
- *
- * const cache = createSemanticCache({
- *   embedder: myEmbedder,
- *   annIndex: index,
- * });
- * ```
- */
-
-/** Search result from an ANN index */
-interface ANNSearchResult {
-    /** ID of the matched item */
-    id: number;
-    /** Similarity score (0-1, higher is more similar) */
-    similarity: number;
-}
-/** ANN Index interface - pluggable vector search backend */
-interface ANNIndex {
-    /** Add a vector to the index */
-    add(id: number, embedding: Embedding): void;
-    /** Remove a vector from the index */
-    remove(id: number): void;
-    /** Search for the k nearest neighbors */
-    search(query: Embedding, k: number, threshold?: number): ANNSearchResult[];
-    /** Rebuild the index (call after batch additions) */
-    rebuild(): void;
-    /** Get the number of indexed vectors */
-    size(): number;
-    /** Clear the index */
-    clear(): void;
-    /** Check if the index needs to be rebuilt (e.g., after additions/removals) */
-    needsRebuild(): boolean;
+interface FactPIIMatch {
+    type: FactPIICategory;
+    value: string;
+    start: number;
+    end: number;
 }
-/**
- * Create a brute-force exact search index.
- *
- * O(n) search, O(1) add/remove. Best for small collections (< 10,000 vectors).
- *
- * @example
- * ```typescript
- * const index = createBruteForceIndex();
- * index.add(0, [0.1, 0.2, 0.3]);
- * index.add(1, [0.4, 0.5, 0.6]);
- *
- * const results = index.search([0.1, 0.2, 0.3], 1);
- * // [{ id: 0, similarity: 1.0 }]
- * ```
- */
-declare function createBruteForceIndex(): ANNIndex;
-/** VP-Tree index configuration */
-interface VPTreeIndexConfig {
-    /** Optional random number generator for deterministic builds. Returns a number in [0, 1). */
-    random?: () => number;
+/** PII categories the built-in synchronous detector covers. */
+type FactPIICategory = "ssn" | "credit_card" | "email";
+/**
+ * Behavior when a pii-tagged fact's incoming value contains detected PII.
+ *
+ * - `"redact"` (default): the fact is rewritten with redacted text (e.g.
+ *   `"[SSN]"`) via a follow-up store write. The system briefly observes
+ *   the raw value during the same microtask the publish landed in, then
+ *   the redacted value overwrites it before any reconcile / agent runs.
+ *   Safe shipping posture for production: the LLM call always sees the
+ *   redacted value.
+ * - `"alert"`: fire `onBlocked` but DO NOT mutate the fact. The raw value
+ *   stays in the store. Use this for monitoring-only deployments where
+ *   the source's transport is already trusted but a regression detector
+ *   is needed (paging ops on every match).
+ *
+ * Note: Directive plugin hooks (`onFactSet`, `onFactsBatch`) are
+ * wrapped by the plugin manager's `safeCall` so a throw from inside the
+ * hook is swallowed. The guardrail therefore cannot reject the write
+ * itself — it can only observe + redact-via-followup-write or alert.
+ * For hard rejection at the publish boundary, a future RFC will add a
+ * pre-commit transform hook on the source primitive.
+ */
+type FactPIIGuardrailMode = "redact" | "alert";
+interface FactPIIGuardrailOptions {
+    /** Default: `"redact"` */
+    mode?: FactPIIGuardrailMode;
+    /**
+     * Built-in categories to scan for. Default: all three (`ssn`,
+     * `credit_card`, `email`). Pass `[]` to opt out of the built-ins and
+     * rely entirely on `customDetector`.
+     */
+    types?: readonly FactPIICategory[];
+    /**
+     * Specific fact keys to scan in addition to the auto-detected
+     * `pii`-tagged set. Useful when a consumer can't change the schema's
+     * meta but knows the key should be screened.
+     */
+    includeKeys?: readonly string[];
+    /**
+     * Exclude these fact keys even if they're pii-tagged. Escape hatch for
+     * a key that's already pre-sanitized upstream of the manager.
+     */
+    excludeKeys?: readonly string[];
+    /**
+     * Called whenever the guardrail detects PII and acts on it. Receives the
+     * fact key, the detected matches, and the action that was taken. Fires
+     * AFTER redact + before any throw in `reject` mode. Use this to alert
+     * SREs without coupling the guardrail to a specific logging backend.
+     */
+    onBlocked?: (key: string, detected: readonly FactPIIMatch[], action: FactPIIGuardrailMode) => void;
+    /**
+     * Custom synchronous detector that runs alongside the built-in regex
+     * scanner. The union of detections is acted on. Useful when the
+     * consumer ships a domain-specific PII detector (e.g. internal
+     * account-number format). MUST be synchronous — `onFactSet` cannot
+     * await deferred work.
+     */
+    customDetector?: (text: string) => readonly FactPIIMatch[];
+    /**
+     * Maximum nesting depth to walk when scanning a structured fact
+     * value. Default `1` — the scanner inspects top-level strings, then
+     * descends one level into the object/array. Arrays and plain objects
+     * count as one depth level each. Maps and Sets are still NOT walked
+     * by the built-in scanner; PII inside those structures must go
+     * through a `customDetector`.
+     *
+     * Per R13-C6 the walker recurses into arrays (Supabase realtime
+     * payloads ship as `payload.new = [{...}]`, MCP resource lists ship
+     * as arrays — those shapes silently bypassed the Tier 0 guard before).
+     *
+     * Consumers with deeply-nested PII shapes have two options:
+     * 1. Pass `walkDepth: 2` (or higher) — the scanner walks plain
+     *    objects and arrays to that depth. Maps and Sets are still
+     *    skipped.
+     * 2. Pass a `customDetector` that walks the consumer-specific shape
+     *    and returns concrete matches — the right answer for
+     *    domain-specific structures (Maps, Sets, getters, Symbol keys).
+     *
+     * Maximum is `5` to prevent pathological recursion on cyclic
+     * structures. Passing anything higher clamps to `5`.
+     *
+     * Property iteration uses `Object.entries`, which skips
+     * Symbol-keyed properties and non-enumerable string keys. If you
+     * store PII under a Symbol key (unusual), a `customDetector` is the
+     * right escape hatch.
+     */
+    walkDepth?: number;
 }
 /**
- * Create a VP-Tree (Vantage Point Tree) index for efficient approximate nearest neighbor search.
+ * Create a Directive plugin that scans pii-tagged fact writes for PII and
+ * redacts or rejects them at the manager boundary.
  *
- * O(log n) search on average, requires rebuild after batch additions.
- * Best for medium collections (1,000 - 100,000 vectors).
+ * Wire it once at `createSystem({ plugins: [...] })`. The plugin caches
+ * the pii-tagged key set on `onInit` so per-write hooks are O(1) lookups.
  *
- * @example
- * ```typescript
- * const index = createVPTreeIndex();
- *
- * // Add vectors
- * for (let i = 0; i < embeddings.length; i++) {
- *   index.add(i, embeddings[i]);
- * }
- *
- * // Build the tree
- * index.rebuild();
- *
- * // Search
- * const results = index.search(queryEmbedding, 5, 0.9);
- * ```
+ * @returns a `Plugin` instance ready to add to `SystemConfig.plugins`.
  */
-declare function createVPTreeIndex(vpConfig?: VPTreeIndexConfig): ANNIndex;
+declare function createFactPIIGuardrail(options?: FactPIIGuardrailOptions): Plugin;
 
-export { type ANNIndex, type ANNSearchResult, DEFAULT_INJECTION_PATTERNS, type DetectedPII, Embedding, type EnhancedPIIGuardrailOptions, type InjectionDetectionResult, type PIIDetectionResult, type PIIDetector, type PIIType, type PromptInjectionGuardrailOptions, type RateLimitGuardrail, type RedactionStyle, STRICT_INJECTION_PATTERNS, type VPTreeIndexConfig, createBruteForceIndex, createContentFilterGuardrail, createEnhancedPIIGuardrail, createLengthGuardrail, createModerationGuardrail, createOutputPIIGuardrail, createOutputSchemaGuardrail, createOutputTypeGuardrail, createPIIGuardrail, createPromptInjectionGuardrail, createRateLimitGuardrail, createToolGuardrail, createUntrustedContentGuardrail, createVPTreeIndex, detectAndRedactPII, detectPII, detectPromptInjection, markUntrustedContent, redactPII, sanitizeInjection };
+export { type FactPIICategory, type FactPIIGuardrailMode, type FactPIIGuardrailOptions, type FactPIIMatch, createFactPIIGuardrail };