@framers/agentos 0.1.69 → 0.1.70

package/dist/orchestration/checkpoint/ICheckpointStore.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @file ICheckpointStore.ts
+ * @description Checkpoint persistence interface and related types for the AgentOS
+ * Unified Orchestration Layer. Checkpoints capture a full snapshot of graph execution
+ * state so that interrupted runs can be resumed or forked from any saved point.
+ */
+import type { CheckpointMetadata, DiagnosticsView, EffectClass, GraphState } from '../ir/types.js';
+export type { CheckpointMetadata } from '../ir/types.js';
+/**
+ * A complete, serialisable snapshot of a graph run captured at a node boundary.
+ *
+ * The store persists one `Checkpoint` per `save()` call and makes them queryable
+ * by `runId` (latest or by `nodeId`) so the runtime can restore execution state
+ * after a crash or perform time-travel debugging.
+ */
+export interface Checkpoint {
+    /** Unique checkpoint identifier (UUIDv4 assigned by the runtime). */
+    id: string;
+    /** Id of the `CompiledExecutionGraph` being executed. */
+    graphId: string;
+    /** Id of the graph run that produced this checkpoint. */
+    runId: string;
+    /** Id of the node at whose boundary this checkpoint was captured. */
+    nodeId: string;
+    /** Unix epoch milliseconds when the checkpoint was persisted. */
+    timestamp: number;
+    /**
+     * Serialised `GraphState` partitions captured at the checkpoint boundary.
+     * `memory` is excluded because it is always rehydrated fresh on resume.
+     */
+    state: {
+        /** The original user-provided input frozen at graph start. */
+        input: unknown;
+        /** Node-to-node communication bag value at the checkpoint boundary. */
+        scratch: unknown;
+        /** Accumulated external outputs at the checkpoint boundary. */
+        artifacts: unknown;
+        /** Accumulated diagnostic telemetry up to this checkpoint. */
+        diagnostics: DiagnosticsView;
+    };
+    /**
+     * Optional snapshot of the memory subsystem state at this checkpoint.
+     * When present the runtime can restore memory context without re-reading from the store.
+     */
+    memorySnapshot?: {
+        /** Memory traces that were read before or during the checkpointed node. */
+        reads: Array<{
+            /** Trace identifier in the memory store. */
+            traceId: string;
+            /** Textual content of the trace. */
+            content: string;
+            /** Consolidation strength in range 0–1. */
+            strength: number;
+        }>;
+        /** Writes that were staged but not yet committed when the checkpoint was taken. */
+        pendingWrites: Array<{
+            /** Memory trace category (matches `MemoryTraceType`). */
+            type: string;
+            /** Textual content to be written. */
+            content: string;
+            /** Visibility scope (matches `MemoryScope`). */
+            scope: string;
+        }>;
+    };
+    /**
+     * Results from every node that completed execution before this checkpoint was taken.
+     * Keyed by node id.
+     */
+    nodeResults: Record<string, {
+        /** The node's declared effect class. */
+        effectClass: EffectClass;
+        /** The output value produced by the node. */
+        output: unknown;
+        /** Wall-clock execution time in milliseconds. */
+        durationMs: number;
+    }>;
+    /** Ordered list of node ids that had completed execution when this checkpoint was taken. */
+    visitedNodes: string[];
+    /** Ids of edges that had been emitted but whose target nodes had not yet started. */
+    pendingEdges: string[];
+}
+/**
+ * Persistence contract for checkpoint snapshots.
+ *
+ * Implementations may back this with in-memory maps (for testing / ephemeral runs),
+ * SQLite / Postgres rows, object storage blobs, or any other durable medium.
+ *
+ * All methods are async to accommodate I/O-bound backends without interface changes.
+ */
+export interface ICheckpointStore {
+    /**
+     * Persist a checkpoint snapshot.
+     *
+     * If a checkpoint with the same `id` already exists it is overwritten.
+     *
+     * @param checkpoint - The snapshot to persist.
+     */
+    save(checkpoint: Checkpoint): Promise<void>;
+    /**
+     * Load a checkpoint for the given `runId`.
+     *
+     * When `nodeId` is supplied, returns the most recent checkpoint for that specific
+     * node within the run. When `nodeId` is omitted, returns the most recent checkpoint
+     * for the run regardless of node (equivalent to `latest(runId)`).
+     *
+     * @param runId  - The graph run identifier.
+     * @param nodeId - Optional node filter.
+     * @returns The matching checkpoint, or `null` when none exists.
+     */
+    load(runId: string, nodeId?: string): Promise<Checkpoint | null>;
+    /**
+     * Return the most recently persisted checkpoint for a run, or `null` when the run
+     * has no checkpoints.
+     *
+     * @param runId - The graph run identifier.
+     */
+    latest(runId: string): Promise<Checkpoint | null>;
+    /**
+     * List lightweight metadata descriptors for all checkpoints belonging to a graph.
+     *
+     * @param graphId - The compiled graph identifier.
+     * @param options.runId  - Optional filter to a single run within the graph.
+     * @param options.limit  - Maximum number of entries to return (most-recent-first).
+     * @returns Array of `CheckpointMetadata`, sorted by `timestamp` descending.
+     */
+    list(graphId: string, options?: {
+        limit?: number;
+        runId?: string;
+    }): Promise<CheckpointMetadata[]>;
+    /**
+     * Permanently remove a checkpoint from the store.
+     *
+     * Silently succeeds when `checkpointId` does not exist.
+     *
+     * @param checkpointId - The checkpoint to remove.
+     */
+    delete(checkpointId: string): Promise<void>;
+    /**
+     * Create a new run branching from an existing checkpoint.
+     *
+     * The operation deep-clones the source checkpoint, assigns a fresh `runId` and
+     * checkpoint `id`, applies any `patchState` overrides, persists the new checkpoint,
+     * and returns the new `runId`.
+     *
+     * @param checkpointId - The checkpoint to fork from.
+     * @param patchState   - Optional partial `GraphState` overrides applied after cloning.
+     * @returns The new `runId` for the forked run.
+     * @throws When `checkpointId` does not exist.
+     */
+    fork(checkpointId: string, patchState?: Partial<GraphState>): Promise<string>;
+}
+//# sourceMappingURL=ICheckpointStore.d.ts.map

