@fluxpointstudios/orynq-sdk-process-trace 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1758 @@
+/**
+ * @fileoverview Type definitions for the process-trace package.
+ * All types are consolidated in this single file to avoid confusion.
+ *
+ * Key concepts:
+ * - TraceEvent: Individual events within a trace (commands, outputs, decisions, etc.)
+ * - TraceSpan: Logical groupings of events with parent-child relationships
+ * - TraceRun: Complete execution trace containing all events and spans
+ * - TraceBundle: Finalized trace with cryptographic commitments
+ * - Visibility: Controls what data is exposed in public views
+ */
+/**
+ * Visibility level for trace events and spans.
+ * - "public": Safe to disclose without revealing sensitive information
+ * - "private": Contains potentially sensitive data, disclosed only with consent
+ * - "secret": Never disclosed, hashes only for verification
+ */
+type Visibility = "public" | "private" | "secret";
+/**
+ * Status of a trace run or span.
+ */
+type TraceStatus = "running" | "completed" | "failed" | "cancelled";
+/**
+ * Schema version for trace format.
+ */
+type SchemaVersion = "1.0";
+/**
+ * Base interface shared by all trace events.
+ * @property kind - Discriminator for event type
+ * @property id - UUID v4 unique identifier
+ * @property seq - Monotonic sequence number (THE ordering authority)
+ * @property timestamp - ISO 8601 timestamp (informational, not for ordering)
+ * @property visibility - Controls disclosure level
+ * @property hash - SHA-256 of canonical(event without hash field)
+ */
+interface BaseTraceEvent {
+    kind: string;
+    id: string;
+    seq: number;
+    timestamp: string;
+    visibility: Visibility;
+    hash?: string;
+}
+/**
+ * Command execution event.
+ * Default visibility: "public" (args may be redacted by policy)
+ */
+interface CommandEvent extends BaseTraceEvent {
+    kind: "command";
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    exitCode?: number;
+}
+/**
+ * Output/result event from command or operation.
+ * Default visibility: "private" (may contain secrets, PII, API responses)
+ */
+interface OutputEvent extends BaseTraceEvent {
+    kind: "output";
+    stream: "stdout" | "stderr" | "combined";
+    content: string;
+    truncated?: boolean;
+    originalSize?: number;
+}
+/**
+ * Decision point event where agent made a choice.
+ * Default visibility: "private" (leaks reasoning/strategy)
+ */
+interface DecisionEvent extends BaseTraceEvent {
+    kind: "decision";
+    decision: string;
+    reasoning?: string;
+    alternatives?: string[];
+    confidence?: number;
+}
+/**
+ * Observation/state assertion event.
+ * Default visibility: "public" (generally safe state assertions)
+ */
+interface ObservationEvent extends BaseTraceEvent {
+    kind: "observation";
+    observation: string;
+    category?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Error event capturing failures.
+ * Default visibility: "private" (stack traces, internal details)
+ */
+interface ErrorTraceEvent extends BaseTraceEvent {
+    kind: "error";
+    error: string;
+    code?: string;
+    stack?: string;
+    recoverable?: boolean;
+}
+/**
+ * Custom event for extension.
+ * Default visibility: "private" (unknown content)
+ */
+interface CustomEvent extends BaseTraceEvent {
+    kind: "custom";
+    eventType: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Discriminated union of all trace event types.
+ */
+type TraceEvent = CommandEvent | OutputEvent | DecisionEvent | ObservationEvent | ErrorTraceEvent | CustomEvent;
+/**
+ * Event kind string literals for type guards.
+ */
+type TraceEventKind = TraceEvent["kind"];
+/**
+ * Default visibility for each event kind.
+ */
+declare const DEFAULT_EVENT_VISIBILITY: Record<TraceEventKind, Visibility>;
+/**
+ * A span represents a logical unit of work containing related events.
+ * Spans can be nested via parentSpanId to form a tree structure.
+ *
+ * @property id - UUID v4 unique identifier
+ * @property spanSeq - Monotonic sequence (THE ordering authority for spans)
+ * @property parentSpanId - Optional parent span for nesting
+ * @property name - Human-readable span name
+ * @property status - Current span status
+ * @property visibility - Span-level visibility (can override events)
+ * @property eventIds - References to events (NOT embedded events)
+ * @property childSpanIds - References to child spans
+ * @property hash - H("poi-trace:span:v1|" + canon(spanHeader) + "|" + eventHashes)
+ */
+interface TraceSpan {
+    id: string;
+    spanSeq: number;
+    parentSpanId?: string;
+    name: string;
+    status: TraceStatus;
+    visibility: Visibility;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    eventIds: string[];
+    childSpanIds: string[];
+    metadata?: Record<string, unknown>;
+    hash?: string;
+}
+/**
+ * Complete trace run containing all events and spans.
+ *
+ * @property id - UUID v4 unique identifier for this run
+ * @property schemaVersion - Always "1.0" for this version
+ * @property agentId - Identifier of the agent that produced this trace
+ * @property status - Current run status
+ * @property events - All events (flat array, ordered by seq)
+ * @property spans - All spans (flat array, parent-child via IDs)
+ * @property rollingHash - Updated after each event
+ * @property rootHash - Final: H(rollingHash + spanHashes)
+ * @property nextSeq - Internal: next seq to assign
+ */
+interface TraceRun {
+    id: string;
+    schemaVersion: SchemaVersion;
+    agentId: string;
+    status: TraceStatus;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    events: TraceEvent[];
+    spans: TraceSpan[];
+    metadata?: Record<string, unknown>;
+    rollingHash: string;
+    rootHash?: string;
+    nextSeq: number;
+    nextSpanSeq: number;
+}
+/**
+ * State for incremental rolling hash computation.
+ */
+interface RollingHashState {
+    currentHash: string;
+    itemCount: number;
+}
+/**
+ * Span-level Merkle tree for selective disclosure.
+ * Leaves are span hashes, ordered by spanSeq.
+ *
+ * @property rootHash - Merkle root (THE disclosure commitment)
+ * @property leafCount - Number of leaf nodes (spans)
+ * @property depth - Tree depth
+ * @property leafHashes - For local proof generation (optional storage)
+ */
+interface TraceMerkleTree {
+    rootHash: string;
+    leafCount: number;
+    depth: number;
+    leafHashes: string[];
+}
+/**
+ * Merkle proof for a single leaf (span).
+ *
+ * @property leafHash - Hash of the leaf being proven
+ * @property leafIndex - 0-indexed position in leaf array
+ * @property siblings - Path from leaf to root with position hints
+ * @property rootHash - Expected Merkle root
+ */
+interface MerkleProof {
+    leafHash: string;
+    leafIndex: number;
+    siblings: Array<{
+        hash: string;
+        position: "left" | "right";
+    }>;
+    rootHash: string;
+}
+/**
+ * Annotated span with full data for public disclosure.
+ */
+interface AnnotatedSpan extends TraceSpan {
+    events: TraceEvent[];
+}
+/**
+ * Public view of a trace bundle - safe to share externally.
+ * Contains only public spans with their events, plus hashes of redacted spans.
+ *
+ * @property redactionPolicyId - Identifies which redaction rules were applied
+ * @property redactionRulesHash - H(canonical(redactionRules)) for reproducibility
+ */
+interface TraceBundlePublicView {
+    runId: string;
+    agentId: string;
+    schemaVersion: SchemaVersion;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    status: string;
+    totalEvents: number;
+    totalSpans: number;
+    rootHash: string;
+    merkleRoot: string;
+    publicSpans: AnnotatedSpan[];
+    redactedSpanHashes: Array<{
+        spanId: string;
+        hash: string;
+    }>;
+    redactionPolicyId?: string;
+    redactionRulesHash?: string;
+}
+/**
+ * Complete trace bundle with cryptographic commitments.
+ * Contains both public view and private data.
+ *
+ * @property formatVersion - Bundle format version
+ * @property publicView - Safe to share externally
+ * @property privateRun - Full trace data
+ * @property merkleRoot - Span-level Merkle root
+ * @property rootHash - Rolling hash final (execution sequence)
+ * @property manifestHash - Set after manifest creation
+ * @property signerId - Optional signer identifier
+ * @property signature - Optional signature over bundle
+ */
+interface TraceBundle {
+    formatVersion: SchemaVersion;
+    publicView: TraceBundlePublicView;
+    privateRun: TraceRun;
+    merkleRoot: string;
+    rootHash: string;
+    manifestHash?: string;
+    signerId?: string;
+    signature?: string;
+}
+/**
+ * Interface for signing providers.
+ * Consumers provide implementation (e.g., HSM, KMS, local key).
+ */
+interface SignatureProvider {
+    signerId: string;
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    verify(data: Uint8Array, signature: Uint8Array, signerId: string): Promise<boolean>;
+}
+/**
+ * Information about a stored chunk.
+ *
+ * @property index - Chunk sequence number
+ * @property hash - SHA-256 of chunk content (BEFORE compression)
+ * @property size - Bytes (uncompressed)
+ * @property compressedSize - Bytes (if compressed)
+ * @property compression - Hint for consumers (process-trace doesn't compress)
+ * @property spanIds - Which spans are in this chunk
+ */
+interface ChunkInfo {
+    index: number;
+    hash: string;
+    size: number;
+    compressedSize?: number;
+    compression?: "gzip" | "none";
+    spanIds: string[];
+}
+/**
+ * Chunk data ready for storage.
+ */
+interface Chunk {
+    info: ChunkInfo;
+    content: string;
+}
+/**
+ * Manifest describing stored trace data.
+ * This file is public-safe and serves as the entry point for retrieval.
+ *
+ * Storage layout:
+ * ```
+ * <storageUri>/
+ *   manifest.json              # TraceManifest (public-safe)
+ *   chunks/
+ *     <hash1>.json.gz          # Compressed chunk
+ *     <hash2>.json.gz
+ * ```
+ */
+interface TraceManifest {
+    formatVersion: SchemaVersion;
+    runId: string;
+    agentId: string;
+    rootHash: string;
+    merkleRoot: string;
+    manifestHash?: string;
+    totalEvents: number;
+    totalSpans: number;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    chunks: ChunkInfo[];
+    publicView: TraceBundlePublicView;
+}
+/**
+ * Disclosure mode determines what data is revealed.
+ * - "membership": Merkle proof only (proves span exists, hash matches)
+ * - "full": Merkle proof + span data + event data
+ */
+type DisclosureMode = "membership" | "full";
+/**
+ * Result of selective disclosure operation.
+ */
+interface DisclosureResult {
+    mode: DisclosureMode;
+    rootHash: string;
+    merkleRoot: string;
+    disclosedSpans: Array<{
+        spanId: string;
+        proof: MerkleProof;
+        span?: TraceSpan;
+        events?: TraceEvent[];
+    }>;
+}
+/**
+ * Result of bundle verification.
+ */
+interface TraceVerificationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    checks: {
+        rollingHashValid: boolean;
+        rootHashValid: boolean;
+        merkleRootValid: boolean;
+        spanHashesValid: boolean;
+        eventHashesValid: boolean;
+        sequenceValid: boolean;
+    };
+}
+/**
+ * Result of manifest verification.
+ */
+interface ManifestVerificationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    checks: {
+        manifestHashValid: boolean;
+        chunkHashesValid: boolean;
+        rootHashMatches: boolean;
+        merkleRootMatches: boolean;
+    };
+}
+/**
+ * Options for creating a new trace.
+ */
+interface CreateTraceOptions {
+    agentId: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for creating a new span.
+ */
+interface CreateSpanOptions {
+    name: string;
+    parentSpanId?: string;
+    visibility?: Visibility;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for creating a manifest with chunks.
+ */
+interface CreateManifestOptions {
+    chunkSize?: number;
+    compression?: "gzip" | "none";
+}
+/**
+ * Domain separation prefixes for hashing.
+ * These prevent cross-context hash collisions.
+ */
+declare const HASH_DOMAIN_PREFIXES: {
+    readonly event: "poi-trace:event:v1|";
+    readonly roll: "poi-trace:roll:v1|";
+    readonly span: "poi-trace:span:v1|";
+    readonly leaf: "poi-trace:leaf:v1|";
+    readonly node: "poi-trace:node:v1|";
+    readonly manifest: "poi-trace:manifest:v1|";
+    readonly root: "poi-trace:root:v1|";
+};
+/**
+ * Type for domain prefix keys.
+ */
+type HashDomain = keyof typeof HASH_DOMAIN_PREFIXES;
+
+/**
+ * @fileoverview Selective disclosure of trace spans with Merkle proofs.
+ *
+ * Location: packages/process-trace/src/disclosure.ts
+ *
+ * This module implements selective disclosure functionality for trace bundles,
+ * enabling privacy-preserving audits and compliance workflows. It allows verifiers
+ * to prove the existence of specific spans without revealing the entire trace.
+ *
+ * Key Concepts:
+ * - Selective Disclosure: Reveal only specific spans from a trace bundle
+ * - Membership Proofs: Prove a span exists without revealing its contents
+ * - Full Disclosure: Prove existence AND reveal span data with events
+ *
+ * Disclosure Modes:
+ * - "membership": Merkle proof only - proves span exists with specific hash
+ *   without exposing the actual span data. Useful for compliance checks.
+ * - "full": Merkle proof + span data + event data - allows verifier to
+ *   recompute hashes and fully verify the span contents.
+ *
+ * Use Cases:
+ * - Audit: "Show me span 3" (full mode) - auditor sees exactly what happened
+ * - Compliance: "Prove span exists" (membership) - no data exposure
+ * - Selective sharing: Disclose only public spans to external parties
+ *
+ * Used by:
+ * - Audit workflows: Selective disclosure of trace spans
+ * - Compliance verification: Prove span existence without data exposure
+ * - API endpoints: Create and verify disclosure requests
+ *
+ * @example
+ * ```typescript
+ * // Full disclosure of specific spans
+ * const result = await selectiveDisclose(bundle, ["span-1", "span-3"], "full");
+ * for (const disclosed of result.disclosedSpans) {
+ *   console.log("Span:", disclosed.span?.name);
+ *   console.log("Events:", disclosed.events?.length);
+ * }
+ *
+ * // Membership proof only (no data exposure)
+ * const membershipResult = await selectiveDisclose(bundle, ["span-2"], "membership");
+ *
+ * // Verify disclosure against anchor
+ * const verification = await verifyDisclosure(result, anchor.rootHash, anchor.merkleRoot);
+ * if (!verification.valid) {
+ *   console.error("Verification failed:", verification.errors);
+ * }
+ * ```
+ */
+
+/**
+ * Disclosure request structure for API use.
+ *
+ * This interface defines the shape of a disclosure request that can be
+ * transmitted over network APIs. It contains all the information needed
+ * to identify the bundle and specify which spans to disclose.
+ *
+ * @property bundleRootHash - The root hash of the bundle for identification
+ * @property bundleMerkleRoot - The Merkle root for verification
+ * @property spanIds - Array of span IDs to disclose
+ * @property mode - Disclosure mode (membership or full)
+ */
+interface DisclosureRequest {
+    bundleRootHash: string;
+    bundleMerkleRoot: string;
+    spanIds: string[];
+    mode: DisclosureMode;
+}
+/**
+ * Check if a span can be disclosed (exists in bundle).
+ *
+ * This function performs a simple existence check to determine if a span
+ * with the given ID exists in the bundle. It searches the privateRun.spans
+ * array for a matching span ID.
+ *
+ * @param bundle - The trace bundle to check
+ * @param spanId - The ID of the span to look for
+ * @returns true if the span exists in the bundle, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (canDisclose(bundle, "span-123")) {
+ *   const result = await selectiveDisclose(bundle, ["span-123"], "full");
+ * } else {
+ *   console.error("Span not found in bundle");
+ * }
+ * ```
+ */
+declare function canDisclose(bundle: TraceBundle, spanId: string): boolean;
+/**
+ * Get span index by ID (needed for proof generation).
+ *
+ * Returns the index of a span in the sorted spans array (sorted by spanSeq).
+ * This index is used for Merkle proof generation, as the proof depends on
+ * the position of the span's leaf in the Merkle tree.
+ *
+ * @param bundle - The trace bundle containing the span
+ * @param spanId - The ID of the span to find
+ * @returns The 0-indexed position of the span in the sorted array
+ * @throws Error if the span is not found in the bundle
+ *
+ * @example
+ * ```typescript
+ * const index = getSpanIndex(bundle, "span-456");
+ * console.log(`Span is at index ${index} in the Merkle tree`);
+ * ```
+ */
+declare function getSpanIndex(bundle: TraceBundle, spanId: string): number;
+/**
+ * Create a disclosure request (for API use).
+ *
+ * This function creates a structured disclosure request object that can be
+ * serialized and transmitted over network APIs. The request contains all
+ * information needed to identify the bundle and specify which spans to disclose.
+ *
+ * @param bundle - The trace bundle to create a request for
+ * @param spanIds - Array of span IDs to request disclosure for
+ * @param mode - The disclosure mode (membership or full)
+ * @returns A DisclosureRequest object ready for transmission
+ *
+ * @example
+ * ```typescript
+ * const request = createDisclosureRequest(
+ *   bundle,
+ *   ["span-1", "span-3"],
+ *   "full"
+ * );
+ *
+ * // Send request to disclosure service
+ * const response = await fetch("/api/disclose", {
+ *   method: "POST",
+ *   body: JSON.stringify(request),
+ * });
+ * ```
+ */
+declare function createDisclosureRequest(bundle: TraceBundle, spanIds: string[], mode: DisclosureMode): DisclosureRequest;
+/**
+ * Selectively disclose specific spans from a bundle.
+ *
+ * This function generates disclosure results for the specified spans. Depending
+ * on the disclosure mode, it includes either just Merkle proofs (membership mode)
+ * or Merkle proofs plus full span and event data (full mode).
+ *
+ * The function validates that all requested spans exist in the bundle before
+ * proceeding with disclosure generation.
+ *
+ * @param bundle - The trace bundle containing all data
+ * @param spanIds - IDs of spans to disclose
+ * @param mode - Disclosure mode:
+ *   - "membership": Merkle proof only (proves span exists with hash)
+ *   - "full": Merkle proof + span data + event data
+ * @returns Promise resolving to DisclosureResult with proofs and optionally data
+ * @throws Error if any requested spanId does not exist in the bundle
+ *
+ * @example
+ * ```typescript
+ * // Full disclosure - includes span data and events
+ * const fullResult = await selectiveDisclose(bundle, ["span-1"], "full");
+ * console.log(fullResult.disclosedSpans[0].span?.name);
+ * console.log(fullResult.disclosedSpans[0].events?.length);
+ *
+ * // Membership disclosure - proof only, no data
+ * const membershipResult = await selectiveDisclose(bundle, ["span-1"], "membership");
+ * // membershipResult.disclosedSpans[0].span is undefined
+ * // membershipResult.disclosedSpans[0].events is undefined
+ * ```
+ */
+declare function selectiveDisclose(bundle: TraceBundle, spanIds: string[], mode: DisclosureMode): Promise<DisclosureResult>;
+/**
+ * Verify a disclosure result against expected hashes.
+ *
+ * This function performs comprehensive verification of a disclosure result:
+ * 1. Checks that rootHash matches the expected value from the anchor
+ * 2. Checks that merkleRoot matches the expected value from the anchor
+ * 3. For each disclosed span, verifies the Merkle proof
+ * 4. For full mode disclosures, verifies span hash recomputation
+ *
+ * @param disclosure - The disclosure result to verify
+ * @param expectedRootHash - Expected root hash from anchor/on-chain commitment
+ * @param expectedMerkleRoot - Expected Merkle root from anchor/on-chain commitment
+ * @returns Promise resolving to verification result with validity status and errors
+ *
+ * @example
+ * ```typescript
+ * const disclosure = await selectiveDisclose(bundle, ["span-1"], "full");
+ * const verification = await verifyDisclosure(
+ *   disclosure,
+ *   anchor.rootHash,
+ *   anchor.merkleRoot
+ * );
+ *
+ * if (verification.valid) {
+ *   console.log("Disclosure verified successfully");
+ * } else {
+ *   console.error("Verification failed:", verification.errors);
+ * }
+ * ```
+ */
+declare function verifyDisclosure(disclosure: DisclosureResult, expectedRootHash: string, expectedMerkleRoot: string): Promise<{
+    valid: boolean;
+    errors: string[];
+}>;
+/**
+ * Verify a single span's disclosure (with data).
+ *
+ * This function performs detailed verification of a disclosed span:
+ * 1. Recomputes the span hash from the provided span and events
+ * 2. Computes the expected leaf hash from the span hash
+ * 3. Verifies the leaf hash matches the proof's leafHash
+ * 4. Verifies the Merkle proof is valid
+ *
+ * This is used for "full" mode disclosures where span data is provided.
+ *
+ * @param disclosed - Object containing spanId, proof, span data, and events
+ * @param expectedMerkleRoot - Expected Merkle root from anchor/on-chain commitment
+ * @returns Promise resolving to verification result with validity status and errors
+ *
+ * @example
+ * ```typescript
+ * const result = await verifySpanDisclosure(
+ *   {
+ *     spanId: "span-123",
+ *     proof: merkleProof,
+ *     span: spanData,
+ *     events: spanEvents,
+ *   },
+ *   expectedMerkleRoot
+ * );
+ *
+ * if (result.valid) {
+ *   console.log("Span data is authentic and included in the trace");
+ * }
+ * ```
+ */
+declare function verifySpanDisclosure(disclosed: {
+    spanId: string;
+    proof: MerkleProof;
+    span: TraceSpan;
+    events: TraceEvent[];
+}, expectedMerkleRoot: string): Promise<{
+    valid: boolean;
+    errors: string[];
+}>;
+
+/**
+ * @fileoverview Main API for building traces - creating runs, adding spans, events, and finalizing.
+ *
+ * Location: packages/process-trace/src/trace-builder.ts
+ *
+ * This module provides the primary entry points for constructing trace runs. It handles:
+ * - Creating new trace runs with proper initialization
+ * - Adding spans (logical groupings of related events)
+ * - Adding events with automatic sequencing, timestamping, and hashing
+ * - Closing spans and computing span hashes
+ * - Finalizing traces with Merkle tree construction and root hash computation
+ * - Generating public views for external sharing
+ *
+ * The trace builder maintains internal state (rolling hash, sequence counters) and
+ * ensures cryptographic integrity at each step. Events are ordered by monotonic
+ * sequence numbers (seq), not timestamps, to guarantee deterministic ordering.
+ *
+ * Used by:
+ * - Agent implementations to record execution traces
+ * - Integration tests for trace verification
+ * - Audit workflows for compliance reporting
+ *
+ * @example
+ * ```typescript
+ * // Create a new trace
+ * const run = await createTrace({ agentId: "agent-1" });
+ *
+ * // Add a span for a logical unit of work
+ * const span = addSpan(run, { name: "build-project" });
+ *
+ * // Add events to the span
+ * await addEvent(run, span.id, { kind: "command", command: "npm install" });
+ * await addEvent(run, span.id, { kind: "output", stream: "stdout", content: "done" });
+ *
+ * // Close the span and finalize
+ * await closeSpan(run, span.id);
+ * const bundle = await finalizeTrace(run);
+ * ```
+ */
+
+/**
+ * Create a new trace run.
+ *
+ * Initializes a fresh trace with:
+ * - Unique UUID for the run ID
+ * - Schema version "1.0"
+ * - Status "running"
+ * - Genesis rolling hash state
+ * - Empty events and spans arrays
+ * - Sequence counters at 0
+ *
+ * @param opts - Options for creating the trace
+ * @param opts.agentId - Identifier of the agent producing this trace
+ * @param opts.description - Optional human-readable description
+ * @param opts.metadata - Optional key-value metadata
+ * @returns Promise resolving to the initialized TraceRun
+ *
+ * @example
+ * ```typescript
+ * const run = await createTrace({
+ *   agentId: "claude-agent-v1",
+ *   description: "Build and test the project",
+ *   metadata: { environment: "production" },
+ * });
+ * ```
+ */
+declare function createTrace(opts: CreateTraceOptions): Promise<TraceRun>;
+/**
+ * Add a new span to a trace run.
+ *
+ * Creates a span with:
+ * - Unique UUID for span ID
+ * - Assigned spanSeq from run.nextSpanSeq
+ * - Status "running"
+ * - Empty eventIds and childSpanIds arrays
+ *
+ * If a parentSpanId is provided, the span is added to the parent's childSpanIds.
+ *
+ * @param run - The trace run to add the span to (mutated in place)
+ * @param opts - Options for creating the span
+ * @param opts.name - Human-readable name for the span
+ * @param opts.parentSpanId - Optional parent span ID for nesting
+ * @param opts.visibility - Span visibility level (defaults to "private")
+ * @param opts.metadata - Optional key-value metadata
+ * @returns The created TraceSpan
+ * @throws Error if the run is finalized or parent span is not found
+ *
+ * @example
+ * ```typescript
+ * // Create a top-level span
+ * const buildSpan = addSpan(run, { name: "build" });
+ *
+ * // Create a nested span
+ * const installSpan = addSpan(run, {
+ *   name: "npm-install",
+ *   parentSpanId: buildSpan.id,
+ *   visibility: "public",
+ * });
+ * ```
+ */
+declare function addSpan(run: TraceRun, opts: CreateSpanOptions): TraceSpan;
+/**
+ * Get a span by ID from a run.
+ *
+ * @param run - The trace run to search
+ * @param spanId - The span ID to find
+ * @returns The span if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const span = getSpan(run, "some-span-id");
+ * if (span) {
+ *   console.log(`Found span: ${span.name}`);
+ * }
+ * ```
+ */
+declare function getSpan(run: TraceRun, spanId: string): TraceSpan | undefined;
+/**
+ * Get events for a span.
+ *
+ * Returns all events belonging to the specified span, sorted by sequence number.
+ *
+ * @param run - The trace run containing the events
+ * @param spanId - The span ID to get events for
+ * @returns Array of TraceEvents for the span, sorted by seq
+ *
+ * @example
+ * ```typescript
+ * const events = getSpanEvents(run, span.id);
+ * for (const event of events) {
+ *   console.log(`Event ${event.seq}: ${event.kind}`);
+ * }
+ * ```
+ */
+declare function getSpanEvents$1(run: TraceRun, spanId: string): TraceEvent[];
+/**
+ * Type helper to extract the event type by kind.
+ * Used for type-safe event creation without runtime fields.
+ */
+type EventWithoutRuntimeFields<K extends TraceEventKind> = Omit<Extract<TraceEvent, {
+    kind: K;
+}>, "id" | "seq" | "timestamp" | "hash">;
+/**
+ * Add an event to a span within a trace run.
+ *
+ * Automatically assigns:
+ * - Unique UUID for event ID
+ * - Monotonic sequence number from run.nextSeq
+ * - ISO 8601 timestamp
+ * - Default visibility based on event kind (if not specified)
+ * - Computed event hash
+ *
+ * Also updates the run's rolling hash to maintain cryptographic chain.
+ *
+ * @param run - The trace run (mutated in place)
+ * @param spanId - ID of the span to add event to
+ * @param event - Event data without runtime fields (id, seq, timestamp, hash)
+ * @returns Promise resolving to the complete TraceEvent
+ * @throws Error if run is finalized, span not found, or span is closed
+ *
+ * @example
+ * ```typescript
+ * // Add a command event
+ * const cmdEvent = await addEvent(run, span.id, {
+ *   kind: "command",
+ *   command: "npm install",
+ *   args: ["--save-dev", "typescript"],
+ *   visibility: "public",
+ * });
+ *
+ * // Add an output event (will use default "private" visibility)
+ * const outEvent = await addEvent(run, span.id, {
+ *   kind: "output",
+ *   stream: "stdout",
+ *   content: "added 120 packages",
+ * });
+ * ```
+ */
+declare function addEvent<K extends TraceEventKind>(run: TraceRun, spanId: string, event: EventWithoutRuntimeFields<K>): Promise<TraceEvent>;
+/**
+ * Close a span, marking it as completed/failed/cancelled.
+ *
+ * Sets the span's:
+ * - status (default "completed")
+ * - endedAt timestamp
+ * - durationMs (calculated from startedAt to endedAt)
+ * - hash (computed from span header + event hashes)
+ *
+ * @param run - The trace run containing the span (mutated in place)
+ * @param spanId - ID of the span to close
+ * @param status - Final status (default "completed")
+ * @throws Error if span not found or already closed
+ *
+ * @example
+ * ```typescript
+ * // Close with default "completed" status
+ * await closeSpan(run, span.id);
+ *
+ * // Close with explicit status
+ * await closeSpan(run, span.id, "failed");
+ * ```
+ */
+declare function closeSpan(run: TraceRun, spanId: string, status?: TraceStatus): Promise<void>;
+/**
+ * Check if a run is finalized.
+ *
+ * A run is considered finalized when it has a rootHash set.
+ *
+ * @param run - The trace run to check
+ * @returns true if the run is finalized
+ *
+ * @example
+ * ```typescript
+ * if (!isFinalized(run)) {
+ *   // Can still add spans and events
+ *   await addEvent(run, span.id, { kind: "command", command: "ls" });
+ * }
+ * ```
+ */
+declare function isFinalized(run: TraceRun): boolean;
+/**
+ * Finalize a trace run, computing all final hashes and creating a bundle.
+ *
+ * Finalization performs:
+ * 1. Closes any open spans (with status "completed")
+ * 2. Sets run status to "completed"
+ * 3. Sets run endedAt and durationMs
+ * 4. Builds Merkle tree from spans
+ * 5. Computes root hash from rolling hash + span hashes
+ * 6. Creates public view (only public spans with their events)
+ * 7. Returns complete TraceBundle
+ *
+ * After finalization, no more spans or events can be added.
+ *
+ * @param run - The trace run to finalize (mutated in place)
+ * @returns Promise resolving to the complete TraceBundle
+ * @throws Error if the run is already finalized
+ *
+ * @example
+ * ```typescript
+ * // Finalize and get the bundle
+ * const bundle = await finalizeTrace(run);
+ *
+ * // Access the cryptographic commitments
+ * console.log(`Root hash: ${bundle.rootHash}`);
+ * console.log(`Merkle root: ${bundle.merkleRoot}`);
+ *
+ * // Access the public view for sharing
+ * console.log(`Public spans: ${bundle.publicView.publicSpans.length}`);
+ * ```
+ */
+declare function finalizeTrace(run: TraceRun): Promise<TraceBundle>;
+/**
+ * Get total event count for a trace run.
+ *
+ * @param run - The trace run
+ * @returns Number of events in the run
+ */
+declare function getEventCount(run: TraceRun): number;
+/**
+ * Get total span count for a trace run.
+ *
+ * @param run - The trace run
+ * @returns Number of spans in the run
+ */
+declare function getSpanCount(run: TraceRun): number;
+/**
+ * Get all root spans (spans without a parent).
+ *
+ * @param run - The trace run
+ * @returns Array of root-level spans
+ */
+declare function getRootSpans(run: TraceRun): TraceSpan[];
+/**
+ * Get child spans for a given parent span.
+ *
+ * @param run - The trace run
+ * @param parentSpanId - The parent span ID
+ * @returns Array of child spans
+ */
+declare function getChildSpans(run: TraceRun, parentSpanId: string): TraceSpan[];
+/**
+ * Get an event by ID from a run.
+ *
+ * @param run - The trace run
+ * @param eventId - The event ID to find
+ * @returns The event if found, undefined otherwise
+ */
+declare function getEvent(run: TraceRun, eventId: string): TraceEvent | undefined;
+/**
+ * Get all events of a specific kind from a run.
+ *
+ * @param run - The trace run
+ * @param kind - The event kind to filter by
+ * @returns Array of events matching the kind
+ */
+declare function getEventsByKind<K extends TraceEventKind>(run: TraceRun, kind: K): Extract<TraceEvent, {
+    kind: K;
+}>[];
+
+/**
+ * @fileoverview Rolling hash computation for trace events using domain-separated SHA-256.
+ *
+ * Location: packages/process-trace/src/rolling-hash.ts
+ *
+ * This module implements cryptographic rolling hash computation for the process-trace
+ * package. Rolling hashes provide tamper-evident sequencing of trace events, ensuring
+ * that any modification to the event sequence is detectable.
+ *
+ * Domain Separation:
+ * - Event hashes use prefix "poi-trace:event:v1|" to prevent cross-context collisions
+ * - Rolling hashes use prefix "poi-trace:roll:v1|" for chain linking
+ * - Root hashes use prefix "poi-trace:root:v1|" for final commitment
+ *
+ * The rolling hash forms a hash chain: each hash incorporates the previous hash,
+ * creating an ordered, tamper-evident sequence. This is similar to blockchain
+ * block linking but at the event level.
+ *
+ * Used by:
+ * - TraceBuilder: Incrementally updates rolling hash as events are added
+ * - TraceBundle: Computes final root hash for the complete trace
+ * - TraceVerifier: Validates that event sequences have not been tampered with
+ *
+ * @example
+ * ```typescript
+ * // Initialize rolling hash state
+ * const state = await initRollingHash();
+ *
+ * // Add events incrementally
+ * for (const event of events) {
+ *   const eventHash = await computeEventHash(event);
+ *   state = await updateRollingHash(state, eventHash);
+ * }
+ *
+ * // Or compute in batch
+ * const finalHash = await computeRollingHash(events);
+ *
+ * // Compute root hash including span hashes
+ * const rootHash = await computeRootHash(finalHash, spans);
+ * ```
+ */
+
+/**
+ * Compute hash for a single event using domain separation.
+ *
+ * The event hash is computed as:
+ * `H("poi-trace:event:v1|" + canonicalize(eventWithoutHash))`
+ *
+ * The 'hash' field is removed before hashing to avoid circularity - otherwise
+ * computing the hash would require knowing the hash.
+ *
+ * @param event - The trace event to hash
+ * @returns Promise resolving to the event hash as a lowercase hex string
+ *
+ * @example
+ * ```typescript
+ * const event: TraceEvent = {
+ *   kind: "command",
+ *   id: "550e8400-e29b-41d4-a716-446655440000",
+ *   seq: 1,
+ *   timestamp: "2024-01-15T10:30:00.000Z",
+ *   visibility: "public",
+ *   command: "npm install",
+ * };
+ * const hash = await computeEventHash(event);
+ * // Returns 64-character hex string
+ * ```
+ */
+declare function computeEventHash(event: TraceEvent): Promise<string>;
+/**
+ * Initialize rolling hash state with the genesis hash.
+ *
+ * The genesis hash is computed as:
+ * `H("poi-trace:roll:v1|genesis")`
+ *
+ * This provides a well-known starting point for all rolling hash chains,
+ * ensuring that empty traces have a deterministic hash value.
+ *
+ * @returns Promise resolving to the initial rolling hash state
+ *
+ * @example
+ * ```typescript
+ * const state = await initRollingHash();
+ * console.log(state.currentHash); // Genesis hash
+ * console.log(state.itemCount);   // 0
+ * ```
+ */
+declare function initRollingHash(): Promise<RollingHashState>;
+/**
+ * Update rolling hash state with a new event hash.
+ *
+ * The new rolling hash is computed as:
+ * `H("poi-trace:roll:v1|" + prevHash + "|" + eventHash)`
+ *
+ * This creates a hash chain where each hash depends on all previous hashes,
+ * making it impossible to modify earlier events without invalidating all
+ * subsequent hashes.
+ *
+ * @param state - Current rolling hash state
+ * @param eventHash - Hash of the event to add (from computeEventHash)
+ * @returns Promise resolving to the updated rolling hash state
+ *
+ * @example
+ * ```typescript
+ * let state = await initRollingHash();
+ *
+ * const eventHash = await computeEventHash(event);
+ * state = await updateRollingHash(state, eventHash);
+ *
+ * console.log(state.currentHash); // New rolling hash
+ * console.log(state.itemCount);   // 1
+ * ```
+ */
+declare function updateRollingHash(state: RollingHashState, eventHash: string): Promise<RollingHashState>;
+/**
+ * Compute rolling hash for a sequence of events (batch mode).
+ *
+ * This function processes all events and returns the final rolling hash.
+ * Events are sorted by their `seq` field before processing to ensure
+ * deterministic ordering.
+ *
+ * The result is identical to calling `updateRollingHash` sequentially
+ * for each event, making it suitable for verification.
+ *
+ * @param events - Array of trace events to hash
+ * @returns Promise resolving to the final rolling hash as a hex string
+ *
+ * @example
+ * ```typescript
+ * const events: TraceEvent[] = [
+ *   { kind: "command", seq: 1, ... },
+ *   { kind: "output", seq: 2, ... },
+ *   { kind: "decision", seq: 3, ... },
+ * ];
+ *
+ * const finalHash = await computeRollingHash(events);
+ * ```
+ */
+declare function computeRollingHash(events: TraceEvent[]): Promise<string>;
+/**
+ * Verify that a rolling hash matches the expected value for given events.
+ *
+ * This function recomputes the rolling hash from the events and compares
+ * it to the expected value. Used to verify trace integrity.
+ *
+ * @param events - Array of trace events to verify
+ * @param expectedHash - The expected rolling hash value
+ * @returns Promise resolving to true if the hash matches, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyRollingHash(events, storedRollingHash);
+ * if (!isValid) {
+ *   console.error("Trace has been tampered with!");
+ * }
+ * ```
+ */
+declare function verifyRollingHash(events: TraceEvent[], expectedHash: string): Promise<boolean>;
+/**
+ * Compute the final root hash from rolling hash and span hashes.
+ *
+ * The root hash is computed as:
+ * `H("poi-trace:root:v1|" + rollingHash + "|" + spanHash1 + "|" + spanHash2 + ...)`
+ *
+ * Spans are sorted by their `spanSeq` field before joining to ensure
+ * deterministic ordering. This creates a single commitment that covers
+ * both the event sequence (via rolling hash) and the span structure.
+ *
+ * @param rollingHash - The final rolling hash from all events
+ * @param spans - Array of trace spans (must have hash field populated)
+ * @returns Promise resolving to the root hash as a hex string
+ *
+ * @example
+ * ```typescript
+ * const rollingHash = await computeRollingHash(events);
+ * const rootHash = await computeRootHash(rollingHash, spans);
+ *
+ * // rootHash can now be published as the trace commitment
+ * ```
+ */
+declare function computeRootHash(rollingHash: string, spans: TraceSpan[]): Promise<string>;
+/**
+ * Compute event hashes for multiple events in batch.
+ * Useful for pre-computing hashes before building a Merkle tree.
+ *
+ * @param events - Array of trace events
+ * @returns Promise resolving to array of event hashes in seq order
+ */
+declare function computeEventHashes(events: TraceEvent[]): Promise<string[]>;
+/**
+ * Get the genesis hash for testing and verification.
+ * This is the initial hash value before any events are added.
+ *
+ * @returns Promise resolving to the genesis hash
+ */
+declare function getGenesisHash(): Promise<string>;
+
+/**
+ * @fileoverview Merkle tree implementation for span-level selective disclosure.
+ *
+ * Location: packages/process-trace/src/merkle.ts
+ *
+ * This module implements a span-level Merkle tree that enables selective disclosure
+ * of trace spans. Verifiers can prove inclusion of specific spans without revealing
+ * the entire trace, supporting privacy-preserving audit and compliance workflows.
+ *
+ * Domain Separation Rules:
+ * - spanHash = H("poi-trace:span:v1|" + canon(spanHeader) + "|" + eventHash1 + "|" + eventHash2 + ...)
+ * - merkleLeaf = H("poi-trace:leaf:v1|" + spanHash)
+ * - merkleNode = H("poi-trace:node:v1|" + left + "|" + right)
+ *
+ * Used by:
+ * - TraceBuilder: builds Merkle tree when finalizing traces
+ * - Verification: verifies span inclusion proofs
+ * - Selective disclosure: generates proofs for specific spans
+ */
+
+/**
+ * Compute the hash for a span including its event hashes.
+ *
+ * The span hash is computed as:
+ * H("poi-trace:span:v1|" + canon(spanHeaderWithoutHash) + "|" + eventHash1 + "|" + eventHash2 + ...)
+ *
+ * The span header includes all fields except the `hash` field itself.
+ * Event hashes are concatenated in sequence order, joined by "|".
+ *
+ * @param span - The span to compute hash for
+ * @param eventHashes - Array of event hashes in sequence order
+ * @returns Promise resolving to the span hash as a hex string
+ *
+ * @example
+ * const spanHash = await computeSpanHash(span, ["abc123...", "def456..."]);
+ */
+declare function computeSpanHash(span: TraceSpan, eventHashes: string[]): Promise<string>;
+/**
+ * Build a Merkle tree from spans.
+ *
+ * Leaves are computed as H("poi-trace:leaf:v1|" + spanHash) in spanSeq order.
+ * Internal nodes are computed as H("poi-trace:node:v1|" + left + "|" + right).
+ *
+ * ODD-LEAF RULE: If there is an odd number of nodes at any level, the last
+ * hash is duplicated to create a balanced tree.
+ *
+ * @param spans - Array of spans (will be sorted by spanSeq)
+ * @param events - Array of all events (used to get hashes for spans)
+ * @returns Promise resolving to the complete Merkle tree
+ *
+ * @example
+ * const tree = await buildSpanMerkleTree(spans, events);
+ * console.log(tree.rootHash); // Merkle root for disclosure commitment
+ */
+declare function buildSpanMerkleTree(spans: TraceSpan[], events: TraceEvent[]): Promise<TraceMerkleTree>;
+/**
+ * Generate a Merkle proof for a specific span by index.
+ *
+ * The proof contains the sibling hashes along the path from the leaf to the root,
+ * with position hints ("left" or "right") indicating which side each sibling is on.
+ *
+ * @param tree - The complete Merkle tree
+ * @param spanIndex - 0-indexed position of the span in the tree
+ * @returns MerkleProof for the specified span
+ * @throws Error if spanIndex is out of bounds
+ *
+ * @example
+ * const proof = generateMerkleProof(tree, 2);
+ * console.log(proof.siblings); // [{hash: "...", position: "right"}, ...]
+ */
+declare function generateMerkleProof(tree: TraceMerkleTree, spanIndex: number): MerkleProof;
+/**
+ * Verify a Merkle proof against the expected root.
+ *
+ * Starting from the leaf hash, the proof is recomputed by combining with
+ * sibling hashes according to their positions. The final computed root
+ * must match the expected rootHash in the proof.
+ *
+ * @param proof - The Merkle proof to verify
+ * @returns Promise resolving to true if the proof is valid
+ *
+ * @example
+ * const valid = await verifyMerkleProof(proof);
+ * if (!valid) {
+ *   throw new Error("Merkle proof verification failed");
+ * }
+ */
+declare function verifyMerkleProof(proof: MerkleProof): Promise<boolean>;
+/**
+ * Verify a span's inclusion using its proof and data.
+ *
+ * This function recomputes the span hash from the provided span and events,
+ * then verifies that the resulting leaf hash matches the proof and that
+ * the proof is valid against the expected root.
+ *
+ * @param proof - The Merkle proof for the span
+ * @param span - The span data to verify
+ * @param events - The events belonging to this span
+ * @returns Promise resolving to true if span is validly included
+ *
+ * @example
+ * const valid = await verifySpanInclusion(proof, span, spanEvents);
+ * if (valid) {
+ *   console.log("Span is cryptographically included in the trace");
+ * }
+ */
+declare function verifySpanInclusion(proof: MerkleProof, span: TraceSpan, events: TraceEvent[]): Promise<boolean>;
+
+/**
+ * @fileoverview Bundle creation, extraction, verification, and signing for trace bundles.
+ *
+ * Location: packages/process-trace/src/bundle.ts
+ *
+ * This module provides the core functionality for working with trace bundles:
+ * - Creating bundles from finalized trace runs
+ * - Extracting public views for safe external sharing
+ * - Verifying bundle integrity (hashes, sequences, merkle proofs)
+ * - Signing and verifying bundle signatures
+ *
+ * A TraceBundle is the finalized, immutable form of a trace run that includes:
+ * - The complete private trace run data
+ * - A public view with redacted sensitive information
+ * - Cryptographic commitments (rootHash, merkleRoot)
+ * - Optional signature for authenticity verification
+ *
+ * Visibility Rules:
+ * - "public": Events/spans are included in the publicView
+ * - "private": Hash included in redactedSpanHashes, data not disclosed
+ * - "secret": Hash included in redactedSpanHashes, data never disclosed
+ *
+ * Used by:
+ * - TraceBuilder: Creates bundles when finalizing traces
+ * - TraceVerifier: Validates bundle integrity
+ * - TraceStorage: Prepares bundles for storage/transmission
+ * - Disclosure workflows: Extracts public views for sharing
+ *
+ * @example
+ * ```typescript
+ * // Create a bundle from a finalized run
+ * const bundle = await createBundle(finalizedRun);
+ *
+ * // Extract public view for sharing
+ * const publicView = extractPublicView(bundle);
+ *
+ * // Verify bundle integrity
+ * const result = await verifyBundle(bundle);
+ * if (!result.valid) {
+ *   console.error("Bundle verification failed:", result.errors);
+ * }
+ *
+ * // Sign a bundle
+ * const signedBundle = await signBundle(bundle, signatureProvider);
+ * ```
+ */
+
+/**
+ * Check if a span should be included in public view.
+ *
+ * Only spans with visibility "public" are included in the public view.
+ * Private and secret spans are redacted (only their hashes are included).
+ *
+ * @param span - The span to check
+ * @returns true if the span is public and should be included in publicView
+ *
+ * @example
+ * ```typescript
+ * if (isPublicSpan(span)) {
+ *   publicSpans.push(span);
+ * } else {
+ *   redactedSpanHashes.push({ spanId: span.id, hash: span.hash });
+ * }
+ * ```
+ */
+declare function isPublicSpan(span: TraceSpan): boolean;
+/**
+ * Check if an event should be included in public view.
+ *
+ * Only events with visibility "public" are included in the public view.
+ * Private and secret events are not disclosed.
+ *
+ * @param event - The event to check
+ * @returns true if the event is public and should be included in publicView
+ *
+ * @example
+ * ```typescript
+ * const publicEvents = events.filter(isPublicEvent);
+ * ```
+ */
+declare function isPublicEvent(event: TraceEvent): boolean;
+/**
+ * Filter events by visibility, returning only public events.
+ *
+ * This function creates a new array containing only events with
+ * visibility === "public". The original array is not modified.
+ *
+ * @param events - Array of trace events to filter
+ * @returns Array containing only public events
+ *
+ * @example
+ * ```typescript
+ * const allEvents = getSpanEvents(span, run.events);
+ * const publicEvents = filterPublicEvents(allEvents);
+ * ```
+ */
+declare function filterPublicEvents(events: TraceEvent[]): TraceEvent[];
+/**
+ * Create a bundle from a finalized trace run.
+ *
+ * The run should already have rootHash computed (i.e., be finalized).
+ * This function:
+ * 1. Validates the run is finalized
+ * 2. Builds the Merkle tree if not already computed
+ * 3. Creates the public view with redacted sensitive data
+ * 4. Returns the complete bundle
+ *
+ * @param run - The finalized trace run (must have rootHash)
+ * @returns Promise resolving to the complete TraceBundle
+ * @throws Error if the run is not finalized (missing rootHash)
+ *
+ * @example
+ * ```typescript
+ * // Finalize the run first
+ * const finalizedRun = await finalizeTraceRun(run);
+ *
+ * // Create the bundle
+ * const bundle = await createBundle(finalizedRun);
+ * console.log(bundle.rootHash); // Cryptographic commitment
+ * console.log(bundle.merkleRoot); // Merkle root for selective disclosure
+ * ```
+ */
+declare function createBundle(run: TraceRun): Promise<TraceBundle>;
+/**
+ * Extract the public view from a bundle.
+ *
+ * Returns only public spans with their public events.
+ * This is a convenience function that returns the pre-computed public view
+ * from the bundle. Use this for sharing trace information externally.
+ *
+ * Note: The public view is computed when the bundle is created, so this
+ * function simply returns the existing public view. If you need to
+ * re-compute the public view (e.g., with different redaction rules),
+ * you should create a new bundle.
+ *
+ * @param bundle - The trace bundle
+ * @returns The TraceBundlePublicView (safe to share externally)
+ *
+ * @example
+ * ```typescript
+ * const bundle = await createBundle(run);
+ * const publicView = extractPublicView(bundle);
+ *
+ * // Safe to share externally
+ * await sendToAuditSystem(publicView);
+ * ```
+ */
+declare function extractPublicView(bundle: TraceBundle): TraceBundlePublicView;
+/**
+ * Verify a bundle's integrity.
+ *
+ * Performs comprehensive validation including:
+ * - Event hashes are correct (recomputed and compared)
+ * - Span hashes are correct (recomputed and compared)
+ * - Rolling hash matches (recomputed from events)
+ * - Root hash matches (recomputed from rolling hash + span hashes)
+ * - Merkle root matches (recomputed from span tree)
+ * - Event sequence is monotonic (0, 1, 2, ...)
+ * - Span sequence is monotonic (0, 1, 2, ...)
+ *
+ * @param bundle - The trace bundle to verify
+ * @returns Promise resolving to comprehensive verification result
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyBundle(bundle);
+ *
+ * if (!result.valid) {
+ *   console.error("Bundle verification failed!");
+ *   console.error("Errors:", result.errors);
+ *   console.error("Warnings:", result.warnings);
+ *   console.error("Checks:", result.checks);
+ * }
+ * ```
+ */
+declare function verifyBundle(bundle: TraceBundle): Promise<TraceVerificationResult>;
+/**
+ * Sign a bundle using the provided signature provider.
+ *
+ * Signs the canonical JSON of { rootHash, merkleRoot, manifestHash? }.
+ * The signature and signer ID are added to the bundle.
+ *
+ * @param bundle - The bundle to sign
+ * @param provider - The signature provider implementation
+ * @returns Promise resolving to the signed bundle (new object, original unchanged)
+ *
+ * @example
+ * ```typescript
+ * const provider: SignatureProvider = {
+ *   signerId: "agent-123",
+ *   sign: async (data) => await myHSM.sign(data),
+ *   verify: async (data, sig, signerId) => await myHSM.verify(data, sig),
+ * };
+ *
+ * const signedBundle = await signBundle(bundle, provider);
+ * console.log(signedBundle.signature); // Hex-encoded signature
+ * console.log(signedBundle.signerId);  // "agent-123"
+ * ```
+ */
+declare function signBundle(bundle: TraceBundle, provider: SignatureProvider): Promise<TraceBundle>;
+/**
+ * Verify a bundle's signature.
+ *
+ * Recomputes the signing payload and verifies the signature using
+ * the provider. The bundle must have both signature and signerId set.
+ *
+ * @param bundle - The signed bundle to verify
+ * @param provider - The signature provider implementation
+ * @returns Promise resolving to true if signature is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyBundleSignature(signedBundle, provider);
+ * if (!isValid) {
+ *   throw new Error("Bundle signature verification failed!");
+ * }
+ * ```
+ */
+declare function verifyBundleSignature(bundle: TraceBundle, provider: SignatureProvider): Promise<boolean>;
+/**
+ * Get all events belonging to a specific span.
+ *
+ * @param span - The span to get events for
+ * @param events - Array of all events
+ * @returns Array of events belonging to the span, sorted by seq
+ */
+declare function getSpanEvents(span: TraceSpan, events: TraceEvent[]): TraceEvent[];
+/**
+ * Count events by visibility level in a run.
+ *
+ * @param run - The trace run to analyze
+ * @returns Object with counts for each visibility level
+ */
+declare function countEventsByVisibility(run: TraceRun): Record<Visibility, number>;
+/**
+ * Count spans by visibility level in a run.
+ *
+ * @param run - The trace run to analyze
+ * @returns Object with counts for each visibility level
+ */
+declare function countSpansByVisibility(run: TraceRun): Record<Visibility, number>;
+
+/**
+ * @fileoverview Manifest creation and verification for off-chain trace storage.
+ *
+ * Location: packages/process-trace/src/manifest.ts
+ *
+ * This module provides functionality for creating manifests and chunks from trace bundles,
+ * enabling efficient off-chain storage of trace data. The manifest serves as a public-safe
+ * entry point for trace retrieval, while chunks contain the actual span and event data.
+ *
+ * Key features:
+ * - Creates manifests with cryptographic commitments for integrity verification
+ * - Chunks trace data by size for efficient storage and retrieval
+ * - Provides verification functions to ensure manifest and chunk integrity
+ * - Supports reconstruction of trace bundles from manifests and chunks
+ *
+ * Storage Layout (for consumers):
+ * ```
+ * <storageUri>/
+ *   manifest.json              # TraceManifest (public-safe)
+ *   chunks/
+ *     <hash1>.json             # Or .json.gz if compressed by consumer
+ *     <hash2>.json
+ * ```
+ *
+ * Used by:
+ * - Storage adapters for persisting trace data
+ * - Retrieval workflows for reconstructing traces
+ * - Verification workflows for validating stored traces
+ *
+ * @example
+ * ```typescript
+ * // Create manifest for storage
+ * const { manifest, chunks } = await createManifest(bundle, { chunkSize: 500_000 });
+ *
+ * // Store chunks (consumer handles actual storage)
+ * for (const chunk of chunks) {
+ *   const path = getChunkPath(chunk.info);
+ *   await storage.write(path, chunk.content);
+ * }
+ *
+ * // Store manifest
+ * await storage.write("manifest.json", JSON.stringify(manifest));
+ *
+ * // Later: verify
+ * const result = await verifyManifest(manifest, loadedChunks);
+ * if (!result.valid) {
+ *   console.error("Manifest verification failed:", result.errors);
+ * }
+ * ```
+ */
+
+/**
+ * Create a manifest and chunks from a trace bundle.
+ *
+ * Chunks contain private span/event data for off-chain storage. Each chunk
+ * includes a subset of spans and their associated events, grouped to fit
+ * within the target chunk size.
+ *
+ * The manifest contains:
+ * - Metadata from the bundle (runId, agentId, timestamps, etc.)
+ * - Cryptographic commitments (rootHash, merkleRoot)
+ * - Chunk information (index, hash, size, spanIds)
+ * - The complete publicView for quick access
+ *
+ * @param bundle - Finalized trace bundle to create manifest from
+ * @param options - Optional chunking options
+ * @param options.chunkSize - Target chunk size in bytes (default: 1MB)
+ * @param options.compression - Compression hint for consumers (default: "none")
+ * @returns Promise resolving to manifest and array of chunks
+ *
+ * @example
+ * ```typescript
+ * const { manifest, chunks } = await createManifest(bundle, {
+ *   chunkSize: 500_000, // 500KB chunks
+ * });
+ *
+ * console.log(`Created ${chunks.length} chunks`);
+ * console.log(`Manifest hash: ${manifest.manifestHash}`);
+ * ```
+ */
+declare function createManifest(bundle: TraceBundle, options?: CreateManifestOptions): Promise<{
+    manifest: TraceManifest;
+    chunks: Chunk[];
+}>;
+/**
+ * Compute the manifest hash.
+ *
+ * The manifest hash is computed as:
+ * `H("poi-trace:manifest:v1|" + canonical(manifestWithoutHash))`
+ *
+ * This hash serves as a cryptographic commitment to the manifest contents,
+ * enabling integrity verification of stored manifests.
+ *
+ * @param manifest - Manifest object without the manifestHash field
+ * @returns Promise resolving to the manifest hash as a hex string
+ *
+ * @example
+ * ```typescript
+ * const manifestHash = await computeManifestHash(manifestWithoutHash);
+ * const completeManifest = { ...manifestWithoutHash, manifestHash };
+ * ```
+ */
+declare function computeManifestHash(manifest: Omit<TraceManifest, "manifestHash">): Promise<string>;
+/**
+ * Verify a manifest against its chunks.
+ *
+ * Performs comprehensive validation including:
+ * - Manifest hash matches recomputed hash
+ * - Each chunk hash matches its content
+ * - All chunk indices are present
+ * - Root hash in manifest is present
+ * - Merkle root in manifest is present
+ *
+ * @param manifest - The manifest to verify
+ * @param chunks - The chunks referenced by the manifest
+ * @returns Promise resolving to verification result with errors and check statuses
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyManifest(manifest, chunks);
+ * if (!result.valid) {
+ *   console.error("Verification failed:", result.errors);
+ * } else {
+ *   console.log("Manifest and chunks are valid");
+ * }
+ * ```
+ */
+declare function verifyManifest(manifest: TraceManifest, chunks: Chunk[]): Promise<ManifestVerificationResult>;
+/**
+ * Reconstruct a trace bundle from manifest and chunks.
+ *
+ * This is the inverse operation of createManifest. It parses all chunk
+ * contents, merges spans and events, and reconstructs the complete
+ * TraceBundle.
+ *
+ * Note: The reconstructed bundle will use the publicView from the manifest
+ * and construct a privateRun from the chunk data.
+ *
+ * @param manifest - The manifest describing the trace
+ * @param chunks - All chunks referenced by the manifest
+ * @returns Promise resolving to the reconstructed TraceBundle
+ * @throws Error if required chunks are missing or corrupted
+ *
+ * @example
+ * ```typescript
+ * // Load manifest and chunks from storage
+ * const manifest = JSON.parse(await storage.read("manifest.json"));
+ * const chunks = await loadChunks(manifest.chunks);
+ *
+ * // Reconstruct the bundle
+ * const bundle = await reconstructBundleFromManifest(manifest, chunks);
+ *
+ * // Now you can access the full trace data
+ * console.log(`Reconstructed ${bundle.privateRun.events.length} events`);
+ * ```
+ */
+declare function reconstructBundleFromManifest(manifest: TraceManifest, chunks: Chunk[]): Promise<TraceBundle>;
+/**
+ * Get the storage path for a chunk.
+ *
+ * Returns the relative path where the chunk should be stored.
+ * The consumer is responsible for adding any compression suffix
+ * (e.g., ".gz" if compressed) and handling the actual storage.
+ *
+ * @param chunkInfo - Information about the chunk
+ * @returns The relative storage path for the chunk
+ *
+ * @example
+ * ```typescript
+ * const path = getChunkPath(chunk.info);
+ * // Returns: "chunks/abc123...def.json"
+ *
+ * // Consumer adds compression suffix if needed
+ * const storagePath = chunk.info.compression === "gzip"
+ *   ? path + ".gz"
+ *   : path;
+ * ```
+ */
+declare function getChunkPath(chunkInfo: ChunkInfo): string;
+/**
+ * Parse chunk content from JSON string.
+ *
+ * Parses the serialized chunk content and returns the spans and events
+ * contained within. This function handles the internal chunk format.
+ *
+ * @param content - JSON string of chunk content
+ * @returns Object containing spans and events arrays
+ * @throws Error if content cannot be parsed or is malformed
+ *
+ * @example
+ * ```typescript
+ * const { spans, events } = parseChunkContent(chunk.content);
+ * console.log(`Chunk contains ${spans.length} spans and ${events.length} events`);
+ * ```
+ */
+declare function parseChunkContent(content: string): {
+    spans: TraceSpan[];
+    events: TraceEvent[];
+};
+
+/**
+ * @summary Main entry point for @fluxpointstudios/orynq-sdk-process-trace package.
+ *
+ * This package provides cryptographic process tracing for Proof-of-Intent SDK.
+ * It enables agents to create tamper-evident execution traces with:
+ * - Rolling hash chains for event ordering verification
+ * - Span-level Merkle trees for selective disclosure
+ * - Public/private visibility controls for privacy-preserving audits
+ *
+ * Key features:
+ * - TraceBuilder API for creating and managing trace runs
+ * - Event and span hash computation with domain separation
+ * - Bundle creation with cryptographic commitments
+ * - Merkle proof generation for selective disclosure
+ * - Signature support via pluggable providers
+ *
+ * Usage:
+ * ```typescript
+ * import {
+ *   createTrace,
+ *   addSpan,
+ *   addEvent,
+ *   closeSpan,
+ *   finalizeTrace,
+ * } from "@fluxpointstudios/orynq-sdk-process-trace";
+ *
+ * const run = await createTrace({ agentId: "agent-1" });
+ * const span = addSpan(run, { name: "build-project" });
+ * await addEvent(run, span.id, { kind: "command", command: "npm install" });
+ * await closeSpan(run, span.id);
+ * const bundle = await finalizeTrace(run);
+ * ```
+ */
+
+/**
+ * Package version.
+ * Updated automatically during build.
+ */
+declare const VERSION = "0.1.0";
+
+export { type AnnotatedSpan, type BaseTraceEvent, type Chunk, type ChunkInfo, type CommandEvent, type CreateManifestOptions, type CreateSpanOptions, type CreateTraceOptions, type CustomEvent, DEFAULT_EVENT_VISIBILITY, type DecisionEvent, type DisclosureMode, type DisclosureRequest, type DisclosureResult, type ErrorTraceEvent, HASH_DOMAIN_PREFIXES, type HashDomain, type ManifestVerificationResult, type MerkleProof, type ObservationEvent, type OutputEvent, type RollingHashState, type SchemaVersion, type SignatureProvider, type TraceBundle, type TraceBundlePublicView, type TraceEvent, type TraceEventKind, type TraceManifest, type TraceMerkleTree, type TraceRun, type TraceSpan, type TraceStatus, type TraceVerificationResult, VERSION, type Visibility, addEvent, addSpan, buildSpanMerkleTree, canDisclose, closeSpan, computeEventHash, computeEventHashes, computeManifestHash, computeRollingHash, computeRootHash, computeSpanHash, countEventsByVisibility, countSpansByVisibility, createBundle, createDisclosureRequest, createManifest, createTrace, extractPublicView, filterPublicEvents, finalizeTrace, generateMerkleProof, getSpanEvents as getBundleSpanEvents, getChildSpans, getChunkPath, getEvent, getEventCount, getEventsByKind, getGenesisHash, getRootSpans, getSpan, getSpanCount, getSpanEvents$1 as getSpanEvents, getSpanIndex, initRollingHash, isFinalized, isPublicEvent, isPublicSpan, parseChunkContent, reconstructBundleFromManifest, selectiveDisclose, signBundle, updateRollingHash, verifyBundle, verifyBundleSignature, verifyDisclosure, verifyManifest, verifyMerkleProof, verifyRollingHash, verifySpanDisclosure, verifySpanInclusion };