@tenova/swt3-ai 0.3.4 → 0.4.1

package/dist/witness.d.ts

@@ -0,0 +1,193 @@
+/**
+ * SWT3 AI Witness SDK — Core Witness class.
+ *
+ * Usage:
+ *   import { Witness } from "@tenova/swt3-ai";
+ *   import OpenAI from "openai";
+ *
+ *   const witness = new Witness({
+ *     endpoint: "https://sovereign.tenova.io",
+ *     apiKey: "axm_live_...",
+ *     tenantId: "YOUR_TENANT_ID",
+ *   });
+ *
+ *   const client = witness.wrap(new OpenAI()) as OpenAI;
+ *   const response = await client.chat.completions.create({ ... });
+ *
+ *   // Graceful shutdown
+ *   await witness.flush();
+ *
+ * Copyright (c) 2026 Tenable Nova LLC. Apache 2.0. Patent pending.
+ */
+import { type VercelOnFinishOptions } from "./adapters/vercel-ai.js";
+import type { WitnessPayload, WitnessReceipt, InferenceRecord } from "./types.js";
+export interface WitnessOptions {
+    endpoint: string;
+    apiKey: string;
+    tenantId: string;
+    clearingLevel?: 0 | 1 | 2 | 3;
+    bufferSize?: number;
+    flushInterval?: number;
+    timeout?: number;
+    maxRetries?: number;
+    latencyThresholdMs?: number;
+    guardrailsRequired?: number;
+    guardrailNames?: string[];
+    procedures?: string[];
+    factorHandoff?: "file";
+    factorHandoffPath?: string;
+    agentId?: string;
+    signingKey?: string;
+    cycleId?: string;
+    strict?: boolean;
+    policyVersion?: string;
+    jurisdiction?: string;
+    legalBasis?: string;
+    purposeClass?: string;
+    onFlush?: (payloads: WitnessPayload[], receipts: WitnessReceipt[]) => void;
+}
+/**
+ * Raised when strict (gatekeeper) mode blocks an inference due to
+ * insufficient guardrails. The inference never reaches the AI model.
+ */
+export declare class GatekeeperError extends Error {
+    readonly required: number;
+    readonly active: number;
+    readonly missingNames: string[];
+    constructor(required: number, active: number, missingNames?: string[]);
+}
+export declare class Witness {
+    private config;
+    private buffer;
+    private handoffWarned;
+    private _strict;
+    constructor(options: WitnessOptions);
+    /**
+     * Wrap an AI client with transparent witnessing.
+     *
+     * Supported: OpenAI, Anthropic
+     * Returns a proxy that behaves identically to the original client.
+     *
+     * Usage:
+     *   const client = witness.wrap(new OpenAI()) as OpenAI;
+     *   const client = witness.wrap(new Anthropic()) as Anthropic;
+     */
+    wrap(client: unknown): unknown;
+    /** Whether strict (gatekeeper) mode is enabled. Used by adapters. */
+    get strict(): boolean;
+    /**
+     * Pre-call guardrail gate (strict mode only).
+     *
+     * Evaluates whether configured guardrail requirements are met BEFORE
+     * the inference call reaches the AI model. If requirements are not met,
+     * throws `GatekeeperError` and mints an AI-GRD.3 anchor recording
+     * the rejection. The rejection is evidence — it is enqueued for flush.
+     *
+     * This method is SYNCHRONOUS — evaluates local config only, no network.
+     *
+     * @throws {GatekeeperError} if guardrail requirements are not met
+     */
+    gateCheck(_messages?: unknown, _model?: string): string;
+    /**
+     * Wrap a function as a witnessed tool call (AI-TOOL.1).
+     *
+     * Usage:
+     *   const search = witness.wrapTool(searchDatabase, "search_db");
+     *   const result = await search("SELECT ...");
+     *
+     * Each call mints an AI-TOOL.1 anchor with:
+     *   factor_a = 1 (tool was called)
+     *   factor_b = latency_ms
+     *   factor_c = 1 if succeeded, 0 if exception raised
+     */
+    wrapTool<T extends (...args: any[]) => any>(fn: T, toolName?: string): T;
+    /**
+     * Wrap a function as a witnessed access attempt (AI-ACC.1).
+     *
+     * Usage:
+     *   const queryDb = witness.wrapAccess(dbQuery, "prod-database", "read-only analytics");
+     *   const result = await queryDb("SELECT ...");
+     *
+     * Each call mints an AI-ACC.1 anchor with:
+     *   factor_a = 1 (access attempt occurred)
+     *   factor_b = 1 if within declared scope (or no scope set), 0 if out of scope
+     *   factor_c = 1 if access granted, 0 if denied/failed
+     */
+    wrapAccess<T extends (...args: any[]) => any>(fn: T, resourceName?: string, scope?: string): T;
+    /**
+     * Witness a security/adversarial detection result (AI-SEC.1).
+     *
+     * Call after running your own detection system (Prompt Guard, LlamaGuard,
+     * NeMo Guardrails, etc.) to record the result as a tamper-evident anchor.
+     *
+     * @param threatScore - Detection score from your system (0-1000 scale).
+     * @param options.threshold - Score above which input is a threat. Default 500.
+     * @param options.threatType - One of: none, prompt_injection, data_poisoning,
+     *   model_extraction, jailbreak, adversarial_input.
+     *
+     * @example
+     *   const score = await promptGuard.scan(userInput);
+     *   witness.witnessSecurityScan(score, { threatType: "prompt_injection" });
+     */
+    witnessSecurityScan(threatScore: number, options?: {
+        threshold?: number;
+        threatType?: string;
+    }): void;
+    /**
+     * Witness an input validation/sanitization result (AI-SEC.2).
+     *
+     * Call after validating or sanitizing user input before inference.
+     *
+     * @param passed - True if input accepted (clean or sanitized). False if blocked.
+     * @param options.sanitized - True if input was modified during validation.
+     *
+     * @example
+     *   const { clean, modified } = mySanitizer.validate(userInput);
+     *   witness.witnessInputValidation(clean, { sanitized: modified });
+     */
+    witnessInputValidation(passed: boolean, options?: {
+        sanitized?: boolean;
+    }): void;
+    /**
+     * Revoke a previously-issued witness anchor (AI-REV.1).
+     *
+     * Mints an AI-REV.1 anchor that references the target anchor's
+     * fingerprint, creating an immutable revocation receipt.
+     *
+     * @param fingerprint - The 12-character anchor fingerprint to revoke.
+     * @param reason - Revocation reason: model_recall, policy_violation,
+     *   data_contamination, consent_withdrawal, regulatory_order,
+     *   error_correction, or unspecified.
+     * @returns The fingerprint of the revocation anchor itself.
+     */
+    revoke(fingerprint: string, reason?: string): string;
+    /**
+     * Record a witnessed inference. Extracts factors, applies clearing,
+     * and enqueues payloads for background flush.
+     *
+     * If factorHandoff is configured, factors are written to the handoff
+     * destination BEFORE clearing proceeds. If the handoff fails, the
+     * payload is NOT transmitted.
+     */
+    record(inference: InferenceRecord, authorizationId?: string): void;
+    /**
+     * Create a Vercel AI SDK `onFinish` callback for streamText / generateText.
+     *
+     * Usage:
+     *   const result = await streamText({
+     *     model: openai("gpt-4o"),
+     *     prompt: myPrompt,
+     *     onFinish: witness.vercelOnFinish({ promptText: myPrompt }),
+     *   });
+     */
+    vercelOnFinish(options?: VercelOnFinishOptions): (result: unknown) => void;
+    /** Force-flush all buffered payloads. */
+    flush(): Promise<WitnessReceipt[]>;
+    /** Stop the witness and flush remaining payloads. */
+    stop(): Promise<WitnessReceipt[]>;
+    /** Number of payloads waiting. */
+    get pending(): number;
+    /** All receipts from completed flushes. */
+    get receipts(): WitnessReceipt[];
+}
+//# sourceMappingURL=witness.d.ts.map