package/dist/orchestration/checkpoint/ICheckpointStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ICheckpointStore.d.ts","sourceRoot":"","sources":["../../../src/orchestration/checkpoint/ICheckpointStore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGnG,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAMzD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,KAAK,EAAE;QACL,8DAA8D;QAC9D,KAAK,EAAE,OAAO,CAAC;QACf,uEAAuE;QACvE,OAAO,EAAE,OAAO,CAAC;QACjB,+DAA+D;QAC/D,SAAS,EAAE,OAAO,CAAC;QACnB,8DAA8D;QAC9D,WAAW,EAAE,eAAe,CAAC;KAC9B,CAAC;IAEF;;;OAGG;IACH,cAAc,CAAC,EAAE;QACf,2EAA2E;QAC3E,KAAK,EAAE,KAAK,CAAC;YACX,4CAA4C;YAC5C,OAAO,EAAE,MAAM,CAAC;YAChB,oCAAoC;YACpC,OAAO,EAAE,MAAM,CAAC;YAChB,2CAA2C;YAC3C,QAAQ,EAAE,MAAM,CAAC;SAClB,CAAC,CAAC;QACH,mFAAmF;QACnF,aAAa,EAAE,KAAK,CAAC;YACnB,yDAAyD;YACzD,IAAI,EAAE,MAAM,CAAC;YACb,qCAAqC;YACrC,OAAO,EAAE,MAAM,CAAC;YAChB,gDAAgD;YAChD,KAAK,EAAE,MAAM,CAAC;SACf,CAAC,CAAC;KACJ,CAAC;IAEF;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAC1B,wCAAwC;QACxC,WAAW,EAAE,WAAW,CAAC;QACzB,6CAA6C;QAC7C,MAAM,EAAE,OAAO,CAAC;QAChB,iDAAiD;QACjD,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IAEH,4FAA4F;IAC5F,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,qFAAqF;IACrF,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C;;;;;;;;;;OAUG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAElD;;;;;;;OAOG;IACH,IAAI,CACF,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAEjC;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/E"}

package/dist/orchestration/checkpoint/ICheckpointStore.js

