@tenova/swt3-ai 0.5.1 → 0.5.3

package/dist/witness.js

@@ -24,13 +24,158 @@ 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 { WriteAheadLog } from "./wal.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 { wrapOllama, isOllamaClient } from "./adapters/ollama.js";
+import { queryHardware as queryHw, topologyCode as topoCode, queryTPM as queryTpm, ZERO_PCR_HASH } from "./hardware.js";
+import { queryEnvironment as queryEnv } from "./environment.js";
+import { TrustRegistry, verifyCredential, signCredential, TRUST_LEVEL_NAMES, } from "./trust.js";
 import { createVercelOnFinish } from "./adapters/vercel-ai.js";
-import { loadConfig as loadConfigFromFile } from "./config.js";
+import { QUANTIZATION_CODES, POLICY_CATEGORIES, BINDING_METHODS, APPROVAL_STATUS, PII_EVENT_TYPES } from "./types.js";
+import { loadFullConfig, validatePolicy } from "./config.js";
+import { MerkleAccumulator } from "./merkle.js";
+// ── Chain Density Enforcement ──────────────────────────────────────────
+function globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp("^" + escaped + "$");
+}
+function parseVelocity(spec) {
+    const parts = spec.split("/");
+    const limit = parseInt(parts[0], 10);
+    const windowS = parseInt(parts[1].replace("s", ""), 10);
+    return { limit, windowMs: windowS * 1000 };
+}
+export class PolicyViolationError extends Error {
+    violation;
+    constructor(violation) {
+        super(`Chain policy violation: ${violation.reason}`);
+        this.name = "PolicyViolationError";
+        this.violation = violation;
+    }
+}
+/**
+ * Chain density enforcement engine.
+ *
+ * Evaluates tool calls against rate limits, depth limits, allow/blocklists,
+ * and custom rules. All checks are in-memory, zero network calls.
+ * Instantiated from McpPolicyConfig by Witness.fromConfig().
+ */
+export class ChainEnforcer {
+    velocityWindow = [];
+    velocityLimit = 0;
+    velocityWindowMs = 0;
+    chainDepth = 0;
+    maxChainDepth;
+    allowPatterns;
+    blockPatterns;
+    failSecure;
+    customRules;
+    lastToolName = null;
+    tokenCount = 0;
+    maxTokensPerSession;
+    _violations = [];
+    constructor(policy) {
+        if (policy.maxVelocity) {
+            const parsed = parseVelocity(policy.maxVelocity);
+            this.velocityLimit = parsed.limit;
+            this.velocityWindowMs = parsed.windowMs;
+        }
+        this.maxChainDepth = policy.maxChainDepth ?? Infinity;
+        this.maxTokensPerSession = policy.maxTokensPerSession ?? Infinity;
+        this.allowPatterns = (policy.toolAllowlist?.length)
+            ? policy.toolAllowlist.map(globToRegex)
+            : null;
+        this.blockPatterns = (policy.toolBlocklist ?? []).map(globToRegex);
+        this.failSecure = policy.failSecure ?? true;
+        this.customRules = (policy.rules ?? []).map((r) => ({
+            ...r,
+            regex: globToRegex(r.match),
+        }));
+    }
+    check(toolName) {
+        const now = Date.now();
+        // 1. Blocklist
+        for (const pattern of this.blockPatterns) {
+            if (pattern.test(toolName)) {
+                return this.violation("blocklist", toolName, "blocked", `Tool "${toolName}" is on the blocklist`, now);
+            }
+        }
+        // 2. Allowlist (skip if null = all allowed)
+        if (this.allowPatterns) {
+            const allowed = this.allowPatterns.some((p) => p.test(toolName));
+            if (!allowed) {
+                return this.violation("allowlist", toolName, "blocked", `Tool "${toolName}" is not on the allowlist`, now);
+            }
+        }
+        // 3. Velocity (sliding window)
+        if (this.velocityLimit > 0) {
+            const cutoff = now - this.velocityWindowMs;
+            while (this.velocityWindow.length > 0 && this.velocityWindow[0] <= cutoff) {
+                this.velocityWindow.shift();
+            }
+            if (this.velocityWindow.length >= this.velocityLimit) {
+                const action = this.failSecure ? "blocked" : "logged";
+                return this.violation("velocity", toolName, action, `Rate limit exceeded: ${this.velocityLimit} calls per ${this.velocityWindowMs / 1000}s`, now, { currentCount: this.velocityWindow.length, limit: this.velocityLimit });
+            }
+            this.velocityWindow.push(now);
+        }
+        // 4. Depth tracking
+        if (this.maxChainDepth < Infinity) {
+            if (toolName !== this.lastToolName && this.lastToolName !== null) {
+                this.chainDepth = 0;
+            }
+            this.chainDepth++;
+            this.lastToolName = toolName;
+            if (this.chainDepth > this.maxChainDepth) {
+                const action = this.failSecure ? "blocked" : "logged";
+                return this.violation("depth", toolName, action, `Chain depth ${this.chainDepth} exceeds max ${this.maxChainDepth}`, now, { currentDepth: this.chainDepth, maxDepth: this.maxChainDepth });
+            }
+        }
+        // 5. Token budget
+        if (this.maxTokensPerSession < Infinity && this.tokenCount >= this.maxTokensPerSession) {
+            const action = this.failSecure ? "blocked" : "logged";
+            const v = this.violation("token_budget", toolName, action, `Token budget exceeded: ${this.tokenCount} tokens consumed, limit is ${this.maxTokensPerSession}`, now, { currentTokens: this.tokenCount, limit: this.maxTokensPerSession });
+            this._violations.push(v);
+            return v;
+        }
+        // 6. Custom rules
+        for (const rule of this.customRules) {
+            if (rule.regex.test(toolName)) {
+                return this.violation(`custom:${rule.reason}`, toolName, rule.action === "block" ? "blocked" : "logged", rule.reason, now, rule.params);
+            }
+        }
+        return null;
+    }
+    resetDepth() {
+        this.chainDepth = 0;
+        this.lastToolName = null;
+    }
+    recordTokens(count) {
+        this.tokenCount += count;
+    }
+    resetTokens() {
+        this.tokenCount = 0;
+    }
+    get currentTokenCount() {
+        return this.tokenCount;
+    }
+    get violations() {
+        return this._violations;
+    }
+    clearViolations() {
+        this._violations = [];
+    }
+    violation(rule, toolName, action, reason, timestamp, context) {
+        const v = { rule, toolName, action, reason, timestamp, ...(context ? { context } : {}) };
+        this._violations.push(v);
+        return v;
+    }
+}
 /**
  * Raised when strict (gatekeeper) mode blocks an inference due to
  * insufficient guardrails. The inference never reaches the AI model.
@@ -71,8 +216,128 @@ export class Witness {
      * Requires: `npm install yaml`
      */
     static fromConfig(path, overrides) {
-        const config = loadConfigFromFile(path);
-        return new Witness({ ...config, ...overrides });
+        const loaded = loadFullConfig(path);
+        const mergedOptions = { ...loaded.witnessOptions, ...overrides };
+        // Re-validate policy AFTER overrides to prevent silent downgrades
+        if (loaded.policy && overrides) {
+            validatePolicy(mergedOptions, {
+                require_signing: loaded.policy.requireSigning,
+                min_clearing_level: loaded.policy.minClearingLevel,
+                required_procedures: loaded.policy.requiredProcedures,
+                require_agent_id: loaded.policy.requireAgentId,
+                max_flush_interval: loaded.policy.maxFlushInterval,
+                require_jurisdiction: loaded.policy.requireJurisdiction,
+            });
+        }
+        const witness = new Witness(mergedOptions);
+        witness._configHash = loaded.configHash;
+        if (loaded.trustMesh) {
+            witness._configureTrustMesh(loaded.trustMesh);
+        }
+        if (loaded.hardware) {
+            witness._hardwareConfig = loaded.hardware;
+            if (loaded.hardware.requireAttestation) {
+                witness.witnessHardware();
+            }
+        }
+        if (loaded.densityPolicy) {
+            witness._densityPolicy = loaded.densityPolicy;
+        }
+        if (loaded.mcpPolicy) {
+            witness._mcpPolicy = loaded.mcpPolicy;
+            const p = loaded.mcpPolicy;
+            if (p.maxVelocity || p.maxChainDepth !== undefined || p.maxTokensPerSession !== undefined ||
+                p.toolAllowlist?.length || p.toolBlocklist?.length || p.rules?.length) {
+                witness._chainEnforcer = new ChainEnforcer(p);
+            }
+        }
+        if (loaded.merkle) {
+            witness._merkleConfig = loaded.merkle;
+            if (loaded.merkle.enabled) {
+                witness._merkleAccumulator = new MerkleAccumulator({
+                    tenantId: loaded.witnessOptions.tenantId
+                        ?? loaded.witnessOptions.tenant_id,
+                });
+            }
+        }
+        return witness;
+    }
+    _configHash;
+    _hardwareConfig;
+    _densityPolicy;
+    _mcpPolicy;
+    _merkleConfig;
+    _merkleAccumulator;
+    _chainEnforcer;
+    get configHash() {
+        return this._configHash;
+    }
+    /** Density policy from YAML config (null if not configured). */
+    get densityPolicy() {
+        return this._densityPolicy;
+    }
+    /** MCP tool witnessing policy from YAML config (null if not configured). */
+    get mcpPolicy() {
+        return this._mcpPolicy;
+    }
+    /** Merkle accumulator config from YAML config (null if not configured). */
+    get merkleConfig() {
+        return this._merkleConfig;
+    }
+    /** SDK-side Merkle accumulator (created when merkle.enabled is true). */
+    get merkleAccumulator() {
+        return this._merkleAccumulator;
+    }
+    /** Chain density enforcer (created when chain density fields are configured). */
+    get chainEnforcer() {
+        return this._chainEnforcer;
+    }
+    /** Record token usage against the chain enforcer's session budget. */
+    recordSessionTokens(count) {
+        if (this._chainEnforcer) {
+            this._chainEnforcer.recordTokens(count);
+        }
+    }
+    _recordChainViolation(violation) {
+        const record = {
+            modelId: violation.toolName,
+            modelHash: sha256Truncated(violation.toolName),
+            promptHash: sha256Truncated(violation.rule),
+            responseHash: sha256Truncated(violation.reason),
+            latencyMs: 0,
+            guardrailsActive: 0,
+            guardrailsRequired: 0,
+            guardrailPassed: false,
+            hasRefusal: true,
+            provider: "chain-enforcer",
+            guardrailNames: [],
+            toolName: violation.toolName,
+            toolCallId: `chain-${violation.timestamp}`,
+        };
+        this.record(record);
+    }
+    _configureTrustMesh(mesh) {
+        const registry = this.trustRegistry;
+        for (const t of mesh.trustedTenants)
+            registry.trustTenant(t);
+        for (const ta of mesh.trustedAgents)
+            registry.trustAgent(ta.tenant, ta.agent);
+        for (const a of mesh.denyAgents)
+            registry.denyAgent(a);
+        for (const t of mesh.denyTenants)
+            registry.denyTenant(t);
+        registry.setRequireSignature(mesh.requireSignature);
+        registry.setMinTrustLevel(mesh.minTrustLevel);
+        registry.setFreshnessWindow(mesh.freshnessWindow);
+        if (mesh.requiredProcedures.length > 0) {
+            registry.setRequiredProcedures(mesh.requiredProcedures);
+        }
+        for (const sk of mesh.signingKeys) {
+            registry.registerSigningKey(sk.agent, sk.key);
+        }
+        if (mesh.mode === "strict" && !mesh.requireSignature) {
+            registry.setRequireSignature(true);
+        }
     }
     constructor(options) {
         this._gatewayMode = options.gatewayMode ?? false;
@@ -115,10 +380,26 @@ export class Witness {
             jurisdiction: options.jurisdiction,
             legalBasis: options.legalBasis,
             purposeClass: options.purposeClass,
+            tokenBudget: options.tokenBudget,
             onFlush: options.onFlush,
         };
         this._strict = options.strict ?? false;
-        this.buffer = new WitnessBuffer(this.config);
+        // WAL: crash-resilient buffer persistence + replay protection (patent pending)
+        let wal;
+        if (options.walPath) {
+            wal = new WriteAheadLog(this.config.tenantId, {
+                walDir: options.walPath,
+                replayWindow: options.replayWindow,
+            });
+        }
+        this.buffer = new WitnessBuffer(this.config, undefined, wal);
+        // Recover any unflushed payloads from a previous crash
+        if (wal) {
+            const recovered = wal.recover();
+            if (recovered.length > 0) {
+                this.buffer.enqueueMany(recovered);
+            }
+        }
     }
     /**
      * Wrap an AI client with transparent witnessing.
@@ -199,6 +480,16 @@ export class Witness {
         const name = toolName ?? fn.name ?? "anonymous";
         const self = this;
         const wrapper = function (...args) {
+            // Chain density enforcement -- BEFORE execution
+            if (self._chainEnforcer) {
+                const violation = self._chainEnforcer.check(name);
+                if (violation) {
+                    if (violation.action === "blocked") {
+                        throw new PolicyViolationError(violation);
+                    }
+                    self._recordChainViolation(violation);
+                }
+            }
             const callId = randomUUID().replace(/-/g, "").slice(0, 12);
             const start = performance.now();
             let succeeded = true;
@@ -433,6 +724,367 @@ export class Witness {
         }
         this.buffer.enqueueMany([payload]);
     }
+    /**
+     * Witness a RAG retrieval step (AI-RAG.1 + optional AI-RAG.2).
+     *
+     * Records what context chunks were retrieved and from which corpus.
+     * Chunk text is NEVER transmitted -- only SHA-256 hashes.
+     *
+     * Automatically emits AI-RAG.2 (Context Relevance) when
+     * similarityThreshold is set and chunks have similarityScore.
+     *
+     * @param options.chunks - Raw strings (auto-hashed) or RagChunk objects.
+     * @param options.corpusId - Identifier for the retrieval corpus/index.
+     * @param options.similarityThreshold - When set and chunks have scores,
+     *   AI-RAG.2 is emitted alongside AI-RAG.1.
+     * @returns Array of WitnessPayload objects (1-2 payloads).
+     *
+     * @example
+     *   witness.witnessRagContext({
+     *     chunks: ["chunk text 1", "chunk text 2"],
+     *     corpusId: "legal-docs-v3",
+     *   });
+     */
+    witnessRagContext(options) {
+        const normalized = options.chunks.map((chunk) => {
+            if (typeof chunk === "string") {
+                return { contentHash: sha256Truncated(chunk) };
+            }
+            return chunk;
+        });
+        const payloads = [];
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12)
+            : undefined;
+        // --- AI-RAG.1: Context Retrieval Provenance ---
+        const [ts1, ep1] = timestampMs();
+        const fa1 = normalized.length;
+        const fb1 = options.corpusId ? 1 : 0;
+        const fc1 = 0;
+        const fp1 = mintFingerprint(this.config.tenantId, "AI-RAG.1", fa1, fb1, fc1, ts1);
+        const p1 = {
+            procedure_id: "AI-RAG.1",
+            factor_a: fa1,
+            factor_b: fb1,
+            factor_c: fc1,
+            clearing_level: this.config.clearingLevel,
+            anchor_fingerprint: fp1,
+            anchor_epoch: ep1,
+            fingerprint_timestamp_ms: ts1,
+        };
+        if (this.config.clearingLevel <= 1) {
+            p1.ai_model_id = options.embeddingModel ?? "rag-retrieval";
+            const ctx = {
+                provider: "rag",
+                chunk_count: normalized.length,
+                chunk_hashes: normalized.map((c) => c.contentHash),
+            };
+            if (options.corpusId)
+                ctx.corpus_id = options.corpusId;
+            if (options.corpusHash)
+                ctx.corpus_hash = options.corpusHash;
+            if (options.embeddingModel)
+                ctx.embedding_model = options.embeddingModel;
+            if (options.retrievalLatencyMs != null)
+                ctx.retrieval_latency_ms = options.retrievalLatencyMs;
+            if (options.topK != null)
+                ctx.top_k = options.topK;
+            p1.ai_context = ctx;
+        }
+        if (this.config.clearingLevel <= 2 && options.retrievalLatencyMs != null) {
+            p1.ai_latency_ms = options.retrievalLatencyMs;
+        }
+        this._applyOperationalMetadata(p1, policyHash);
+        payloads.push(p1);
+        // --- AI-RAG.2: Context Relevance (conditional) ---
+        const scoredChunks = normalized.filter((c) => c.similarityScore != null);
+        if (options.similarityThreshold != null && scoredChunks.length > 0) {
+            const scores = scoredChunks.map((c) => c.similarityScore);
+            const avgSim = scores.reduce((a, b) => a + b, 0) / scores.length;
+            const belowCount = scores.filter((s) => s < options.similarityThreshold).length;
+            const [ts2, ep2] = timestampMs();
+            const fa2 = Math.round(options.similarityThreshold * 1000);
+            const fb2 = Math.round(avgSim * 1000);
+            const fc2 = belowCount;
+            const fp2 = mintFingerprint(this.config.tenantId, "AI-RAG.2", fa2, fb2, fc2, ts2);
+            const p2 = {
+                procedure_id: "AI-RAG.2",
+                factor_a: fa2,
+                factor_b: fb2,
+                factor_c: fc2,
+                clearing_level: this.config.clearingLevel,
+                anchor_fingerprint: fp2,
+                anchor_epoch: ep2,
+                fingerprint_timestamp_ms: ts2,
+            };
+            if (this.config.clearingLevel <= 1) {
+                p2.ai_model_id = options.embeddingModel ?? "rag-retrieval";
+                p2.ai_context = {
+                    provider: "rag",
+                    similarity_threshold: options.similarityThreshold,
+                    avg_similarity: Math.round(avgSim * 10000) / 10000,
+                    min_similarity: Math.round(Math.min(...scores) * 10000) / 10000,
+                    chunks_below_threshold: belowCount,
+                    chunk_scores: scores.map((s) => Math.round(s * 10000) / 10000),
+                };
+            }
+            this._applyOperationalMetadata(p2, policyHash);
+            payloads.push(p2);
+        }
+        this.buffer.enqueueMany(payloads);
+        return payloads;
+    }
+    // -- Model Weight & Adapter Methods (AI-MDL.5/6/7) --
+    /**
+     * Hash a model weight file and return a ModelWeightInfo.
+     *
+     * Call ONCE at startup, not per-inference. File I/O is synchronous.
+     *
+     * @example
+     *   const info = Witness.hashModelFile("/models/llama-3.1-70b.safetensors");
+     *   witness.witnessModelWeights(info);
+     */
+    static hashModelFile(filePath, format) {
+        const { createHash } = require("node:crypto");
+        const fs = require("node:fs");
+        const path = require("node:path");
+        const hash = createHash("sha256");
+        const buf = fs.readFileSync(filePath);
+        hash.update(buf);
+        const ext = path.extname(filePath).replace(".", "");
+        return {
+            fileHash: hash.digest("hex"),
+            filePath,
+            fileSizeBytes: buf.length,
+            format: format ?? (ext || undefined),
+        };
+    }
+    /**
+     * Witness model weight file integrity (AI-MDL.5).
+     *
+     * @param weights - ModelWeightInfo (from hashModelFile() or manual),
+     *   or file path string (blocks for large files -- prefer hashModelFile()).
+     * @param options.expectedHash - If provided and matches, PASS. If mismatches, FAIL.
+     */
+    witnessModelWeights(weights, options) {
+        const info = typeof weights === "string"
+            ? Witness.hashModelFile(weights)
+            : weights;
+        const match = options?.expectedHash ? info.fileHash === options.expectedHash : true;
+        const [ts, epoch] = timestampMs();
+        const fa = 1, fb = match ? 1 : 0, fc = 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-MDL.5", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-MDL.5", 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 = info.format ?? "model-weights";
+            const ctx = { provider: "model-weights", file_hash: info.fileHash };
+            if (info.filePath)
+                ctx.file_path = info.filePath;
+            if (info.fileSizeBytes != null)
+                ctx.file_size_bytes = info.fileSizeBytes;
+            if (info.format)
+                ctx.format = info.format;
+            if (options?.expectedHash)
+                ctx.expected_hash = options.expectedHash;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness active LoRA/QLoRA/PEFT adapter stack (AI-MDL.6).
+     */
+    witnessAdapterStack(adapters, baseModelId) {
+        const allVerified = adapters.length === 0 || adapters.every((a) => a.adapterHash);
+        const [ts, epoch] = timestampMs();
+        const fa = adapters.length, fb = allVerified ? 1 : 0, fc = 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-MDL.6", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-MDL.6", 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 = baseModelId ?? "unknown-base";
+            const adapterList = adapters.map((a) => {
+                const obj = { name: a.name, hash: a.adapterHash };
+                if (a.baseModel)
+                    obj.base_model = a.baseModel;
+                return obj;
+            });
+            payload.ai_context = { provider: "adapter", adapters: adapterList };
+            if (baseModelId)
+                payload.ai_context.base_model_id = baseModelId;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness model quantization method (AI-MDL.7).
+     *
+     * @param method - fp32, fp16, bf16, int8, int4, gptq, awq, gguf.
+     */
+    witnessQuantization(method, options) {
+        const code = QUANTIZATION_CODES[method.toLowerCase()] ?? 0;
+        const [ts, epoch] = timestampMs();
+        const fa = 1, fb = 1, fc = code;
+        const fp = mintFingerprint(this.config.tenantId, "AI-MDL.7", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-MDL.7", 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 = `quantization-${method.toLowerCase()}`;
+            const ctx = { provider: "quantization", method: method.toLowerCase() };
+            if (options?.bits != null)
+                ctx.bits = options.bits;
+            if (options?.groupSize != null)
+                ctx.group_size = options.groupSize;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    // -- Procedural Knowledge / Skills Methods (AI-SKILL.1/2/3) --
+    /**
+     * Witness active skill/tool/plugin manifest (AI-SKILL.1).
+     *
+     * @param skills - Skill name strings (auto-hashed) or SkillInfo objects.
+     * @param options.expectedManifestHash - Expected hash of the full manifest.
+     *
+     * @example
+     *   witness.witnessSkillManifest(["code_exec", "web_search", "file_read"]);
+     */
+    witnessSkillManifest(skills, options) {
+        const normalized = skills.map((s) => typeof s === "string" ? { name: s, skillHash: sha256Truncated(s) } : s);
+        const manifestParts = normalized
+            .map((si) => si.skillHash ?? sha256Truncated(si.name))
+            .sort();
+        const computedManifest = sha256Truncated(manifestParts.join(":"));
+        const match = options?.expectedManifestHash ? computedManifest === options.expectedManifestHash : true;
+        const [ts, epoch] = timestampMs();
+        const fa = normalized.length, fb = match ? 1 : 0, fc = 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-SKILL.1", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-SKILL.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 = "skill-manifest";
+            payload.ai_context = {
+                provider: "skill-manifest",
+                skills: normalized.map((si) => {
+                    const obj = { name: si.name };
+                    if (si.version)
+                        obj.version = si.version;
+                    if (si.skillHash)
+                        obj.hash = si.skillHash;
+                    return obj;
+                }),
+                manifest_hash: computedManifest,
+            };
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness persistent memory sources influencing a decision (AI-SKILL.2).
+     */
+    witnessMemoryContext(sources) {
+        const allIdentified = sources.length > 0 && sources.every((s) => s.sourceId || s.contentHash);
+        const [ts, epoch] = timestampMs();
+        const fa = sources.length, fb = allIdentified ? 1 : 0, fc = 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-SKILL.2", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-SKILL.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 = "memory-context";
+            payload.ai_context = {
+                provider: "memory",
+                sources: sources.map((s) => {
+                    const obj = { type: s.sourceType };
+                    if (s.sourceId)
+                        obj.id = s.sourceId;
+                    if (s.contentHash)
+                        obj.hash = s.contentHash;
+                    return obj;
+                }),
+                total_sources: sources.length,
+            };
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness RLHF/DPO reward model binding (AI-SKILL.3).
+     */
+    witnessRewardModel(modelId, options) {
+        const identified = Boolean(modelId?.trim());
+        const [ts, epoch] = timestampMs();
+        const fa = 1, fb = identified ? 1 : 0, fc = 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-SKILL.3", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-SKILL.3", 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 = modelId;
+            const ctx = { provider: "reward-model", model_id: modelId };
+            if (options?.modelHash)
+                ctx.model_hash = options.modelHash;
+            if (options?.method)
+                ctx.method = options.method;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /** Apply operational metadata (agent_id, signing, CJT fields) to a payload. */
+    _applyOperationalMetadata(payload, policyHash) {
+        if (payload.procedure_id)
+            this._witnessedProcedures.add(payload.procedure_id);
+        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 (policyHash)
+            payload.policy_version_hash = policyHash;
+        if (this.config.signingKey) {
+            payload.payload_signature = signPayload(this.config.signingKey, payload.anchor_fingerprint, this.config.agentId);
+            if (this.config.signingKeyId)
+                payload.signing_key_id = this.config.signingKeyId;
+            if (this.config.signingKeyVersion !== undefined)
+                payload.signing_key_version = this.config.signingKeyVersion;
+        }
+    }
     /**
      * Revoke a previously-issued witness anchor (AI-REV.1).
      *
@@ -445,11 +1097,588 @@ export class Witness {
      *   error_correction, or unspecified.
      * @returns The fingerprint of the revocation anchor itself.
      */
+    /**
+     * Witness accelerator hardware inventory (AI-HW.1).
+     *
+     * Records what GPU/accelerator hardware is present. Call ONCE at
+     * service startup, not per-inference. If no GPUs are detectable,
+     * returns a payload with factor_a=0, factor_b=0 (graceful no-op).
+     *
+     * @param options.snapshot - Pre-computed HardwareSnapshot (from queryHardware()).
+     *   If omitted, auto-detects via nvidia-smi.
+     * @param options.expectedTopology - Expected topology (e.g., "NVL72").
+     *   If provided and doesn't match detected topology, factor_b=0.
+     */
+    witnessHardware(options) {
+        const snapshot = options?.snapshot ?? queryHw();
+        const gpuCount = snapshot.gpus.length;
+        let allHealthy = gpuCount > 0;
+        if (options?.expectedTopology && snapshot.topology !== options.expectedTopology) {
+            allHealthy = false;
+        }
+        const fa = gpuCount;
+        const fb = allHealthy ? 1 : 0;
+        const fc = topoCode(snapshot.topology);
+        const [ts, epoch] = timestampMs();
+        const fp = mintFingerprint(this.config.tenantId, "AI-HW.1", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-HW.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 = `hw-${snapshot.topology}`;
+            const ctx = {
+                provider: "nvidia-hw",
+                topology: snapshot.topology,
+                interconnect: snapshot.interconnect,
+                total_memory_mb: snapshot.totalMemoryMb,
+                gpu_count: gpuCount,
+                hostname_hash: snapshot.hostnameHash,
+            };
+            if (snapshot.driverVersion)
+                ctx.driver_version = snapshot.driverVersion;
+            if (snapshot.cudaVersion)
+                ctx.cuda_version = snapshot.cudaVersion;
+            if (snapshot.gpus.length > 0) {
+                ctx.gpus = snapshot.gpus.map((g) => ({
+                    name: g.name,
+                    memory_mb: g.memoryMb,
+                    bus_id_hash: g.busIdHash,
+                    uuid_hash: g.uuidHash,
+                }));
+            }
+            if (options?.expectedTopology)
+                ctx.expected_topology = options.expectedTopology;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12)
+            : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness TPM 2.0 platform attestation (AI-HW.3).
+     *
+     * Reads PCR registers 0-7 via tpm2-tools and mints an anchor proving
+     * host firmware integrity. All raw PCR digests are SHA-256 hashed
+     * before leaving the module.
+     *
+     * @param options.snapshot - Pre-computed TPMSnapshot (from queryTPM()).
+     */
+    witnessTPMAttestation(options) {
+        const snapshot = options?.snapshot ?? queryTpm();
+        const pcrCount = snapshot.pcrs.length;
+        const allNonZero = pcrCount > 0 && snapshot.pcrs.every((pcr) => pcr.digestHash !== ZERO_PCR_HASH);
+        const fa = pcrCount;
+        const fb = allNonZero ? 1 : 0;
+        const fc = 0; // reserved
+        const [ts, epoch] = timestampMs();
+        const fp = mintFingerprint(this.config.tenantId, "AI-HW.3", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-HW.3",
+            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 = "tpm-attestation";
+            const ctx = {
+                provider: "tpm-2.0",
+                pcr_count: pcrCount,
+                all_non_zero: allNonZero,
+                manufacturer_hash: snapshot.manufacturer,
+                firmware_hash: snapshot.firmwareVersion,
+                endorsement_key_hash: snapshot.endorsementKeyHash,
+                hostname_hash: snapshot.hostnameHash,
+            };
+            if (snapshot.pcrs.length > 0) {
+                ctx.pcrs = snapshot.pcrs.map((pcr) => ({
+                    index: pcr.index,
+                    bank: pcr.bank,
+                    digest_hash: pcr.digestHash,
+                }));
+            }
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12)
+            : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    // ── Environment (AI-ENV.1 / AI-ENV.2) ────────────────────────────
+    /**
+     * Witness thermal integrity of the compute environment (AI-ENV.1).
+     *
+     * Call at service startup or on a periodic schedule, not per-inference.
+     * Auto-detects Linux thermal zones. Pass manual values for XFRA/Span nodes.
+     *
+     * @param options.temperatureCelsius - Measured temperature (auto-detected if omitted)
+     * @param options.thresholdCelsius - Safe maximum (default 85)
+     * @param options.snapshot - Pre-computed EnvironmentSnapshot
+     * @param options.nodeType - Node type: datacenter, edge, residential, mobile
+     */
+    witnessEnvironment(options) {
+        const snapshot = options?.snapshot ?? queryEnv();
+        const temp = options?.temperatureCelsius ?? snapshot.temperatureCelsius;
+        const threshold = options?.thresholdCelsius ?? 85;
+        const nodeType = options?.nodeType ?? snapshot.nodeType ?? "unknown";
+        const fa = Math.round(Number(temp) || 0);
+        const fb = Math.round(Number(threshold) || 85);
+        const fc = fa <= fb ? 1 : 0;
+        const [ts, epoch] = timestampMs();
+        const fp = mintFingerprint(this.config.tenantId, "AI-ENV.1", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-ENV.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 = `env-thermal-${nodeType}`;
+            payload.ai_context = {
+                provider: "env-telemetry",
+                node_type: nodeType,
+                temperature_celsius: temp,
+                threshold_celsius: threshold,
+                thermal_zones: snapshot.thermalZones,
+                hostname_hash: snapshot.hostnameHash,
+            };
+        }
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12)
+            : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness power integrity of the compute environment (AI-ENV.2).
+     *
+     * Call at service startup or on a periodic schedule, not per-inference.
+     * Pass manual values from Span panel API, IPMI, or other power monitoring.
+     *
+     * @param options.powerWatts - Current power draw in watts
+     * @param options.capacityWatts - Total available capacity in watts
+     * @param options.throttled - Whether power throttling is active
+     * @param options.snapshot - Pre-computed EnvironmentSnapshot
+     * @param options.nodeType - Node type: datacenter, edge, residential, mobile
+     */
+    witnessEnergyDraw(options) {
+        const snapshot = options?.snapshot ?? queryEnv();
+        const power = Number(options?.powerWatts ?? snapshot.powerWatts) || 0;
+        const capacity = Number(options?.capacityWatts ?? 0) || 0;
+        const headroom = Math.max(0, capacity - power);
+        const throttled = options?.throttled ?? false;
+        const nodeType = options?.nodeType ?? snapshot.nodeType ?? "unknown";
+        const fa = Math.round(power);
+        const fb = Math.round(headroom);
+        const fc = throttled ? 1 : 0;
+        const [ts, epoch] = timestampMs();
+        const fp = mintFingerprint(this.config.tenantId, "AI-ENV.2", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-ENV.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 = `env-power-${nodeType}`;
+            payload.ai_context = {
+                provider: "env-telemetry",
+                node_type: nodeType,
+                power_watts: power,
+                capacity_watts: capacity,
+                headroom_watts: headroom,
+                throttled,
+                power_domains: snapshot.powerDomains,
+                hostname_hash: snapshot.hostnameHash,
+            };
+        }
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12)
+            : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    // ── Chain, Violation, Charter, Registry, Reviewer, Safe State ───
+    /**
+     * Witness a multi-agent chain handoff (AI-CHAIN.1).
+     */
+    witnessChainHandoff(depth, targetAgent, options) {
+        const accepted = options?.accepted ?? true;
+        const [ts, epoch] = timestampMs();
+        const fa = depth;
+        const fb = this.config.cycleId ? 1 : 0;
+        const fc = accepted ? 1 : 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-CHAIN.1", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-CHAIN.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 = targetAgent;
+            payload.ai_context = {
+                provider: "chain", target_agent: targetAgent, depth, accepted,
+            };
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness a policy violation (AI-VIO.1).
+     */
+    witnessViolation(severity, description, options) {
+        const autoDetected = options?.autoDetected ?? false;
+        const policyCategory = options?.policyCategory ?? "unspecified";
+        const [ts, epoch] = timestampMs();
+        const fa = Math.max(1, Math.min(4, severity));
+        const fb = autoDetected ? 1 : 0;
+        const fc = POLICY_CATEGORIES[policyCategory] ?? 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-VIO.1", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-VIO.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 = `violation-sev${fa}`;
+            payload.ai_context = {
+                provider: "violation", severity: fa, description, auto_detected: autoDetected, policy_category: policyCategory,
+            };
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness an agent charter or system prompt hash (AI-CHR.1).
+     */
+    witnessCharter(options) {
+        if (!options.charterText && !options.charterHash) {
+            throw new Error("Provide charterText or charterHash");
+        }
+        const computed = options.charterHash ?? sha256Truncated(options.charterText);
+        const match = options.expectedHash ? computed === options.expectedHash : true;
+        const [ts, epoch] = timestampMs();
+        const fa = 1, fb = match ? 1 : 0, fc = 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-CHR.1", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-CHR.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 = "charter";
+            const ctx = { provider: "charter", charter_hash: computed };
+            if (options.expectedHash)
+                ctx.expected_hash = options.expectedHash;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness a model registry check (AI-MDL.8).
+     */
+    witnessModelRegistry(modelId, registryId, options) {
+        const found = options?.found ?? true;
+        const status = options?.status ?? "approved";
+        const [ts, epoch] = timestampMs();
+        const fa = 1, fb = found ? 1 : 0, fc = APPROVAL_STATUS[status] ?? 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-MDL.8", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-MDL.8", 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 = modelId;
+            payload.ai_context = {
+                provider: "model-registry", model_id: modelId, registry_id: registryId, found, status,
+            };
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness reviewer identity binding (AI-HITL.3).
+     */
+    witnessReviewerIdentity(required, actual, options) {
+        const method = options?.method ?? "session";
+        const [ts, epoch] = timestampMs();
+        const fa = required, fb = actual, fc = BINDING_METHODS[method] ?? 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-HITL.3", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-HITL.3", 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 = "reviewer-identity";
+            const ctx = {
+                provider: "reviewer", required, actual, method,
+            };
+            if (options?.reviewerIdHash)
+                ctx.reviewer_id_hash = options.reviewerIdHash;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness safe state attestation (AI-SAFE.1).
+     */
+    witnessSafeState(options) {
+        const mechanismExists = options?.mechanismExists ?? true;
+        const safeStateConfirmed = options?.safeStateConfirmed ?? true;
+        const [ts, epoch] = timestampMs();
+        const fa = 1, fb = mechanismExists ? 1 : 0, fc = safeStateConfirmed ? 1 : 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-SAFE.1", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-SAFE.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 = "safe-state";
+            const ctx = {
+                provider: "safe-state", mechanism_exists: mechanismExists, safe_state_confirmed: safeStateConfirmed,
+            };
+            if (options?.mechanismType)
+                ctx.mechanism_type = options.mechanismType;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    // ── Training Data (AI-DATA.3 / AI-DATA.4) ──────────────────────
+    /**
+     * Witness training dataset summary statistics (AI-DATA.3).
+     */
+    witnessTrainingStats(rowCount, featureCount, options) {
+        const [ts, epoch] = timestampMs();
+        const fa = rowCount;
+        const fb = featureCount;
+        const fc = options?.classBalanceRatio != null ? Math.floor(options.classBalanceRatio * 1000) : 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-DATA.3", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-DATA.3", 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 = "training-stats";
+            const ctx = {
+                provider: "training-stats", row_count: rowCount, feature_count: featureCount,
+            };
+            if (options?.classBalanceRatio != null)
+                ctx.class_balance_ratio = options.classBalanceRatio;
+            if (options?.distributionHash)
+                ctx.distribution_hash = options.distributionHash;
+            if (options?.classLabels)
+                ctx.class_labels = options.classLabels;
+            if (options?.summary)
+                ctx.summary = options.summary;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    /**
+     * Witness a training data PII lifecycle event (AI-DATA.4).
+     */
+    witnessTrainingPiiLifecycle(recordsAffected, options) {
+        const completed = options?.completed ?? true;
+        const eventType = options?.eventType ?? "unspecified";
+        const [ts, epoch] = timestampMs();
+        const fa = recordsAffected;
+        const fb = completed ? 1 : 0;
+        const fc = PII_EVENT_TYPES[eventType] ?? 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-DATA.4", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-DATA.4", 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 = "pii-lifecycle";
+            const ctx = {
+                provider: "pii-lifecycle", event_type: eventType,
+                records_affected: recordsAffected, completed,
+            };
+            if (options?.datasetId)
+                ctx.dataset_id = options.datasetId;
+            if (options?.scope)
+                ctx.scope = options.scope;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    // ── Bias Assessment (AI-FAIR.3) ─────────────────────────────────
+    /**
+     * Witness a bias assessment (AI-FAIR.3).
+     * Records that a bias assessment was conducted, how many protected
+     * attributes were tested, and whether all fairness thresholds were met.
+     *
+     * @param protectedAttributeCount - Number of demographic dimensions tested
+     * @param allThresholdsMet - true if all fairness thresholds passed
+     * @param options.maxDisparityPct - Worst-case disparity percentage (0-100)
+     * @param options.methodology - Assessment methodology name
+     * @param options.protectedAttributes - List of protected attributes tested
+     */
+    witnessBiasAssessment(protectedAttributeCount, allThresholdsMet, options) {
+        const [ts, epoch] = timestampMs();
+        const fa = protectedAttributeCount;
+        const fb = allThresholdsMet ? 1 : 0;
+        const fc = options?.maxDisparityPct != null ? Math.round(options.maxDisparityPct) : 0;
+        const fp = mintFingerprint(this.config.tenantId, "AI-FAIR.3", fa, fb, fc, ts);
+        const payload = {
+            procedure_id: "AI-FAIR.3", 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 = "bias-assessment";
+            const ctx = {
+                provider: "bias-assessment",
+                protected_attribute_count: protectedAttributeCount,
+                all_thresholds_met: allThresholdsMet,
+            };
+            if (options?.methodology)
+                ctx.methodology = options.methodology;
+            if (options?.protectedAttributes)
+                ctx.protected_attributes = options.protectedAttributes;
+            if (options?.maxDisparityPct != null)
+                ctx.max_disparity_pct = options.maxDisparityPct;
+            payload.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(payload, policyHash);
+        this.buffer.enqueueMany([payload]);
+        return payload;
+    }
+    // ── Trust Mesh (AI-TRUST.1 / AI-TRUST.2) ────────────────────────
+    _trustRegistry;
+    _witnessedProcedures = new Set();
+    get trustRegistry() {
+        if (!this._trustRegistry)
+            this._trustRegistry = new TrustRegistry();
+        return this._trustRegistry;
+    }
+    set trustRegistry(registry) {
+        this._trustRegistry = registry;
+    }
+    presentCredential() {
+        const ts = Date.now();
+        const fpInput = `${this.config.agentId || "anonymous"}:${this.config.tenantId}:${ts}`;
+        const credential = {
+            agentId: this.config.agentId || "anonymous",
+            tenantId: this.config.tenantId,
+            anchorFingerprint: sha256Truncated(fpInput, 12),
+            anchorTimestampMs: ts,
+            isSigned: Boolean(this.config.signingKey),
+            procedures: [...this._witnessedProcedures],
+            clearingLevel: this.config.clearingLevel,
+            hasHardwareAttestation: this._witnessedProcedures.has("AI-HW.1") || this._witnessedProcedures.has("AI-HW.3"),
+            hasGuardrails: this.config.guardrailsRequired > 0 || this.config.guardrailNames.length > 0,
+        };
+        if (this.config.signingKey) {
+            credential.credentialSignature = signCredential(credential, this.config.signingKey);
+        }
+        return credential;
+    }
+    verifyTrust(credential) {
+        const result = verifyCredential(credential, this.trustRegistry, this.config.tenantId);
+        // Mint AI-TRUST.1
+        const [ts1, ep1] = timestampMs();
+        const fa1 = 1, fb1 = result.granted ? 1 : 0, fc1 = result.trustLevel;
+        const fp1 = mintFingerprint(this.config.tenantId, "AI-TRUST.1", fa1, fb1, fc1, ts1);
+        const p1 = {
+            procedure_id: "AI-TRUST.1",
+            factor_a: fa1, factor_b: fb1, factor_c: fc1,
+            clearing_level: this.config.clearingLevel,
+            anchor_fingerprint: fp1, anchor_epoch: ep1, fingerprint_timestamp_ms: ts1,
+        };
+        if (this.config.clearingLevel <= 1) {
+            p1.ai_model_id = `trust-${TRUST_LEVEL_NAMES[result.trustLevel] ?? "unknown"}`;
+            const ctx = {
+                provider: "trust-mesh",
+                counterpart_agent_id: credential.agentId,
+                counterpart_tenant_id: credential.tenantId,
+                trust_level: result.trustLevel,
+                trust_level_name: TRUST_LEVEL_NAMES[result.trustLevel] ?? "unknown",
+                checks_performed: result.checksPerformed,
+                checks_passed: result.checksPassed,
+                granted: result.granted,
+            };
+            if (result.denialReason)
+                ctx.denial_reason = result.denialReason;
+            p1.ai_context = ctx;
+        }
+        const policyHash = this.config.policyVersion
+            ? sha256Truncated(this.config.policyVersion, 12) : undefined;
+        this._applyOperationalMetadata(p1, policyHash);
+        this.buffer.enqueueMany([p1]);
+        // Mint AI-TRUST.2
+        const [ts2, ep2] = timestampMs();
+        const fa2 = result.checksPerformed, fb2 = result.checksPassed;
+        const fc2 = result.granted ? 1 : 0;
+        const fp2 = mintFingerprint(this.config.tenantId, "AI-TRUST.2", fa2, fb2, fc2, ts2);
+        const p2 = {
+            procedure_id: "AI-TRUST.2",
+            factor_a: fa2, factor_b: fb2, factor_c: fc2,
+            clearing_level: this.config.clearingLevel,
+            anchor_fingerprint: fp2, anchor_epoch: ep2, fingerprint_timestamp_ms: ts2,
+        };
+        if (this.config.clearingLevel <= 1) {
+            p2.ai_model_id = "trust-handshake";
+            p2.ai_context = {
+                provider: "trust-mesh",
+                counterpart_agent_id: credential.agentId,
+                handshake_result: result.granted ? "granted" : "denied",
+            };
+        }
+        this._applyOperationalMetadata(p2, policyHash);
+        this.buffer.enqueueMany([p2]);
+        return result;
+    }
     revoke(fingerprint, reason = "unspecified") {
         if (!fingerprint?.trim()) {
             throw new Error("fingerprint is required for revocation");
         }
-        if (!(reason in REVOCATION_REASONS)) {
+        if (!Object.prototype.hasOwnProperty.call(REVOCATION_REASONS, reason)) {
             throw new Error(`Unknown revocation reason: "${reason}". Valid: ${Object.keys(REVOCATION_REASONS).sort().join(", ")}`);
         }
         const policyHash = this.config.policyVersion