@noetic-tools/core 0.0.1 → 0.1.0

package/dist/portable.js

@@ -1,34 +1,8 @@
-//#region Portable Adapters
-/** @public */
-export { createInMemoryFsAdapter } from './adapters/in-memory-fs-adapter';
-/** @public */
-export { createInMemoryShellAdapter } from './adapters/in-memory-shell-adapter';
-/** @public */
-export { createInMemorySubprocessAdapter } from './adapters/in-memory-subprocess-adapter';
-//#endregion
-//#region Builders
-/** @public */
-export { step } from './builders/step-builders';
-/** @public */
-export { tool, toolWithGenerator } from './builders/tool-builder';
-//#endregion
-//#region Memory Layers
-/** @public */
-export { durableTaskState } from './memory/layers/durable-task-state';
-/** @public */
-export { historyWindow } from './memory/layers/history-window';
-/** @public */
-export { observationalMemory } from './memory/layers/observational-memory';
-/** @public */
-export { planMemory } from './memory/layers/plan';
-/** @public */
-export { toolMemoryLayer } from './memory/layers/tool-memory-layer';
-/** @public */
-export { workingMemory } from './memory/layers/working-memory';
-//#endregion
-//#region Runtime
-/** @public */
-export { AgentHarness } from './runtime/agent-harness';
-/** @public */
-export { createInMemoryStorage } from './runtime/in-memory-storage';
-//#endregion
+export * from './portable/adapters';
+export * from './portable/ask-user';
+export * from './portable/builders';
+export * from './portable/memory-layers';
+export * from './portable/runtime';
+export * from './portable/until';
+/** @public */
+export { Slot } from './types/memory';

package/dist/runtime/broadcaster-utils.d.ts

