@noetic-tools/context 1.0.0

package/dist/context/layer-lifecycle.d.ts

@@ -0,0 +1,239 @@
+import type { ContextLayer, ExecutionContext, Item, ItemLog, ItemSchemaRegistry, LLMResponse, ScopedStorage, SteeringDecision, StorageAdapter } from '@noetic-tools/types';
+export interface LayerStateStore {
+    get<T>(executionId: string, layerId: string): T | undefined;
+    set<T>(executionId: string, layerId: string, state: T): void;
+    /**
+     * Whether ANY state entry exists for the (execution, layer) pair — including
+     * an explicit `undefined` written by a layer clearing its state. This is what
+     * lets the lifecycle distinguish "init never ran for this execution" (no
+     * entry → an init-bearing layer is skipped) from "layer legitimately cleared
+     * its state" (entry present → hooks keep running with `undefined` state).
+     * Optional so custom stores keep compiling; without it, the lifecycle falls
+     * back to the legacy sentinel (init-bearing layer with no state is skipped).
+     */
+    has?(executionId: string, layerId: string): boolean;
+    cleanup(executionId: string): void;
+    diagnostic: (layerId: string, hook: string, error: unknown) => void;
+    /**
+     * Register a durable write-through target for a layer's state under an
+     * execution. Once registered, EVERY `set()` for that (execution, layer) pair
+     * is asynchronously mirrored to `target` (key `'state'`); `set(…, undefined)`
+     * deletes the durable key. Writes are coalesced per key (latest wins) and
+     * mirror failures are reported via `diagnostic(layerId, 'persist', e)` —
+     * they never throw. Optional so custom stores keep compiling; without it,
+     * no durable mirroring occurs.
+     */
+    registerDurable?(executionId: string, layerId: string, target: ScopedStorage): void;
+    /** Await all in-flight durable mirror writes for an execution. */
+    flush?(executionId: string): Promise<void>;
+    /**
+     * Mark a layer disabled for an execution (its `init` failed with
+     * `onInitError: 'disable'`). Disabled layers are skipped by every later
+     * hook. Optional so custom stores keep compiling; without explicit
+     * tracking, the lifecycle falls back to the legacy sentinel (init-bearing
+     * layer with no state).
+     */
+    disable?(executionId: string, layerId: string): void;
+    /** Whether a layer was disabled for an execution. */
+    isDisabled?(executionId: string, layerId: string): boolean;
+}
+interface InitLayersParams {
+    layers: ContextLayer[];
+    ctx: ExecutionContext;
+    storage: StorageAdapter;
+    store: LayerStateStore;
+}
+interface RecallLayersParams {
+    layers: ContextLayer[];
+    query: string;
+    ctx: ExecutionContext;
+    log: ItemLog;
+    budgets: Map<string, number>;
+    store: LayerStateStore;
+    itemSchemas?: ItemSchemaRegistry;
+}
+interface StoreLayersParams {
+    layers: ContextLayer[];
+    response: LLMResponse;
+    ctx: ExecutionContext;
+    log: ItemLog;
+    store: LayerStateStore;
+    /**
+     * Unused by storeLayers itself — durable persistence is centralized in the
+     * state store's write-through (registered in `initLayers`). Accepted so
+     * existing call sites keep compiling.
+     */
+    storage?: StorageAdapter;
+    /** When provided, an eventual layer whose store produces new state is marked stale for the next recall. */
+    recallCache?: RecallCache;
+}
+interface SpawnLayersParams {
+    layers: ContextLayer[];
+    parentCtx: ExecutionContext;
+    childCtx: ExecutionContext;
+    store: LayerStateStore;
+    itemSchemas?: ItemSchemaRegistry;
+    /**
+     * When provided, durable write-through targets are registered for the child
+     * execution (non-execution scopes only), so state written during the child's
+     * run is mirrored durably just like the parent's.
+     */
+    storage?: StorageAdapter;
+}
+interface ReturnLayersParams<T = unknown> {
+    layers: ContextLayer[];
+    parentCtx: ExecutionContext;
+    childCtx: ExecutionContext;
+    childLog: ItemLog;
+    result: T;
+    store: LayerStateStore;
+}
+interface CompleteLayersParams {
+    layers: ContextLayer[];
+    ctx: ExecutionContext;
+    log: ItemLog;
+    outcome: 'success' | 'failure' | 'aborted';
+    store: LayerStateStore;
+}
+interface DisposeLayersParams {
+    layers: ContextLayer[];
+    ctx: ExecutionContext;
+    store: LayerStateStore;
+}
+interface BeforeToolCallLayersParams {
+    layers: ContextLayer[];
+    toolName: string;
+    toolArgs: unknown;
+    ctx: ExecutionContext;
+    store: LayerStateStore;
+}
+interface AfterModelCallLayersParams {
+    layers: ContextLayer[];
+    response: LLMResponse;
+    ctx: ExecutionContext;
+    store: LayerStateStore;
+}
+interface ProjectHistoryLayersParams {
+    layers: ContextLayer[];
+    items: ReadonlyArray<Item>;
+    ctx: ExecutionContext;
+    store: LayerStateStore;
+}
+/** @public A request to re-render the context window, collected from onItemAppend hooks. */
+export interface RerenderRequest {
+    layerId: string;
+    slot: number;
+    timing: 'immediate' | 'batched';
+    scope: 'self' | 'slot-after' | 'all';
+}
+/** @public Result of running items through the onItemAppend pipeline. */
+export interface AppendPipelineResult {
+    /** Final items to append after all transformations. */
+    items: Item[];
+    /** Re-render requests collected from layers. */
+    rerenderRequests: RerenderRequest[];
+}
+interface RunAppendPipelineParams {
+    layers: ContextLayer[];
+    items: Item[];
+    ctx: ExecutionContext;
+    log: ItemLog;
+    store: LayerStateStore;
+}
+interface ExecuteRerenderParams {
+    requests: RerenderRequest[];
+    layers: ContextLayer[];
+    ctx: ExecutionContext;
+    log: ItemLog;
+    budgets: Map<string, number>;
+    store: LayerStateStore;
+    itemSchemas?: ItemSchemaRegistry;
+    /** Query for context-aware recall (e.g., last user message) */
+    query?: string;
+    /** Current re-render depth (for loop protection) */
+    depth?: number;
+}
+export declare function createLayerStateStore(diagnostic?: (layerId: string, hook: string, error: unknown) => void): LayerStateStore;
+interface RecallCacheEntry {
+    layerId: string;
+    items: Item[];
+    tokenCount: number;
+}
+/**
+ * Per-harness memoization for `recallMode: 'eventual'` layers. Eventual recall
+ * serves the cached entry when warm and re-runs only when `store()` produces new
+ * state (which marks the entry stale), so a slow layer's `recall()` does not run
+ * on every turn.
+ */
+export interface RecallCache {
+    entries: Map<string, RecallCacheEntry>;
+    stale: Set<string>;
+}
+export declare function createRecallCache(): RecallCache;
+export declare function mostRestrictive(decisions: SteeringDecision[]): SteeringDecision;
+export declare function initLayers({ layers, ctx, storage, store }: InitLayersParams): Promise<void>;
+export declare function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas, }: RecallLayersParams): Promise<{
+    layerId: string;
+    items: Item[];
+    tokenCount: number;
+}[]>;
+type RecallEntry = {
+    layerId: string;
+    items: Item[];
+    tokenCount: number;
+};
+interface RecallLayersModeParams extends RecallLayersParams {
+    /** When true, treat every layer as atomic regardless of its `recallMode`. */
+    forceAtomic?: boolean;
+}
+/**
+ * Recall the layers that must complete before the model call: those with
+ * `recallMode !== 'eventual'`, or every layer when `forceAtomic` is set.
+ */
+export declare function recallLayersAtomic({ forceAtomic, ...params }: RecallLayersModeParams): Promise<RecallEntry[]>;
+interface RecallLayersEventualParams extends RecallLayersModeParams {
+    cache: RecallCache;
+}
+/**
+ * Recall `recallMode: 'eventual'` layers, served from {@link RecallCache}.
+ * A cold or store-invalidated (stale) entry is recalled and cached; a warm
+ * entry is returned as-is, so an eventual layer's `recall()` runs only after
+ * its `store()` produces new state. Returns nothing when `forceAtomic` is set —
+ * those layers are then handled by {@link recallLayersAtomic} instead.
+ */
+export declare function recallLayersEventual({ cache, forceAtomic, ...params }: RecallLayersEventualParams): Promise<RecallEntry[]>;
+export declare function storeLayers({ layers, response, ctx, log, store, recallCache, }: StoreLayersParams): Promise<void>;
+export declare function disposeLayers({ layers, ctx, store }: DisposeLayersParams): Promise<void>;
+export declare function spawnLayers({ layers, parentCtx, childCtx, store, itemSchemas, storage, }: SpawnLayersParams): Promise<{
+    layerId: string;
+    childState: unknown;
+    items: Item[];
+}[]>;
+export declare function returnLayers<T>({ layers, parentCtx, childCtx, childLog, result, store, }: ReturnLayersParams<T>): Promise<T>;
+export declare function completeLayers({ layers, ctx, log, outcome, store, }: CompleteLayersParams): Promise<void>;
+export declare function beforeToolCallLayers({ layers, toolName, toolArgs, ctx, store, }: BeforeToolCallLayersParams): Promise<SteeringDecision>;
+export declare function afterModelCallLayers({ layers, response, ctx, store, }: AfterModelCallLayersParams): Promise<SteeringDecision>;
+/**
+ * Run history items through every layer's `projectHistory` hook in slot order.
+ * Each layer receives the previous layer's output. Storage (`itemLog`) is
+ * never mutated — this is a pure projection over the input array. Returns
+ * the projected items unchanged when no layer registers the hook.
+ */
+export declare function projectHistoryLayers({ layers, items, ctx, store, }: ProjectHistoryLayersParams): Promise<ReadonlyArray<Item>>;
+/**
+ * Run items through the onItemAppend pipeline.
+ * Each layer can filter, transform, or inject items.
+ * Returns final items to append and any re-render requests.
+ */
+export declare function runAppendPipeline({ layers, items, ctx, log, store, }: RunAppendPipelineParams): Promise<AppendPipelineResult>;
+/**
+ * Execute re-render based on collected requests.
+ * Determines which layers need re-recall based on scope and runs them.
+ * Returns new recall results to merge into view.
+ */
+export declare function executeRerender({ requests, layers, ctx, log, budgets, store, itemSchemas, query, depth, }: ExecuteRerenderParams): Promise<{
+    layerId: string;
+    items: Item[];
+    tokenCount: number;
+}[]>;
+export {};