@noetic-tools/types 0.1.1 → 1.0.0

package/README.md

@@ -14,6 +14,10 @@ both of which re-export the parts relevant to their public surface. Application
 code normally imports these types from `@noetic-tools/core` rather than from
 this package directly.
 
+The `MemoryLayer` contract is additionally exported at the
+`@noetic-tools/types/contract` subpath for memory-layer authors who want the
+contract without the rest of the vocabulary.
+
 ## License
 
 Apache-2.0

package/dist/errors/noetic-error.d.ts

@@ -11,8 +11,16 @@ export declare class NoeticErrorImpl extends Error {
 /**
  * Type guard for `NoeticErrorImpl`.
  *
+ * Uses an `instanceof` fast path, then falls back to a structural check
+ * (`Error` carrying a `noeticError.kind: string`). The fallback keeps the
+ * guard reliable when multiple copies of `@noetic-tools/types` are loaded
+ * (e.g. mixed `src`/`dist` resolution or duplicated node_modules), where
+ * `instanceof` fails across realms. The inner `kind` is deliberately not
+ * validated against the closed `NoeticError` union so errors minted by a
+ * newer copy of the package still pass (forward compatibility).
+ *
  * @public
  * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticErrorImpl`.
+ * @returns `true` if `e` is a `NoeticErrorImpl` (or structurally equivalent).
  */
 export declare function isNoeticError(e: unknown): e is NoeticErrorImpl;

package/dist/errors/noetic-error.js

@@ -14,12 +14,30 @@ export class NoeticErrorImpl extends Error {
 /**
  * Type guard for `NoeticErrorImpl`.
  *
+ * Uses an `instanceof` fast path, then falls back to a structural check
+ * (`Error` carrying a `noeticError.kind: string`). The fallback keeps the
+ * guard reliable when multiple copies of `@noetic-tools/types` are loaded
+ * (e.g. mixed `src`/`dist` resolution or duplicated node_modules), where
+ * `instanceof` fails across realms. The inner `kind` is deliberately not
+ * validated against the closed `NoeticError` union so errors minted by a
+ * newer copy of the package still pass (forward compatibility).
+ *
  * @public
  * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticErrorImpl`.
+ * @returns `true` if `e` is a `NoeticErrorImpl` (or structurally equivalent).
  */
 export function isNoeticError(e) {
-    return e instanceof NoeticErrorImpl;
+    if (e instanceof NoeticErrorImpl) {
+        return true;
+    }
+    if (!(e instanceof Error)) {
+        return false;
+    }
+    if (!('noeticError' in e)) {
+        return false;
+    }
+    const inner = e.noeticError;
+    return (typeof inner === 'object' && inner !== null && 'kind' in inner && typeof inner.kind === 'string');
 }
 function formatMessage(error) {
     switch (error.kind) {
@@ -43,6 +61,10 @@ function formatMessage(error) {
             return `Budget exceeded: ${error.field} limit ${error.limit}, actual ${error.actual}`;
         case 'steering_denied':
             return `Steering denied${error.guidance ? `: ${error.guidance}` : ''}`;
+        case 'item_schema_mismatch':
+            return error.itemType
+                ? `Item type '${error.itemType}' did not match any registered item extension schema.`
+                : `Item did not match any registered ${error.category} extension schema.`;
         case 'handle_evicted':
             return `Subprocess handle '${error.handleId}' evicted (step '${error.stepId}'): adapter returned null for ${error.gracePeriodMs}ms`;
         default: {

package/dist/schemas/item.d.ts

@@ -11,6 +11,11 @@
  * Use this at trust boundaries (loading persisted session files, accepting
  * externally-supplied transcripts) where we need to reject garbage JSON but
  * don't need to re-validate every provider field TypeScript already types.
+ *
+ * Extension schemas registered on the registry are **gates, not
+ * normalizers**: they validate item shape and the ORIGINAL value is returned
+ * on match. Zod transforms, defaults, and key-stripping in extension schemas
+ * are unsupported — their output is discarded. Declare pure shape validators.
  */
 import { z } from 'zod';
 import type { Item, ItemSchemaExtensions } from '../types/items.js';
@@ -18,7 +23,14 @@ import type { Item, ItemSchemaExtensions } from '../types/items.js';
 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, memory-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
+ * does not declare. Transforms and defaults in extension schemas are
+ * unsupported — their parsed output is never used.
+ */
 export declare class ItemSchemaRegistry {
     readonly extensions: ItemSchemaExtensions;
     readonly strictUnknownExtensions: boolean;
@@ -28,6 +40,13 @@ export declare class ItemSchemaRegistry {
     extend(extensions?: ItemSchemaExtensions): ItemSchemaRegistry;
     parse(value: unknown): Item;
     parseMany(values: Iterable<unknown>): Item[];
+    /**
+     * Validate `value` against the schemas registered for `category` only.
+     *
+     * When no schemas are registered for the category, falls back to
+     * `parse()`. Throws a `NoeticErrorImpl` with kind `item_schema_mismatch`
+     * when schemas exist for the category and none match.
+     */
     parseWithCategory(value: unknown, category: ItemSchemaCategory): Item;
 }
 /** @public Default item schema registry. */

package/dist/schemas/item.js

@@ -11,8 +11,14 @@
  * Use this at trust boundaries (loading persisted session files, accepting
  * externally-supplied transcripts) where we need to reject garbage JSON but
  * don't need to re-validate every provider field TypeScript already types.
+ *
+ * Extension schemas registered on the registry are **gates, not
+ * normalizers**: they validate item shape and the ORIGINAL value is returned
+ * on match. Zod transforms, defaults, and key-stripping in extension schemas
+ * are unsupported — their output is discarded. Declare pure shape validators.
  */
 import { z } from 'zod';
+import { NoeticErrorImpl } from '../errors/noetic-error.js';
 function isItemLike(value) {
     if (typeof value !== 'object' || value === null) {
         return false;
@@ -85,15 +91,19 @@ function isKnownBaseType(type) {
         type.startsWith('openrouter:'));
 }
 function schemaMismatch(category) {
-    return new z.ZodError([
-        {
-            code: 'custom',
-            message: `Item did not match any registered ${category} extension schema.`,
-            path: [],
-        },
-    ]);
+    return new NoeticErrorImpl({
+        kind: 'item_schema_mismatch',
+        category,
+    });
 }
-/** @public Runtime item validator with optional tool, memory-layer, and harness extension schemas. */
+/**
+ * @public Runtime item validator with optional tool, memory-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
+ * does not declare. Transforms and defaults in extension schemas are
+ * unsupported — their parsed output is never used.
+ */
 export class ItemSchemaRegistry {
     extensions;
     strictUnknownExtensions;
@@ -116,25 +126,30 @@ export class ItemSchemaRegistry {
         for (const schema of schemas) {
             const parsed = schema.safeParse(value);
             if (parsed.success) {
-                return ItemSchema.parse(parsed.data);
+                // Gate, not normalizer: return the original value, not the
+                // zod-stripped clone, so undeclared fields survive validation.
+                return base;
             }
         }
         if (this.strictUnknownExtensions && !isKnownBaseType(base.type)) {
-            throw new z.ZodError([
-                {
-                    code: 'custom',
-                    message: `Item type '${base.type}' did not match any registered item extension schema.`,
-                    path: [
-                        'type',
-                    ],
-                },
-            ]);
+            throw new NoeticErrorImpl({
+                kind: 'item_schema_mismatch',
+                category: 'items',
+                itemType: base.type,
+            });
         }
         return base;
     }
     parseMany(values) {
         return Array.from(values, (value) => this.parse(value));
     }
+    /**
+     * Validate `value` against the schemas registered for `category` only.
+     *
+     * When no schemas are registered for the category, falls back to
+     * `parse()`. Throws a `NoeticErrorImpl` with kind `item_schema_mismatch`
+     * when schemas exist for the category and none match.
+     */
     parseWithCategory(value, category) {
         const schemas = schemasForCategory(this.extensions, category);
         if (schemas.length === 0) {
@@ -143,7 +158,8 @@ export class ItemSchemaRegistry {
         for (const schema of schemas) {
             const parsed = schema.safeParse(value);
             if (parsed.success) {
-                return ItemSchema.parse(parsed.data);
+                // Gate, not normalizer: validate shape, return the original value.
+                return ItemSchema.parse(value);
             }
         }
         throw schemaMismatch(category);

package/dist/types/channel.d.ts

@@ -23,6 +23,12 @@ export interface ExternalChannel<T> extends Channel<T> {
 }
 /** @public Handle for sending messages to a channel and checking its closed state. */
 export interface ChannelHandle<T> {
+    /**
+     * External-sender write: synchronous and never back-pressured. When a
+     * queue channel is at capacity the OLDEST item is dropped (with a warning)
+     * so external callers (HTTP handlers, CLI prompts) never block. Internal
+     * senders (`ctx.send`) get async back-pressure instead.
+     */
     send(value: T): void;
     readonly closed: boolean;
     readonly channel: Channel<T>;

package/dist/types/context.d.ts

@@ -8,7 +8,7 @@ import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
 import type { ExecuteInput } from './items.js';
-import type { ContextMemory, MemoryLayer, StorageAdapter } from './memory.js';
+import type { ContextMemory, MemoryLayer, ProjectionPolicy, StorageAdapter } from './memory.js';
 import type { Span } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
 import type { SteeringDecision } from './steering.js';
@@ -98,6 +98,8 @@ export interface ContextHarness {
     readonly config: {
         readonly name: string;
         readonly params: Record<string, unknown>;
+        /** Harness-wide default projection policy; a step's `projection` overrides it. */
+        readonly projection?: ProjectionPolicy;
     };
     readonly fs: FsAdapter;
     readonly shell: ShellAdapter;
@@ -128,10 +130,18 @@ export interface ContextHarness {
     afterModelCall(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
     runAppendPipeline(layers: MemoryLayer[], items: import('./items.js').Item[], ctx: Context): Promise<ContextAppendPipelineResult>;
     recallLayers(layers: MemoryLayer[], input: string, ctx: Context): Promise<ContextRecallLayerOutput[]>;
+    recallLayersAtomic(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
+    recallLayersEventual(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
     projectHistory(layers: MemoryLayer[], items: ReadonlyArray<import('./items.js').Item>, ctx: Context): Promise<ReadonlyArray<import('./items.js').Item>>;
     storeLayers(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<void>;
     previewRequestItems(scope?: unknown): Promise<ReadonlyArray<import('./items.js').Item>>;
-    send<T>(channel: Channel<T>, value: T, ctx: Context): void;
+    /**
+     * Internal-sender channel write. Resolves immediately unless the target
+     * queue channel is at capacity, in which case the send parks until a
+     * consumer frees a slot (back-pressure; default 30s timeout →
+     * `channel_timeout`, abort → `cancelled`).
+     */
+    send<T>(channel: Channel<T>, value: T, ctx: Context): Promise<void>;
     recv<T>(channel: Channel<T>, ctx: Context, opts?: {
         timeout?: number;
     }): Promise<T>;
@@ -189,7 +199,14 @@ export interface Context<TMemory = ContextMemory, TState = unknown> {
     recv<T>(channel: Channel<T>, opts?: {
         timeout?: number;
     }): Promise<T>;
-    send<T>(channel: Channel<T>, value: T): void;
+    /**
+     * Send a value into a channel. Resolves immediately for value/topic
+     * channels and for queue channels below capacity. When a queue channel is
+     * at capacity the returned promise parks until a consumer dequeues an item
+     * (back-pressure): after the default 30s timeout it rejects with
+     * `channel_timeout`, and aborting the context rejects it with `cancelled`.
+     */
+    send<T>(channel: Channel<T>, value: T): Promise<void>;
     tryRecv<T>(channel: Channel<T>): T | null;
     checkpoint(): Promise<void>;
     complete<T>(value: T): void;

package/dist/types/error.d.ts

@@ -40,6 +40,18 @@ export type NoeticError = {
 } | {
     kind: 'cancelled';
     reason?: string;
+} | {
+    /**
+     * Raised by `ItemSchemaRegistry` when an item fails extension-schema
+     * validation: either a category item (e.g. a tool result) matches none
+     * of the schemas registered for its category, or — under
+     * `strictUnknownExtensions` — an unknown item type matches no
+     * registered extension schema. `itemType` is set for the
+     * unknown-item-type case.
+     */
+    kind: 'item_schema_mismatch';
+    category: 'items' | 'developerMessages' | 'toolCalls' | 'toolResults';
+    itemType?: string;
 } | {
     kind: 'budget_exceeded';
     field: 'cost' | 'steps' | 'duration';

package/dist/types/memory.d.ts

@@ -288,6 +288,26 @@ export interface MemoryLayer<TState = unknown> {
     hooks: MemoryHooks<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
+     *   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
+     *   (its `recall`/`store`/etc. are skipped). Opt in only for non-critical layers.
+     */
+    onInitError?: 'throw' | 'disable';
+    /**
+     * Recall mode controlling whether this layer's `recall()` blocks the model call.
+     * - `'atomic'` (default): recall runs synchronously in the hot path; the
+     *   harness waits for it before assembling the view.
+     * - `'eventual'`: recall is served from cache and never blocks; the cache
+     *   refreshes after `store()` produces new state, so the next turn sees it.
+     *
+     * A harness configured with `forceAtomicRecall` treats every layer as atomic,
+     * ignoring this field.
+     */
+    recallMode?: 'atomic' | 'eventual';
     /** Typed functions and data exposed to code steps via `ctx.memory['layerId']` and automatically as LLM tools. */
     provides?: LayerProvides;
     /** Optional item schemas contributed by this layer, primarily for developer-role memory items. */

package/dist/types/runtime.d.ts

@@ -6,7 +6,7 @@ import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
 import type { ExecuteInput, Item, ItemSchemaExtensions } from './items.js';
-import type { ContextMemory, MemoryLayer, StorageAdapter } from './memory.js';
+import type { ContextMemory, MemoryLayer, ProjectionPolicy, StorageAdapter } from './memory.js';
 import type { Span } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
 import type { SteeringDecision } from './steering.js';
@@ -28,6 +28,10 @@ export interface AgentConfig<TParams extends Record<string, unknown> = Record<st
     itemSchemas?: ItemSchemaExtensions;
     /** Whether unknown extension item types must match a registered schema. Defaults to true. */
     strictItemSchemas?: boolean;
+    /** Default projection policy for all LLM steps. Individual steps override via `step.projection`. */
+    projection?: ProjectionPolicy;
+    /** When true, every layer is recalled atomically regardless of its `recallMode` (no eventual/cached recall). */
+    forceAtomicRecall?: boolean;
 }
 /** @public How a message submitted during an active turn is delivered to the model.
  *
@@ -191,7 +195,13 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     readonly rootCwdState: CwdState;
     /** Update the harness root cwd. Used by the TUI when the user issues a `! cd`. */
     setRootCwd(nextCwd: string): void;
-    send<T>(channel: Channel<T>, value: T, ctx: Context): void;
+    /**
+     * Internal-sender channel write (back-pressured): resolves immediately
+     * unless the queue channel is at capacity, in which case it parks until a
+     * consumer frees a slot (30s default timeout → `channel_timeout`; context
+     * abort → `cancelled`).
+     */
+    send<T>(channel: Channel<T>, value: T, ctx: Context): Promise<void>;
     recv<T>(channel: Channel<T>, ctx: Context, opts?: {
         timeout?: number;
     }): Promise<T>;
@@ -199,6 +209,10 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
     initLayers(layers: MemoryLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
     recallLayers(layers: MemoryLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
+    /** Recall only atomic layers (or all layers when the harness forces atomic recall). Blocks until complete. */
+    recallLayersAtomic(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
+    /** Recall eventual layers from cache (non-blocking); returns nothing when the harness forces atomic recall. */
+    recallLayersEventual(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
     /**
      * Compute the items that would be sent to the model on the next turn for a
      * session — its accumulated history plus the harness's memory-layer recall

package/dist/types/step.d.ts

@@ -3,7 +3,7 @@ import type { Channel } from './channel.js';
 import type { ModelParams, RetryPolicy, StepMeta } from './common.js';
 import type { Context } from './context.js';
 import type { NoeticError } from './error.js';
-import type { ContextMemory, MemoryConfig, MemoryLayer } from './memory.js';
+import type { ContextMemory, MemoryConfig, MemoryLayer, ProjectionPolicy } from './memory.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
 import type { Tool } from './tool.js';
 /**
@@ -99,6 +99,8 @@ export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
     params?: ModelParams;
     /** Controls framework event emission for this step. Defaults to `true`. Set `false` to suppress all framework events. A filter function receives `(eventType, data)` and returns `boolean`. */
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+    /** Projection policy for this step's context window. Overrides the harness-level default. */
+    projection?: ProjectionPolicy;
 }
 /** @public A step that invokes a single tool directly, bypassing the LLM. */
 export interface StepTool<_TMemory = ContextMemory, I = unknown, O = unknown> {

package/dist/util/message-helpers.d.ts

@@ -2,13 +2,33 @@ import type { LLMResponse } from '../types/common.js';
 import type { Context } from '../types/context.js';
 import type { InputMessageItem, Item, MessageItem } from '../types/items.js';
 export declare function isAssistantMessage(item: unknown): item is MessageItem;
-export declare function isUserMessage(item: unknown): item is MessageItem;
+/** @public Input message item narrowed to the `user` role. */
+export type UserMessageItem = InputMessageItem & {
+    readonly role: 'user';
+};
+export declare function isUserMessage(item: unknown): item is UserMessageItem;
 export declare function isOutputText(part: {
     type: string;
 }): part is {
     type: 'output_text';
     text: string;
 };
+/** True for any content part carrying a string `text` field (input_text, output_text, …). */
+export declare function isTextPart(part: {
+    type: string;
+}): part is {
+    type: string;
+    text: string;
+};
+/** Extracts assistant/output text from items for memory buffering (one string per message). */
+export declare function collectOutputText(items: ReadonlyArray<Item>): string[];
+/**
+ * Extracts text from INPUT items for memory buffering: concatenates the text
+ * content parts of message items (user `input_text` and any text parts) and
+ * appends the `output` of `function_call_output` (tool result) items. Empty
+ * strings are dropped.
+ */
+export declare function collectInputText(items: ReadonlyArray<Item>): string[];
 export declare function createMessage(text: string, role: 'user' | 'developer'): InputMessageItem;
 export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
 /** Naive token estimate: ~4 chars per token */

package/dist/util/message-helpers.js

@@ -21,6 +21,47 @@ export function isUserMessage(item) {
 export function isOutputText(part) {
     return part.type === 'output_text';
 }
+/** True for any content part carrying a string `text` field (input_text, output_text, …). */
+export function isTextPart(part) {
+    return 'text' in part && typeof part.text === 'string';
+}
+/** Extracts assistant/output text from items for memory buffering (one string per message). */
+export function collectOutputText(items) {
+    return items
+        .filter(isAssistantMessage)
+        .map((i) => i.content
+        .filter(isOutputText)
+        .map((c) => c.text)
+        .join(''))
+        .filter((t) => t.length > 0);
+}
+/**
+ * Extracts text from INPUT items for memory buffering: concatenates the text
+ * content parts of message items (user `input_text` and any text parts) and
+ * appends the `output` of `function_call_output` (tool result) items. Empty
+ * strings are dropped.
+ */
+export function collectInputText(items) {
+    const texts = [];
+    for (const item of items) {
+        if (item.type === 'message') {
+            let text = '';
+            for (const part of item.content) {
+                if (isTextPart(part)) {
+                    text += part.text;
+                }
+            }
+            if (text.length > 0) {
+                texts.push(text);
+            }
+            continue;
+        }
+        if (item.type === 'function_call_output' && item.output.length > 0) {
+            texts.push(item.output);
+        }
+    }
+    return texts;
+}
 export function createMessage(text, role) {
     return {
         id: crypto.randomUUID(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",
@@ -60,7 +60,7 @@
   "scripts": {
     "build": "bunx tsc -p tsconfig.build.json && bun scripts/add-js-extensions.ts",
     "verify:esm": "bun scripts/verify-node-esm.ts",
-    "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm",
+    "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm && bun scripts/strip-dev-conditions.ts",
     "test": "bun test",
     "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov",
     "test:ci": "bun test --coverage --coverage-reporter=lcov",