@noetic-tools/types 2.2.0 → 3.0.0

package/dist/deprecated.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Deprecated aliases from the "memory layer" era of the framework.
+ *
+ * The layer system assembles the model's *context window* — recall, budget
+ * allocation, history projection, the item-append pipeline — so it is named
+ * after context, not memory. Every name below still resolves to its
+ * replacement; nothing here changes behaviour.
+ *
+ * These are scheduled for removal in the next major of `@noetic-tools/types`.
+ */
+import type { ContextConfig, ContextData, ContextLayer, ContextLayerHooks, InferContext, InferContextShape } from './types/context-layer.js';
+import type { ContextScope, LayerCallModelRequest } from './types/context-scope.js';
+import type { LayerTraceSpan } from './types/observability.js';
+import type { ToolContextDeclaration } from './types/tool.js';
+import type { ToolContext } from './types/tool-context.js';
+/** @public @deprecated Renamed to {@link ContextLayer}. */
+export type MemoryLayer<TState = unknown> = ContextLayer<TState>;
+/** @public @deprecated Renamed to {@link ContextLayerHooks}. */
+export type MemoryHooks<TState = unknown> = ContextLayerHooks<TState>;
+/** @public @deprecated Renamed to {@link ContextConfig}. */
+export type MemoryConfig<TLayers extends readonly ContextLayer[] = readonly ContextLayer[]> = ContextConfig<TLayers>;
+/** @public @deprecated Renamed to {@link ContextData}. */
+export type ContextMemory = ContextData;
+/** @public @deprecated Renamed to {@link InferContext}. */
+export type InferMemory<T extends {
+    readonly _shape: unknown;
+}> = InferContext<T>;
+/** @public @deprecated Renamed to {@link InferContextShape}. */
+export type InferMemoryShape<T extends readonly ContextLayer[]> = InferContextShape<T>;
+/** @public @deprecated Renamed to {@link ContextScope}. */
+export type MemoryScope = ContextScope;
+/** @public @deprecated Renamed to {@link LayerCallModelRequest}. */
+export type MemoryCallModelRequest = LayerCallModelRequest;
+/** @public @deprecated Renamed to {@link LayerTraceSpan}. */
+export type MemoryTraceSpan = LayerTraceSpan;
+/** @public @deprecated Renamed to {@link ToolContext}. */
+export type ToolMemory = ToolContext;
+/** @public @deprecated Renamed to {@link ToolContextDeclaration}. */
+export type ToolMemoryDeclaration<TState = unknown> = ToolContextDeclaration<TState>;

package/dist/index.d.ts

@@ -2,6 +2,7 @@
  * @noetic-tools/types — foundational type contracts and primitives shared
  * across the Noetic framework.
  */
+export * from './deprecated.js';
 export * from './errors/noetic-config-error.js';
 export * from './errors/noetic-error.js';
 export * from './schemas/item.js';
@@ -9,15 +10,15 @@ export * from './schemas/workflow.js';
 export * from './types/channel.js';
 export * from './types/common.js';
 export * from './types/context.js';
+export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
+export * from './types/context-scope.js';
 export * from './types/detached.js';
 export * from './types/error.js';
 export * from './types/fs-adapter.js';
 export * from './types/harness-result.js';
 export * from './types/items.js';
-export * from './types/memory.js';
-export * from './types/memory-context.js';
 export * from './types/observability.js';
 export * from './types/output-codec.js';
 export * from './types/runtime.js';

package/dist/index.js

@@ -2,6 +2,7 @@
  * @noetic-tools/types — foundational type contracts and primitives shared
  * across the Noetic framework.
  */
+export * from './deprecated.js';
 export * from './errors/noetic-config-error.js';
 export * from './errors/noetic-error.js';
 export * from './schemas/item.js';
@@ -9,15 +10,15 @@ export * from './schemas/workflow.js';
 export * from './types/channel.js';
 export * from './types/common.js';
 export * from './types/context.js';
+export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
+export * from './types/context-scope.js';
 export * from './types/detached.js';
 export * from './types/error.js';
 export * from './types/fs-adapter.js';
 export * from './types/harness-result.js';
 export * from './types/items.js';
