@noetic-tools/types 0.2.0 → 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

@@ -135,7 +135,13 @@ export interface ContextHarness {
     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>;
@@ -193,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/runtime.d.ts

@@ -195,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>;

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

@@ -2,7 +2,11 @@ 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 {

package/dist/util/message-helpers.js

@@ -28,7 +28,7 @@ export function isTextPart(part) {
 /** Extracts assistant/output text from items for memory buffering (one string per message). */
 export function collectOutputText(items) {
     return items
-        .filter((i) => i.type === 'message')
+        .filter(isAssistantMessage)
         .map((i) => i.content
         .filter(isOutputText)
         .map((c) => c.text)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "0.2.0",
+  "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",