@vauban-org/agent-sdk 0.16.0

package/dist/trace/canonical.js

@@ -0,0 +1,139 @@
+/**
+ * canonical — RFC 8785 JSON canonicalization with deterministic pre-processing.
+ *
+ * Pre-processing contract (applied depth-first before canonicalize):
+ *   - Buffer / Uint8Array   → base64 string (RFC 4648 §4, no padding stripping)
+ *   - undefined             → key is omitted (JSON.stringify-compatible semantics)
+ *   - Date                  → ISO-8601 string via .toISOString()
+ *   - BigInt                → { __bigint: string } (decimal representation)
+ *   - NaN / Infinity / -0   → throws NonSerializablePayloadError
+ *   - Circular references   → throws NonSerializablePayloadError
+ *   - Everything else       → left unchanged (strings, booleans, null, plain numbers)
+ *
+ * Usage:
+ *   import { canonicalize, NonSerializablePayloadError } from './canonical.js';
+ *   const json = canonicalize({ b: 2, a: 1 }); // '{"a":1,"b":2}'
+ *
+ * @module trace/canonical
+ */
+import { canonicalize as _rfcCanonicalize } from "json-canonicalize";
+/**
+ * Thrown when the value graph contains a non-serializable primitive
+ * (NaN, Infinity, -0) or a circular reference.
+ */
+export class NonSerializablePayloadError extends Error {
+    path;
+    constructor(reason, path) {
+        super(`NonSerializablePayloadError: ${reason} at path /${path.join("/")}`);
+        this.path = path;
+        this.name = "NonSerializablePayloadError";
+    }
+}
+/**
+ * Convert a Uint8Array (or Node Buffer) to a base64 string.
+ * Uses globalThis.btoa when available (browser/edge), falls back to
+ * Buffer.from().toString('base64') on Node.js.
+ */
+function uint8ToBase64(bytes) {
+    if (typeof globalThis.btoa === "function") {
+        let binary = "";
+        for (let i = 0; i < bytes.length; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return globalThis.btoa(binary);
+    }
+    // Node.js fallback
+    return Buffer.from(bytes).toString("base64");
+}
+/**
+ * Recursively pre-process a value so that it is safe to pass to the
+ * RFC 8785 canonicalizer.  Returns a new value — never mutates input.
+ *
+ * @param value  Input to preprocess.
+ * @param path   Breadcrumb path for error messages (internal use).
+ * @param seen   Cycle detection set (internal use).
+ */
+function preprocess(value, path, seen) {
+    // Null / primitives (boolean, string, number — checked below for special floats)
+    if (value === null)
+        return null;
+    if (value === undefined)
+        return undefined; // caller omits the key
+    // Special float values that cannot be represented in JSON
+    if (typeof value === "number") {
+        if (Number.isNaN(value)) {
+            throw new NonSerializablePayloadError("NaN is not serializable", path);
+        }
+        if (!Number.isFinite(value)) {
+            throw new NonSerializablePayloadError(`${value > 0 ? "Infinity" : "-Infinity"} is not serializable`, path);
+        }
+        // -0: Object.is(-0, -0) → true but JSON.stringify(-0) === '0'.
+        // We normalise -0 → 0 would silently change data.  Throw instead.
+        if (Object.is(value, -0)) {
+            throw new NonSerializablePayloadError("-0 is not serializable", path);
+        }
+        return value;
+    }
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return value;
+    // BigInt — JSON-serialisable wrapper
+    if (typeof value === "bigint") {
+        return { __bigint: value.toString(10) };
+    }
+    // Date → ISO-8601 string
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    // Uint8Array / Buffer → base64 string
+    if (value instanceof Uint8Array) {
+        return uint8ToBase64(value);
+    }
+    // Objects and Arrays — cycle detection + recursive descent
+    if (typeof value === "object") {
+        if (seen.has(value)) {
+            throw new NonSerializablePayloadError("circular reference detected", path);
+        }
+        seen.add(value);
+        let result;
+        if (Array.isArray(value)) {
+            result = value.map((item, i) => preprocess(item, [...path, String(i)], seen));
+        }
+        else {
+            const obj = {};
+            for (const [k, v] of Object.entries(value)) {
+                const processed = preprocess(v, [...path, k], seen);
+                if (processed !== undefined) {
+                    obj[k] = processed;
+                }
+                // undefined values → key omitted (consistent with JSON.stringify behaviour)
+            }
+            result = obj;
+        }
+        seen.delete(value); // allow same object to appear in sibling branches
+        return result;
+    }
+    // Functions, symbols, etc. — omit like JSON.stringify
+    if (typeof value === "function" || typeof value === "symbol") {
+        return undefined;
+    }
+    // Unreachable in TypeScript but guards against unknown runtime types
+    throw new NonSerializablePayloadError(`unhandled type: ${typeof value}`, path);
+}
+/**
+ * Produce the RFC 8785 canonical JSON string of any value.
+ *
+ * Pre-processes the value graph (Buffer→base64, Date→ISO-8601,
+ * BigInt→{__bigint}, undefined→omit, cycles/NaN/Inf/-0→throw)
+ * then applies `json-canonicalize` for deterministic key ordering.
+ *
+ * @throws {NonSerializablePayloadError} for NaN, Infinity, -0, or cycles.
+ */
+export function canonicalize(value) {
+    const preprocessed = preprocess(value, [], new Set());
+    // json-canonicalize already handles key sorting per RFC 8785.
+    // We pass the pre-processed value (all types are now JSON-safe).
+    return _rfcCanonicalize(preprocessed);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/trace/canonical.js.map

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

package/dist/trace/policy.d.ts

@@ -0,0 +1,103 @@
+/**
+ * PayloadPolicy — 4-axis payload handling policy for trace steps.
+ *
+ * Axes:
+ *   include    — store the full (optionally PII-redacted) payload
+ *   redact     — remove PII fields before storing; hash the original
+ *   hmac       — hash + HMAC(original, out-of-band key); no plaintext stored
+ *   hash-only  — SHA-256 of canonical payload; no plaintext, no HMAC
+ *
+ * defaultPolicy(env, piiFields?) — fail-closed in production:
+ *   - prod without piiFields → throws PRODUCTION_PII_FIELDS_REQUIRED
+ *   - prod with piiFields    → { kind: 'redact', piiFields } (no detector by default, R8-I3)
+ *   - dev                    → { kind: 'include' } (full payloads for debugging)
+ *
+ * STRICT_PII_DETECTOR is opt-in only — never activated by defaultPolicy.
+ *
+ * @module trace/policy
+ */
+/**
+ * A function that returns true when the given field value is suspected
+ * to contain PII. Used to extend structural redaction (piiFields) with
+ * heuristic scanning.
+ *
+ * NOTE: defaultPolicy does NOT activate a PIIDetector by default (R8-I3).
+ * Opt in explicitly: { kind: 'redact', piiFields: [...], piiDetector: STRICT_PII_DETECTOR }
+ */
+export type PIIDetector = (value: unknown) => boolean;
+/** Store the full payload (PII fields removed if present). Dev-safe. */
+export interface IncludePolicy {
+    kind: "include";
+}
+/** Remove piiFields from the stored payload. HMAC the original for auditability. */
+export interface RedactPolicy {
+    kind: "redact";
+    /** Field names to remove from the payload before storage. */
+    piiFields: readonly string[];
+    /**
+     * Optional detector run on every value in the payload. When it fires,
+     * the owning key is redacted even if not in piiFields.
+     * Intentionally absent by default (R8-I3 — false-positive risk).
+     */
+    piiDetector?: PIIDetector;
+}
+/** HMAC-SHA-256(canonical(original), key) + SHA-256 hash. No plaintext stored. */
+export interface HmacPolicy {
+    kind: "hmac";
+    /** Key provider for HMAC operations. */
+    keyProvider: import("../ports/key-provider.js").KeyProvider;
+    /** Key identifier passed to keyProvider.getKey(). */
+    keyId: string;
+}
+/** SHA-256(canonical(payload)) only. No plaintext, no HMAC. */
+export interface HashOnlyPolicy {
+    kind: "hash-only";
+}
+/** Discriminated union of all supported payload policies. */
+export type PayloadPolicy = IncludePolicy | RedactPolicy | HmacPolicy | HashOnlyPolicy;
+/**
+ * Result of applying a PayloadPolicy to a value.
+ */
+export interface PayloadHashResult {
+    /** Hex-encoded SHA-256 of canonical(processed_value). */
+    hash: string;
+    /** The effective policy kind that was applied. */
+    policy: PayloadPolicy["kind"];
+    /**
+     * The processed payload to store inline in the trace step.
+     * undefined for 'hmac' and 'hash-only' policies.
+     */
+    storedValue?: unknown;
+    /**
+     * HMAC-SHA-256(canonical(original), key).
+     * Present only when policy is 'hmac'.
+     */
+    hmac?: string;
+}
+/**
+ * Compute SHA-256(canonical(processed_value)) according to a PayloadPolicy.
+ *
+ * - include:   stores the full value; hash = SHA-256(canonical(value))
+ * - redact:    stores redacted value; hash = SHA-256(canonical(redacted))
+ * - hmac:      stores nothing; hash = SHA-256(canonical(value)); hmac = HMAC(canonical(value), key)
+ * - hash-only: stores nothing; hash = SHA-256(canonical(value))
+ */
+export declare function payloadHash(value: unknown, policy: PayloadPolicy): Promise<PayloadHashResult>;
+/**
+ * Factory for sensible default PayloadPolicies.
+ *
+ * Fail-closed production contract (CH2):
+ *   - Calling defaultPolicy('prod') without piiFields throws immediately.
+ *     This forces the caller to declare what PII exists — silence is not
+ *     consent in a production compliance context.
+ *   - To explicitly opt out of redaction in prod, use { kind: 'include' }
+ *     directly and accept the WARNING that will be logged at boot.
+ *
+ * STRICT_PII_DETECTOR is NOT activated by this function (R8-I3).
+ * Activate it explicitly: { kind: 'redact', piiFields: [...], piiDetector: STRICT_PII_DETECTOR }
+ *
+ * @param env        'dev' or 'prod'
+ * @param piiFields  Required in prod. Field names to structurally redact.
+ */
+export declare function defaultPolicy(env: "dev" | "prod", piiFields?: readonly string[]): PayloadPolicy;
+//# sourceMappingURL=policy.d.ts.map

package/dist/trace/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/trace/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAItD,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,6DAA6D;IAC7D,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,WAAW,EAAE,OAAO,0BAA0B,EAAE,WAAW,CAAC;IAC5D,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,YAAY,GACZ,UAAU,GACV,cAAc,CAAC;AA0EnB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,iBAAiB,CAAC,CA6B5B;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,KAAK,GAAG,MAAM,EACnB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAC5B,aAAa,CAYf"}

package/dist/trace/policy.js

@@ -0,0 +1,137 @@
+/**
+ * PayloadPolicy — 4-axis payload handling policy for trace steps.
+ *
+ * Axes:
+ *   include    — store the full (optionally PII-redacted) payload
+ *   redact     — remove PII fields before storing; hash the original
+ *   hmac       — hash + HMAC(original, out-of-band key); no plaintext stored
+ *   hash-only  — SHA-256 of canonical payload; no plaintext, no HMAC
+ *
+ * defaultPolicy(env, piiFields?) — fail-closed in production:
+ *   - prod without piiFields → throws PRODUCTION_PII_FIELDS_REQUIRED
+ *   - prod with piiFields    → { kind: 'redact', piiFields } (no detector by default, R8-I3)
+ *   - dev                    → { kind: 'include' } (full payloads for debugging)
+ *
+ * STRICT_PII_DETECTOR is opt-in only — never activated by defaultPolicy.
+ *
+ * @module trace/policy
+ */
+import { canonicalize } from "./canonical.js";
+// ─── SHA-256 via Web Crypto (zero external deps) ─────────────────────────────
+/**
+ * Compute SHA-256 of a UTF-8 string using Web Crypto API.
+ * Requires Node >= 20 (globalThis.crypto.subtle available).
+ */
+async function sha256(input) {
+    const encoded = new TextEncoder().encode(input);
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded);
+    return bufferToHex(hashBuffer);
+}
+/**
+ * Compute HMAC-SHA-256 of a UTF-8 string using Web Crypto API.
+ * @param input   The message to sign.
+ * @param key     Raw key bytes.
+ */
+async function hmacSha256(input, key) {
+    // Ensure we have a plain ArrayBuffer (SharedArrayBuffer is not accepted by importKey)
+    const keyBuffer = key.buffer instanceof ArrayBuffer
+        ? key.buffer.slice(key.byteOffset, key.byteOffset + key.byteLength)
+        : new Uint8Array(key).buffer;
+    const cryptoKey = await globalThis.crypto.subtle.importKey("raw", keyBuffer, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const encoded = new TextEncoder().encode(input);
+    const sigBuffer = await globalThis.crypto.subtle.sign("HMAC", cryptoKey, encoded);
+    return bufferToHex(sigBuffer);
+}
+function bufferToHex(buffer) {
+    return Array.from(new Uint8Array(buffer))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// ─── Redaction helpers ────────────────────────────────────────────────────────
+/**
+ * Deep-redact piiFields and optionally piiDetector from an object.
+ * Returns a new object — never mutates input.
+ */
+function deepRedact(value, piiFields, piiDetector) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((item) => deepRedact(item, piiFields, piiDetector));
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (piiFields.has(k)) {
+            result[k] = "[REDACTED]";
+        }
+        else if (piiDetector !== undefined && piiDetector(v)) {
+            result[k] = "[REDACTED]";
+        }
+        else {
+            result[k] = deepRedact(v, piiFields, piiDetector);
+        }
+    }
+    return result;
+}
+/**
+ * Compute SHA-256(canonical(processed_value)) according to a PayloadPolicy.
+ *
+ * - include:   stores the full value; hash = SHA-256(canonical(value))
+ * - redact:    stores redacted value; hash = SHA-256(canonical(redacted))
+ * - hmac:      stores nothing; hash = SHA-256(canonical(value)); hmac = HMAC(canonical(value), key)
+ * - hash-only: stores nothing; hash = SHA-256(canonical(value))
+ */
+export async function payloadHash(value, policy) {
+    const canonical = canonicalize(value);
+    switch (policy.kind) {
+        case "include": {
+            const hash = await sha256(canonical);
+            return { hash, policy: "include", storedValue: value };
+        }
+        case "redact": {
+            const piiSet = new Set(policy.piiFields);
+            const redacted = deepRedact(value, piiSet, policy.piiDetector);
+            const redactedCanonical = canonicalize(redacted);
+            const hash = await sha256(redactedCanonical);
+            return { hash, policy: "redact", storedValue: redacted };
+        }
+        case "hmac": {
+            const hash = await sha256(canonical);
+            const key = await policy.keyProvider.getKey(policy.keyId);
+            const hmac = await hmacSha256(canonical, key);
+            return { hash, policy: "hmac", hmac };
+        }
+        case "hash-only": {
+            const hash = await sha256(canonical);
+            return { hash, policy: "hash-only" };
+        }
+    }
+}
+// ─── defaultPolicy ───────────────────────────────────────────────────────────
+/**
+ * Factory for sensible default PayloadPolicies.
+ *
+ * Fail-closed production contract (CH2):
+ *   - Calling defaultPolicy('prod') without piiFields throws immediately.
+ *     This forces the caller to declare what PII exists — silence is not
+ *     consent in a production compliance context.
+ *   - To explicitly opt out of redaction in prod, use { kind: 'include' }
+ *     directly and accept the WARNING that will be logged at boot.
+ *
+ * STRICT_PII_DETECTOR is NOT activated by this function (R8-I3).
+ * Activate it explicitly: { kind: 'redact', piiFields: [...], piiDetector: STRICT_PII_DETECTOR }
+ *
+ * @param env        'dev' or 'prod'
+ * @param piiFields  Required in prod. Field names to structurally redact.
+ */
+export function defaultPolicy(env, piiFields) {
+    if (env === "prod") {
+        if (!piiFields || piiFields.length === 0) {
+            throw new Error("PRODUCTION_PII_FIELDS_REQUIRED: production policy requires non-empty piiFields. " +
+                "Use { kind: 'include' } explicitly to opt out (will log a WARNING at boot).");
+        }
+        // piiDetector intentionally absent by default (R8-I3)
+        return { kind: "redact", piiFields };
+    }
+    return { kind: "include" };
+}
+//# sourceMappingURL=policy.js.map

package/dist/trace/policy.js.map

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

package/dist/trace/schema.d.ts

@@ -0,0 +1,195 @@
+/**
+ * TRACE_V1 schema — Audit-ready immutable trace format.
+ *
+ * Design:
+ *   - Chain-of-custody via prevStepHash + stepHash (SHA-256 Merkle chain).
+ *   - Anti-splice: every step carries runId (AR6).
+ *   - Anti-truncation: Trace.totalSteps cross-verified against steps.length.
+ *   - HITL transitions: via 'hitl' phase + 'hitl_gate' type (no parentStepIndex — hierarchy via 'handoff_initiated' event, R8-B2).
+ *   - TSA receipt optional (present | pending | failed).
+ *   - Config hash (CH9): configHash = SHA-256(canonical(config)).
+ *   - Agent signature reserved (CH8).
+ *
+ * @module trace/schema
+ */
+/** Semver version of this trace schema. Increment MINOR on additive changes,
+ *  MAJOR on breaking changes (new required fields or removed fields). */
+export declare const TRACE_SCHEMA_VERSION: "0.1.0-draft";
+/** Status of an optional TSA receipt for a Trace. */
+export type ReceiptStatus = "present" | "pending" | "failed";
+/**
+ * A single step in a ReAct/OODA agent run.
+ * Steps form an append-only chain: each step hashes its predecessor.
+ */
+export interface TraceStep {
+    /** Zero-based monotone index within the run. */
+    index: number;
+    /**
+     * Run identifier — repeated on every step to prevent splice attacks (AR6).
+     * Cross-verified against Trace.runId at verification time.
+     */
+    runId: string;
+    /**
+     * OODA / ReAct phase of this step.
+     * - observe: input collection / perception
+     * - orient: context enrichment / memory retrieval
+     * - decide: LLM reasoning step
+     * - act: tool execution / side-effect
+     * - feedback: result integration
+     * - guard: safety / policy check
+     * - hitl: human-in-the-loop gate
+     */
+    phase: "observe" | "orient" | "decide" | "act" | "feedback" | "guard" | "hitl";
+    /**
+     * Structural type of this step.
+     * NOTE: hierarchy of sub-agents is encoded via a 'handoff_initiated'
+     * event (R8-B2) — NOT via parentStepIndex, which is intentionally absent.
+     */
+    type: "llm_call" | "tool_call" | "guard_check" | "phase_transition" | "hitl_gate";
+    /** Unix epoch milliseconds when this step started. */
+    timestamp: number;
+    /** Wall-clock duration of this step in milliseconds. */
+    durationMs: number;
+    /**
+     * SHA-256(canonical(redacted_or_hashed_input)).
+     * Always present regardless of policy.
+     */
+    inputHash: string;
+    /**
+     * HMAC-SHA-256(canonical(original_input), out-of-band_key).
+     * Present only when policy is 'hmac'. Allows offline re-verification
+     * without storing plaintext.
+     */
+    inputOriginalHmac?: string;
+    /**
+     * Stored payload according to the policy:
+     *   - 'include': full redacted value
+     *   - 'redact': object with PII fields removed
+     *   - 'hmac': undefined (only hash + hmac stored)
+     *   - 'hash-only': undefined
+     */
+    storedInput?: unknown;
+    /** SHA-256(canonical(redacted_or_hashed_output)). Always present. */
+    outputHash: string;
+    /** HMAC-SHA-256(canonical(original_output), out-of-band_key). Present when policy is 'hmac'. */
+    outputOriginalHmac?: string;
+    /** Stored output payload per policy (same semantics as storedInput). */
+    storedOutput?: unknown;
+    /**
+     * Effective payload policy for this step.
+     * Derived from PayloadPolicy.kind at trace-build time.
+     */
+    policy: "include" | "redact" | "hmac" | "hash-only";
+    /** LLM token usage. Undefined for non-LLM steps. */
+    tokens?: {
+        input: number;
+        output: number;
+        /** Prompt-cache read tokens (Anthropic / OpenAI). */
+        cacheRead?: number;
+    };
+    /** Estimated cost in USD for this step. Undefined for non-billable steps. */
+    costUsd?: number;
+    /** LLM model that produced this step. Undefined for non-LLM steps. */
+    model?: {
+        provider: string;
+        name: string;
+        version: string;
+    };
+    /** Tool name for 'tool_call' steps. */
+    toolName?: string;
+    /** Guard name for 'guard_check' steps. */
+    guardName?: string;
+    /**
+     * Hash of the previous step's stepHash (or all-zeros for step 0).
+     * Enables chain-of-custody verification: any tampering or reordering
+     * breaks the chain.
+     */
+    prevStepHash: string;
+    /**
+     * SHA-256(canonical({ ...step fields (excluding stepHash), runId })).
+     * Computed after all other fields are set.
+     */
+    stepHash: string;
+}
+/**
+ * RFC 3161 / TSA-style timestamping receipt.
+ * Optional — traces without a receipt still have integrity via
+ * the Merkle chain; the receipt adds a trusted external timestamp.
+ */
+export interface SignedReceipt {
+    /** TSA endpoint URL that issued this receipt. */
+    tsa: string;
+    /** ISO-8601 timestamp from the TSA. */
+    timestamp: string;
+    /** TSA-issued signature (base64). */
+    signature: string;
+    /** Hash algorithm used. Always sha-256 in this schema version. */
+    algorithm: "sha-256";
+    /** The message hash that was timestamped (= Trace.rootHash). */
+    hashedMessage: string;
+    /** TSA certificate chain (PEM, base64). Optional — may be pinned out-of-band. */
+    certChain?: string[];
+}
+/**
+ * A complete, verifiable trace of one agent run.
+ *
+ * Integrity invariants:
+ *   - steps[i].prevStepHash === steps[i-1].stepHash (chain)
+ *   - steps[i].runId === runId (anti-splice)
+ *   - steps.length === totalSteps (anti-truncation)
+ *   - rootHash === SHA-256(canonical(steps.map(s => s.stepHash)))
+ *   - configHash === SHA-256(canonical(config)) (CH9)
+ */
+export interface Trace {
+    /** Schema version for forward-compatibility checks. */
+    schemaVersion: typeof TRACE_SCHEMA_VERSION;
+    /** Unique identifier for this run. UUID v4 recommended. */
+    runId: string;
+    /** Identifier of the agent that produced this trace. */
+    agentId: string;
+    /** Semantic version of the agent code. */
+    agentVersion: string;
+    /** Unix epoch milliseconds when the run started. */
+    startedAt: number;
+    /** Unix epoch milliseconds when the run finished. */
+    completedAt: number;
+    /** Terminal status of the run. */
+    status: "completed" | "failed" | "skipped";
+    /** Ordered list of steps. */
+    steps: TraceStep[];
+    /**
+     * Anti-truncation guard: must equal steps.length.
+     * A mismatch signals that steps were removed after the trace was finalized.
+     */
+    totalSteps: number;
+    /**
+     * SHA-256(canonical(steps.map(s => s.stepHash))).
+     * The root of the step Merkle chain.
+     */
+    rootHash: string;
+    /**
+     * Arbitrary run configuration (model IDs, pipeline params, env flags, …).
+     * Stored as-is; hashed separately for tamper-evidence.
+     */
+    config: Record<string, unknown>;
+    /**
+     * SHA-256(canonical(config)) — CH9.
+     * Verifiers recompute this to detect config drift between runs.
+     */
+    configHash: string;
+    /**
+     * Reserved for a future agent-level signature (CH8).
+     * When present, agentSignature = Sign(rootHash, agentPrivKey).
+     */
+    agentSignature?: string;
+    /** TSA receipt if external timestamping was requested. */
+    receipt?: SignedReceipt;
+    /** Status of the TSA receipt fetch. */
+    receiptStatus?: ReceiptStatus;
+    /**
+     * Unix epoch milliseconds for the next receipt retry attempt.
+     * Set when receiptStatus === 'pending'.
+     */
+    receiptRetryAt?: number;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/trace/schema.d.ts.map

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

package/dist/trace/schema.js

@@ -0,0 +1,18 @@
+/**
+ * TRACE_V1 schema — Audit-ready immutable trace format.
+ *
+ * Design:
+ *   - Chain-of-custody via prevStepHash + stepHash (SHA-256 Merkle chain).
+ *   - Anti-splice: every step carries runId (AR6).
+ *   - Anti-truncation: Trace.totalSteps cross-verified against steps.length.
+ *   - HITL transitions: via 'hitl' phase + 'hitl_gate' type (no parentStepIndex — hierarchy via 'handoff_initiated' event, R8-B2).
+ *   - TSA receipt optional (present | pending | failed).
+ *   - Config hash (CH9): configHash = SHA-256(canonical(config)).
+ *   - Agent signature reserved (CH8).
+ *
+ * @module trace/schema
+ */
+/** Semver version of this trace schema. Increment MINOR on additive changes,
+ *  MAJOR on breaking changes (new required fields or removed fields). */
+export const TRACE_SCHEMA_VERSION = "0.1.0-draft";
+//# sourceMappingURL=schema.js.map

package/dist/trace/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/trace/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;yEACyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAsB,CAAC"}

package/dist/trace/strict-pii-detector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * STRICT_PII_DETECTOR — ultra-conservative, opt-in PIIDetector.
+ *
+ * Detects:
+ *   - Email addresses (RFC 5321 — local-part + domain + TLD ≥ 2 chars)
+ *   - IBANs (ISO 13616 — country code + check digits mod-97 + BBAN)
+ *
+ * Intentionally NOT detecting:
+ *   - Phone numbers: catastrophic false-positive rate on amounts and IDs.
+ *   - SSN / NSS: locale-dependent patterns with high FP on numeric sequences.
+ *
+ * Activation:
+ *   This detector is NEVER activated by defaultPolicy() (R8-I3).
+ *   Opt in explicitly:
+ *     { kind: 'redact', piiFields: ['email'], piiDetector: STRICT_PII_DETECTOR }
+ *
+ * @module trace/strict-pii-detector
+ */
+import type { PIIDetector } from "./policy.js";
+/**
+ * Ultra-conservative PII detector for strings.
+ * Returns true only for values that match email or IBAN patterns with checksum.
+ *
+ * Note: operates on leaves of the value tree only (non-string values → false).
+ * The redaction logic in policy.ts handles recursive traversal.
+ */
+export declare const STRICT_PII_DETECTOR: PIIDetector;
+//# sourceMappingURL=strict-pii-detector.d.ts.map

package/dist/trace/strict-pii-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict-pii-detector.d.ts","sourceRoot":"","sources":["../../src/trace/strict-pii-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA4H/C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAKjC,CAAC"}