@peac/capture-core 0.10.7

package/dist/session.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * @peac/capture-core - Capture Session
+ *
+ * Stateful capture pipeline that orchestrates hashing, deduplication,
+ * and spool storage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultCaptureSession = void 0;
+exports.createCaptureSession = createCaptureSession;
+// =============================================================================
+// Capture Session Implementation
+// =============================================================================
+/**
+ * Default capture session implementation.
+ *
+ * Orchestrates:
+ * 1. Deduplication check
+ * 2. Payload hashing (input/output)
+ * 3. Entry creation with chain linking
+ * 4. Spool storage
+ * 5. Dedupe index update
+ */
+class DefaultCaptureSession {
+    store;
+    dedupe;
+    hasher;
+    closed = false;
+    // Concurrency serialization: queue captures to prevent race conditions
+    // on sequence numbers and chain linkage
+    captureQueue = Promise.resolve();
+    constructor(config) {
+        this.store = config.store;
+        this.dedupe = config.dedupe;
+        this.hasher = config.hasher;
+    }
+    /**
+     * Capture an action.
+     *
+     * Process:
+     * 1. Validate action
+     * 2. Serialize via queue (prevents race conditions)
+     * 3. Check for duplicate (by action.id)
+     * 4. Hash input/output payloads
+     * 5. Create spool entry with chain link
+     * 6. Append to spool
+     * 7. Update dedupe index
+     *
+     * Concurrency: Capture calls are serialized to prevent race conditions
+     * on sequence numbers and chain linkage.
+     *
+     * GUARANTEE: This method NEVER throws. All failures are returned as
+     * CaptureResult with success=false. This ensures the capture queue
+     * remains healthy and subsequent captures can proceed.
+     */
+    async capture(action) {
+        try {
+            // Check session state (convert throw to result)
+            if (this.closed) {
+                return {
+                    success: false,
+                    code: 'E_CAPTURE_SESSION_CLOSED',
+                    message: 'CaptureSession is closed',
+                };
+            }
+            // 1. Validate action (can run before serialization)
+            const validationError = this.validateAction(action);
+            if (validationError) {
+                return {
+                    success: false,
+                    code: 'E_CAPTURE_INVALID_ACTION',
+                    message: validationError,
+                };
+            }
+            // 2. Serialize capture operations to prevent race conditions
+            let result;
+            const capturePromise = this.captureQueue.then(async () => {
+                result = await this.captureInternal(action);
+            });
+            // Keep queue alive regardless of outcome
+            this.captureQueue = capturePromise.catch(() => {
+                // Swallow errors to keep queue alive for subsequent captures
+            });
+            // Await result, but catch any unexpected throws
+            await capturePromise;
+            return result;
+        }
+        catch (error) {
+            // Last-resort catch: convert ANY unexpected throw to CaptureResult
+            // This should never happen if captureInternal is correct, but provides safety
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                code: 'E_CAPTURE_INTERNAL',
+                message: `Internal capture error: ${message}`,
+            };
+        }
+    }
+    /**
+     * Internal capture logic (runs serialized).
+     *
+     * IMPORTANT: This method must NEVER throw - it always returns CaptureResult.
+     * This is critical for queue safety: if this throws, the queue chain would
+     * propagate the rejection to the caller while the queue itself stays healthy.
+     */
+    async captureInternal(action) {
+        try {
+            // 3. Check for duplicate (inside try/catch for queue safety)
+            if (await this.dedupe.has(action.id)) {
+                return {
+                    success: false,
+                    code: 'E_CAPTURE_DUPLICATE',
+                    message: `Action ${action.id} already captured`,
+                };
+            }
+            // 4. Hash payloads
+            const inputDigest = action.input_bytes
+                ? await this.hasher.digest(action.input_bytes)
+                : undefined;
+            const outputDigest = action.output_bytes
+                ? await this.hasher.digest(action.output_bytes)
+                : undefined;
+            // 5. Get current chain state
+            const prevDigest = await this.store.getHeadDigest();
+            const sequence = (await this.store.getSequence()) + 1;
+            // 6. Build entry (without entry_digest)
+            // DETERMINISM: Derive captured_at from action timestamps, not wall clock.
+            // This ensures the same action stream produces identical chain digests.
+            const capturedAt = action.completed_at ?? action.started_at;
+            const partialEntry = {
+                captured_at: capturedAt,
+                action: this.stripPayloadBytes(action),
+                input_digest: inputDigest,
+                output_digest: outputDigest,
+                prev_entry_digest: prevDigest,
+                sequence,
+            };
+            // 7. Compute entry digest
+            const entryDigest = await this.hasher.digestEntry(partialEntry);
+            // 8. Complete entry
+            const entry = {
+                ...partialEntry,
+                entry_digest: entryDigest,
+            };
+            // 9. Append to spool
+            await this.store.append(entry);
+            // 10. Update dedupe index
+            await this.dedupe.set(action.id, {
+                sequence,
+                entry_digest: entryDigest,
+                captured_at: capturedAt,
+                emitted: false,
+            });
+            return { success: true, entry };
+        }
+        catch (error) {
+            // Determine error type
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('hash') || message.includes('digest')) {
+                return {
+                    success: false,
+                    code: 'E_CAPTURE_HASH_FAILED',
+                    message: `Hash failed: ${message}`,
+                };
+            }
+            return {
+                success: false,
+                code: 'E_CAPTURE_STORE_FAILED',
+                message: `Store failed: ${message}`,
+            };
+        }
+    }
+    /**
+     * Commit pending writes to durable storage.
+     */
+    async commit() {
+        this.assertNotClosed();
+        await this.store.commit();
+    }
+    /**
+     * Get the current spool head digest.
+     */
+    async getHeadDigest() {
+        this.assertNotClosed();
+        return this.store.getHeadDigest();
+    }
+    /**
+     * Close the session and release resources.
+     */
+    async close() {
+        if (!this.closed) {
+            await this.store.close();
+            this.closed = true;
+        }
+    }
+    // =============================================================================
+    // Private Helpers
+    // =============================================================================
+    /**
+     * Validate action has required fields.
+     */
+    validateAction(action) {
+        if (!action.id || action.id.trim() === '') {
+            return 'Missing action.id';
+        }
+        if (!action.kind || action.kind.trim() === '') {
+            return 'Missing action.kind';
+        }
+        if (!action.platform || action.platform.trim() === '') {
+            return 'Missing action.platform';
+        }
+        if (!action.started_at || action.started_at.trim() === '') {
+            return 'Missing action.started_at';
+        }
+        return null;
+    }
+    /**
+     * Strip payload bytes from action for storage.
+     */
+    stripPayloadBytes(action) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { input_bytes, output_bytes, ...rest } = action;
+        return rest;
+    }
+    /**
+     * Assert session is not closed.
+     */
+    assertNotClosed() {
+        if (this.closed) {
+            throw new Error('CaptureSession is closed');
+        }
+    }
+}
+exports.DefaultCaptureSession = DefaultCaptureSession;
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a capture session.
+ */
+function createCaptureSession(config) {
+    return new DefaultCaptureSession(config);
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/testkit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @peac/capture-core/testkit
+ *
+ * In-memory implementations for testing.
+ * NOT for production use - use @peac/capture-node for durable storage.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createInMemorySpoolStore,
+ *   createInMemoryDedupeIndex,
+ * } from '@peac/capture-core/testkit';
+ * ```
+ */
+export { InMemorySpoolStore, InMemoryDedupeIndex, createInMemorySpoolStore, createInMemoryDedupeIndex, } from './memory';
+//# sourceMappingURL=testkit.d.ts.map

package/dist/testkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testkit.d.ts","sourceRoot":"","sources":["../src/testkit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,UAAU,CAAC"}

package/dist/testkit.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @peac/capture-core/testkit
+ *
+ * In-memory implementations for testing.
+ * NOT for production use - use @peac/capture-node for durable storage.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createInMemorySpoolStore,
+ *   createInMemoryDedupeIndex,
+ * } from '@peac/capture-core/testkit';
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInMemoryDedupeIndex = exports.createInMemorySpoolStore = exports.InMemoryDedupeIndex = exports.InMemorySpoolStore = void 0;
+var memory_1 = require("./memory");
+Object.defineProperty(exports, "InMemorySpoolStore", { enumerable: true, get: function () { return memory_1.InMemorySpoolStore; } });
+Object.defineProperty(exports, "InMemoryDedupeIndex", { enumerable: true, get: function () { return memory_1.InMemoryDedupeIndex; } });
+Object.defineProperty(exports, "createInMemorySpoolStore", { enumerable: true, get: function () { return memory_1.createInMemorySpoolStore; } });
+Object.defineProperty(exports, "createInMemoryDedupeIndex", { enumerable: true, get: function () { return memory_1.createInMemoryDedupeIndex; } });
+//# sourceMappingURL=testkit.js.map

package/dist/testkit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testkit.js","sourceRoot":"","sources":["../src/testkit.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,mCAKkB;AAJhB,4GAAA,kBAAkB,OAAA;AAClB,6GAAA,mBAAmB,OAAA;AACnB,kHAAA,wBAAwB,OAAA;AACxB,mHAAA,yBAAyB,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,282 @@
+/**
+ * @peac/capture-core - Type Definitions
+ *
+ * Runtime-neutral types for the capture pipeline.
+ * NO Node.js APIs, NO fs, NO path - pure types and interfaces only.
+ *
+ * Filesystem implementations belong in @peac/capture-node.
+ */
+import type { Digest } from '@peac/schema';
+/**
+ * Execution status of a captured action.
+ */
+export type ActionStatus = 'ok' | 'error' | 'timeout' | 'canceled';
+/**
+ * Policy snapshot at capture time.
+ */
+export interface PolicySnapshot {
+    /** Policy decision that allowed/denied the action */
+    decision: 'allow' | 'deny' | 'constrained';
+    /** Whether sandbox mode was enabled */
+    sandbox_enabled?: boolean;
+    /** Whether elevated permissions were granted */
+    elevated?: boolean;
+    /** Hash of the effective policy document (64 lowercase hex) */
+    policy_digest?: string;
+}
+/**
+ * Runtime-neutral captured action.
+ *
+ * This is the input to the capture pipeline, before any hashing or
+ * transformation. Platform-specific adapters convert their events
+ * to this common format.
+ *
+ * IMPORTANT: Timestamps are ISO 8601 strings for deterministic serialization.
+ */
+export interface CapturedAction {
+    /** Stable ID for idempotency/dedupe (REQUIRED) */
+    id: string;
+    /** Event kind - "tool.call", "http.request", etc. */
+    kind: string;
+    /** Platform identifier - "openclaw", "mcp", "a2a", "claude-code" */
+    platform: string;
+    /** Platform version (optional) */
+    platform_version?: string;
+    /** Plugin that captured this (optional) */
+    plugin_id?: string;
+    /** Tool name (for tool.call kind) */
+    tool_name?: string;
+    /** Tool provider (optional) */
+    tool_provider?: string;
+    /** Resource URI (for http/fs kinds) */
+    resource_uri?: string;
+    /** HTTP method (for http.request kind) */
+    resource_method?: string;
+    /** Raw input bytes (will be hashed, then discarded) */
+    input_bytes?: Uint8Array;
+    /** Raw output bytes (will be hashed, then discarded) */
+    output_bytes?: Uint8Array;
+    /** Start time (ISO 8601 string for determinism) */
+    started_at: string;
+    /** Completion time (ISO 8601 string) */
+    completed_at?: string;
+    /** Duration in milliseconds from monotonic clock */
+    duration_ms?: number;
+    /** Execution status */
+    status?: ActionStatus;
+    /** Error code if status is 'error' */
+    error_code?: string;
+    /** Whether the error is retryable */
+    retryable?: boolean;
+    /** Policy snapshot at execution time */
+    policy?: PolicySnapshot;
+    /** Platform-specific metadata (will be stored in extensions) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Spool entry - the post-hashing record that can be serialized.
+ *
+ * This contains computed digests but NOT raw payload bytes (privacy-preserving).
+ * The format is deterministic for tamper-evident chaining.
+ */
+export interface SpoolEntry {
+    /** When this entry was captured (RFC 3339) */
+    captured_at: string;
+    /** The captured action (without raw bytes) */
+    action: Omit<CapturedAction, 'input_bytes' | 'output_bytes'>;
+    /** Input payload digest (computed inline) */
+    input_digest?: Digest;
+    /** Output payload digest (computed inline) */
+    output_digest?: Digest;
+    /** Digest of previous entry in spool (chain link) */
+    prev_entry_digest: string;
+    /** Digest of this entry (for next entry's prev) */
+    entry_digest: string;
+    /** Sequence number in the spool (monotonic) */
+    sequence: number;
+}
+/**
+ * Abstract spool storage interface.
+ *
+ * Implementations handle the actual storage mechanism:
+ * - InMemorySpoolStore (for tests, in this package)
+ * - FsSpoolStore (in @peac/capture-node)
+ * - CloudSpoolStore (future, for serverless)
+ */
+export interface SpoolStore {
+    /**
+     * Append an entry to the spool.
+     * Returns the assigned sequence number.
+     */
+    append(entry: SpoolEntry): Promise<number>;
+    /**
+     * Commit/sync the spool to durable storage.
+     * No-op for in-memory stores.
+     */
+    commit(): Promise<void>;
+    /**
+     * Read entries starting from a sequence number.
+     * Returns entries in order.
+     */
+    read(fromSequence: number, limit?: number): Promise<SpoolEntry[]>;
+    /**
+     * Get the current head digest (last entry's digest).
+     * Returns genesis digest if spool is empty.
+     */
+    getHeadDigest(): Promise<string>;
+    /**
+     * Get the current sequence number (last entry's sequence).
+     * Returns 0 if spool is empty.
+     */
+    getSequence(): Promise<number>;
+    /**
+     * Close the store and release resources.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Dedupe entry - tracks captured actions to prevent duplicates.
+ */
+export interface DedupeEntry {
+    /** Sequence number in spool */
+    sequence: number;
+    /** Entry digest for verification */
+    entry_digest: string;
+    /** When the action was captured */
+    captured_at: string;
+    /** Whether a receipt has been emitted */
+    emitted: boolean;
+}
+/**
+ * Abstract dedupe index interface.
+ *
+ * All methods are async to support durable backends (sqlite, kv, etc.)
+ * without forcing implementers to use sync filesystem calls.
+ *
+ * Implementations handle the actual storage:
+ * - InMemoryDedupeIndex (for tests, in this package)
+ * - PersistentDedupeIndex (in @peac/capture-node)
+ */
+export interface DedupeIndex {
+    /** Get entry by action ID */
+    get(actionId: string): Promise<DedupeEntry | undefined>;
+    /** Set entry for action ID */
+    set(actionId: string, entry: DedupeEntry): Promise<void>;
+    /** Check if action ID exists */
+    has(actionId: string): Promise<boolean>;
+    /** Mark an entry as emitted */
+    markEmitted(actionId: string): Promise<boolean>;
+    /** Delete entry (for cleanup) */
+    delete(actionId: string): Promise<boolean>;
+    /** Get count of entries */
+    size(): Promise<number>;
+    /** Clear all entries */
+    clear(): Promise<void>;
+}
+/**
+ * Hasher configuration.
+ */
+export interface HasherConfig {
+    /** Maximum bytes to hash before truncating (default: 1MB) */
+    truncateThreshold?: number;
+}
+/**
+ * Hasher interface for computing payload digests.
+ */
+export interface Hasher {
+    /**
+     * Compute digest for payload bytes.
+     * Automatically truncates if payload exceeds threshold.
+     */
+    digest(payload: Uint8Array): Promise<Digest>;
+    /**
+     * Compute digest for a spool entry (for chaining).
+     * Uses deterministic serialization (JCS).
+     */
+    digestEntry(entry: Omit<SpoolEntry, 'entry_digest'>): Promise<string>;
+}
+/**
+ * Capture session configuration.
+ */
+export interface CaptureSessionConfig {
+    /** Spool store implementation */
+    store: SpoolStore;
+    /** Dedupe index implementation */
+    dedupe: DedupeIndex;
+    /** Hasher implementation */
+    hasher: Hasher;
+}
+/**
+ * Capture result for a single action.
+ */
+export type CaptureResult = {
+    success: true;
+    entry: SpoolEntry;
+} | {
+    success: false;
+    code: CaptureErrorCode;
+    message: string;
+};
+/**
+ * Capture error codes.
+ *
+ * Layer-separated error codes:
+ * - E_CAPTURE_* codes are for capture pipeline failures, NOT schema validation
+ * - E_INTERACTION_* codes (in @peac/schema) are for receipt/profile validation
+ */
+export type CaptureErrorCode = 'E_CAPTURE_DUPLICATE' | 'E_CAPTURE_HASH_FAILED' | 'E_CAPTURE_STORE_FAILED' | 'E_CAPTURE_INVALID_ACTION' | 'E_CAPTURE_SESSION_CLOSED' | 'E_CAPTURE_INTERNAL';
+/**
+ * Capture session - stateful capture pipeline instance.
+ */
+export interface CaptureSession {
+    /**
+     * Capture an action.
+     * Returns success with entry, or failure with error code.
+     */
+    capture(action: CapturedAction): Promise<CaptureResult>;
+    /**
+     * Commit any pending writes to durable storage.
+     */
+    commit(): Promise<void>;
+    /**
+     * Get the current spool head digest.
+     */
+    getHeadDigest(): Promise<string>;
+    /**
+     * Close the session and release resources.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Spool anchor extension data.
+ *
+ * When included in a receipt, this allows external verifiers to
+ * check the spool chain without access to the full spool file.
+ */
+export interface SpoolAnchor {
+    /** Current head digest of the spool chain */
+    spool_head_digest: string;
+    /** Sequence number in the spool */
+    sequence: number;
+    /** Timestamp of the anchor */
+    anchored_at: string;
+}
+/**
+ * Genesis digest - the "prev" digest for the first entry in a spool.
+ * 64 zeros represents "no previous entry".
+ */
+export declare const GENESIS_DIGEST: string;
+/**
+ * Default truncation threshold: 1MB (1024 * 1024 bytes).
+ */
+export declare const DEFAULT_TRUNCATE_THRESHOLD: number;
+/**
+ * Size constants for truncation algorithms.
+ */
+export declare const SIZE_CONSTANTS: {
+    readonly K: 1024;
+    readonly M: number;
+    readonly TRUNC_64K: number;
+    readonly TRUNC_1M: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * @peac/capture-core - Type Definitions
+ *
+ * Runtime-neutral types for the capture pipeline.
+ * NO Node.js APIs, NO fs, NO path - pure types and interfaces only.
+ *
+ * Filesystem implementations belong in @peac/capture-node.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIZE_CONSTANTS = exports.DEFAULT_TRUNCATE_THRESHOLD = exports.GENESIS_DIGEST = void 0;
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Genesis digest - the "prev" digest for the first entry in a spool.
+ * 64 zeros represents "no previous entry".
+ */
+exports.GENESIS_DIGEST = '0'.repeat(64);
+/**
+ * Default truncation threshold: 1MB (1024 * 1024 bytes).
+ */
+exports.DEFAULT_TRUNCATE_THRESHOLD = 1024 * 1024;
+/**
+ * Size constants for truncation algorithms.
+ */
+exports.SIZE_CONSTANTS = {
+    K: 1024, // 1 KB
+    M: 1024 * 1024, // 1 MB
+    TRUNC_64K: 64 * 1024, // 64 KB
+    TRUNC_1M: 1024 * 1024, // 1 MB
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA6VH,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;;GAGG;AACU,QAAA,cAAc,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAE7C;;GAEG;AACU,QAAA,0BAA0B,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtD;;GAEG;AACU,QAAA,cAAc,GAAG;IAC5B,CAAC,EAAE,IAAI,EAAE,OAAO;IAChB,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO;IACvB,SAAS,EAAE,EAAE,GAAG,IAAI,EAAE,QAAQ;IAC9B,QAAQ,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO;CACtB,CAAC"}