@noetic-tools/core 5.7.0 → 5.8.0

package/dist/interpreter/child-span.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Spans for child contexts (`spawn` children and `inParallel` paths). A child
+ * context carries its own span, so events its steps add to `ctx.span` (e.g.
+ * `loop.verdict`) and the model/tool spans they open nest under the child
+ * rather than being lost to a no-op span.
+ */
+import type { Context, Span } from '@noetic-tools/types';
+/** Opens a span named `name` under `parent.span`, stamped with the owning step id. */
+export declare function openChildSpan(parent: Context, name: string, stepId: string): Span;
+/**
+ * Runs `run` inside `span`, then ends the span and exports it, whether `run`
+ * returns or throws. A failure stamps `noetic.error.kind`; any failure but
+ * cancellation also stamps `error: true`.
+ */
+export declare function traceChild<T>(parent: Context, span: Span, run: () => Promise<T>): Promise<T>;
+/** Ends a span whose child never ran: it was cancelled before it started. */
+export declare function closeUnstartedSpan(parent: Context, span: Span): Promise<void>;

package/dist/interpreter/child-span.js

@@ -0,0 +1,51 @@
+/**
+ * Spans for child contexts (`spawn` children and `inParallel` paths). A child
+ * context carries its own span, so events its steps add to `ctx.span` (e.g.
+ * `loop.verdict`) and the model/tool spans they open nest under the child
+ * rather than being lost to a no-op span.
+ */
+import { isNoeticError } from '@noetic-tools/types';
+import { NoeticAttr } from '../observability/genai-attributes.js';
+/** Opens a span named `name` under `parent.span`, stamped with the owning step id. */
+export function openChildSpan(parent, name, stepId) {
+    const span = parent.harness.createSpan(name, parent.span);
+    span.setAttribute(NoeticAttr.NODE_ID, stepId);
+    return span;
+}
+/**
+ * Runs `run` inside `span`, then ends the span and exports it, whether `run`
+ * returns or throws. A failure stamps `noetic.error.kind`; any failure but
+ * cancellation also stamps `error: true`.
+ */
+export async function traceChild(parent, span, run) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        markFailed(span, e);
+        throw e;
+    }
+    finally {
+        await closeChildSpan(parent, span);
+    }
+}
+/** Ends a span whose child never ran: it was cancelled before it started. */
+export async function closeUnstartedSpan(parent, span) {
+    span.setAttribute(NoeticAttr.ERROR_KIND, 'cancelled');
+    await closeChildSpan(parent, span);
+}
+function markFailed(span, error) {
+    const kind = isNoeticError(error) ? error.noeticError.kind : undefined;
+    if (kind !== undefined) {
+        span.setAttribute(NoeticAttr.ERROR_KIND, kind);
+    }
+    if (kind !== 'cancelled') {
+        span.setAttribute('error', true);
+    }
+}
+async function closeChildSpan(parent, span) {
+    span.end();
+    await parent.harness.traceExporter.export([
+        span,
+    ]);
+}

package/dist/interpreter/execute-action.js

@@ -5,6 +5,7 @@ import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isN
 import { emitToolUi } from '../runtime/tool-ui.js';
 import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, lineageKey, noteCacheOutcome, resolveCacheConfig, resolveLayerTools, returnLayers, shouldEmit, snapshotCwdState, spawnLayers, } from './action-deps.js';
 import { isServerToolSpec, SteeringAction } from './action-types.js';
+import { openChildSpan, traceChild } from './child-span.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { collectAllTools, deduplicateTools } from './collect-tools.js';
 import { prepareBandedView, stampAnchoringAttributes } from './context-assembly.js';