@@ -0,0 +1,8 @@
+/**
+ * @file ICheckpointStore.ts
+ * @description Checkpoint persistence interface and related types for the AgentOS
+ * Unified Orchestration Layer. Checkpoints capture a full snapshot of graph execution
+ * state so that interrupted runs can be resumed or forked from any saved point.
+ */
+export {};
+//# sourceMappingURL=ICheckpointStore.js.map

package/dist/orchestration/checkpoint/ICheckpointStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ICheckpointStore.js","sourceRoot":"","sources":["../../../src/orchestration/checkpoint/ICheckpointStore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/orchestration/checkpoint/InMemoryCheckpointStore.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file InMemoryCheckpointStore.ts
+ * @description In-memory implementation of `ICheckpointStore` backed by a `Map<string, Checkpoint>`.
+ *
+ * Intended for unit tests, local development, and ephemeral graph runs where durability is
+ * not required. All data is lost when the process exits.
+ *
+ * Thread-safety note: Node.js is single-threaded so no explicit locking is needed, but callers
+ * should be aware that concurrent async operations on the same store instance may interleave.
+ */
+import type { GraphState } from '../ir/types.js';
+import type { Checkpoint, CheckpointMetadata, ICheckpointStore } from './ICheckpointStore.js';
+/**
+ * In-memory `ICheckpointStore` implementation.
+ *
+ * All checkpoints are stored in a `Map` keyed by checkpoint `id`. Scans are O(n) over
+ * the number of stored checkpoints — acceptable for test workloads; a production store
+ * should use indexed secondary keys (runId, graphId).
+ *
+ * @example
+ * ```ts
+ * const store = new InMemoryCheckpointStore();
+ * await store.save(checkpoint);
+ * const restored = await store.latest(runId);
+ * ```
+ */
+export declare class InMemoryCheckpointStore implements ICheckpointStore {
+    /** Primary storage map — checkpoint.id → Checkpoint. */
+    private readonly _checkpoints;
+    /**
+     * Persist a checkpoint snapshot.
+     *
+     * Overwrites any existing entry with the same `id`.
+     *
+     * {@inheritDoc ICheckpointStore.save}
+     */
+    save(checkpoint: Checkpoint): Promise<void>;
+    /**
+     * Load a checkpoint for the given `runId`.
+     *
+     * Scans the full store filtering by `runId` and optionally `nodeId`. When multiple
+     * checkpoints match, returns the one with the highest `timestamp`.
+     *
+     * {@inheritDoc ICheckpointStore.load}
+     */
+    load(runId: string, nodeId?: string): Promise<Checkpoint | null>;
+    /**
+     * Return the most recently persisted checkpoint for a run.
+     *
+     * Equivalent to `load(runId)` with no `nodeId` filter.
+     *
+     * {@inheritDoc ICheckpointStore.latest}
+     */
+    latest(runId: string): Promise<Checkpoint | null>;
+    /**
+     * List lightweight metadata for all checkpoints belonging to a graph.
+     *
+     * Results are sorted by `timestamp` descending (most recent first). When
+     * `options.limit` is set, only the first `limit` entries are returned after sorting.
+     *
+     * {@inheritDoc ICheckpointStore.list}
+     */
+    list(graphId: string, options?: {
+        limit?: number;
+        runId?: string;
+    }): Promise<CheckpointMetadata[]>;
+    /**
+     * Permanently remove a checkpoint from the store.
+     *
+     * Silently succeeds when `checkpointId` does not exist.
+     *
+     * {@inheritDoc ICheckpointStore.delete}
+     */
+    delete(checkpointId: string): Promise<void>;
+    /**
+     * Create a new run branching from an existing checkpoint.
+     *
+     * Steps:
+     * 1. Loads the source checkpoint (throws if missing).
+     * 2. Deep-clones via `structuredClone`.
+     * 3. Assigns a fresh `runId` and `id` via `crypto.randomUUID()`.
+     * 4. Applies `patchState` overrides via `Object.assign` on each state partition.
+     * 5. Saves the forked checkpoint and returns the new `runId`.
+     *
+     * {@inheritDoc ICheckpointStore.fork}
+     */
+    fork(checkpointId: string, patchState?: Partial<GraphState>): Promise<string>;
+}
+//# sourceMappingURL=InMemoryCheckpointStore.d.ts.map