package/dist/witness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"witness.d.ts","sourceRoot":"","sources":["../src/witness.ts"],"names":[],"mappings":"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"}

package/dist/witness.js

@@ -0,0 +1,487 @@
+/**
+ * SWT3 AI Witness SDK — Core Witness class.
+ *
+ * Usage:
+ *   import { Witness } from "@tenova/swt3-ai";
+ *   import OpenAI from "openai";
+ *
+ *   const witness = new Witness({
+ *     endpoint: "https://sovereign.tenova.io",
+ *     apiKey: "axm_live_...",
+ *     tenantId: "YOUR_TENANT_ID",
+ *   });
+ *
+ *   const client = witness.wrap(new OpenAI()) as OpenAI;
+ *   const response = await client.chat.completions.create({ ... });
+ *
+ *   // Graceful shutdown
+ *   await witness.flush();
+ *
+ * Copyright (c) 2026 Tenable Nova LLC. Apache 2.0. Patent pending.
+ */
+import { randomUUID } from "node:crypto";
+import { sha256Truncated, mintFingerprint, timestampMs } from "./fingerprint.js";
+import { extractPayloads, extractGatekeeperPayload, extractRevocationPayload, REVOCATION_REASONS } from "./clearing.js";
+import { signPayload } from "./signing.js";
+import { WitnessBuffer } from "./buffer.js";
+import { writeHandoffFiles } from "./handoff.js";
+import { wrapOpenAI } from "./adapters/openai.js";
+import { wrapAnthropic } from "./adapters/anthropic.js";
+import { wrapBedrock } from "./adapters/bedrock.js";
+import { createVercelOnFinish } from "./adapters/vercel-ai.js";
+/**
+ * Raised when strict (gatekeeper) mode blocks an inference due to
+ * insufficient guardrails. The inference never reaches the AI model.
+ */
+export class GatekeeperError extends Error {
+    required;
+    active;
+    missingNames;
+    constructor(required, active, missingNames = []) {
+        const msg = `Gatekeeper blocked: ${active} guardrails active, ${required} required` +
+            (missingNames.length ? `. Missing: ${missingNames.join(", ")}` : "");
+        super(msg);
+        this.name = "GatekeeperError";
+        this.required = required;
+        this.active = active;
+        this.missingNames = missingNames;
+    }
+}
+export class Witness {
+    config;
+    buffer;
+    handoffWarned = false;
+    _strict;
+    constructor(options) {
+        if (!options.endpoint)
+            throw new Error("endpoint is required");
+        if (!options.apiKey)
+            throw new Error("apiKey is required");
+        if (!options.apiKey.startsWith("axm_"))
+            throw new Error("apiKey must start with 'axm_'");
+        if (!options.tenantId)
+            throw new Error("tenantId is required");
+        if (options.factorHandoff && options.factorHandoff !== "file") {
+            throw new Error("factorHandoff must be 'file'");
+        }
+        if (options.factorHandoff === "file" && !options.factorHandoffPath) {
+            throw new Error("factorHandoffPath is required when factorHandoff is 'file'");
+        }
+        this.config = {
+            endpoint: options.endpoint.replace(/\/+$/, ""),
+            apiKey: options.apiKey,
+            tenantId: options.tenantId,
+            clearingLevel: options.clearingLevel ?? 1,
+            bufferSize: options.bufferSize ?? 10,
+            flushInterval: options.flushInterval ?? 5.0,
+            timeout: options.timeout ?? 10000,
+            maxRetries: options.maxRetries ?? 3,
+            latencyThresholdMs: options.latencyThresholdMs ?? 30000,
+            guardrailsRequired: options.guardrailsRequired ?? 0,
+            guardrailNames: options.guardrailNames ?? [],
+            procedures: options.procedures,
+            factorHandoff: options.factorHandoff,
+            factorHandoffPath: options.factorHandoffPath,
+            agentId: options.agentId,
+            signingKey: options.signingKey,
+            cycleId: options.cycleId,
+            policyVersion: options.policyVersion,
+            jurisdiction: options.jurisdiction,
+            legalBasis: options.legalBasis,
+            purposeClass: options.purposeClass,
+            onFlush: options.onFlush,
+        };
+        this._strict = options.strict ?? false;
+        this.buffer = new WitnessBuffer(this.config);
+    }
+    /**
+     * Wrap an AI client with transparent witnessing.
+     *
+     * Supported: OpenAI, Anthropic
+     * Returns a proxy that behaves identically to the original client.
+     *
+     * Usage:
+     *   const client = witness.wrap(new OpenAI()) as OpenAI;
+     *   const client = witness.wrap(new Anthropic()) as Anthropic;
+     */
+    wrap(client) {
+        const proto = Object.getPrototypeOf(client);
+        const name = proto?.constructor?.name ?? "";
+        const obj = client;
+        // OpenAI: has client.chat.completions
+        if (name === "OpenAI" || obj?.chat) {
+            return wrapOpenAI(client, this);
+        }
+        // Anthropic: has client.messages
+        if (name === "Anthropic" || (obj?.messages && !obj?.chat)) {
+            return wrapAnthropic(client, this);
+        }
+        // AWS Bedrock: has client.send and client.config
+        if (name === "BedrockRuntimeClient" || (obj?.send && obj?.config)) {
+            return wrapBedrock(client, this);
+        }
+        throw new TypeError(`Unsupported client: ${name || "unknown"}. Supported: OpenAI, Anthropic, BedrockRuntimeClient.`);
+    }
+    /** Whether strict (gatekeeper) mode is enabled. Used by adapters. */
+    get strict() {
+        return this._strict;
+    }
+    /**
+     * Pre-call guardrail gate (strict mode only).
+     *
+     * Evaluates whether configured guardrail requirements are met BEFORE
+     * the inference call reaches the AI model. If requirements are not met,
+     * throws `GatekeeperError` and mints an AI-GRD.3 anchor recording
+     * the rejection. The rejection is evidence — it is enqueued for flush.
+     *
+     * This method is SYNCHRONOUS — evaluates local config only, no network.
+     *
+     * @throws {GatekeeperError} if guardrail requirements are not met
+     */
+    gateCheck(_messages, _model) {
+        const required = this.config.guardrailsRequired;
+        const active = this.config.guardrailNames.length;
+        const gatePassed = active >= required;
+        // Mint AI-GRD.3 anchor regardless of outcome — rejection is evidence
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12)
+            : undefined;
+        const payload = extractGatekeeperPayload(this.config.tenantId, required, active, gatePassed, this.config.clearingLevel, this.config.agentId, this.config.signingKey, this.config.cycleId, policyHash, this.config.jurisdiction, this.config.legalBasis, this.config.purposeClass);
+        this.buffer.enqueueMany([payload]);
+        if (!gatePassed) {
+            throw new GatekeeperError(required, active);
+        }
+        return payload.anchor_fingerprint;
+    }
+    /**
+     * Wrap a function as a witnessed tool call (AI-TOOL.1).
+     *
+     * Usage:
+     *   const search = witness.wrapTool(searchDatabase, "search_db");
+     *   const result = await search("SELECT ...");
+     *
+     * Each call mints an AI-TOOL.1 anchor with:
+     *   factor_a = 1 (tool was called)
+     *   factor_b = latency_ms
+     *   factor_c = 1 if succeeded, 0 if exception raised
+     */
+    wrapTool(fn, toolName) {
+        const name = toolName ?? fn.name ?? "anonymous";
+        const self = this;
+        const wrapper = function (...args) {
+            const callId = randomUUID().replace(/-/g, "").slice(0, 12);
+            const start = performance.now();
+            let succeeded = true;
+            let result;
+            const finish = () => {
+                const elapsedMs = Math.round(performance.now() - start);
+                const inputHash = sha256Truncated(JSON.stringify(args));
+                const outputHash = sha256Truncated(succeeded ? JSON.stringify(result) : "ERROR");
+                const record = {
+                    modelId: name,
+                    modelHash: sha256Truncated(name),
+                    promptHash: inputHash,
+                    responseHash: outputHash,
+                    latencyMs: elapsedMs,
+                    guardrailsActive: 0,
+                    guardrailsRequired: 0,
+                    guardrailPassed: true,
+                    hasRefusal: !succeeded,
+                    provider: "tool",
+                    guardrailNames: [],
+                    toolName: name,
+                    toolCallId: callId,
+                };
+                self.record(record);
+            };
+            try {
+                result = fn.apply(this, args);
+            }
+            catch (err) {
+                succeeded = false;
+                finish();
+                throw err;
+            }
+            // Handle async functions (Promise detection)
+            if (result && typeof result.then === "function") {
+                return result.then((v) => {
+                    result = v;
+                    finish();
+                    return v;
+                }, (err) => {
+                    succeeded = false;
+                    finish();
+                    throw err;
+                });
+            }
+            finish();
+            return result;
+        };
+        return wrapper;
+    }
+    /**
+     * Wrap a function as a witnessed access attempt (AI-ACC.1).
+     *
+     * Usage:
+     *   const queryDb = witness.wrapAccess(dbQuery, "prod-database", "read-only analytics");
+     *   const result = await queryDb("SELECT ...");
+     *
+     * Each call mints an AI-ACC.1 anchor with:
+     *   factor_a = 1 (access attempt occurred)
+     *   factor_b = 1 if within declared scope (or no scope set), 0 if out of scope
+     *   factor_c = 1 if access granted, 0 if denied/failed
+     */
+    wrapAccess(fn, resourceName, scope) {
+        const name = resourceName ?? fn.name ?? "unknown-resource";
+        const self = this;
+        const wrapper = function (...args) {
+            const start = performance.now();
+            let granted = true;
+            let result;
+            const finish = () => {
+                const elapsedMs = Math.round(performance.now() - start);
+                const inputHash = sha256Truncated(JSON.stringify(args));
+                const outputHash = sha256Truncated(granted ? JSON.stringify(result) : "ACCESS_DENIED");
+                const record = {
+                    modelId: name,
+                    modelHash: sha256Truncated(name),
+                    promptHash: inputHash,
+                    responseHash: outputHash,
+                    latencyMs: elapsedMs,
+                    guardrailsActive: 0,
+                    guardrailsRequired: 0,
+                    guardrailPassed: true,
+                    hasRefusal: !granted,
+                    provider: "access",
+                    guardrailNames: [],
+                    accessTarget: name,
+                    accessGranted: granted,
+                    accessScope: scope,
+                };
+                self.record(record);
+            };
+            try {
+                result = fn.apply(this, args);
+            }
+            catch (err) {
+                granted = false;
+                finish();
+                throw err;
+            }
+            // Handle async functions (Promise detection)
+            if (result && typeof result.then === "function") {
+                return result.then((v) => {
+                    result = v;
+                    finish();
+                    return v;
+                }, (err) => {
+                    granted = false;
+                    finish();
+                    throw err;
+                });
+            }
+            finish();
+            return result;
+        };
+        return wrapper;
+    }
+    /**
+     * Witness a security/adversarial detection result (AI-SEC.1).
+     *
+     * Call after running your own detection system (Prompt Guard, LlamaGuard,
+     * NeMo Guardrails, etc.) to record the result as a tamper-evident anchor.
+     *
+     * @param threatScore - Detection score from your system (0-1000 scale).
+     * @param options.threshold - Score above which input is a threat. Default 500.
+     * @param options.threatType - One of: none, prompt_injection, data_poisoning,
+     *   model_extraction, jailbreak, adversarial_input.
+     *
+     * @example
+     *   const score = await promptGuard.scan(userInput);
+     *   witness.witnessSecurityScan(score, { threatType: "prompt_injection" });
+     */
+    witnessSecurityScan(threatScore, options) {
+        const threshold = options?.threshold ?? 500;
+        const threatType = options?.threatType ?? "none";
+        const threatCodes = {
+            none: 0, prompt_injection: 1, data_poisoning: 2,
+            model_extraction: 3, jailbreak: 4, adversarial_input: 5,
+        };
+        const [ts, epoch] = timestampMs();
+        const fa = threshold;
+        const fb = threatScore;
+        const fc = threatCodes[threatType] ?? 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-SEC.1", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-SEC.1",
+            factor_a: fa,
+            factor_b: fb,
+            factor_c: fc,
+            clearing_level: this.config.clearingLevel,
+            anchor_fingerprint: fp,
+            anchor_epoch: epoch,
+            fingerprint_timestamp_ms: ts,
+        };
+        if (this.config.clearingLevel <= 1) {
+            payload.ai_model_id = "security-scan";
+            payload.ai_context = { provider: "security" };
+        }
+        if (this.config.agentId)
+            payload.agent_id = this.config.agentId;
+        if (this.config.cycleId)
+            payload.cycle_id = this.config.cycleId;
+        if (this.config.jurisdiction)
+            payload.jurisdiction = this.config.jurisdiction;
+        if (this.config.legalBasis)
+            payload.legal_basis = this.config.legalBasis;
+        if (this.config.purposeClass)
+            payload.purpose_class = this.config.purposeClass;
+        if (this.config.policyVersion) {
+            payload.policy_version_hash = sha256Truncated(this.config.policyVersion, 12);
+        }
+        if (this.config.signingKey) {
+            payload.payload_signature = signPayload(this.config.signingKey, fp, this.config.agentId);
+        }
+        this.buffer.enqueueMany([payload]);
+    }
+    /**
+     * Witness an input validation/sanitization result (AI-SEC.2).
+     *
+     * Call after validating or sanitizing user input before inference.
+     *
+     * @param passed - True if input accepted (clean or sanitized). False if blocked.
+     * @param options.sanitized - True if input was modified during validation.
+     *
+     * @example
+     *   const { clean, modified } = mySanitizer.validate(userInput);
+     *   witness.witnessInputValidation(clean, { sanitized: modified });
+     */
+    witnessInputValidation(passed, options) {
+        const sanitized = options?.sanitized ?? false;
+        const [ts, epoch] = timestampMs();
+        const fa = 1;
+        const fb = passed ? 1 : 0;
+        const fc = (passed && !sanitized) ? 0 : (passed && sanitized) ? 1 : 2;
+        const fp = mintFingerprint(this.config.tenantId, "AI-SEC.2", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-SEC.2",
+            factor_a: fa,
+            factor_b: fb,
+            factor_c: fc,
+            clearing_level: this.config.clearingLevel,
+            anchor_fingerprint: fp,
+            anchor_epoch: epoch,
+            fingerprint_timestamp_ms: ts,
+        };
+        if (this.config.clearingLevel <= 1) {
+            payload.ai_model_id = "input-validation";
+            payload.ai_context = { provider: "security" };
+        }
+        if (this.config.agentId)
+            payload.agent_id = this.config.agentId;
+        if (this.config.cycleId)
+            payload.cycle_id = this.config.cycleId;
+        if (this.config.jurisdiction)
+            payload.jurisdiction = this.config.jurisdiction;
+        if (this.config.legalBasis)
+            payload.legal_basis = this.config.legalBasis;
+        if (this.config.purposeClass)
+            payload.purpose_class = this.config.purposeClass;
+        if (this.config.policyVersion) {
+            payload.policy_version_hash = sha256Truncated(this.config.policyVersion, 12);
+        }
+        if (this.config.signingKey) {
+            payload.payload_signature = signPayload(this.config.signingKey, fp, this.config.agentId);
+        }
+        this.buffer.enqueueMany([payload]);
+    }
+    /**
+     * Revoke a previously-issued witness anchor (AI-REV.1).
+     *
+     * Mints an AI-REV.1 anchor that references the target anchor's
+     * fingerprint, creating an immutable revocation receipt.
+     *
+     * @param fingerprint - The 12-character anchor fingerprint to revoke.
+     * @param reason - Revocation reason: model_recall, policy_violation,
+     *   data_contamination, consent_withdrawal, regulatory_order,
+     *   error_correction, or unspecified.
+     * @returns The fingerprint of the revocation anchor itself.
+     */
+    revoke(fingerprint, reason = "unspecified") {
+        if (!fingerprint?.trim()) {
+            throw new Error("fingerprint is required for revocation");
+        }
+        if (!(reason in REVOCATION_REASONS)) {
+            throw new Error(`Unknown revocation reason: "${reason}". Valid: ${Object.keys(REVOCATION_REASONS).sort().join(", ")}`);
+        }
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12)
+            : undefined;
+        const payload = extractRevocationPayload(this.config.tenantId, fingerprint.trim(), reason, this.config.clearingLevel, this.config.agentId, this.config.signingKey, this.config.cycleId, policyHash, this.config.jurisdiction, this.config.legalBasis, this.config.purposeClass);
+        this.buffer.enqueueMany([payload]);
+        return payload.anchor_fingerprint;
+    }
+    /**
+     * Record a witnessed inference. Extracts factors, applies clearing,
+     * and enqueues payloads for background flush.
+     *
+     * If factorHandoff is configured, factors are written to the handoff
+     * destination BEFORE clearing proceeds. If the handoff fails, the
+     * payload is NOT transmitted.
+     */
+    record(inference, authorizationId) {
+        // Merge guardrail config
+        if (this.config.guardrailNames.length > 0 && inference.guardrailNames.length === 0) {
+            inference.guardrailNames = this.config.guardrailNames;
+            inference.guardrailsActive = this.config.guardrailNames.length;
+            inference.guardrailsRequired = this.config.guardrailsRequired;
+        }
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12)
+            : undefined;
+        const payloads = extractPayloads(inference, this.config.tenantId, this.config.clearingLevel, this.config.latencyThresholdMs, this.config.guardrailsRequired, this.config.procedures, this.config.agentId, this.config.signingKey, this.config.cycleId, policyHash, this.config.jurisdiction, this.config.legalBasis, this.config.purposeClass, authorizationId);
+        // Factor handoff: write full (uncleared) data to custody destination
+        // BEFORE enqueuing the cleared payload for transmission.
+        // If this fails, we do NOT proceed.
+        if (this.config.factorHandoff === "file" && this.config.factorHandoffPath) {
+            writeHandoffFiles(payloads, inference, this.config.tenantId, this.config.factorHandoffPath);
+            if (!this.handoffWarned) {
+                this.handoffWarned = true;
+                console.info(`\n  [SWT3] ${payloads.length} anchors saved locally to ${this.config.factorHandoffPath}` +
+                    `\n  [SWT3] \u26a0 Local anchors won\u2019t survive a compliance audit.` +
+                    `\n  [SWT3] Connect to Axiom Engine \u2192 https://sovereign.tenova.io/signup?ref=sdk (free)\n`);
+            }
+        }
+        this.buffer.enqueueMany(payloads);
+    }
+    /**
+     * Create a Vercel AI SDK `onFinish` callback for streamText / generateText.
+     *
+     * Usage:
+     *   const result = await streamText({
+     *     model: openai("gpt-4o"),
+     *     prompt: myPrompt,
+     *     onFinish: witness.vercelOnFinish({ promptText: myPrompt }),
+     *   });
+     */
+    vercelOnFinish(options) {
+        return createVercelOnFinish(this, options);
+    }
+    /** Force-flush all buffered payloads. */
+    async flush() {
+        return this.buffer.flush();
+    }
+    /** Stop the witness and flush remaining payloads. */
+    async stop() {
+        return this.buffer.stop();
+    }
+    /** Number of payloads waiting. */
+    get pending() {
+        return this.buffer.pending;
+    }
+    /** All receipts from completed flushes. */
+    get receipts() {
+        return this.buffer.receipts;
+    }
+}
+//# sourceMappingURL=witness.js.map