@@ -433,6 +434,7 @@ function recordTurnOutcome(params) {
         toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
         usage: response.usage,
         cost: response.cost,
+        serviceTier: response.serviceTier,
         responseItems: response.items,
     };
     if (isMutableContext(ctx)) {
@@ -705,9 +707,11 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
     // `id: childId` keeps the ContextImpl's id in sync with the executionId
     // used by spawnLayers/returnLayers in the layer-state store, so writes via
     // `ctx.context[layerId]` and spawn-boundary hooks read from the same key.
+    const span = openChildSpan(baseCtx, 'spawn', step.id);
     const childCtx = new ContextImpl({
         harness: baseCtx.harness,
         parent: baseCtx,
+        span,
         items: childItems,
         state: cloneWithGuard(baseCtx.state, `Spawn '${step.id}'`),
         threadId: baseCtx.threadId,
@@ -723,23 +727,24 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
         ledger: baseCtx instanceof ContextImpl ? baseCtx.ledger : undefined,
     });
     try {
-        // Execute the child step. Its token/cost usage needs no merge here: every
-        // charge recorded on `childCtx` is also charged up its `usageParent`
-        // chain as it is spent, so a child that throws still bills the parent.
-        const childOutput = await executeStep(step.child, input, frameworkCast(childCtx));
-        // Pipeline result through layer onReturn hooks
-        if (!hasLayers || !parentExecutionCtx) {
-            return childOutput;
-        }
-        const pipelinedResult = await returnLayers({
-            layers,
-            parentCtx: parentExecutionCtx,
-            childCtx: childExecutionCtx,
-            childLog: childCtx.itemLog,
-            result: childOutput,
-            store: layerStore,
+        return await traceChild(baseCtx, span, async () => {
+            // Execute the child step. Its token/cost usage needs no merge here: every
+            // charge recorded on `childCtx` is also charged up its `usageParent`
+            // chain as it is spent, so a child that throws still bills the parent.
+            const childOutput = await executeStep(step.child, input, frameworkCast(childCtx));
+            // Pipeline result through layer onReturn hooks
+            if (!hasLayers || !parentExecutionCtx) {
+                return childOutput;
+            }
+            return returnLayers({
+                layers,
+                parentCtx: parentExecutionCtx,
+                childCtx: childExecutionCtx,
+                childLog: childCtx.itemLog,
+                result: childOutput,
+                store: layerStore,
+            });
         });
-        return pipelinedResult;
     }
     finally {
         // Clean up child execution state to prevent memory leaks — runs on success and error

package/dist/interpreter/execute-control.js

@@ -2,9 +2,11 @@
  * Control-flow step handlers: conditional, inParallel, loop, schedule.
  */
 import { createMessage, frameworkCast, isNoeticError, NoeticErrorImpl } from '@noetic-tools/types';
+import { NoeticAttr, NoeticEvent } from '../observability/genai-attributes.js';
 import { ContextImpl } from '../runtime/context-impl.js';
 import { snapshotCwdState } from '../runtime/cwd-helpers.js';
 import { contextToExecCtx, returnLayers, spawnLayers } from './action-deps.js';
+import { closeUnstartedSpan, openChildSpan, traceChild } from './child-span.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { getContextChannelStore, isContextImpl, isMutableContext } from './typeguards.js';
 //#region conditional
@@ -19,17 +21,20 @@ export async function executeConditional(step, input, ctx, executeStep) {
 }
 //#endregion
 //#region inParallel
-function createChildContexts(ctx, count, stepId) {
+function createChildContexts(ctx, paths, stepId) {
     const threadId = isContextImpl(ctx) ? ctx.threadId : crypto.randomUUID();
     const resourceId = isContextImpl(ctx) ? ctx.resourceId : undefined;
     const channelStore = getContextChannelStore(ctx);
     const parentPath = isContextImpl(ctx) ? ctx.currentPath() : '';
     const parentLedger = isContextImpl(ctx) ? ctx.ledger : undefined;
-    return Array.from({
-        length: count,
-    }, (_unused, index) => new ContextImpl({
+    return paths.map((path, index) => new ContextImpl({
         harness: ctx.harness,
         parent: ctx,
+        span: openPathSpan(ctx, {
+            stepId,
+            pathId: path.id,
+            index,
+        }),
         /* Ledger paths must stay unique across sibling paths: a child ContextImpl
          * starts with an empty frontier, so without a prefix every path would
          * restart at the root and collide with its siblings. */
@@ -52,6 +57,35 @@ function createChildContexts(ctx, count, stepId) {
         unifiedTools: ctx.unifiedTools,
     }));
 }
+function openPathSpan(ctx, { stepId, pathId, index, }) {
+    const span = openChildSpan(ctx, 'inParallel.path', pathId);
+    span.setAttribute(NoeticAttr.PARALLEL_ID, stepId);
+    span.setAttribute(NoeticAttr.PARALLEL_INDEX, index);
+    return span;
+}
+/**
+ * Ends each path's span when the path settles. A path that never starts (queued
+ * behind a fail-fast abort, or unstarted when a race settles) has no run to
+ * wrap, so `closeUnstarted` ends its span as cancelled.
+ */
+function tracePaths(ctx, executeStep, childContexts) {
+    const unstarted = new Set(childContexts);
+    return {
+        executeStep: (step, input, childCtx) => {
+            const child = frameworkCast(childCtx);
+            if (!unstarted.delete(child)) {
+                return executeStep(step, input, childCtx);
+            }
+            return traceChild(ctx, child.span, () => executeStep(step, input, childCtx));
+        },
+        async closeUnstarted() {
+            for (const child of unstarted) {
+                await closeUnstartedSpan(ctx, child.span);
+            }
+            unstarted.clear();
+        },
+    };
+}
 function createForkLayerBridge({ ctx, childContexts, opts, }) {
     const layers = ctx.layers;
     const layerStore = opts?.layerStore;
@@ -136,13 +170,14 @@ export async function executeInParallel(step, input, ctx, rawExecuteStep, opts)
             failed: [],
         });
     }
-    const childContexts = createChildContexts(baseCtx, paths.length, step.id);
+    const childContexts = createChildContexts(baseCtx, paths, step.id);
     const concurrency = step.concurrency ?? paths.length;
-    const executeStep = withForkLayers(rawExecuteStep, childContexts, createForkLayerBridge({
+    const traced = tracePaths(baseCtx, withForkLayers(rawExecuteStep, childContexts, createForkLayerBridge({
         ctx: baseCtx,
         childContexts,
         opts,
-    }));
+    })), childContexts);
+    const executeStep = traced.executeStep;
     try {
         switch (step.mode) {
             case 'all':
@@ -168,6 +203,7 @@ export async function executeInParallel(step, input, ctx, rawExecuteStep, opts)
         for (const child of childContexts) {
             child.detachFromParent();
         }
+        await traced.closeUnstarted();
     }
 }
 async function runWithConcurrency(tasks, concurrency) {
@@ -368,6 +404,10 @@ async function executeSettle(step, paths, input, ctx, childContexts, executeStep
     });
     return step.merge(results, ctx);
 }
+//#endregion
+//#region loop
+/** History entries a loop keeps when `maxHistorySize` is unset; oldest drop first. */
+const DEFAULT_MAX_HISTORY = 100;
 function hasTextField(value) {
     return typeof value === 'object' && value !== null && 'text' in value;
 }
@@ -409,7 +449,7 @@ export async function executeLoop(step, input, ctx, executeStep) {
     const startTime = Date.now();
     let stepCount = 0;
     const maxIterations = step.maxIterations ?? 1e3;
-    const maxHistory = step.maxHistorySize ?? 100;
+    const maxHistory = step.maxHistorySize ?? DEFAULT_MAX_HISTORY;
     let totalIterations = 0;
     // Validate maxIterations
     if (!Number.isFinite(maxIterations) || maxIterations < 1) {
@@ -515,6 +555,7 @@ export async function executeLoop(step, input, ctx, executeStep) {
                 reason: `Predicate error: ${predicateError instanceof Error ? predicateError.message : String(predicateError)}`,
             };
         }
+        recordVerdict(ctx, step.id, totalIterations, verdict);
         if (verdict.stop) {
             if (lastOutput === undefined) {
                 throw new NoeticErrorImpl({
@@ -614,6 +655,21 @@ function park(parkCtx) {
         });
     });
 }
+/**
+ * Adds a `loop.verdict` event to the enclosing span; loops open no span of
+ * their own. Leaves out `feedback`, which can be large or sensitive.
+ */
+function recordVerdict(ctx, loop, iteration, verdict) {
+    const attributes = {
+        loop,
+        iteration,
+        stop: verdict.stop,
+    };
+    if (verdict.reason !== undefined) {
+        attributes.reason = verdict.reason;
+    }
+    ctx.span.addEvent(NoeticEvent.LOOP_VERDICT, attributes);
+}
 function recordIterationError(ctx, error) {
     const message = error instanceof Error ? error.message : String(error);
     const stack = error instanceof Error && error.stack ? error.stack : '';

package/dist/interpreter/execute.d.ts

@@ -13,6 +13,16 @@ import type { Context, Step } from '@noetic-tools/types';
  * continue to work.
  */
 export declare function executeNoAdapter<TContext, I, O>(step: Step<TContext, I, O>, input: I, ctx: Context<TContext>): Promise<O>;
+/**
+ * @internal
+ * The ledger key this dispatch records and replays under, or undefined when the
+ * step bypasses the ledger (spec 23a § Identity). A `durable: false` step and a
+ * `schedule` (which never completes) are neither replayed nor recorded; the opt-out
+ * covers this step only, so its children still resolve their own keys. A
+ * `replayKey` replaces the positional path with `key:<key>`. A throwing `replayKey`
+ * costs this dispatch its durability, not its run: the step executes unrecorded.
+ */
+export declare function resolveLedgerKey<TContext, I, O>(step: Step<TContext, I, O>, input: I, ctx: Context<TContext>): string | undefined;
 /**
  * Executes a step within the interpreter, dispatching to the appropriate handler by step kind.
  *

package/dist/interpreter/execute.js

@@ -1,6 +1,7 @@
 import { frameworkCast, NoeticErrorImpl } from '@noetic-tools/types';
 import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
 import { ContextImpl } from '../runtime/context-impl.js';
+import { REPLAY_KEY_PREFIX } from '../runtime/durable/step-ledger.js';
 import { DetachedHandleImpl } from '../util/detached-handle.js';
 import { executeAcpAgent } from './execute-acp-agent.js';
 import { executeCallModel, executeInvokeTool, executeRunCode, executeSpawn, executeWithContext, } from './execute-action.js';
@@ -112,7 +113,35 @@ export async function executeNoAdapter(step, input, ctx) {
     }
 }
 /**
- * Resume path: when a previous run recorded this exact step at `ledgerPath`,
+ * @internal
+ * The ledger key this dispatch records and replays under, or undefined when the
+ * step bypasses the ledger (spec 23a § Identity). A `durable: false` step and a
+ * `schedule` (which never completes) are neither replayed nor recorded; the opt-out
+ * covers this step only, so its children still resolve their own keys. A
+ * `replayKey` replaces the positional path with `key:<key>`. A throwing `replayKey`
+ * costs this dispatch its durability, not its run: the step executes unrecorded.
+ */
+export function resolveLedgerKey(step, input, ctx) {
+    const impl = asContextImpl(frameworkCast(ctx));
+    if (!impl?.ledger || step.id.length === 0) {
+        return undefined;
+    }
+    if (step.durable === false || step.kind === 'schedule') {
+        return undefined;
+    }
+    if (!step.replayKey) {
+        return impl.currentPath();
+    }
+    try {
+        return `${REPLAY_KEY_PREFIX}${step.replayKey(input, ctx)}`;
+    }
+    catch (error) {
+        console.warn(`execute: replayKey for step "${step.id}" threw; running it without replay or recording:`, error instanceof Error ? error.message : String(error));
+        return undefined;
+    }
+}
+/**
+ * Resume path: when a previous run recorded this exact step at `ledgerKey`,
  * replay its output instead of re-running. Held as a helper (rather than inline
  * in `execute`) so the resume branch stays flat: it pops the frontier itself —
  * the caller returns before the normal `leaveStep` runs — and emits
@@ -120,13 +149,13 @@ export async function executeNoAdapter(step, input, ctx) {
  * the caller dispatches the step normally.
  */
 function replayFromLedger(opts) {
-    const { ledger, ledgerPath, impl, step, broadcaster, agentName } = opts;
-    if (!ledger || ledgerPath === undefined || ledger.isEmpty) {
+    const { ledger, ledgerKey, impl, step, broadcaster, agentName } = opts;
+    if (!ledger || ledgerKey === undefined || ledger.isEmpty) {
         return {
             hit: false,
         };
     }
-    const replayed = ledger.take(ledgerPath, {
+    const replayed = ledger.take(ledgerKey, {
         id: step.id,
         kind: step.kind,
     });
@@ -154,16 +183,16 @@ function replayFromLedger(opts) {
 }
 /**
  * Record a completed step's output so a resumed run replays it rather than
- * re-executing. A no-op without a ledger or ledger path. Only successes reach
+ * re-executing. A no-op without a ledger or ledger key. Only successes reach
  * here — a step that threw skips this call in `execute` and runs again on resume.
  */
 async function recordToLedger(opts) {
-    const { ledger, ledgerPath, step, output } = opts;
-    if (!ledger || ledgerPath === undefined) {
+    const { ledger, ledgerKey, step, output } = opts;
+    if (!ledger || ledgerKey === undefined) {
         return;
     }
     await ledger.record({
-        path: ledgerPath,
+        path: ledgerKey,
         stepId: step.id,
         kind: step.kind,
         output,
@@ -231,14 +260,14 @@ export async function execute(step, input, ctx) {
         });
     }
     /* Resume: a previous run that completed this exact step replays its recorded
-     * output instead of re-running it. `ledgerPath`/`ledger` are captured before
+     * output instead of re-running it. `ledgerKey`/`ledger` are captured before
      * dispatch and reused by the record below, because `leaveStep` pops the path
      * on the way out. */
-    const ledgerPath = impl && step.id.length > 0 ? impl.currentPath() : undefined;
+    const ledgerKey = resolveLedgerKey(step, input, ctx);
     const ledger = impl?.ledger;
     const replay = replayFromLedger({
         ledger,
-        ledgerPath,
+        ledgerKey,
         impl,
         step,
         broadcaster,
@@ -323,7 +352,7 @@ export async function execute(step, input, ctx) {
      * again. */
     await recordToLedger({
         ledger,
-        ledgerPath,
+        ledgerKey,
         step,
         output: result,
     });

package/dist/observability/genai-attributes.d.ts

@@ -1,59 +1,75 @@
 export declare const GenAI: {
-    readonly SYSTEM: 'gen_ai.system';
-    readonly REQUEST_MODEL: 'gen_ai.request.model';
-    readonly USAGE_INPUT_TOKENS: 'gen_ai.usage.input_tokens';
-    readonly USAGE_OUTPUT_TOKENS: 'gen_ai.usage.output_tokens';
+    readonly SYSTEM: "gen_ai.system";
+    readonly REQUEST_MODEL: "gen_ai.request.model";
+    readonly USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
     /** Prompt tokens served from the provider's cache. Absent if unreported. */
-    readonly USAGE_CACHED_INPUT_TOKENS: 'gen_ai.usage.cached_input_tokens';
+    readonly USAGE_CACHED_INPUT_TOKENS: "gen_ai.usage.cached_input_tokens";
     /** Prompt tokens written into the provider's cache. Absent if unreported. */
-    readonly USAGE_CACHE_WRITE_TOKENS: 'gen_ai.usage.cache_write_tokens';
-    readonly COST: 'gen_ai.cost';
+    readonly USAGE_CACHE_WRITE_TOKENS: "gen_ai.usage.cache_write_tokens";
+    readonly COST: "gen_ai.cost";
 };
 export declare const ToolAttr: {
-    readonly NAME: 'tool.name';
-    readonly NEEDS_APPROVAL: 'tool.needs_approval';
+    readonly NAME: "tool.name";
+    readonly NEEDS_APPROVAL: "tool.needs_approval";
 };
 export declare const NoeticAttr: {
     /** Full JSON-serialised `WorkflowDocument` (the DAG, lossless). */
-    readonly WORKFLOW_DOCUMENT: 'noetic.workflow.document';
+    readonly WORKFLOW_DOCUMENT: "noetic.workflow.document";
     /** Workflow document schema version. */
-    readonly WORKFLOW_VERSION: 'noetic.workflow.version';
+    readonly WORKFLOW_VERSION: "noetic.workflow.version";
     /** Count of declared nodes in the workflow tree. */
-    readonly WORKFLOW_NODE_COUNT: 'noetic.workflow.node_count';
+    readonly WORKFLOW_NODE_COUNT: "noetic.workflow.node_count";
     /** JSON array of `{ id, kind }` for every declared node (flattened graph). */
-    readonly WORKFLOW_NODES: 'noetic.workflow.nodes';
+    readonly WORKFLOW_NODES: "noetic.workflow.nodes";
     /** JSON array of `{ from, to }` parent→child edges between declared nodes. */
-    readonly WORKFLOW_EDGES: 'noetic.workflow.edges';
-    /** Id of the declared workflow node an `llm.call`/`tool.call` span belongs to. */
-    readonly NODE_ID: 'noetic.node.id';
+    readonly WORKFLOW_EDGES: "noetic.workflow.edges";
+    /**
+     * Id of the step a span belongs to: the declared workflow node of an
+     * `llm.call`/`tool.call`, the `decide` step of a `decide.call`, the `spawn`
+     * step of a `spawn` span, the path step of an `inParallel.path` span.
+     */
+    readonly NODE_ID: "noetic.node.id";
+    /** Id of the `inParallel` step an `inParallel.path` span belongs to. */
+    readonly PARALLEL_ID: "noetic.parallel.id";
+    /** Zero-based position of the path among its `inParallel` siblings. */
+    readonly PARALLEL_INDEX: "noetic.parallel.index";
+    /** `NoeticError` kind a `spawn`/`inParallel.path` span failed with. */
+    readonly ERROR_KIND: "noetic.error.kind";
     /**
      * Conversation/session this run belongs to (the run's `ctx.threadId`). Stamped
      * on the root `workflow.run` span so every turn of a multi-turn session shares
      * one id, letting a consumer group per-run traces back into their session.
      */
-    readonly SESSION_ID: 'noetic.session.id';
+    readonly SESSION_ID: "noetic.session.id";
     /** Resource the session is scoped to (the run's `ctx.resourceId`), when set. */
-    readonly RESOURCE_ID: 'noetic.resource.id';
+    readonly RESOURCE_ID: "noetic.resource.id";
     /** Id of the anchoring epoch the assembled view belongs to. */
-    readonly CONTEXT_EPOCH_ID: 'noetic.context.epoch.id';
+    readonly CONTEXT_EPOCH_ID: "noetic.context.epoch.id";
     /** Assemblies served by the current epoch, including this one. */
-    readonly CONTEXT_EPOCH_AGE: 'noetic.context.epoch.age';
+    readonly CONTEXT_EPOCH_AGE: "noetic.context.epoch.age";
     /** Why the epoch re-anchored on this assembly, when it did. */
-    readonly CONTEXT_REANCHOR_REASON: 'noetic.context.reanchor_reason';
+    readonly CONTEXT_REANCHOR_REASON: "noetic.context.reanchor_reason";
     /** Tokens in the anchor band (the cache-stable prefix). */
-    readonly CONTEXT_ANCHOR_TOKENS: 'noetic.context.anchor_tokens';
+    readonly CONTEXT_ANCHOR_TOKENS: "noetic.context.anchor_tokens";
     /** Tokens in the live band (rendered after history). */
-    readonly CONTEXT_LIVE_TOKENS: 'noetic.context.live_tokens';
+    readonly CONTEXT_LIVE_TOKENS: "noetic.context.live_tokens";
     /** Tokens spent superseding stale anchors. */
-    readonly CONTEXT_DELTA_TOKENS: 'noetic.context.delta_tokens';
+    readonly CONTEXT_DELTA_TOKENS: "noetic.context.delta_tokens";
     /** JSON array of `{ id, placement, served }` per contributing layer. */
-    readonly CONTEXT_LAYER_PLACEMENTS: 'noetic.context.layer_placements';
+    readonly CONTEXT_LAYER_PLACEMENTS: "noetic.context.layer_placements";
     /** JSON array of `{ id, rate, rebillTokens }` per contributing layer. */
-    readonly CONTEXT_LAYER_CHURN: 'noetic.context.layer_churn';
+    readonly CONTEXT_LAYER_CHURN: "noetic.context.layer_churn";
     /** `native` or `estimated` — where a decision's probabilities came from. */
-    readonly DECISION_SOURCE: 'noetic.decision.source';
+    readonly DECISION_SOURCE: "noetic.decision.source";
     /** Comma-separated ids of questions the model refused. */
-    readonly DECISION_REFUSED: 'noetic.decision.refused';
+    readonly DECISION_REFUSED: "noetic.decision.refused";
     /** Prefix for per-question attributes: `noetic.decision.<id>.value` etc. */
-    readonly DECISION_PREFIX: 'noetic.decision.';
+    readonly DECISION_PREFIX: "noetic.decision.";
+};
+export declare const NoeticEvent: {
+    /** One per loop iteration: `{ loop, iteration, stop, reason? }`. */
+    readonly LOOP_VERDICT: "loop.verdict";
+    /** A channel dropped data or is waiting with no timeout: `{ kind, channelName, message, capacity?, operation? }`. */
+    readonly CHANNEL_WARNING: "channel.warning";
 };

package/dist/observability/genai-attributes.js

@@ -27,8 +27,18 @@ export const NoeticAttr = {
     WORKFLOW_NODES: 'noetic.workflow.nodes',
     /** JSON array of `{ from, to }` parent→child edges between declared nodes. */
     WORKFLOW_EDGES: 'noetic.workflow.edges',
-    /** Id of the declared workflow node an `llm.call`/`tool.call` span belongs to. */
+    /**
+     * Id of the step a span belongs to: the declared workflow node of an
+     * `llm.call`/`tool.call`, the `decide` step of a `decide.call`, the `spawn`
+     * step of a `spawn` span, the path step of an `inParallel.path` span.
+     */
     NODE_ID: 'noetic.node.id',
+    /** Id of the `inParallel` step an `inParallel.path` span belongs to. */
+    PARALLEL_ID: 'noetic.parallel.id',
+    /** Zero-based position of the path among its `inParallel` siblings. */
+    PARALLEL_INDEX: 'noetic.parallel.index',
+    /** `NoeticError` kind a `spawn`/`inParallel.path` span failed with. */
+    ERROR_KIND: 'noetic.error.kind',
     /**
      * Conversation/session this run belongs to (the run's `ctx.threadId`). Stamped
      * on the root `workflow.run` span so every turn of a multi-turn session shares
@@ -60,3 +70,11 @@ export const NoeticAttr = {
     /** Prefix for per-question attributes: `noetic.decision.<id>.value` etc. */
     DECISION_PREFIX: 'noetic.decision.',
 };
+// Span event names. Steps that open no span of their own (e.g. `loop`) add
+// these to the enclosing `ctx.span`.
+export const NoeticEvent = {
+    /** One per loop iteration: `{ loop, iteration, stop, reason? }`. */
+    LOOP_VERDICT: 'loop.verdict',
+    /** A channel dropped data or is waiting with no timeout: `{ kind, channelName, message, capacity?, operation? }`. */
+    CHANNEL_WARNING: 'channel.warning',
+};

package/dist/runtime/channel-store.d.ts

@@ -1,4 +1,36 @@
 import type { Channel, ChannelHandle, ExternalChannel } from '@noetic-tools/types';
+import type { ChannelSnapshot } from '../types/checkpoint.js';
+/**
+ * A channel condition worth surfacing but not worth failing on. `AgentHarness`
+ * records these as `channel.warning` span events (spec 10); a bare store
+ * prints them with `console.warn`.
+ */
+export type ChannelWarning = {
+    /** An external sender hit a full queue and the oldest item was dropped. */
+    kind: 'overflow_drop';
+    channelName: string;
+    capacity: number;
+    message: string;
+} | {
+    /** An external subscriber's private buffer filled and its oldest value was dropped. */
+    kind: 'subscriber_drop';
+    channelName: string;
+    capacity: number;
+    message: string;
+} | {
+    /** A `recv` or parked `send` is waiting with `timeout: 0`, so nothing will time it out. */
+    kind: 'unbounded_wait';
+    channelName: string;
+    operation: 'recv' | 'send';
+    message: string;
+};
+/** Options accepted by the `ChannelStore` constructor. */
+export interface ChannelStoreOpts {
+    /** Receives every channel warning. Defaults to `warnToConsole`. */
+    onWarning?: (warning: ChannelWarning) => void;
+}
+/** Print a channel warning with the `[noetic]` prefix. */
+export declare function warnToConsole(warning: ChannelWarning): void;
 /** Options accepted by internal (back-pressured) `send`. */
 export interface ChannelSendOpts {
     /**
@@ -21,7 +53,34 @@ export declare class ChannelStore {
      */
     private handleObserved;
     private subscribersByExecution;
+    /**
+     * Channel name → ids of the root executions that used it, which decides
+     * the channels an execution's checkpoint carries. Ids stay after their
+     * execution closes: a host may checkpoint a finished run, and channel
+     * state itself lives for the harness lifetime (spec 06, Lifecycle).
+     */
+    private users;
+    private readonly warn;
+    constructor(opts?: ChannelStoreOpts);
     private getOrCreate;
+    /**
+     * Record that `executionId` (a root execution) uses `channel`, so the
+     * channel rides along in its checkpoints.
+     */
+    claim<T>(channel: Channel<T>, executionId: string): void;
+    private addUser;
+    /**
+     * Stored state (values, queued items) of every channel `executionId` used.
+     * Parked receivers, parked senders, and subscribers are live promises and
+     * stay out; topic channels store nothing and are skipped.
+     */
+    snapshot(executionId: string): ChannelSnapshot[];
+    /**
+     * Refill channel state from a checkpoint and mark `executionId` as a user.
+     * A channel that already has live state keeps it — live state is never
+     * older than a snapshot.
+     */
+    restore(executionId: string, snapshots: readonly ChannelSnapshot[]): void;
     /**
      * Subscribe to wake notifications on a channel without consuming any value.
      * Fired once on the next `send()` for any mode, then auto-removed. Returns
@@ -42,8 +101,12 @@ export declare class ChannelStore {
      * - **topic**: deliver to current subscribers, resolve immediately.
      *
      * External callers use `ChannelHandle.send` (sync, drop-oldest) instead.
+     * `opts.timeout: 0` parks with no timeout and warns `unbounded_wait`.
+     *
+     * @throws `NoeticConfigError` with code `INVALID_CHANNEL_TIMEOUT` (as a
+     * rejection) when `opts.timeout` is negative.
      */
-    send<T>(channel: Channel<T>, value: T, opts?: ChannelSendOpts): Promise<void>;
+    send<T>(channel: Channel<T>, value: NoInfer<T>, opts?: ChannelSendOpts): Promise<void>;
     /** Park an internal sender on a full queue until a slot frees (FIFO). */
     private parkSender;
     /**
@@ -53,6 +116,15 @@ export declare class ChannelStore {
     private promotePendingSender;
     /** Fire-and-reset the one-shot wake subscribers for a channel state. */
     private fireWakes;
+    /**
+     * Receive by mode: value returns the current value, queue dequeues the
+     * head, topic waits for the next send. A receiver that has to wait gets
+     * `channel_timeout` after `timeout` ms; `0` waits with no timeout in every
+     * mode and warns `unbounded_wait`.
+     *
+     * @throws `NoeticConfigError` with code `INVALID_CHANNEL_TIMEOUT` (as a
+     * rejection) when `timeout` is negative.
+     */
     recv<T>(channel: Channel<T>, timeout?: number, signal?: AbortSignal): Promise<T>;
     tryRecv<T>(channel: Channel<T>): T | null;
     private waitWithTimeout;