package/dist/orchestration/checkpoint/InMemoryCheckpointStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryCheckpointStore.d.ts","sourceRoot":"","sources":["../../../src/orchestration/checkpoint/InMemoryCheckpointStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAuB9F;;;;;;;;;;;;;GAaG;AACH,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAE9D;;;;;;OAMG;IACG,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;;;;;;OAOG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAYtE;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAIvD;;;;;;;OAOG;IACG,IAAI,CACR,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAiBhC;;;;;;OAMG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;CAmCpF"}

package/dist/orchestration/checkpoint/InMemoryCheckpointStore.js

@@ -0,0 +1,156 @@
+/**
+ * @file InMemoryCheckpointStore.ts
+ * @description In-memory implementation of `ICheckpointStore` backed by a `Map<string, Checkpoint>`.
+ *
+ * Intended for unit tests, local development, and ephemeral graph runs where durability is
+ * not required. All data is lost when the process exits.
+ *
+ * Thread-safety note: Node.js is single-threaded so no explicit locking is needed, but callers
+ * should be aware that concurrent async operations on the same store instance may interleave.
+ */
+/**
+ * Derives a `CheckpointMetadata` descriptor from a full `Checkpoint` without copying the
+ * heavyweight `state` payload.
+ *
+ * `stateSize` is approximated via `JSON.stringify` length — sufficient for ranking and
+ * display purposes; no guarantee of byte-level accuracy.
+ *
+ * @internal
+ */
+function toMetadata(checkpoint) {
+    return {
+        id: checkpoint.id,
+        runId: checkpoint.runId,
+        graphId: checkpoint.graphId,
+        nodeId: checkpoint.nodeId,
+        timestamp: checkpoint.timestamp,
+        stateSize: JSON.stringify(checkpoint.state).length,
+        hasMemorySnapshot: checkpoint.memorySnapshot !== undefined,
+    };
+}
+/**
+ * In-memory `ICheckpointStore` implementation.
+ *
+ * All checkpoints are stored in a `Map` keyed by checkpoint `id`. Scans are O(n) over
+ * the number of stored checkpoints — acceptable for test workloads; a production store
+ * should use indexed secondary keys (runId, graphId).
+ *
+ * @example
+ * ```ts
+ * const store = new InMemoryCheckpointStore();
+ * await store.save(checkpoint);
+ * const restored = await store.latest(runId);
+ * ```
+ */
+export class InMemoryCheckpointStore {
+    constructor() {
+        /** Primary storage map — checkpoint.id → Checkpoint. */
+        this._checkpoints = new Map();
+    }
+    /**
+     * Persist a checkpoint snapshot.
+     *
+     * Overwrites any existing entry with the same `id`.
+     *
+     * {@inheritDoc ICheckpointStore.save}
+     */
+    async save(checkpoint) {
+        this._checkpoints.set(checkpoint.id, checkpoint);
+    }
+    /**
+     * Load a checkpoint for the given `runId`.
+     *
+     * Scans the full store filtering by `runId` and optionally `nodeId`. When multiple
+     * checkpoints match, returns the one with the highest `timestamp`.
+     *
+     * {@inheritDoc ICheckpointStore.load}
+     */
+    async load(runId, nodeId) {
+        const candidates = Array.from(this._checkpoints.values()).filter((cp) => cp.runId === runId && (nodeId === undefined || cp.nodeId === nodeId));
+        if (candidates.length === 0)
+            return null;
+        // Return the most recently saved checkpoint among the matches.
+        candidates.sort((a, b) => b.timestamp - a.timestamp);
+        return candidates[0];
+    }
+    /**
+     * Return the most recently persisted checkpoint for a run.
+     *
+     * Equivalent to `load(runId)` with no `nodeId` filter.
+     *
+     * {@inheritDoc ICheckpointStore.latest}
+     */
+    async latest(runId) {
+        return this.load(runId);
+    }
+    /**
+     * List lightweight metadata for all checkpoints belonging to a graph.
+     *
+     * Results are sorted by `timestamp` descending (most recent first). When
+     * `options.limit` is set, only the first `limit` entries are returned after sorting.
+     *
+     * {@inheritDoc ICheckpointStore.list}
+     */
+    async list(graphId, options) {
+        let results = Array.from(this._checkpoints.values()).filter((cp) => cp.graphId === graphId &&
+            (options?.runId === undefined || cp.runId === options.runId));
+        // Most-recent-first ordering.
+        results.sort((a, b) => b.timestamp - a.timestamp);
+        if (options?.limit !== undefined && options.limit > 0) {
+            results = results.slice(0, options.limit);
+        }
+        return results.map(toMetadata);
+    }
+    /**
+     * Permanently remove a checkpoint from the store.
+     *
+     * Silently succeeds when `checkpointId` does not exist.
+     *
+     * {@inheritDoc ICheckpointStore.delete}
+     */
+    async delete(checkpointId) {
+        this._checkpoints.delete(checkpointId);
+    }
+    /**
+     * Create a new run branching from an existing checkpoint.
+     *
+     * Steps:
+     * 1. Loads the source checkpoint (throws if missing).
+     * 2. Deep-clones via `structuredClone`.
+     * 3. Assigns a fresh `runId` and `id` via `crypto.randomUUID()`.
+     * 4. Applies `patchState` overrides via `Object.assign` on each state partition.
+     * 5. Saves the forked checkpoint and returns the new `runId`.
+     *
+     * {@inheritDoc ICheckpointStore.fork}
+     */
+    async fork(checkpointId, patchState) {
+        const source = this._checkpoints.get(checkpointId);
+        if (!source) {
+            throw new Error(`InMemoryCheckpointStore.fork: checkpoint "${checkpointId}" not found`);
+        }
+        // Deep clone so mutations to the forked checkpoint cannot affect the source.
+        const forked = structuredClone(source);
+        // Assign fresh identifiers so the fork is a distinct run.
+        forked.runId = crypto.randomUUID();
+        forked.id = crypto.randomUUID();
+        forked.timestamp = Date.now();
+        // Apply optional state patches — each partition is merged independently.
+        if (patchState !== undefined) {
+            if (patchState.input !== undefined) {
+                Object.assign(forked.state.input, patchState.input);
+            }
+            if (patchState.scratch !== undefined) {
+                Object.assign(forked.state.scratch, patchState.scratch);
+            }
+            if (patchState.artifacts !== undefined) {
+                Object.assign(forked.state.artifacts, patchState.artifacts);
+            }
+            if (patchState.diagnostics !== undefined) {
+                Object.assign(forked.state.diagnostics, patchState.diagnostics);
+            }
+        }
+        await this.save(forked);
+        return forked.runId;
+    }
+}
+//# sourceMappingURL=InMemoryCheckpointStore.js.map

