@peac/schema 0.10.5 → 0.10.7

package/dist/interaction.d.ts

@@ -0,0 +1,1085 @@
+/**
+ * PEAC Interaction Evidence Types (v0.10.7+)
+ *
+ * Interaction evidence captures what happened during agent execution.
+ * This is an extension type - stored at evidence.extensions["org.peacprotocol/interaction@0.1"]
+ *
+ * Design principles:
+ * - Wire-stable: Uses extensions mechanism (NOT a top-level evidence field)
+ * - Hash-only by default: Privacy-preserving content digests
+ * - Open kind registry: Not a closed enum, converges through convention
+ * - 1 receipt = 1 interaction: No batching (use bundles for that)
+ *
+ * @see docs/specs/INTERACTION-EVIDENCE.md
+ */
+import { z } from 'zod';
+import type { JsonValue } from '@peac/kernel';
+import type { PEACEnvelope } from './envelope.js';
+import type { WorkflowContext } from './workflow.js';
+/**
+ * Extension key for interaction evidence
+ * Used in evidence.extensions['org.peacprotocol/interaction@0.1']
+ */
+export declare const INTERACTION_EXTENSION_KEY = "org.peacprotocol/interaction@0.1";
+/**
+ * Canonical digest algorithms (NORMATIVE)
+ *
+ * k = 1024 bytes (binary), m = 1024*1024 bytes (binary)
+ * NO case-insensitivity, NO regex matching - strict canonical set only.
+ */
+export declare const CANONICAL_DIGEST_ALGS: readonly ["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"];
+/**
+ * Size constants for digest truncation (NORMATIVE)
+ */
+export declare const DIGEST_SIZE_CONSTANTS: {
+    readonly k: 1024;
+    readonly m: number;
+    readonly 'trunc-64k': 65536;
+    readonly 'trunc-1m': 1048576;
+};
+/**
+ * Result status values for interaction outcomes
+ */
+export declare const RESULT_STATUSES: readonly ["ok", "error", "timeout", "canceled"];
+/**
+ * Redaction modes for payload references
+ */
+export declare const REDACTION_MODES: readonly ["hash_only", "redacted", "plaintext_allowlisted"];
+/**
+ * Policy decision values
+ */
+export declare const POLICY_DECISIONS: readonly ["allow", "deny", "constrained"];
+/**
+ * Well-known interaction kinds (informational, not normative)
+ *
+ * The kind field accepts any string matching the kind grammar.
+ * These well-known values are listed in the PEAC registries for interop.
+ * New kinds do NOT require protocol updates - just use the name.
+ *
+ * Custom kinds: use "custom:<reverse-dns>" or "<reverse-dns>:<token>"
+ */
+export declare const WELL_KNOWN_KINDS: readonly ["tool.call", "http.request", "fs.read", "fs.write", "message"];
+/**
+ * Reserved kind prefixes (NORMATIVE)
+ *
+ * Kinds starting with these prefixes that are NOT in WELL_KNOWN_KINDS
+ * MUST be rejected to prevent namespace pollution.
+ */
+export declare const RESERVED_KIND_PREFIXES: readonly ["peac.", "org.peacprotocol."];
+/**
+ * Interaction evidence limits (DoS protection)
+ */
+export declare const INTERACTION_LIMITS: {
+    /** Maximum interaction ID length */
+    readonly maxInteractionIdLength: 256;
+    /** Maximum kind length */
+    readonly maxKindLength: 128;
+    /** Maximum platform name length */
+    readonly maxPlatformLength: 64;
+    /** Maximum version string length */
+    readonly maxVersionLength: 64;
+    /** Maximum plugin ID length */
+    readonly maxPluginIdLength: 128;
+    /** Maximum tool name length */
+    readonly maxToolNameLength: 256;
+    /** Maximum provider length */
+    readonly maxProviderLength: 128;
+    /** Maximum URI length */
+    readonly maxUriLength: 2048;
+    /** Maximum method length */
+    readonly maxMethodLength: 16;
+    /** Maximum error code length */
+    readonly maxErrorCodeLength: 128;
+    /** Maximum payment reference length */
+    readonly maxPaymentReferenceLength: 256;
+    /** Maximum receipt RID length */
+    readonly maxReceiptRidLength: 128;
+};
+/**
+ * Kind format pattern
+ *
+ * Lowercase letters, digits, dots, underscores, colons, hyphens.
+ * Must start with a letter, end with letter or digit.
+ * Min 2 chars, max 128 chars.
+ *
+ * Examples: "tool.call", "http.request", "custom:com.example.foo"
+ */
+export declare const KIND_FORMAT_PATTERN: RegExp;
+/**
+ * Extension key format pattern (NORMATIVE)
+ *
+ * Reverse-DNS domain + '/' + key name + optional version
+ * Pattern: ^([a-z0-9-]+\.)+[a-z0-9-]+\/[a-z][a-z0-9._:-]{0,126}[a-z0-9](?:@[0-9]+(?:\.[0-9]+)*)?$
+ *
+ * Examples:
+ * - "com.example/foo"
+ * - "org.peacprotocol/interaction@0.1"
+ * - "io.vendor/custom-data"
+ */
+export declare const EXTENSION_KEY_PATTERN: RegExp;
+/**
+ * Digest value format (64 lowercase hex chars)
+ */
+export declare const DIGEST_VALUE_PATTERN: RegExp;
+/**
+ * Digest algorithm schema - strict canonical set
+ */
+export declare const DigestAlgSchema: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+/**
+ * Digest schema for privacy-preserving content hashing
+ */
+export declare const DigestSchema: z.ZodObject<{
+    /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+    alg: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+    /** 64 lowercase hex chars (SHA-256 output) */
+    value: z.ZodString;
+    /** Original byte length before any truncation (REQUIRED) */
+    bytes: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    value: string;
+    alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+    bytes: number;
+}, {
+    value: string;
+    alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+    bytes: number;
+}>;
+/**
+ * Payload reference schema (on-wire, portable)
+ */
+export declare const PayloadRefSchema: z.ZodObject<{
+    /** Content digest */
+    digest: z.ZodObject<{
+        /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+        alg: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+        /** 64 lowercase hex chars (SHA-256 output) */
+        value: z.ZodString;
+        /** Original byte length before any truncation (REQUIRED) */
+        bytes: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    }, {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    }>;
+    /** Redaction mode */
+    redaction: z.ZodEnum<["hash_only", "redacted", "plaintext_allowlisted"]>;
+}, "strict", z.ZodTypeAny, {
+    digest: {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    };
+    redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+}, {
+    digest: {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    };
+    redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+}>;
+/**
+ * Executor identity schema (who ran this)
+ */
+export declare const ExecutorSchema: z.ZodObject<{
+    /** Platform identifier: 'openclaw', 'mcp', 'a2a', 'claude-code' */
+    platform: z.ZodString;
+    /** Platform version */
+    version: z.ZodOptional<z.ZodString>;
+    /** Plugin that captured this */
+    plugin_id: z.ZodOptional<z.ZodString>;
+    /** Hash of plugin package (provenance) */
+    plugin_digest: z.ZodOptional<z.ZodObject<{
+        /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+        alg: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+        /** 64 lowercase hex chars (SHA-256 output) */
+        value: z.ZodString;
+        /** Original byte length before any truncation (REQUIRED) */
+        bytes: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    }, {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    platform: string;
+    version?: string | undefined;
+    plugin_id?: string | undefined;
+    plugin_digest?: {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    } | undefined;
+}, {
+    platform: string;
+    version?: string | undefined;
+    plugin_id?: string | undefined;
+    plugin_digest?: {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    } | undefined;
+}>;
+/**
+ * Tool target schema (for tool.call kind)
+ */
+export declare const ToolTargetSchema: z.ZodObject<{
+    /** Tool name */
+    name: z.ZodString;
+    /** Tool provider */
+    provider: z.ZodOptional<z.ZodString>;
+    /** Tool version */
+    version: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    version?: string | undefined;
+    provider?: string | undefined;
+}, {
+    name: string;
+    version?: string | undefined;
+    provider?: string | undefined;
+}>;
+/**
+ * Resource target schema (for http/fs kinds)
+ */
+export declare const ResourceTargetSchema: z.ZodObject<{
+    /** Resource URI */
+    uri: z.ZodOptional<z.ZodString>;
+    /** HTTP method or operation */
+    method: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    method?: string | undefined;
+    uri?: string | undefined;
+}, {
+    method?: string | undefined;
+    uri?: string | undefined;
+}>;
+/**
+ * Execution result schema
+ */
+export declare const ResultSchema: z.ZodObject<{
+    /** Result status */
+    status: z.ZodEnum<["ok", "error", "timeout", "canceled"]>;
+    /** Error code (PEAC error code or namespaced) */
+    error_code: z.ZodOptional<z.ZodString>;
+    /** Whether the operation can be retried */
+    retryable: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    status: "error" | "ok" | "timeout" | "canceled";
+    error_code?: string | undefined;
+    retryable?: boolean | undefined;
+}, {
+    status: "error" | "ok" | "timeout" | "canceled";
+    error_code?: string | undefined;
+    retryable?: boolean | undefined;
+}>;
+/**
+ * Policy context schema (policy state at execution time)
+ */
+export declare const PolicyContextSchema: z.ZodObject<{
+    /** Policy decision */
+    decision: z.ZodEnum<["allow", "deny", "constrained"]>;
+    /** Whether sandbox mode was enabled */
+    sandbox_enabled: z.ZodOptional<z.ZodBoolean>;
+    /** Whether elevated permissions were granted */
+    elevated: z.ZodOptional<z.ZodBoolean>;
+    /** Hash of effective policy document */
+    effective_policy_digest: z.ZodOptional<z.ZodObject<{
+        /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+        alg: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+        /** 64 lowercase hex chars (SHA-256 output) */
+        value: z.ZodString;
+        /** Original byte length before any truncation (REQUIRED) */
+        bytes: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    }, {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    decision: "allow" | "deny" | "constrained";
+    sandbox_enabled?: boolean | undefined;
+    elevated?: boolean | undefined;
+    effective_policy_digest?: {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    } | undefined;
+}, {
+    decision: "allow" | "deny" | "constrained";
+    sandbox_enabled?: boolean | undefined;
+    elevated?: boolean | undefined;
+    effective_policy_digest?: {
+        value: string;
+        alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+        bytes: number;
+    } | undefined;
+}>;
+/**
+ * References schema (links to related evidence)
+ */
+export declare const RefsSchema: z.ZodObject<{
+    /** Links to evidence.payment.reference */
+    payment_reference: z.ZodOptional<z.ZodString>;
+    /** Correlation across receipts */
+    related_receipt_rid: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    payment_reference?: string | undefined;
+    related_receipt_rid?: string | undefined;
+}, {
+    payment_reference?: string | undefined;
+    related_receipt_rid?: string | undefined;
+}>;
+/**
+ * Kind schema with format validation
+ */
+export declare const KindSchema: z.ZodString;
+/**
+ * Interaction evidence schema with invariant refinements
+ *
+ * ALL REJECT invariants are enforced here. This ensures that
+ * both direct schema validation and ordered validation produce
+ * consistent results.
+ */
+export declare const InteractionEvidenceV01Schema: z.ZodEffects<z.ZodObject<{
+    /** Stable ID for idempotency/dedupe (REQUIRED) */
+    interaction_id: z.ZodString;
+    /** Event kind - open string, not closed enum (REQUIRED) */
+    kind: z.ZodString;
+    /** Executor identity (REQUIRED) */
+    executor: z.ZodObject<{
+        /** Platform identifier: 'openclaw', 'mcp', 'a2a', 'claude-code' */
+        platform: z.ZodString;
+        /** Platform version */
+        version: z.ZodOptional<z.ZodString>;
+        /** Plugin that captured this */
+        plugin_id: z.ZodOptional<z.ZodString>;
+        /** Hash of plugin package (provenance) */
+        plugin_digest: z.ZodOptional<z.ZodObject<{
+            /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+            alg: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+            /** 64 lowercase hex chars (SHA-256 output) */
+            value: z.ZodString;
+            /** Original byte length before any truncation (REQUIRED) */
+            bytes: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        }, {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        platform: string;
+        version?: string | undefined;
+        plugin_id?: string | undefined;
+        plugin_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    }, {
+        platform: string;
+        version?: string | undefined;
+        plugin_id?: string | undefined;
+        plugin_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    }>;
+    /** Tool target (when kind is tool-related) */
+    tool: z.ZodOptional<z.ZodObject<{
+        /** Tool name */
+        name: z.ZodString;
+        /** Tool provider */
+        provider: z.ZodOptional<z.ZodString>;
+        /** Tool version */
+        version: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        version?: string | undefined;
+        provider?: string | undefined;
+    }, {
+        name: string;
+        version?: string | undefined;
+        provider?: string | undefined;
+    }>>;
+    /** Resource target (when kind is http/fs-related) */
+    resource: z.ZodOptional<z.ZodObject<{
+        /** Resource URI */
+        uri: z.ZodOptional<z.ZodString>;
+        /** HTTP method or operation */
+        method: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        method?: string | undefined;
+        uri?: string | undefined;
+    }, {
+        method?: string | undefined;
+        uri?: string | undefined;
+    }>>;
+    /** Input payload reference */
+    input: z.ZodOptional<z.ZodObject<{
+        /** Content digest */
+        digest: z.ZodObject<{
+            /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+            alg: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+            /** 64 lowercase hex chars (SHA-256 output) */
+            value: z.ZodString;
+            /** Original byte length before any truncation (REQUIRED) */
+            bytes: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        }, {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        }>;
+        /** Redaction mode */
+        redaction: z.ZodEnum<["hash_only", "redacted", "plaintext_allowlisted"]>;
+    }, "strict", z.ZodTypeAny, {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    }, {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    }>>;
+    /** Output payload reference */
+    output: z.ZodOptional<z.ZodObject<{
+        /** Content digest */
+        digest: z.ZodObject<{
+            /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+            alg: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+            /** 64 lowercase hex chars (SHA-256 output) */
+            value: z.ZodString;
+            /** Original byte length before any truncation (REQUIRED) */
+            bytes: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        }, {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        }>;
+        /** Redaction mode */
+        redaction: z.ZodEnum<["hash_only", "redacted", "plaintext_allowlisted"]>;
+    }, "strict", z.ZodTypeAny, {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    }, {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    }>>;
+    /** Start time (RFC 3339) (REQUIRED) */
+    started_at: z.ZodString;
+    /** Completion time (RFC 3339) */
+    completed_at: z.ZodOptional<z.ZodString>;
+    /** Duration in milliseconds (OPTIONAL, non-normative) */
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    /** Execution outcome */
+    result: z.ZodOptional<z.ZodObject<{
+        /** Result status */
+        status: z.ZodEnum<["ok", "error", "timeout", "canceled"]>;
+        /** Error code (PEAC error code or namespaced) */
+        error_code: z.ZodOptional<z.ZodString>;
+        /** Whether the operation can be retried */
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        status: "error" | "ok" | "timeout" | "canceled";
+        error_code?: string | undefined;
+        retryable?: boolean | undefined;
+    }, {
+        status: "error" | "ok" | "timeout" | "canceled";
+        error_code?: string | undefined;
+        retryable?: boolean | undefined;
+    }>>;
+    /** Policy context at execution */
+    policy: z.ZodOptional<z.ZodObject<{
+        /** Policy decision */
+        decision: z.ZodEnum<["allow", "deny", "constrained"]>;
+        /** Whether sandbox mode was enabled */
+        sandbox_enabled: z.ZodOptional<z.ZodBoolean>;
+        /** Whether elevated permissions were granted */
+        elevated: z.ZodOptional<z.ZodBoolean>;
+        /** Hash of effective policy document */
+        effective_policy_digest: z.ZodOptional<z.ZodObject<{
+            /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+            alg: z.ZodEnum<["sha-256", "sha-256:trunc-64k", "sha-256:trunc-1m"]>;
+            /** 64 lowercase hex chars (SHA-256 output) */
+            value: z.ZodString;
+            /** Original byte length before any truncation (REQUIRED) */
+            bytes: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        }, {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        decision: "allow" | "deny" | "constrained";
+        sandbox_enabled?: boolean | undefined;
+        elevated?: boolean | undefined;
+        effective_policy_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    }, {
+        decision: "allow" | "deny" | "constrained";
+        sandbox_enabled?: boolean | undefined;
+        elevated?: boolean | undefined;
+        effective_policy_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    }>>;
+    /** References to related evidence */
+    refs: z.ZodOptional<z.ZodObject<{
+        /** Links to evidence.payment.reference */
+        payment_reference: z.ZodOptional<z.ZodString>;
+        /** Correlation across receipts */
+        related_receipt_rid: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        payment_reference?: string | undefined;
+        related_receipt_rid?: string | undefined;
+    }, {
+        payment_reference?: string | undefined;
+        related_receipt_rid?: string | undefined;
+    }>>;
+    /** Platform-specific extensions (MUST be namespaced) */
+    extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strict", z.ZodTypeAny, {
+    started_at: string;
+    interaction_id: string;
+    kind: string;
+    executor: {
+        platform: string;
+        version?: string | undefined;
+        plugin_id?: string | undefined;
+        plugin_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    };
+    policy?: {
+        decision: "allow" | "deny" | "constrained";
+        sandbox_enabled?: boolean | undefined;
+        elevated?: boolean | undefined;
+        effective_policy_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    } | undefined;
+    resource?: {
+        method?: string | undefined;
+        uri?: string | undefined;
+    } | undefined;
+    result?: {
+        status: "error" | "ok" | "timeout" | "canceled";
+        error_code?: string | undefined;
+        retryable?: boolean | undefined;
+    } | undefined;
+    completed_at?: string | undefined;
+    tool?: {
+        name: string;
+        version?: string | undefined;
+        provider?: string | undefined;
+    } | undefined;
+    input?: {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    } | undefined;
+    output?: {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    } | undefined;
+    duration_ms?: number | undefined;
+    refs?: {
+        payment_reference?: string | undefined;
+        related_receipt_rid?: string | undefined;
+    } | undefined;
+    extensions?: Record<string, unknown> | undefined;
+}, {
+    started_at: string;
+    interaction_id: string;
+    kind: string;
+    executor: {
+        platform: string;
+        version?: string | undefined;
+        plugin_id?: string | undefined;
+        plugin_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    };
+    policy?: {
+        decision: "allow" | "deny" | "constrained";
+        sandbox_enabled?: boolean | undefined;
+        elevated?: boolean | undefined;
+        effective_policy_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    } | undefined;
+    resource?: {
+        method?: string | undefined;
+        uri?: string | undefined;
+    } | undefined;
+    result?: {
+        status: "error" | "ok" | "timeout" | "canceled";
+        error_code?: string | undefined;
+        retryable?: boolean | undefined;
+    } | undefined;
+    completed_at?: string | undefined;
+    tool?: {
+        name: string;
+        version?: string | undefined;
+        provider?: string | undefined;
+    } | undefined;
+    input?: {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    } | undefined;
+    output?: {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    } | undefined;
+    duration_ms?: number | undefined;
+    refs?: {
+        payment_reference?: string | undefined;
+        related_receipt_rid?: string | undefined;
+    } | undefined;
+    extensions?: Record<string, unknown> | undefined;
+}>, {
+    started_at: string;
+    interaction_id: string;
+    kind: string;
+    executor: {
+        platform: string;
+        version?: string | undefined;
+        plugin_id?: string | undefined;
+        plugin_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    };
+    policy?: {
+        decision: "allow" | "deny" | "constrained";
+        sandbox_enabled?: boolean | undefined;
+        elevated?: boolean | undefined;
+        effective_policy_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    } | undefined;
+    resource?: {
+        method?: string | undefined;
+        uri?: string | undefined;
+    } | undefined;
+    result?: {
+        status: "error" | "ok" | "timeout" | "canceled";
+        error_code?: string | undefined;
+        retryable?: boolean | undefined;
+    } | undefined;
+    completed_at?: string | undefined;
+    tool?: {
+        name: string;
+        version?: string | undefined;
+        provider?: string | undefined;
+    } | undefined;
+    input?: {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    } | undefined;
+    output?: {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    } | undefined;
+    duration_ms?: number | undefined;
+    refs?: {
+        payment_reference?: string | undefined;
+        related_receipt_rid?: string | undefined;
+    } | undefined;
+    extensions?: Record<string, unknown> | undefined;
+}, {
+    started_at: string;
+    interaction_id: string;
+    kind: string;
+    executor: {
+        platform: string;
+        version?: string | undefined;
+        plugin_id?: string | undefined;
+        plugin_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    };
+    policy?: {
+        decision: "allow" | "deny" | "constrained";
+        sandbox_enabled?: boolean | undefined;
+        elevated?: boolean | undefined;
+        effective_policy_digest?: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        } | undefined;
+    } | undefined;
+    resource?: {
+        method?: string | undefined;
+        uri?: string | undefined;
+    } | undefined;
+    result?: {
+        status: "error" | "ok" | "timeout" | "canceled";
+        error_code?: string | undefined;
+        retryable?: boolean | undefined;
+    } | undefined;
+    completed_at?: string | undefined;
+    tool?: {
+        name: string;
+        version?: string | undefined;
+        provider?: string | undefined;
+    } | undefined;
+    input?: {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    } | undefined;
+    output?: {
+        digest: {
+            value: string;
+            alg: "sha-256" | "sha-256:trunc-64k" | "sha-256:trunc-1m";
+            bytes: number;
+        };
+        redaction: "hash_only" | "redacted" | "plaintext_allowlisted";
+    } | undefined;
+    duration_ms?: number | undefined;
+    refs?: {
+        payment_reference?: string | undefined;
+        related_receipt_rid?: string | undefined;
+    } | undefined;
+    extensions?: Record<string, unknown> | undefined;
+}>;
+export type DigestAlg = z.infer<typeof DigestAlgSchema>;
+export type Digest = z.infer<typeof DigestSchema>;
+export type PayloadRef = z.infer<typeof PayloadRefSchema>;
+export type Executor = z.infer<typeof ExecutorSchema>;
+export type ToolTarget = z.infer<typeof ToolTargetSchema>;
+export type ResourceTarget = z.infer<typeof ResourceTargetSchema>;
+export type ResultStatus = z.infer<typeof ResultSchema>['status'];
+export type Result = z.infer<typeof ResultSchema>;
+export type PolicyDecision = z.infer<typeof PolicyContextSchema>['decision'];
+export type PolicyContext = z.infer<typeof PolicyContextSchema>;
+export type Refs = z.infer<typeof RefsSchema>;
+export type InteractionEvidenceV01 = z.infer<typeof InteractionEvidenceV01Schema>;
+/**
+ * Validation error with code and optional field path
+ */
+export interface ValidationError {
+    /** Machine-readable error code (E_INTERACTION_*) */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** JSON path to the problematic field */
+    field?: string;
+}
+/**
+ * Validation warning with code and optional field path
+ */
+export interface ValidationWarning {
+    /** Machine-readable warning code (W_INTERACTION_*) */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** JSON path to the problematic field */
+    field?: string;
+}
+/**
+ * Result of interaction evidence validation.
+ *
+ * Warning-capable API: returns both errors (fatal) and warnings (non-fatal).
+ * This enables conformance testing with warning fixtures.
+ */
+export type InteractionValidationResult = {
+    valid: true;
+    value: InteractionEvidenceV01;
+    warnings: ValidationWarning[];
+} | {
+    valid: false;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+};
+/**
+ * Validate interaction evidence with explicit evaluation ordering.
+ *
+ * Returns canonical error codes per validation ordering.
+ * This function does NOT depend on Zod's internal validation ordering.
+ * Cross-language implementations MUST produce identical error_code values
+ * for the same invalid input.
+ *
+ * Validation order:
+ * 1. Required field presence
+ * 2. Required field format (interaction_id, kind, started_at)
+ * 3. Kind format and reserved prefix check
+ * 4. Executor field validation
+ * 5. Optional field format (completed_at, digests, etc.)
+ * 6. Cross-field invariants (timing, output-result, error-detail)
+ * 7. Extension key namespacing
+ * 8. Target consistency (kind prefix -> target field)
+ *
+ * @param input - Raw input to validate
+ * @returns Validation result with canonical error codes on failure
+ */
+export declare function validateInteractionOrdered(input: unknown): InteractionValidationResult;
+/**
+ * Simple validation result for conformance harness compatibility.
+ *
+ * This matches the pattern used by other PEAC validators (workflow, etc.)
+ * and allows conformance fixtures to test without needing to handle the
+ * full warning-capable API shape.
+ */
+export interface SimpleValidationResult {
+    /** Whether the input is valid */
+    valid: boolean;
+    /** Error code on failure */
+    error_code?: string;
+    /** Field path on failure */
+    error_field?: string;
+}
+/**
+ * Validate interaction evidence (simple API for conformance harness)
+ *
+ * This is the recommended entry point for conformance testing.
+ * Returns a simple result matching the existing harness contract.
+ *
+ * ## Warnings Contract
+ *
+ * This compat API intentionally **omits warnings** from the result.
+ * Warnings are available via validateInteractionOrdered() for consumers
+ * who explicitly opt in. Stable consumers should:
+ * - Use this function for pass/fail validation
+ * - Use validateInteractionOrdered() only when warnings are needed
+ *
+ * This prevents breaking changes if warning codes are added/modified.
+ *
+ * @param input - Raw input to validate
+ * @returns Simple validation result with error_code on failure (no warnings)
+ */
+export declare function validateInteraction(input: unknown): SimpleValidationResult;
+/**
+ * Validate interaction evidence (throwing)
+ *
+ * @param evidence - Object to validate
+ * @returns Validated InteractionEvidenceV01
+ * @throws ZodError if validation fails
+ */
+export declare function validateInteractionEvidence(evidence: unknown): InteractionEvidenceV01;
+/**
+ * Check if an object is valid interaction evidence (non-throwing)
+ *
+ * @param evidence - Object to check
+ * @returns True if valid InteractionEvidenceV01
+ */
+export declare function isValidInteractionEvidence(evidence: unknown): evidence is InteractionEvidenceV01;
+/**
+ * Check if a kind is in the well-known registry
+ *
+ * @param kind - Kind string to check
+ * @returns True if well-known
+ */
+export declare function isWellKnownKind(kind: string): kind is (typeof WELL_KNOWN_KINDS)[number];
+/**
+ * Check if a kind uses a reserved prefix
+ *
+ * @param kind - Kind string to check
+ * @returns True if uses reserved prefix
+ */
+export declare function isReservedKindPrefix(kind: string): boolean;
+/**
+ * Check if a digest uses truncation
+ *
+ * @param digest - Digest to check
+ * @returns True if truncated
+ */
+export declare function isDigestTruncated(digest: Digest): boolean;
+/**
+ * Get interaction evidence from a PEAC envelope
+ *
+ * @param receipt - PEAC envelope to read from
+ * @returns Interaction evidence if present, undefined otherwise
+ */
+export declare function getInteraction(receipt: PEACEnvelope): InteractionEvidenceV01 | undefined;
+/**
+ * Set interaction evidence on a PEAC envelope (mutates)
+ *
+ * @param receipt - PEAC envelope to modify
+ * @param interaction - Interaction evidence to set
+ */
+export declare function setInteraction(receipt: PEACEnvelope, interaction: InteractionEvidenceV01): void;
+/**
+ * Check if a PEAC envelope has interaction evidence
+ *
+ * @param receipt - PEAC envelope to check
+ * @returns True if interaction evidence is present
+ */
+export declare function hasInteraction(receipt: PEACEnvelope): boolean;
+/**
+ * ReceiptView - pure view layer that makes extensions feel like top-level fields
+ *
+ * Does NOT modify the underlying envelope; just provides convenient access.
+ * This projection allows code to work with interaction evidence as if it were
+ * a first-class field while maintaining wire format stability.
+ */
+export interface ReceiptView {
+    /** The underlying envelope (unchanged) */
+    readonly envelope: PEACEnvelope;
+    /** Interaction evidence (from extension) - feels like top-level */
+    readonly interaction?: InteractionEvidenceV01;
+    /** Array form for uniform pipeline processing */
+    readonly interactions: readonly InteractionEvidenceV01[];
+    /** Workflow context (from auth.extensions) */
+    readonly workflow?: WorkflowContext;
+}
+/**
+ * Create a view over a PEAC envelope that provides first-class access
+ * to extension data without modifying the wire format.
+ *
+ * @param envelope - PEAC envelope to create view for
+ * @returns ReceiptView with convenient accessors
+ *
+ * @example
+ * const view = createReceiptView(envelope);
+ * if (view.interaction) {
+ *   console.log(view.interaction.kind);
+ * }
+ */
+export declare function createReceiptView(envelope: PEACEnvelope): ReceiptView;
+/**
+ * Parameters for creating interaction evidence
+ */
+export interface CreateInteractionParams {
+    interaction_id: string;
+    kind: string;
+    executor: {
+        platform: string;
+        version?: string;
+        plugin_id?: string;
+        plugin_digest?: Digest;
+    };
+    tool?: {
+        name: string;
+        provider?: string;
+        version?: string;
+    };
+    resource?: {
+        uri?: string;
+        method?: string;
+    };
+    input?: {
+        digest: Digest;
+        redaction: (typeof REDACTION_MODES)[number];
+    };
+    output?: {
+        digest: Digest;
+        redaction: (typeof REDACTION_MODES)[number];
+    };
+    started_at: string;
+    completed_at?: string;
+    duration_ms?: number;
+    result?: {
+        status: (typeof RESULT_STATUSES)[number];
+        error_code?: string;
+        retryable?: boolean;
+    };
+    policy?: {
+        decision: (typeof POLICY_DECISIONS)[number];
+        sandbox_enabled?: boolean;
+        elevated?: boolean;
+        effective_policy_digest?: Digest;
+    };
+    refs?: {
+        payment_reference?: string;
+        related_receipt_rid?: string;
+    };
+    extensions?: Record<string, JsonValue>;
+}
+/**
+ * Create validated interaction evidence
+ *
+ * @param params - Interaction parameters
+ * @returns Validated InteractionEvidenceV01
+ * @throws ZodError if validation fails
+ */
+export declare function createInteractionEvidence(params: CreateInteractionParams): InteractionEvidenceV01;
+//# sourceMappingURL=interaction.d.ts.map