-export * from './types/memory.js';
-export * from './types/memory-context.js';
 export * from './types/observability.js';
 export * from './types/output-codec.js';
 export * from './types/runtime.js';

package/dist/schemas/item.d.ts

@@ -24,7 +24,7 @@ export declare const ItemSchema: z.ZodCustom<Item, Item>;
 type ItemSchemaCategory = keyof Required<ItemSchemaExtensions>;
 export declare function mergeExtensions(a: ItemSchemaExtensions | undefined, b: ItemSchemaExtensions | undefined): ItemSchemaExtensions;
 /**
- * @public Runtime item validator with optional tool, memory-layer, and harness extension schemas.
+ * @public Runtime item validator with optional tool, context-layer, and harness extension schemas.
  *
  * Extension schemas are pure shape validators (gate, not normalizer): on
  * match the original value is returned unchanged, including fields the schema

package/dist/schemas/item.js

@@ -97,7 +97,7 @@ function schemaMismatch(category) {
     });
 }
 /**
- * @public Runtime item validator with optional tool, memory-layer, and harness extension schemas.
+ * @public Runtime item validator with optional tool, context-layer, and harness extension schemas.
  *
  * Extension schemas are pure shape validators (gate, not normalizer): on
  * match the original value is returned unchanged, including fields the schema

package/dist/types/channel.d.ts

@@ -14,11 +14,13 @@ export interface Channel<T> {
     readonly capacity?: number;
 }
 /**
- * A channel that is writable from outside the execution tree (e.g. user input).
+ * A channel reachable from outside the execution tree: writable via
+ * `getChannelHandle` (e.g. user input) and readable via `getChannelStream`
+ * (e.g. approval requests posted to a chat platform).
  * @public
  */
 export interface ExternalChannel<T> extends Channel<T> {
-    /** Marker indicating the channel accepts writes from external callers. */
+    /** Marker indicating the channel accepts external readers and writers. */
     readonly external: true;
 }
 /** @public Handle for sending messages to a channel and checking its closed state. */

package/dist/types/{memory.d.ts → context-layer.d.ts}

@@ -1,15 +1,15 @@
 import type { ZodType } from 'zod';
 import type { LLMResponse } from './common.js';
 import type { ItemLog } from './context-parts/item-log.js';
+import type { ContextScope, ExecutionContext, ExecutionOutcome } from './context-scope.js';
 import type { Item, ItemSchemaExtensions } from './items.js';
-import type { ExecutionContext, ExecutionOutcome, MemoryScope } from './memory-context.js';
 import type { AfterModelCallParams, AfterModelCallResult, BeforeToolCallParams, BeforeToolCallResult } from './steering.js';
-/** @public Isolation scope controlling how a memory layer's state is keyed and shared. */
+/** @public Isolation scope controlling how a context layer's state is keyed and shared. */
 export type BudgetConfig = number | {
     min: number;
     max: number;
 } | 'auto';
-/** @public Per-hook timeout overrides in milliseconds for a memory layer. */
+/** @public Per-hook timeout overrides in milliseconds for a context layer. */
 export interface LayerTimeouts {
     init?: number;
     recall?: number;
@@ -23,13 +23,13 @@ export interface LayerTimeouts {
     onItemAppend?: number;
     projectHistory?: number;
 }
-/** @public A read-only data projection from layer state, accessible via `ctx.memory['layerId'].prop`. */
+/** @public A read-only data projection from layer state, accessible via `ctx.context['layerId'].prop`. */
 export interface LayerDataDecl<T = unknown, TState = unknown> {
     kind: 'data';
     /** Project a value from the layer's current state. Method syntax enables bivariant assignability. */
     read(state: TState): T;
 }
-/** @public A callable function backed by layer state, accessible via `ctx.memory['layerId'].fn()` or as an LLM tool. */
+/** @public A callable function backed by layer state, accessible via `ctx.context['layerId'].fn()` or as an LLM tool. */
 export interface LayerFunctionDecl<TInput = unknown, TOutput = unknown, TState = unknown> {
     kind: 'function';
     /** Human-readable description (used as tool description when exposed to LLM). */
@@ -44,26 +44,26 @@ export interface LayerFunctionDecl<TInput = unknown, TOutput = unknown, TState =
         state?: TState;
     }>;
 }