package/dist/orchestration/checkpoint/InMemoryCheckpointStore.js.map

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

package/dist/orchestration/checkpoint/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file index.ts
+ * @description Public barrel for the orchestration checkpoint subsystem.
+ *
+ * Exports the `ICheckpointStore` interface, the `Checkpoint` and `CheckpointMetadata`
+ * types, and the built-in `InMemoryCheckpointStore` implementation.
+ */
+export * from './ICheckpointStore.js';
+export { InMemoryCheckpointStore } from './InMemoryCheckpointStore.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/orchestration/checkpoint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/orchestration/checkpoint/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/orchestration/checkpoint/index.js

@@ -0,0 +1,10 @@
+/**
+ * @file index.ts
+ * @description Public barrel for the orchestration checkpoint subsystem.
+ *
+ * Exports the `ICheckpointStore` interface, the `Checkpoint` and `CheckpointMetadata`
+ * types, and the built-in `InMemoryCheckpointStore` implementation.
+ */
+export * from './ICheckpointStore.js';
+export { InMemoryCheckpointStore } from './InMemoryCheckpointStore.js';
+//# sourceMappingURL=index.js.map

package/dist/orchestration/checkpoint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/orchestration/checkpoint/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/orchestration/compiler/GraphCompiler.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file GraphCompiler.ts
+ * @description Compiles an AgentGraph builder's internal state into a `CompiledExecutionGraph` IR object.
+ *
+ * The compiler is a pure, stateless transformation — it accepts a snapshot of the builder's
+ * node map and edge list, lowers Zod schemas to JSON Schema, and produces the canonical IR
+ * that the `GraphRuntime` operates on.
+ *
+ * This is intentionally thin: validation belongs in `GraphValidator`, optimisation passes
+ * (dead-node elimination, edge compaction) can be added as separate compiler passes later.
+ */
+import type { GraphNode, GraphEdge, CompiledExecutionGraph, StateReducers, MemoryConsistencyMode } from '../ir/types.js';
+/**
+ * Everything the compiler needs to produce a `CompiledExecutionGraph`.
+ *
+ * @property name               - Human-readable name embedded in the compiled graph.
+ * @property nodes              - All user-declared nodes keyed by their declared id.
+ * @property edges              - All directed edges (including START / END connections).
+ * @property stateSchema        - Zod schema instances for the three GraphState generics.
+ * @property reducers           - Field-level merge strategies forwarded unchanged to the IR.
+ * @property memoryConsistency  - Graph-wide memory isolation mode.
+ * @property checkpointPolicy   - Graph-wide default checkpoint persistence strategy.
+ */
+export interface GraphCompilerInput {
+    /** Human-readable graph name; used as the `name` field in the compiled output. */
+    name: string;
+    /** All `GraphNode` instances keyed by their assigned id. */
+    nodes: Map<string, GraphNode>;
+    /** All directed edges declared by the builder (start/end sentinels included). */
+    edges: GraphEdge[];
+    /**
+     * Zod schema instances for each of the three `GraphState` generic partitions.
+     * Lowered to JSON Schema during compilation via `lowerZodToJsonSchema`.
+     */
+    stateSchema: {
+        /** Schema for `GraphState.input` — the frozen user-provided input. */
+        input: any;
+        /** Schema for `GraphState.scratch` — the node-to-node communication bag. */
+        scratch: any;
+        /** Schema for `GraphState.artifacts` — accumulated external outputs. */
+        artifacts: any;
+    };
+    /** Field-level reducer configuration passed through to the IR without modification. */
+    reducers: StateReducers;
+    /** Graph-wide memory consistency mode. */
+    memoryConsistency: MemoryConsistencyMode;
+    /** Graph-wide checkpoint persistence strategy. */
+    checkpointPolicy: 'every_node' | 'explicit' | 'none';
+}
+/**
+ * Stateless compiler that transforms AgentGraph builder state into a `CompiledExecutionGraph`.
+ *
+ * Compilation steps:
+ * 1. Flatten the `nodes` Map into a plain array (preserving insertion order).
+ * 2. Copy the `edges` array without transformation.
+ * 3. Lower each Zod state schema to a JSON Schema object via `lowerZodToJsonSchema`.
+ * 4. Assign a unique `id` based on `name` and the current timestamp.
+ * 5. Forward `reducers`, `memoryConsistency`, and `checkpointPolicy` unchanged.
+ *
+ * @example
+ * ```ts
+ * const ir = GraphCompiler.compile({
+ *   name: 'my-agent',
+ *   nodes,
+ *   edges,
+ *   stateSchema: { input: z.object({ topic: z.string() }), scratch: z.object({}), artifacts: z.object({}) },
+ *   reducers: {},
+ *   memoryConsistency: 'snapshot',
+ *   checkpointPolicy: 'none',
+ * });
+ * ```
+ */
+export declare class GraphCompiler {
+    /**
+     * Compile builder state into a `CompiledExecutionGraph` IR object.
+     *
+     * This method is **pure** — it reads from `input` and returns a new object without
+     * mutating any of its arguments.
+     *
+     * @param input - The full set of builder state required for compilation.
+     * @returns A `CompiledExecutionGraph` ready for validation and execution.
+     */
+    static compile(input: GraphCompilerInput): CompiledExecutionGraph;
+}
+//# sourceMappingURL=GraphCompiler.d.ts.map