@@ -13,7 +13,11 @@ export type EmitOption = boolean | ((eventType: string, data: Record<string, unk
  */
 export declare function shouldEmit(emit: EmitOption | undefined, eventType: string, data: Record<string, unknown>): boolean;
 /**
- * Get the EventBroadcaster from a context if available.
+ * Get the EventBroadcaster from a context if available. Walks up the parent
+ * chain so spawned child contexts inherit the session-level broadcaster — the
+ * interpreter never re-installs `_broadcaster` on spawn children, so without
+ * this traversal every LLM call inside a `spawn()` step would be invisible to
+ * the UI stream.
  * Uses property check rather than instanceof to support mock contexts in tests.
  * @internal
  */

package/dist/runtime/broadcaster-utils.js

@@ -26,16 +26,21 @@ function hasBroadcaster(ctx) {
     return typeof ctx._broadcaster === 'object' && ctx._broadcaster !== null;
 }
 /**
- * Get the EventBroadcaster from a context if available.
+ * Get the EventBroadcaster from a context if available. Walks up the parent
+ * chain so spawned child contexts inherit the session-level broadcaster — the
+ * interpreter never re-installs `_broadcaster` on spawn children, so without
+ * this traversal every LLM call inside a `spawn()` step would be invisible to
+ * the UI stream.
  * Uses property check rather than instanceof to support mock contexts in tests.
  * @internal
  */
 export function getBroadcaster(ctx) {
-    if (!ctx) {
-        return undefined;
-    }
-    if (hasBroadcaster(ctx)) {
-        return ctx._broadcaster;
+    let current = ctx;
+    while (current) {
+        if (hasBroadcaster(current)) {
+            return current._broadcaster;
+        }
+        current = current.parent ?? null;
     }
     return undefined;
 }

package/dist/runtime/channel-store.js

@@ -1,5 +1,5 @@
 import { NoeticErrorImpl } from '../errors/noetic-error';
-import { frameworkCast } from '../interpreter/framework-cast';
+import { frameworkCast } from '../util/framework-cast';
 function isExternalChannel(ch) {
     return 'external' in ch && ch.external === true;
 }

package/dist/runtime/context-deps.d.ts

@@ -0,0 +1,4 @@
+export { buildContextMemory } from '../memory/layer-api';
+export type { ItemSchemaRegistry } from '../schemas/item';
+export { defaultItemSchemaRegistry } from '../schemas/item';
+export type { AgentHarnessContract, Channel, ChannelStore, Context, ContextMemory, CwdState, EventBroadcaster, FrontierFrame, FsAdapter, Item, ItemLog, LastLayerUsage, MemoryLayer, Span, StepMeta, TokenUsage, Tool, } from './context-type-deps';

package/dist/runtime/context-deps.js

@@ -0,0 +1,2 @@
+export { buildContextMemory } from '../memory/layer-api';
+export { defaultItemSchemaRegistry } from '../schemas/item';

package/dist/runtime/context-impl.d.ts

@@ -1,14 +1,4 @@
-import type { ItemSchemaRegistry } from '../schemas/item';
-import type { Channel } from '../types/channel';
-import type { StepMeta, TokenUsage, Tool } from '../types/common';
-import type { Context, CwdState, ItemLog, LastLayerUsage } from '../types/context';
-import type { FsAdapter } from '../types/fs-adapter';
-import type { Item } from '../types/items';
-import type { ContextMemory, MemoryLayer } from '../types/memory';
-import type { Span } from '../types/observability';
-import type { AgentHarnessContract } from '../types/runtime';
-import type { ChannelStore } from './channel-store';
-import type { EventBroadcaster } from './event-broadcaster';
+import type { AgentHarnessContract, Channel, ChannelStore, Context, ContextMemory, CwdState, EventBroadcaster, FrontierFrame, FsAdapter, Item, ItemLog, ItemSchemaRegistry, LastLayerUsage, MemoryLayer, Span, StepMeta, TokenUsage, Tool } from './context-deps';
 export declare class ContextImpl implements Context<ContextMemory> {
     readonly id: string;
     stepCount: number;
@@ -34,7 +24,8 @@ export declare class ContextImpl implements Context<ContextMemory> {
     /**
      * Shared channel store for cross-context communication. Inherited by
      * `fork` / `spawn` children so channels published by a sibling are visible
-     * to peers — see `interpreter/execute-fork.ts` and `interpreter/execute-spawn.ts`.
+     * to peers — see `executeFork` and `executeSpawn` in `interpreter/execute-action.ts`
+     * and `interpreter/execute-control.ts`.
      * @internal
      */
     readonly channelStore?: ChannelStore;
@@ -44,6 +35,15 @@ export declare class ContextImpl implements Context<ContextMemory> {
     private _aborted;
     private _abortReason?;
     private _memory?;
+    /**
+     * Stack of steps currently in flight on this context, most-recent last.
+     * Pushed by `enterStep` at the top of `execute()` and popped by
+     * `leaveStep` when the step resolves (success or failure). The harness'
+     * checkpoint writer serialises this stack as the execution frontier so
+     * a restart can identify which step the context was paused inside.
+     * @internal
+     */
+    private readonly _frontier;
     constructor(opts: {
         harness: AgentHarnessContract;
         parent?: Context;
@@ -59,6 +59,14 @@ export declare class ContextImpl implements Context<ContextMemory> {
         itemSchemas?: ItemSchemaRegistry;
         cwdState?: CwdState;
         _broadcaster?: EventBroadcaster;
+        /**
+         * Pre-chosen context id. When set, the ContextImpl adopts this id instead
+         * of generating a fresh UUID. Used by `executeSpawn` so the child's
+         * `ctx.id` matches the `executionId` keyed into the layer-state store —
+         * otherwise writes via `ctx.memory[layerId].state` land on one id while
+         * spawn's `onReturn` reads from another, silently losing the update.
+         */
+        id?: string;
     });
     get elapsed(): number;
     get aborted(): boolean;
@@ -77,4 +85,26 @@ export declare class ContextImpl implements Context<ContextMemory> {
     get completionValue(): unknown;
     get abortReason(): string | undefined;
     abort(reason?: string): void;
+    /**
+     * @internal
+     * Push a frame onto the execution frontier. Called by `execute()` at the
+     * top of every step dispatch so that the frontier reflects exactly the
+     * stack of steps currently in-flight on this context.
+     */
+    enterStep(frame: FrontierFrame): void;
+    /**
+     * @internal
+     * Pop the top frame. Called when a step resolves (success or failure)
+     * so that the frontier unwinds cleanly. The value of `expectedStepId`
+     * is used as a consistency check — if it does not match the top frame
+     * the pop is still performed, but a best-effort warning is surfaced to
+     * stderr rather than swallowed silently.
+     */
+    leaveStep(expectedStepId: string): void;
+    /**
+     * @internal
+     * Return a defensive copy of the current frontier. Consumed by the
+     * checkpoint writer — see `AgentHarness.checkpoint`.
+     */
+    serialiseFrontier(): FrontierFrame[];
 }

package/dist/runtime/context-impl.js

@@ -1,5 +1,4 @@
-import { buildContextMemory } from '../memory/layer-api';
-import { defaultItemSchemaRegistry } from '../schemas/item';
+import { buildContextMemory, defaultItemSchemaRegistry } from './context-deps';
 import { ItemLogImpl } from './item-log-impl';
 const EMPTY_MEMORY = Object.freeze({});
 class NoopSpan {
@@ -39,7 +38,8 @@ export class ContextImpl {
     /**
      * Shared channel store for cross-context communication. Inherited by
      * `fork` / `spawn` children so channels published by a sibling are visible
-     * to peers — see `interpreter/execute-fork.ts` and `interpreter/execute-spawn.ts`.
+     * to peers — see `executeFork` and `executeSpawn` in `interpreter/execute-action.ts`
+     * and `interpreter/execute-control.ts`.
      * @internal
      */
     channelStore;
@@ -49,8 +49,17 @@ export class ContextImpl {
     _aborted = false;
     _abortReason;
     _memory;
+    /**
+     * Stack of steps currently in flight on this context, most-recent last.
+     * Pushed by `enterStep` at the top of `execute()` and popped by
+     * `leaveStep` when the step resolves (success or failure). The harness'
+     * checkpoint writer serialises this stack as the execution frontier so
+     * a restart can identify which step the context was paused inside.
+     * @internal
+     */
+    _frontier = [];
     constructor(opts) {
-        this.id = crypto.randomUUID();
+        this.id = opts.id ?? crypto.randomUUID();
         this._createdAt = Date.now();
         this.harness = opts.harness;
         this.state = opts.state ?? {};
@@ -137,4 +146,42 @@ export class ContextImpl {
         this._aborted = true;
         this._abortReason = reason;
     }
+    /**
+     * @internal
+     * Push a frame onto the execution frontier. Called by `execute()` at the
+     * top of every step dispatch so that the frontier reflects exactly the
+     * stack of steps currently in-flight on this context.
+     */
+    enterStep(frame) {
+        this._frontier.push(frame);
+    }
+    /**
+     * @internal
+     * Pop the top frame. Called when a step resolves (success or failure)
+     * so that the frontier unwinds cleanly. The value of `expectedStepId`
+     * is used as a consistency check — if it does not match the top frame
+     * the pop is still performed, but a best-effort warning is surfaced to
+     * stderr rather than swallowed silently.
+     */
+    leaveStep(expectedStepId) {
+        const top = this._frontier[this._frontier.length - 1];
+        if (top && top.stepId !== expectedStepId) {
+            // A mismatch indicates bookkeeping drift. We unwind best-effort and
+            // let the caller observe via `serialiseFrontier()` if needed.
+            console.warn(`ContextImpl.leaveStep: expected "${expectedStepId}" on top of frontier but saw "${top.stepId}".`);
+        }
+        this._frontier.pop();
+    }
+    /**
+     * @internal
+     * Return a defensive copy of the current frontier. Consumed by the
+     * checkpoint writer — see `AgentHarness.checkpoint`.
+     */
+    serialiseFrontier() {
+        return this._frontier.map((frame) => ({
+            stepId: frame.stepId,
+            input: frame.input,
+            state: frame.state,
+        }));
+    }
 }

package/dist/runtime/context-type-deps.d.ts

@@ -0,0 +1,14 @@
+export type { Channel } from '../types/channel';
+export type { FrontierFrame } from '../types/checkpoint';
+export type { StepMeta, TokenUsage } from '../types/common';
+export type { Context, CwdState } from '../types/context';
+export type { ItemLog } from '../types/context-parts/item-log';
+export type { LastLayerUsage } from '../types/context-parts/layer-usage';
+export type { FsAdapter } from '../types/fs-adapter';
+export type { Item } from '../types/items';
+export type { ContextMemory, MemoryLayer } from '../types/memory';
+export type { Span } from '../types/observability';
+export type { AgentHarnessContract } from '../types/runtime';
+export type { Tool } from '../types/tool';
+export type { ChannelStore } from './channel-store';
+export type { EventBroadcaster } from './event-broadcaster';

package/dist/runtime/context-type-deps.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/detached-handle.d.ts

@@ -1,14 +1,62 @@
 import type { DetachedHandle } from '../types/detached';
 import { DetachedStatus } from '../types/detached';
+import type { SubprocessAdapter, SubprocessHandle } from '../types/subprocess-adapter';
+interface DetachedHandleOpts {
+    /** Id surfaced to callers — usually the execution id (childCtx.id in
+     *  `detachedSpawn`) so consumers can correlate it with their own state. */
+    id: string;
+    /** Step id — used when the adapter surfaces a generic failure and we need
+     *  to produce a `NoeticError` with a meaningful `stepId`. */
+    stepId: string;
+    /** Adapter that produced the handle. */
+    adapter: SubprocessAdapter;
+    /**
+     * Promise that resolves to the adapter-assigned handle. `detachedSpawn`
+     * passes the in-flight `adapter.spawn(request)` promise here so `.await()`
+     * is reachable even before the spawn itself has settled.
+     */
+    spawnPromise: Promise<SubprocessHandle>;
+}
+/**
+ * @public
+ * Thin wrapper over a `SubprocessHandle` that implements the `DetachedHandle`
+ * contract. Polls the adapter until the handle reaches a terminal status,
+ * then reads the result (or error) off `handle.metadata`.
+ *
+ * The polling cadence starts at 10ms and ramps to 100ms after the first
+ * second — responsive for short-lived in-memory steps without burning cycles
+ * on long-running ones.
+ */
 export declare class DetachedHandleImpl<O> implements DetachedHandle<O> {
     readonly id: string;
+    private readonly _stepId;
+    private readonly _adapter;
+    private readonly _spawnPromise;
+    private readonly _startTime;
     private _status;
     private _result;
     private _error;
-    private readonly promise;
-    constructor(id: string, promise: Promise<O>);
+    private _settlementPromise;
+    constructor(opts: DetachedHandleOpts);
     get status(): DetachedStatus;
     get result(): O | undefined;
     get error(): string | undefined;
+    /**
+     * Wait for the underlying handle to settle, up to an optional timeout.
+     * On settlement, the cached status/result/error are updated before
+     * returning — so a caller that inspects `status` after `await()` resolves
+     * observes the final value.
+     */
     await(timeout?: number): Promise<O>;
+    /**
+     * Start (or return the cached) polling promise that resolves on the first
+     * terminal status the adapter reports for this handle.
+     *
+     * A single settlement promise is shared across all `.await()` callers so
+     * repeated calls don't spawn parallel polling loops.
+     */
+    private getOrStartSettlement;
+    private pollUntilSettled;
+    private finalise;
 }
+export {};

package/dist/runtime/detached-handle.js

@@ -1,19 +1,125 @@
 import { NoeticErrorImpl } from '../errors/noetic-error';
 import { DetachedStatus } from '../types/detached';
+import { frameworkCast } from '../util/framework-cast';
+//#endregion
+//#region Helpers
+const INITIAL_POLL_MS = 10;
+const MAX_POLL_MS = 100;
+const POLL_RAMP_AFTER_MS = 1_000;
+/** Upper bound on microtask yields before falling back to timer-based
+ *  polling. Chosen empirically: in-memory step bodies settle within a
+ *  handful of microtasks, and 64 gives plenty of headroom for chained
+ *  awaits inside complex step trees without busy-spinning. */
+const MAX_MICROTASK_YIELDS = 64;
+/** Grace period before treating persistent null `adapter.get(handleId)`
+ *  results as an eviction. Tolerates transient nulls from adapters that
+ *  register the handle asynchronously relative to the spawn promise
+ *  settling, but bounds the worst case so a corrupt adapter doesn't
+ *  produce an infinite poll. */
+const HANDLE_EVICTED_GRACE_MS = 500;
+/**
+ * Yield control to the timer queue so the adapter has a chance to
+ * transition the handle before we issue the next `adapter.get()` call.
+ * Using a timer (even 0ms) ensures we don't spin-lock when the adapter
+ * schedules its completion on a later microtask.
+ */
+function sleep(ms) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isTerminalStatus(status) {
+    return (status === 'completed' || status === 'failed' || status === 'stopped' || status === 'stale');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isNoeticErrorPayload(value) {
+    return isRecord(value) && typeof value.kind === 'string';
+}
+/** Rehydrate a thrown error from the handle metadata. Preserves the
+ *  structured NoeticError shape when present so type-guards like
+ *  `isNoeticError` keep working on the consumer side. */
+function rehydrateError(payload, stepId) {
+    if (!payload) {
+        return new NoeticErrorImpl({
+            kind: 'step_failed',
+            stepId,
+            cause: new Error('Detached spawn failed without an error payload'),
+            retriesExhausted: false,
+        });
+    }
+    if (isNoeticErrorPayload(payload.noeticError)) {
+        return new NoeticErrorImpl(payload.noeticError);
+    }
+    const err = new Error(payload.message);
+    if (payload.name) {
+        err.name = payload.name;
+    }
+    if (payload.stack) {
+        err.stack = payload.stack;
+    }
+    return err;
+}
+function extractResult(metadata) {
+    if (!metadata || metadata.result === undefined) {
+        return undefined;
+    }
+    return frameworkCast(metadata.result);
+}
+function extractError(metadata) {
+    if (!metadata || metadata.error === undefined) {
+        return undefined;
+    }
+    const raw = metadata.error;
+    if (!isRecord(raw)) {
+        return {
+            message: String(raw),
+        };
+    }
+    const message = typeof raw.message === 'string' ? raw.message : 'unknown error';
+    const name = typeof raw.name === 'string' ? raw.name : undefined;
+    const stack = typeof raw.stack === 'string' ? raw.stack : undefined;
+    return {
+        message,
+        name,
+        stack,
+        noeticError: raw.noeticError,
+    };
+}
+//#endregion
 //#region DetachedHandleImpl
+/**
+ * @public
+ * Thin wrapper over a `SubprocessHandle` that implements the `DetachedHandle`
+ * contract. Polls the adapter until the handle reaches a terminal status,
+ * then reads the result (or error) off `handle.metadata`.
+ *
+ * The polling cadence starts at 10ms and ramps to 100ms after the first
+ * second — responsive for short-lived in-memory steps without burning cycles
+ * on long-running ones.
+ */
 export class DetachedHandleImpl {
     id;
+    _stepId;
+    _adapter;
+    _spawnPromise;
+    _startTime;
     _status = DetachedStatus.Running;
     _result;
     _error;
-    promise;
-    constructor(id, promise) {
-        this.id = id;
-        this.promise = promise;
-        promise.then((value) => {
-            this._status = DetachedStatus.Completed;
-            this._result = value;
-        }, (err) => {
+    _settlementPromise;
+    constructor(opts) {
+        this.id = opts.id;
+        this._stepId = opts.stepId;
+        this._adapter = opts.adapter;
+        this._spawnPromise = opts.spawnPromise;
+        this._startTime = Date.now();
+        // Observe spawn failure eagerly so `.error` is populated even if the
+        // caller never invokes `.await()`. We intentionally swallow the
+        // rejection here — `.await()` surfaces it to the caller.
+        this._spawnPromise.catch((err) => {
             this._status = DetachedStatus.Failed;
             this._error = err instanceof Error ? err.message : String(err);
         });
@@ -27,16 +133,23 @@ export class DetachedHandleImpl {
     get error() {
         return this._error;
     }
+    /**
+     * Wait for the underlying handle to settle, up to an optional timeout.
+     * On settlement, the cached status/result/error are updated before
+     * returning — so a caller that inspects `status` after `await()` resolves
+     * observes the final value.
+     */
     async await(timeout) {
+        const settlement = this.getOrStartSettlement();
         if (timeout === undefined || timeout <= 0) {
-            return this.promise;
+            return settlement;
         }
         let timerId;
         const timeoutPromise = new Promise((_resolve, reject) => {
             timerId = setTimeout(() => {
                 reject(new NoeticErrorImpl({
                     kind: 'step_failed',
-                    stepId: this.id,
+                    stepId: this._stepId,
                     cause: new Error(`Detached spawn timed out after ${timeout}ms`),
                     retriesExhausted: false,
                 }));
@@ -44,13 +157,104 @@ export class DetachedHandleImpl {
         });
         try {
             return await Promise.race([
-                this.promise,
+                settlement,
                 timeoutPromise,
             ]);
         }
         finally {
-            clearTimeout(timerId);
+            if (timerId !== undefined) {
+                clearTimeout(timerId);
+            }
+        }
+    }
+    /**
+     * Start (or return the cached) polling promise that resolves on the first
+     * terminal status the adapter reports for this handle.
+     *
+     * A single settlement promise is shared across all `.await()` callers so
+     * repeated calls don't spawn parallel polling loops.
+     */
+    getOrStartSettlement() {
+        if (this._settlementPromise) {
+            return this._settlementPromise;
+        }
+        this._settlementPromise = this.pollUntilSettled();
+        return this._settlementPromise;
+    }
+    async pollUntilSettled() {
+        // Wait for the spawn itself to succeed before we start polling —
+        // otherwise we'd be polling with an undefined handle id.
+        const initialHandle = await this._spawnPromise;
+        if (isTerminalStatus(initialHandle.status)) {
+            return this.finalise(initialHandle);
+        }
+        // Track when the adapter persistently returns null for this handle.
+        // Transient nulls are tolerated for `HANDLE_EVICTED_GRACE_MS`; after
+        // that we raise `handle_evicted` instead of looping forever. A
+        // non-null observation resets the grace window.
+        let firstNullAt = null;
+        const observeNull = () => {
+            if (firstNullAt === null) {
+                firstNullAt = Date.now();
+                return;
+            }
+            if (Date.now() - firstNullAt >= HANDLE_EVICTED_GRACE_MS) {
+                throw new NoeticErrorImpl({
+                    kind: 'handle_evicted',
+                    handleId: initialHandle.id,
+                    stepId: this._stepId,
+                    gracePeriodMs: HANDLE_EVICTED_GRACE_MS,
+                });
+            }
+        };
+        const observeHandle = (h) => {
+            if (h === null) {
+                observeNull();
+                return null;
+            }
+            firstNullAt = null;
+            return h;
+        };
+        // Fast path: yield through the microtask queue first. The in-memory
+        // adapter schedules completion on a microtask, so a handful of yields
+        // typically resolves the handle in sub-millisecond time. This keeps the
+        // interpreter's "route through adapter" overhead negligible.
+        for (let i = 0; i < MAX_MICROTASK_YIELDS; i++) {
+            const handle = observeHandle(await this._adapter.get(initialHandle.id));
+            if (handle && isTerminalStatus(handle.status)) {
+                return this.finalise(handle);
+            }
+            await Promise.resolve();
+        }
+        // Slow path: fall back to timer-based polling for genuinely long-running
+        // handles (out-of-process adapters, async work that doesn't resolve on
+        // the microtask queue).
+        let delay = INITIAL_POLL_MS;
+        for (;;) {
+            const handle = observeHandle(await this._adapter.get(initialHandle.id));
+            if (handle && isTerminalStatus(handle.status)) {
+                return this.finalise(handle);
+            }
+            await sleep(delay);
+            if (Date.now() - this._startTime >= POLL_RAMP_AFTER_MS) {
+                delay = MAX_POLL_MS;
+            }
+        }
+    }
+    finalise(handle) {
+        const metadata = handle.metadata;
+        if (handle.status === 'completed') {
+            const value = extractResult(metadata);
+            this._status = DetachedStatus.Completed;
+            this._result = value;
+            return frameworkCast(value);
         }
+        // Failed / stopped / stale — all map to Failed from the caller's view.
+        const errorPayload = extractError(metadata);
+        const err = rehydrateError(errorPayload, this._stepId);
+        this._status = DetachedStatus.Failed;
+        this._error = err.message;
+        throw err;
     }
 }
 //#endregion

package/dist/runtime/durable/checkpoint-store.d.ts

@@ -0,0 +1,38 @@
+import type { CheckpointSnapshot } from '../../types/checkpoint';
+import type { StorageAdapter } from '../../types/memory';
+export declare const CheckpointKeys: {
+    readonly ExecPrefix: "execution:";
+    readonly SnapshotSuffix: ":snapshot";
+    readonly FrontierSuffix: ":frontier";
+    readonly LayersSuffix: ":layers:";
+    readonly CwdSuffix: ":cwd";
+    readonly AskUserSuffix: ":askUser";
+    readonly ItemLogSuffix: ":itemLog";
+};
+/**
+ * @public
+ * Typed wrapper around a `StorageAdapter` that owns the key layout for
+ * checkpoint snapshots and validates every read with the canonical Zod
+ * schema.
+ *
+ * Corruption or schema-version drift is surfaced as `NoeticConfigError`
+ * (`code === 'CHECKPOINT_SCHEMA_MISMATCH'`) so callers can discard the
+ * offending snapshot without crashing the host.
+ */
+export interface CheckpointStore {
+    /** Persist a snapshot. Later calls for the same `executionId` overwrite. */
+    save(snapshot: CheckpointSnapshot): Promise<void>;
+    /** Load the snapshot for an execution, or `null` if none is recorded. */
+    load(executionId: string): Promise<CheckpointSnapshot | null>;
+    /** List every `executionId` that has a persisted snapshot. */
+    list(): Promise<ReadonlyArray<{
+        executionId: string;
+    }>>;
+    /** Remove the snapshot for `executionId`. No-op when the key is absent. */
+    clear(executionId: string): Promise<void>;
+}
+/** @public Options for `createCheckpointStore`. */
+export interface CreateCheckpointStoreOptions {
+    storage: StorageAdapter;
+}
+export declare function createCheckpointStore(options: CreateCheckpointStoreOptions): CheckpointStore;