-/** @public Map of named data and function declarations exposed by a memory layer. */
+/** @public Map of named data and function declarations exposed by a context layer. */
 export type LayerProvides = Record<string, LayerDataDecl | LayerFunctionDecl>;
 /**
  * Mapped type that produces a flat handle from a layer's `provides` declaration.
  * Data entries become direct property reads; function entries become callable async methods.
  * @public
  */
-export type LayerHandle<T extends MemoryLayer> = T extends {
+export type LayerHandle<T extends ContextLayer> = T extends {
     provides: infer P;
 } ? {
     [K in keyof P]: P[K] extends LayerDataDecl<infer D, unknown> ? D : P[K] extends LayerFunctionDecl<infer I, infer O, unknown> ? (args: I) => Promise<O> : never;
 } : Record<string, never>;
 /** @public Object keyed by layer ID, where each value is a resolved handle for that layer's provides. */
-export type ContextMemory = Readonly<Record<string, Record<string, unknown>>>;
+export type ContextData = Readonly<Record<string, Record<string, unknown>>>;
 /**
- * Maps a tuple of memory layers to a typed object keyed by layer ID.
+ * Maps a tuple of context layers to a typed object keyed by layer ID.
  * Each layer's `provides` is flattened: data → value type, function → async callable.
  * @public
  */
-export type InferMemoryShape<T extends readonly MemoryLayer[]> = {
+export type InferContextShape<T extends readonly ContextLayer[]> = {
     [L in T[number] as L extends {
         readonly id: infer Id extends string;
     } ? Id : never]: L extends {
@@ -73,29 +73,29 @@ export type InferMemoryShape<T extends readonly MemoryLayer[]> = {
     } : Record<string, never>;
 };
 /**
- * Typed wrapper around a tuple of memory layers. Preserves individual layer types
- * for compile-time inference via `InferMemory<typeof config>`.
+ * Typed wrapper around a tuple of context layers. Preserves individual layer types
+ * for compile-time inference via `InferContext<typeof config>`.
  * @public
  */
-export interface MemoryConfig<TLayers extends readonly MemoryLayer[] = readonly MemoryLayer[]> {
+export interface ContextConfig<TLayers extends readonly ContextLayer[] = readonly ContextLayer[]> {
     readonly layers: TLayers;
-    /** Phantom field carrying the inferred memory shape. Never accessed at runtime. */
-    readonly _shape: InferMemoryShape<TLayers>;
+    /** Phantom field carrying the inferred context shape. Never accessed at runtime. */
+    readonly _shape: InferContextShape<TLayers>;
 }
 /**
- * Extract the typed memory shape from a MemoryConfig.
+ * Extract the typed context shape from a ContextConfig.
  * Constrains structurally on the phantom `_shape` field rather than on
- * `MemoryConfig` itself: `MemoryConfig` is invariant in `TLayers` (the `_shape`
+ * `ContextConfig` itself: `ContextConfig` is invariant in `TLayers` (the `_shape`
  * field carries it in an invariant position), so a concrete
- * `MemoryConfig<readonly [SomeLayer]>` does not satisfy the defaulted
- * `MemoryConfig<readonly MemoryLayer[]>`. Since `InferMemory` only reads
- * `_shape`, this constraint accepts any config the `memory()` builder produces.
- * @public Usage: `type Mem = InferMemory<typeof config>`
+ * `ContextConfig<readonly [SomeLayer]>` does not satisfy the defaulted
+ * `ContextConfig<readonly ContextLayer[]>`. Since `InferContext` only reads
+ * `_shape`, this constraint accepts any config the `context()` builder produces.
+ * @public Usage: `type Mem = InferContext<typeof config>`
  */
-export type InferMemory<T extends {
+export type InferContext<T extends {
     readonly _shape: unknown;
 }> = T['_shape'];
-/** @public Well-known ordering slots for positioning memory layers in the recall/store pipeline. */
+/** @public Well-known ordering slots for positioning context layers in the recall/store pipeline. */
 export declare const Slot: {
     readonly REMINDER: 80;
     readonly STEERING: 90;
@@ -107,7 +107,7 @@ export declare const Slot: {
     readonly RAG: 350;
     readonly SEMANTIC_RECALL: 400;
 };
-/** @public Low-level key-value persistence backend used by scoped storage and memory layers. */
+/** @public Low-level key-value persistence backend used by scoped storage and context layers. */
 export interface StorageAdapter {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T): Promise<void>;
@@ -129,7 +129,7 @@ export interface StorageAdapter {
      */
     getMany?<T>(keys: string[]): Promise<Map<string, T>>;
 }
-/** @public Scope-namespaced storage interface provided to memory layer init hooks. */
+/** @public Scope-namespaced storage interface provided to context layer init hooks. */
 export interface ScopedStorage {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T): Promise<void>;
@@ -143,17 +143,17 @@ export interface ScopedStorage {
      */
     getMany<T>(keys: string[]): Promise<Map<string, T>>;
 }
-/** @public Parameters passed to a memory layer's `init` hook. */
+/** @public Parameters passed to a context layer's `init` hook. */
 export interface InitParams {
     storage: ScopedStorage;
     scopeKey: string;
     ctx: ExecutionContext;
 }
-/** @public Value returned by a memory layer's `init` hook, carrying the initial state. */
+/** @public Value returned by a context layer's `init` hook, carrying the initial state. */
 export interface InitResult<TState> {
     state: TState;
 }
-/** @public Parameters passed to a memory layer's `recall` hook before each LLM call. */
+/** @public Parameters passed to a context layer's `recall` hook before each LLM call. */
 export interface RecallParams<TState> {
     log: ItemLog;
     query: string;
@@ -161,13 +161,13 @@ export interface RecallParams<TState> {
     state: TState;
     budget: number;
 }
-/** @public Value returned by a memory layer's `recall` hook, containing items and token count. */
+/** @public Value returned by a context layer's `recall` hook, containing items and token count. */
 export interface RecallResult<TState = unknown> {
     items: Item[];
     tokenCount: number;
     state?: TState;
 }
-/** @public Parameters passed to a memory layer's `store` hook after each LLM response. */
+/** @public Parameters passed to a context layer's `store` hook after each LLM response. */
 export interface StoreParams<TState> {
     newItems: Item[];
     log: ItemLog;
@@ -175,21 +175,21 @@ export interface StoreParams<TState> {
     ctx: ExecutionContext;
     state: TState;
 }
-/** @public Value returned by a memory layer's `store` hook, carrying the updated state. */
+/** @public Value returned by a context layer's `store` hook, carrying the updated state. */
 export interface StoreResult<TState> {
     state: TState;
 }
-/** @public Parameters passed to a memory layer's `onSpawn` hook when a child execution starts. */
+/** @public Parameters passed to a context layer's `onSpawn` hook when a child execution starts. */
 export interface SpawnParams<TState> {
     parentState: TState;
     childCtx: ExecutionContext;
 }
-/** @public Value returned by a memory layer's `onSpawn` hook with the child's initial state. */
+/** @public Value returned by a context layer's `onSpawn` hook with the child's initial state. */
 export interface SpawnResult<TState> {
     childState: TState | null;
     items?: Item[];
 }
-/** @public Parameters passed to a memory layer's `onReturn` hook when a child execution completes. */
+/** @public Parameters passed to a context layer's `onReturn` hook when a child execution completes. */
 export interface ReturnParams<TState> {
     childState: TState;
     childLog: ItemLog;
@@ -203,23 +203,23 @@ export interface ReturnParams<TState> {
      */
     childCtx: ExecutionContext;
 }
-/** @public Value returned by a memory layer's `onReturn` hook with the merged parent state. */
+/** @public Value returned by a context layer's `onReturn` hook with the merged parent state. */
 export interface ReturnResult<TState> {
     parentState: TState;
     result?: unknown;
 }
-/** @public Parameters passed to a memory layer's `onComplete` hook at execution end. */
+/** @public Parameters passed to a context layer's `onComplete` hook at execution end. */
 export interface CompleteParams<TState> {
     log: ItemLog;
     ctx: ExecutionContext;
     state: TState;
     outcome: ExecutionOutcome;
 }
-/** @public Parameters passed to a memory layer's `dispose` hook during teardown. */
+/** @public Parameters passed to a context layer's `dispose` hook during teardown. */
 export interface DisposeParams<TState> {
     state: TState;
 }
-/** @public Parameters passed to a memory layer's `projectHistory` hook to project the history portion of the LLM context window. */
+/** @public Parameters passed to a context layer's `projectHistory` hook to project the history portion of the LLM context window. */
 export interface ProjectHistoryParams<TState> {
     /** Full historical items from the item log, uncapped. */
     items: ReadonlyArray<Item>;
@@ -228,14 +228,14 @@ export interface ProjectHistoryParams<TState> {
     /** Layer's current state snapshot. */
     state: TState;
 }
-/** @public Value returned by a memory layer's `projectHistory` hook, carrying the projected items. */
+/** @public Value returned by a context layer's `projectHistory` hook, carrying the projected items. */
 export interface ProjectHistoryResult {
     /** Items to send to the LLM as history. Typically a subset of the input. */
     items: ReadonlyArray<Item>;
 }
 /** @public Controls which layers re-run recall() when a re-render is triggered. */
 export type RerenderScope = 'self' | 'slot-after' | 'all';
-/** @public Parameters passed to a memory layer's `onItemAppend` hook when input items are about to be appended. */
+/** @public Parameters passed to a context layer's `onItemAppend` hook when input items are about to be appended. */
 export interface OnItemAppendParams<TState> {
     /** Items to be appended (may have been transformed by prior layers in the pipeline). */
     items: Item[];
@@ -246,7 +246,7 @@ export interface OnItemAppendParams<TState> {
     /** Layer's current state snapshot. */
     state: TState;
 }
-/** @public Value returned by a memory layer's `onItemAppend` hook. */
+/** @public Value returned by a context layer's `onItemAppend` hook. */
 export interface OnItemAppendResult<TState> {
     /**
      * Items to actually append to the log.
@@ -265,8 +265,8 @@ export interface OnItemAppendResult<TState> {
     /** Which layers to re-recall (default: 'slot-after'). */
     scope?: RerenderScope;
 }
-/** @public Lifecycle hook implementations for a memory layer. Method syntax enables bivariant assignability for typed layers. */
-export interface MemoryHooks<TState = unknown> {
+/** @public Lifecycle hook implementations for a context layer. Method syntax enables bivariant assignability for typed layers. */
+export interface ContextLayerHooks<TState = unknown> {
     init?(params: InitParams): Promise<InitResult<TState>>;
     recall?(params: RecallParams<TState>): Promise<RecallResult<TState> | string | null>;
     store?(params: StoreParams<TState>): Promise<StoreResult<TState> | undefined>;
@@ -299,10 +299,10 @@ export interface MemoryHooks<TState = unknown> {
     projectHistory?(params: ProjectHistoryParams<TState>): Promise<ProjectHistoryResult>;
 }
 /**
- * A composable memory layer that participates in the recall/store lifecycle.
+ * A composable context layer that participates in the recall/store lifecycle.
  * @public
  */
-export interface MemoryLayer<TState = unknown> {
+export interface ContextLayer<TState = unknown> {
     /** Unique identifier for this layer instance. */
     id: string;
     /** Human-readable name for debugging and trace output. */
@@ -310,16 +310,16 @@ export interface MemoryLayer<TState = unknown> {
     /** Ordering slot (lower = recalled first). Use `Slot` constants for well-known positions. */
     slot: number;
     /** Scope controlling state isolation: `'thread'`, `'resource'`, `'global'`, or `'execution'`. */
-    scope: MemoryScope;
+    scope: ContextScope;
     /** Token budget: a fixed number, a `{ min, max }` range, or `'auto'` for dynamic allocation. */
     budget?: BudgetConfig;
     /** Lifecycle hooks invoked by the runtime at each phase (init, recall, store, etc.). */
-    hooks: MemoryHooks<TState>;
+    hooks: ContextLayerHooks<TState>;
     /** Per-hook timeout overrides in ms. */
     timeouts?: Partial<LayerTimeouts>;
     /**
      * What to do when this layer's `init` hook throws.
-     * - `'throw'` (default): surface the error and abort the execution — memory is
+     * - `'throw'` (default): surface the error and abort the execution — context is
      *   load-bearing, and silent disabling hides failures (and, for the steering
      *   layer, would fail *open*).
      * - `'disable'`: log a diagnostic and run the execution without this layer
@@ -337,9 +337,9 @@ export interface MemoryLayer<TState = unknown> {
      * ignoring this field.
      */
     recallMode?: 'atomic' | 'eventual';
-    /** Typed functions and data exposed to code steps via `ctx.memory['layerId']` and automatically as LLM tools. */
+    /** Typed functions and data exposed to code steps via `ctx.context['layerId']` and automatically as LLM tools. */
     provides?: LayerProvides;
-    /** Optional item schemas contributed by this layer, primarily for developer-role memory items. */
+    /** Optional item schemas contributed by this layer, primarily for developer-role context items. */
     itemSchemas?: Pick<ItemSchemaExtensions, 'developerMessages' | 'items'>;
     /** Default re-render timing when `onItemAppend` requests a re-render. */
     rerenderTiming?: 'immediate' | 'batched';

package/dist/types/{memory.js → context-layer.js}

@@ -1,5 +1,5 @@
 //#endregion
-/** @public Well-known ordering slots for positioning memory layers in the recall/store pipeline. */
+/** @public Well-known ordering slots for positioning context layers in the recall/store pipeline. */
 export const Slot = {
     REMINDER: 80,
     STEERING: 90,

package/dist/types/{memory-context.d.ts → context-scope.d.ts}

@@ -2,17 +2,17 @@ import type { LLMResponse } from './common.js';
 import type { FsAdapter } from './fs-adapter.js';
 import type { Item } from './items.js';
 import type { ShellAdapter } from './shell-adapter.js';
-/** @public Isolation scope controlling how a memory layer's state is keyed and shared. */
-export type MemoryScope = 'thread' | 'resource' | 'global' | 'execution';
-/** @public Terminal outcome of an execution run, reported to memory layers on completion. */
+/** @public Isolation scope controlling how a context layer's state is keyed and shared. */
+export type ContextScope = 'thread' | 'resource' | 'global' | 'execution';
+/** @public Terminal outcome of an execution run, reported to context layers on completion. */
 export type ExecutionOutcome = 'success' | 'failure' | 'aborted';
-/** @public Minimal model-call surface exposed to memory-layer hooks. */
-export interface MemoryCallModelRequest {
+/** @public Minimal model-call surface exposed to context-layer hooks. */
+export interface LayerCallModelRequest {
     model: string;
     items: ReadonlyArray<Item>;
     instructions?: string;
 }
-/** @public Runtime metadata available to memory layer hooks during each lifecycle phase. */
+/** @public Runtime metadata available to context layer hooks during each lifecycle phase. */
 export interface ExecutionContext {
     executionId: string;
     threadId: string;
@@ -28,12 +28,12 @@ export interface ExecutionContext {
     fs: FsAdapter;
     /** Shell adapter for virtual or real shell command execution. */
     shell: ShellAdapter;
-    callModel?: (request: MemoryCallModelRequest) => Promise<LLMResponse>;
+    callModel?: (request: LayerCallModelRequest) => Promise<LLMResponse>;
     tokenize(text: string): number;
     trace: {
         setAttribute(key: string, value: string | number | boolean): void;
         addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
     };
-    /** Snapshot a sibling memory layer's state by its `layer.id`. */
+    /** Snapshot a sibling context layer's state by its `layer.id`. */
     readLayerState<T>(layerId: string): T | undefined;
 }

package/dist/types/context-scope.js

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