package/dist/orchestration/compiler/GraphCompiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphCompiler.d.ts","sourceRoot":"","sources":["../../../src/orchestration/compiler/GraphCompiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,sBAAsB,EACtB,aAAa,EACb,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAOxB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9B,iFAAiF;IACjF,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;OAGG;IACH,WAAW,EAAE;QACX,sEAAsE;QACtE,KAAK,EAAE,GAAG,CAAC;QACX,4EAA4E;QAC5E,OAAO,EAAE,GAAG,CAAC;QACb,wEAAwE;QACxE,SAAS,EAAE,GAAG,CAAC;KAChB,CAAC;IACF,uFAAuF;IACvF,QAAQ,EAAE,aAAa,CAAC;IACxB,0CAA0C;IAC1C,iBAAiB,EAAE,qBAAqB,CAAC;IACzC,kDAAkD;IAClD,gBAAgB,EAAE,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;CACtD;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;IACxB;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,sBAAsB;CAyBlE"}

package/dist/orchestration/compiler/GraphCompiler.js

@@ -0,0 +1,71 @@
+/**
+ * @file GraphCompiler.ts
+ * @description Compiles an AgentGraph builder's internal state into a `CompiledExecutionGraph` IR object.
+ *
+ * The compiler is a pure, stateless transformation — it accepts a snapshot of the builder's
+ * node map and edge list, lowers Zod schemas to JSON Schema, and produces the canonical IR
+ * that the `GraphRuntime` operates on.
+ *
+ * This is intentionally thin: validation belongs in `GraphValidator`, optimisation passes
+ * (dead-node elimination, edge compaction) can be added as separate compiler passes later.
+ */
+import { lowerZodToJsonSchema } from './SchemaLowering.js';
+// ---------------------------------------------------------------------------
+// GraphCompiler
+// ---------------------------------------------------------------------------
+/**
+ * Stateless compiler that transforms AgentGraph builder state into a `CompiledExecutionGraph`.
+ *
+ * Compilation steps:
+ * 1. Flatten the `nodes` Map into a plain array (preserving insertion order).
+ * 2. Copy the `edges` array without transformation.
+ * 3. Lower each Zod state schema to a JSON Schema object via `lowerZodToJsonSchema`.
+ * 4. Assign a unique `id` based on `name` and the current timestamp.
+ * 5. Forward `reducers`, `memoryConsistency`, and `checkpointPolicy` unchanged.
+ *
+ * @example
+ * ```ts
+ * const ir = GraphCompiler.compile({
+ *   name: 'my-agent',
+ *   nodes,
+ *   edges,
+ *   stateSchema: { input: z.object({ topic: z.string() }), scratch: z.object({}), artifacts: z.object({}) },
+ *   reducers: {},
+ *   memoryConsistency: 'snapshot',
+ *   checkpointPolicy: 'none',
+ * });
+ * ```
+ */
+export class GraphCompiler {
+    /**
+     * Compile builder state into a `CompiledExecutionGraph` IR object.
+     *
+     * This method is **pure** — it reads from `input` and returns a new object without
+     * mutating any of its arguments.
+     *
+     * @param input - The full set of builder state required for compilation.
+     * @returns A `CompiledExecutionGraph` ready for validation and execution.
+     */
+    static compile(input) {
+        return {
+            // Unique graph id: name slug + wall-clock timestamp for collision resistance.
+            id: `graph-${input.name}-${Date.now()}`,
+            name: input.name,
+            // Flatten Map → Array preserving the order in which nodes were added to the builder.
+            nodes: Array.from(input.nodes.values()),
+            // Edges are already an array; copy reference (immutable after compile).
+            edges: input.edges,
+            // Lower each Zod schema partition to a plain JSON Schema object.
+            stateSchema: {
+                input: lowerZodToJsonSchema(input.stateSchema.input),
+                scratch: lowerZodToJsonSchema(input.stateSchema.scratch),
+                artifacts: lowerZodToJsonSchema(input.stateSchema.artifacts),
+            },
+            // Forward reducer, consistency, and checkpoint config unchanged.
+            reducers: input.reducers,
+            checkpointPolicy: input.checkpointPolicy,
+            memoryConsistency: input.memoryConsistency,
+        };
+    }
+}
+//# sourceMappingURL=GraphCompiler.js.map

package/dist/orchestration/compiler/GraphCompiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphCompiler.js","sourceRoot":"","sources":["../../../src/orchestration/compiler/GraphCompiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AA4C3D,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,aAAa;IACxB;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CAAC,KAAyB;QACtC,OAAO;YACL,8EAA8E;YAC9E,EAAE,EAAE,SAAS,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE;YACvC,IAAI,EAAE,KAAK,CAAC,IAAI;YAEhB,qFAAqF;YACrF,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAEvC,wEAAwE;YACxE,KAAK,EAAE,KAAK,CAAC,KAAK;YAElB,iEAAiE;YACjE,WAAW,EAAE;gBACX,KAAK,EAAE,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC;gBACpD,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC;gBACxD,SAAS,EAAE,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC;aAC7D;YAED,iEAAiE;YACjE,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;SAC3C,CAAC;IACJ,CAAC;CACF"}