@noetic-tools/context 1.7.0 → 1.8.0

package/dist/context/exec-context-factory.js

@@ -1,4 +1,5 @@
 import { estimateTokens } from '@noetic-tools/types';
+import { exportSpans } from './span-export.js';
 /**
  * Maps a full `Context` to the lightweight `ExecutionContext` consumed by context layer hooks.
  * Centralised here so the mapping stays consistent across agent-harness, layer-api, and the
@@ -24,7 +25,22 @@ export function contextToExecCtx(ctx, overrides) {
         trace: {
             setAttribute: (key, value) => ctx.span.setAttribute(key, value),
             addEvent: (name, attributes) => ctx.span.addEvent(name, attributes),
+            createSpan: (name) => openSpan(ctx, name),
         },
         readLayerState: (layerId) => ctx.harness.getLayerState(readLayerStateId, layerId),
     };
 }
+/** Opens a span under `ctx.span` that exports itself to the harness when it ends. */
+function openSpan(ctx, name) {
+    const span = ctx.harness.createSpan(name, ctx.span);
+    return {
+        setAttribute: (key, value) => span.setAttribute(key, value),
+        addEvent: (event, attributes) => span.addEvent(event, attributes),
+        end: async () => {
+            span.end();
+            await exportSpans(ctx.harness.traceExporter, [
+                span,
+            ]);
+        },
+    };
+}

package/dist/context/hook-call.d.ts

@@ -1,8 +1,9 @@
 /**
- * Timed, traced calls into context layer hooks. Each call of a traced hook adds
- * one `layer.hook` event to the span of the context it runs in (`ctx.trace`),
- * shaped as a `LayerTraceSpan`. Events rather than child spans: an
- * `ExecutionContext` can annotate its span but not open one.
+ * Timed, traced calls into context layer hooks. Each call of a traced hook is
+ * recorded as one `layer.hook` record shaped as a `LayerTraceSpan`: a child
+ * span of the context's span when the context can open one
+ * (`ctx.trace.createSpan`), otherwise an event on the context's span. Never
+ * both, so a backend sees each call once.
  */
 import type { ExecutionContext, LayerTraceSpan } from '@noetic-tools/types';
 type TracedHook = LayerTraceSpan['hook'];
@@ -16,16 +17,27 @@ interface HookCall<T> {
     /** Reads a recall's budget and item count from the hook's result. */
     measure?: (result: T) => Pick<LayerTraceSpan, 'budget' | 'itemCount'>;
 }
-/** Span event recording one layer hook call. Attributes follow `LayerTraceSpan`. */
+/** Name of the span (or span event) recording one layer hook call. */
 export declare const LAYER_HOOK_EVENT = "layer.hook";
+/** Attributes of a `layer.hook` span. A span times itself, so it carries no duration. */
+export declare const LayerHookAttr: {
+    readonly LAYER_ID: "noetic.layer.id";
+    readonly HOOK: "noetic.layer.hook";
+    readonly STATUS: "noetic.layer.status";
+    readonly ITEM_COUNT: "noetic.layer.item_count";
+    readonly BUDGET_ALLOCATED: "noetic.layer.budget.allocated";
+    readonly BUDGET_USED: "noetic.layer.budget.used";
+    readonly BUDGET_YIELDED: "noetic.layer.budget.yielded";
+};
 /**
- * Runs a layer hook under its timeout and records a `layer.hook` event for it.
- * Rethrows whatever the hook threw (or the timeout), so callers keep their own
- * failure handling.
+ * Runs a layer hook under its timeout and records a `layer.hook` span (or
+ * event) for it. Rethrows whatever the hook threw (or the timeout), so callers
+ * keep their own failure handling. The span opens before the hook runs and ends
+ * once it settles.
  */
 export declare function callHook<T>({ ctx, layerId, hook, timeout, run, measure, }: HookCall<T>): Promise<T>;
 /** Records a hook the layer defines but the lifecycle did not call. */
-export declare function traceSkipped(ctx: ExecutionContext, layerId: string, hook: TracedHook): void;
-/** Runs a hook under a timeout without tracing it, for hooks outside `LayerTraceSpan`. */
+export declare function traceSkipped(ctx: ExecutionContext, layerId: string, hook: TracedHook): Promise<void>;
+/** Runs a hook under a timeout without tracing it, for calls that must leave no trace (a peek recall). */
 export declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
 export {};

package/dist/context/hook-call.js

@@ -1,54 +1,66 @@
 /**
- * Timed, traced calls into context layer hooks. Each call of a traced hook adds
- * one `layer.hook` event to the span of the context it runs in (`ctx.trace`),
- * shaped as a `LayerTraceSpan`. Events rather than child spans: an
- * `ExecutionContext` can annotate its span but not open one.
+ * Timed, traced calls into context layer hooks. Each call of a traced hook is
+ * recorded as one `layer.hook` record shaped as a `LayerTraceSpan`: a child
+ * span of the context's span when the context can open one
+ * (`ctx.trace.createSpan`), otherwise an event on the context's span. Never
+ * both, so a backend sees each call once.
  */
 //#endregion
 //#region Public API
-/** Span event recording one layer hook call. Attributes follow `LayerTraceSpan`. */
+/** Name of the span (or span event) recording one layer hook call. */
 export const LAYER_HOOK_EVENT = 'layer.hook';
+/** Attributes of a `layer.hook` span. A span times itself, so it carries no duration. */
+export const LayerHookAttr = {
+    LAYER_ID: 'noetic.layer.id',
+    HOOK: 'noetic.layer.hook',
+    STATUS: 'noetic.layer.status',
+    ITEM_COUNT: 'noetic.layer.item_count',
+    BUDGET_ALLOCATED: 'noetic.layer.budget.allocated',
+    BUDGET_USED: 'noetic.layer.budget.used',
+    BUDGET_YIELDED: 'noetic.layer.budget.yielded',
+};
 /**
- * Runs a layer hook under its timeout and records a `layer.hook` event for it.
- * Rethrows whatever the hook threw (or the timeout), so callers keep their own
- * failure handling.
+ * Runs a layer hook under its timeout and records a `layer.hook` span (or
+ * event) for it. Rethrows whatever the hook threw (or the timeout), so callers
+ * keep their own failure handling. The span opens before the hook runs and ends
+ * once it settles.
  */
 export async function callHook({ ctx, layerId, hook, timeout, run, measure, }) {
+    const span = ctx.trace.createSpan?.(LAYER_HOOK_EVENT);
     const started = performance.now();
-    try {
-        const result = await withTimeout(run(), timeout);
-        traceHook(ctx, {
+    const outcome = await settle(withTimeout(run(), timeout));
+    const duration = performance.now() - started;
+    if (outcome.ok) {
+        await traceHook(ctx, span, {
             layerId,
             hook,
-            duration: performance.now() - started,
+            duration,
             status: 'ok',
-            ...measure?.(result),
-        });
-        return result;
-    }
-    catch (e) {
-        traceHook(ctx, {
-            layerId,
-            hook,
-            duration: performance.now() - started,
-            status: e instanceof HookTimeout ? 'timeout' : 'error',
-            error: {
-                message: e instanceof Error ? e.message : String(e),
-            },
+            ...measure?.(outcome.value),
         });
-        throw e;
+        return outcome.value;
     }
+    await traceHook(ctx, span, {
+        layerId,
+        hook,
+        duration,
+        status: outcome.error instanceof HookTimeout ? 'timeout' : 'error',
+        error: {
+            message: outcome.error instanceof Error ? outcome.error.message : String(outcome.error),
+        },
+    });
+    throw outcome.error;
 }
 /** Records a hook the layer defines but the lifecycle did not call. */
-export function traceSkipped(ctx, layerId, hook) {
-    traceHook(ctx, {
+export async function traceSkipped(ctx, layerId, hook) {
+    await traceHook(ctx, ctx.trace.createSpan?.(LAYER_HOOK_EVENT), {
         layerId,
         hook,
         duration: 0,
         status: 'skipped',
     });
 }
-/** Runs a hook under a timeout without tracing it, for hooks outside `LayerTraceSpan`. */
+/** Runs a hook under a timeout without tracing it, for calls that must leave no trace (a peek recall). */
 export async function withTimeout(promise, ms) {
     if (ms <= 0) {
         return promise;
@@ -68,25 +80,69 @@ class HookTimeout extends Error {
         super(`Timeout after ${ms}ms`);
     }
 }
+async function settle(promise) {
+    try {
+        return {
+            ok: true,
+            value: await promise,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error,
+        };
+    }
+}
+async function traceHook(ctx, span, record) {
+    if (!span) {
+        ctx.trace.addEvent(LAYER_HOOK_EVENT, eventAttributes(record));
+        return;
+    }
+    for (const [key, value] of Object.entries(spanAttributes(record))) {
+        span.setAttribute(key, value);
+    }
+    await span.end();
+}
+function spanAttributes(record) {
+    const attributes = {
+        [LayerHookAttr.LAYER_ID]: record.layerId,
+        [LayerHookAttr.HOOK]: record.hook,
+        [LayerHookAttr.STATUS]: record.status,
+    };
+    if (record.itemCount !== undefined) {
+        attributes[LayerHookAttr.ITEM_COUNT] = record.itemCount;
+    }
+    if (record.budget) {
+        attributes[LayerHookAttr.BUDGET_ALLOCATED] = record.budget.allocated;
+        attributes[LayerHookAttr.BUDGET_USED] = record.budget.used;
+        attributes[LayerHookAttr.BUDGET_YIELDED] = record.budget.yielded;
+    }
+    if (record.error) {
+        attributes.error = true;
+        attributes['error.message'] = record.error.message;
+    }
+    return attributes;
+}
 /** Span event attributes hold only scalars, so nested fields flatten to dotted keys. */
-function traceHook(ctx, span) {
+function eventAttributes(record) {
     const attributes = {
-        layerId: span.layerId,
-        hook: span.hook,
-        duration: span.duration,
-        status: span.status,
+        layerId: record.layerId,
+        hook: record.hook,
+        duration: record.duration,
+        status: record.status,
     };
-    if (span.itemCount !== undefined) {
-        attributes.itemCount = span.itemCount;
+    if (record.itemCount !== undefined) {
+        attributes.itemCount = record.itemCount;
     }
-    if (span.budget) {
-        attributes['budget.allocated'] = span.budget.allocated;
-        attributes['budget.used'] = span.budget.used;
-        attributes['budget.yielded'] = span.budget.yielded;
+    if (record.budget) {
+        attributes['budget.allocated'] = record.budget.allocated;
+        attributes['budget.used'] = record.budget.used;
+        attributes['budget.yielded'] = record.budget.yielded;
     }
-    if (span.error) {
-        attributes['error.message'] = span.error.message;
+    if (record.error) {
+        attributes['error.message'] = record.error.message;
     }
-    ctx.trace.addEvent(LAYER_HOOK_EVENT, attributes);
+    return attributes;
 }
 //#endregion

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

@@ -1,4 +1,5 @@
 import type { ContextLayer, DecisionRecord, ExecutionContext, Item, ItemLog, ItemSchemaRegistry, LLMResponse, ScopedStorage, SteeringDecision, StorageAdapter } from '@noetic-tools/types';
+import type { LiveChild } from './parent-updates.js';
 export interface LayerStateStore {
     get<T>(executionId: string, layerId: string): T | undefined;
     set<T>(executionId: string, layerId: string, state: T): void;
@@ -44,6 +45,17 @@ export interface LayerStateStore {
     disable?(executionId: string, layerId: string): void;
     /** Whether a layer was disabled for an execution. */
     isDisabled?(executionId: string, layerId: string): boolean;
+    /**
+     * Register a running child. From now on every `set()` of the parent's state
+     * for a layer is delivered to that layer's `onParentUpdate` in the child, in
+     * the background. `cleanup(childExecutionId)` forgets the child. Optional so
+     * custom stores keep compiling; without it, children get no parent updates.
+     */
+    adopt?(child: LiveChild): void;
+    /** Stop parent updates to a child and wait for deliveries already running. */
+    release?(childExecutionId: string): Promise<void>;
+    /** Number of registered children, for leak checks. */
+    liveChildren?(): number;
 }
 interface InitLayersParams {
     layers: ContextLayer[];

package/dist/context/layer-lifecycle.js

@@ -1,5 +1,6 @@
 import { createMessage, defaultItemSchemaRegistry, estimateTokens, frameworkCast, NoeticConfigError, NoeticErrorImpl, SteeringAction, } from '@noetic-tools/types';
 import { callHook, traceSkipped, withTimeout } from './hook-call.js';
+import { createLiveChildren } from './parent-updates.js';
 import { createScopedStorage, resolveScopeKey } from './scope.js';
 /** Maximum allowed re-render depth to prevent infinite loops */
 const MAX_RERENDER_DEPTH = 3;
@@ -29,7 +30,7 @@ export function createLayerStateStore(diagnostic) {
         }
         entry.inFlight = null;
     }
-    return {
+    const store = {
         get(executionId, layerId) {
             return frameworkCast(states.get(executionId)?.get(layerId));
         },
@@ -40,6 +41,7 @@ export function createLayerStateStore(diagnostic) {
                 states.set(executionId, execMap);
             }
             execMap.set(layerId, state);
+            children.notify(executionId, layerId, state);
             const entry = durables.get(executionId)?.get(layerId);
             if (!entry) {
                 return;
@@ -88,6 +90,7 @@ export function createLayerStateStore(diagnostic) {
             return disabled.get(executionId)?.has(layerId) ?? false;
         },
         cleanup(executionId) {
+            children.drop(executionId);
             states.delete(executionId);
             durables.delete(executionId);
             disabled.delete(executionId);
@@ -97,8 +100,24 @@ export function createLayerStateStore(diagnostic) {
             durables.get(executionId)?.delete(layerId);
             disabled.get(executionId)?.delete(layerId);
         },
+        adopt(child) {
+            children.adopt(child);
+        },
+        release(childExecutionId) {
+            return children.release(childExecutionId);
+        },
+        liveChildren() {
+            return children.size;
+        },
         diagnostic: report,
     };
+    const children = createLiveChildren(store, (executionId, layer) => isLayerDisabled({
+        store,
+        executionId,
+        layer,
+        state: store.get(executionId, layer.id),
+    }));
+    return store;
 }
 /**
  * Whether a layer must be skipped for this execution — either explicitly
@@ -198,7 +217,7 @@ export async function initLayers({ layers, ctx, storage, store, keep = false, })
         }
         const init = layer.hooks.init;
         if (keep && store.has?.(ctx.executionId, layer.id)) {
-            traceSkipped(ctx, layer.id, 'init');
+            await traceSkipped(ctx, layer.id, 'init');
             continue;
         }
         const scopeKey = resolveScopeKey(layer.scope, ctx);
@@ -274,7 +293,7 @@ export async function recallLayers({ layers, query, ctx, log, budgets, store, it
             state: stored,
         })) {
             if (!peek) {
-                traceSkipped(ctx, layer.id, 'recall');
+                await traceSkipped(ctx, layer.id, 'recall');
             }
             continue; // was disabled
         }
@@ -449,7 +468,7 @@ export async function storeLayers({ layers, response, ctx, log, store, recallCac
             layer,
             state,
         })) {
-            traceSkipped(ctx, layer.id, 'store');
+            await traceSkipped(ctx, layer.id, 'store');
             continue;
         }
         snapshots.push({
@@ -512,14 +531,22 @@ export async function notifyDecision({ layers, record, ctx, store, recallCache,
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'onDecision');
             continue;
         }
+        const onDecision = layer.hooks.onDecision;
         try {
-            const result = await withTimeout(layer.hooks.onDecision({
-                state,
-                record,
+            const result = await callHook({
                 ctx,
-            }), layer.timeouts?.onDecision ?? 5e3);
+                layerId: layer.id,
+                hook: 'onDecision',
+                timeout: layer.timeouts?.onDecision ?? 5e3,
+                run: () => onDecision({
+                    state,
+                    record,
+                    ctx,
+                }),
+            });
             if (result && 'state' in result) {
                 store.set(ctx.executionId, layer.id, result.state);
                 if (recallCache && layer.recallMode === 'eventual') {
@@ -551,7 +578,7 @@ export async function disposeLayers({ layers, ctx, store, scoped = false, }) {
             layer,
             state,
         })) {
-            traceSkipped(ctx, layer.id, 'dispose');
+            await traceSkipped(ctx, layer.id, 'dispose');
             continue;
         }
         const dispose = layer.hooks.dispose;
@@ -607,7 +634,7 @@ export async function spawnLayers({ layers, parentCtx, childCtx, store, itemSche
             layer,
             state: parentState,
         })) {
-            traceSkipped(parentCtx, layer.id, 'onSpawn');
+            await traceSkipped(parentCtx, layer.id, 'onSpawn');
             continue;
         }
         const onSpawn = layer.hooks.onSpawn;
@@ -653,6 +680,9 @@ export async function spawnLayers({ layers, parentCtx, childCtx, store, itemSche
  * `spawn_summary_failed` diagnostic plus a span event on the child's span.
  */
 export async function returnLayers({ layers, stepId, parentCtx, childCtx, childLog, result, store, }) {
+    // The child has finished: no more parent updates, and the ones in flight
+    // land before its state is merged.
+    await store.release?.(childCtx.executionId);
     const sorted = [
         ...layers,
     ].sort((a, b) => a.slot - b.slot);
@@ -667,7 +697,7 @@ export async function returnLayers({ layers, stepId, parentCtx, childCtx, childL
         // initialized state can still be seeded from the child. Skip only when the
         // child produced nothing.
         if (childState === undefined) {
-            traceSkipped(childCtx, layer.id, 'onReturn');
+            await traceSkipped(childCtx, layer.id, 'onReturn');
             continue;
         }
         const onReturn = layer.hooks.onReturn;
@@ -723,7 +753,7 @@ export async function completeLayers({ layers, ctx, log, outcome, store, }) {
             layer,
             state,
         })) {
-            traceSkipped(ctx, layer.id, 'onComplete');
+            await traceSkipped(ctx, layer.id, 'onComplete');
             continue;
         }
         const onComplete = layer.hooks.onComplete;
@@ -766,17 +796,24 @@ export async function beforeToolCallLayers({ layers, toolName, toolArgs, callId,
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'beforeToolCall');
             continue;
         }
+        const beforeToolCall = layer.hooks.beforeToolCall;
         try {
-            const timeout = layer.timeouts?.beforeToolCall ?? 5e3;
-            const result = await withTimeout(layer.hooks.beforeToolCall({
-                toolName,
-                toolArgs,
-                callId,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'beforeToolCall',
+                timeout: layer.timeouts?.beforeToolCall ?? 5e3,
+                run: () => beforeToolCall({
+                    toolName,
+                    toolArgs,
+                    callId,
+                    ctx,
+                    state,
+                }),
+            });
             if (result.state !== undefined) {
                 store.set(ctx.executionId, layer.id, result.state);
             }
@@ -819,15 +856,22 @@ export async function afterModelCallLayers({ layers, response, ctx, store, }) {
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'afterModelCall');
             continue;
         }
+        const afterModelCall = layer.hooks.afterModelCall;
         try {
-            const timeout = layer.timeouts?.afterModelCall ?? 1e4;
-            const result = await withTimeout(layer.hooks.afterModelCall({
-                response,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'afterModelCall',
+                timeout: layer.timeouts?.afterModelCall ?? 1e4,
+                run: () => afterModelCall({
+                    response,
+                    ctx,
+                    state,
+                }),
+            });
             if (result.state !== undefined) {
                 store.set(ctx.executionId, layer.id, result.state);
             }
@@ -867,15 +911,22 @@ export async function projectHistoryLayers({ layers, items, ctx, store, }) {
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'projectHistory');
             continue;
         }
+        const projectHistory = layer.hooks.projectHistory;
         try {
-            const timeout = layer.timeouts?.projectHistory ?? 5e3;
-            const result = await withTimeout(layer.hooks.projectHistory({
-                items: current,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'projectHistory',
+                timeout: layer.timeouts?.projectHistory ?? 5e3,
+                run: () => projectHistory({
+                    items: current,
+                    ctx,
+                    state,
+                }),
+            });
             current = result.items;
         }
         catch (e) {
@@ -913,16 +964,23 @@ export async function runAppendPipeline({ layers, items, ctx, log, store, }) {
             layer,
             state,
         })) {
+            await traceSkipped(ctx, layer.id, 'onItemAppend');
             continue;
         }
+        const onItemAppend = layer.hooks.onItemAppend;
         try {
-            const timeout = layer.timeouts?.onItemAppend ?? DEFAULT_ON_ITEM_APPEND_TIMEOUT;
-            const result = await withTimeout(layer.hooks.onItemAppend({
-                items: currentItems,
-                log,
+            const result = await callHook({
                 ctx,
-                state,
-            }), timeout);
+                layerId: layer.id,
+                hook: 'onItemAppend',
+                timeout: layer.timeouts?.onItemAppend ?? DEFAULT_ON_ITEM_APPEND_TIMEOUT,
+                run: () => onItemAppend({
+                    items: currentItems,
+                    log,
+                    ctx,
+                    state,
+                }),
+            });
             // Update items for next layer in pipeline
             currentItems = result.items;
             // Update state if provided

package/dist/context/parent-updates.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Live children and `onParentUpdate` delivery. A child execution is live from
+ * the moment its spawn (or inParallel path) starts running until it returns or
+ * is cleaned up. While it is live, every write of a parent layer's state is
+ * handed to the same layer's `onParentUpdate` in the child.
+ */
+import type { ContextLayer, ExecutionContext, ItemLog, ItemSchemaRegistry } from '@noetic-tools/types';
+/** @public A running child execution that receives its parent's layer writes. */
+export interface LiveChild {
+    /** Execution whose layer writes the child receives. */
+    parentExecutionId: string;
+    /** The child's execution context; hooks run on it and trace onto its span. */
+    ctx: ExecutionContext;
+    /** The layers active in the child. */
+    layers: ContextLayer[];
+    /** The child's item log, where returned items are appended. */
+    log: ItemLog;
+    itemSchemas?: ItemSchemaRegistry;
+}
+/** The slice of the layer state store that delivery reads and writes through. */
+export interface ParentUpdateStore {
+    get<T>(executionId: string, layerId: string): T | undefined;
+    set<T>(executionId: string, layerId: string, state: T): void;
+    diagnostic: (layerId: string, hook: string, error: unknown) => void;
+}
+/** Whether a layer's hooks are switched off for an execution. */
+type SkipCheck = (executionId: string, layer: ContextLayer) => boolean;
+export interface LiveChildren {
+    adopt(child: LiveChild): void;
+    /** Hands a parent write to every live child of `parentExecutionId`. */
+    notify(parentExecutionId: string, layerId: string, state: unknown): void;
+    /** Stops new deliveries to a child and waits for the ones already running. */
+    release(childExecutionId: string): Promise<void>;
+    /** Forgets a child at once; a delivery still running discards its result. */
+    drop(childExecutionId: string): void;
+    /** Number of live children, for leak checks. */
+    readonly size: number;
+}
+/**
+ * Builds the live-child registry a layer state store dispatches through.
+ * `store` is read lazily, so it may be the object under construction.
+ */
+export declare function createLiveChildren(store: ParentUpdateStore, skips: SkipCheck): LiveChildren;
+export {};

package/dist/context/parent-updates.js

@@ -0,0 +1,117 @@
+/**
+ * Live children and `onParentUpdate` delivery. A child execution is live from
+ * the moment its spawn (or inParallel path) starts running until it returns or
+ * is cleaned up. While it is live, every write of a parent layer's state is
+ * handed to the same layer's `onParentUpdate` in the child.
+ */
+import { defaultItemSchemaRegistry } from '@noetic-tools/types';
+import { callHook } from './hook-call.js';
+//#endregion
+//#region Public API
+const DEFAULT_TIMEOUT = 5e3;
+/**
+ * Builds the live-child registry a layer state store dispatches through.
+ * `store` is read lazily, so it may be the object under construction.
+ */
+export function createLiveChildren(store, skips) {
+    const byChild = new Map();
+    const byParent = new Map();
+    function forget(childExecutionId) {
+        const entry = byChild.get(childExecutionId);
+        if (!entry) {
+            return undefined;
+        }
+        byChild.delete(childExecutionId);
+        const siblings = byParent.get(entry.child.parentExecutionId);
+        siblings?.delete(entry);
+        if (siblings?.size === 0) {
+            byParent.delete(entry.child.parentExecutionId);
+        }
+        entry.open = false;
+        return entry;
+    }
+    return {
+        adopt(child) {
+            const entry = {
+                child,
+                queue: Promise.resolve(),
+                open: true,
+                gone: false,
+            };
+            byChild.set(child.ctx.executionId, entry);
+            let siblings = byParent.get(child.parentExecutionId);
+            if (!siblings) {
+                siblings = new Set();
+                byParent.set(child.parentExecutionId, siblings);
+            }
+            siblings.add(entry);
+        },
+        notify(parentExecutionId, layerId, state) {
+            const siblings = byParent.get(parentExecutionId);
+            if (!siblings) {
+                return;
+            }
+            for (const entry of siblings) {
+                const layer = entry.child.layers.find((l) => l.id === layerId);
+                if (!layer?.hooks.onParentUpdate) {
+                    continue;
+                }
+                entry.queue = entry.queue.then(() => deliver({
+                    entry,
+                    layer,
+                    parentState: state,
+                    store,
+                    skips,
+                }));
+            }
+        },
+        async release(childExecutionId) {
+            const entry = forget(childExecutionId);
+            await entry?.queue;
+        },
+        drop(childExecutionId) {
+            const entry = forget(childExecutionId);
+            if (entry) {
+                entry.gone = true;
+            }
+        },
+        get size() {
+            return byChild.size;
+        },
+    };
+}
+/** Runs one `onParentUpdate` call. Never rejects: failures become diagnostics. */
+async function deliver({ entry, layer, parentState, store, skips }) {
+    const { ctx, log, itemSchemas = defaultItemSchemaRegistry } = entry.child;
+    const onParentUpdate = layer.hooks.onParentUpdate;
+    if (!entry.open || !onParentUpdate || skips(ctx.executionId, layer)) {
+        return;
+    }
+    try {
+        const result = await callHook({
+            ctx,
+            layerId: layer.id,
+            hook: 'onParentUpdate',
+            timeout: layer.timeouts?.onParentUpdate ?? DEFAULT_TIMEOUT,
+            run: () => onParentUpdate({
+                parentState,
+                childState: store.get(ctx.executionId, layer.id),
+                childCtx: ctx,
+            }),
+        });
+        // A child cleaned up mid-call has no state left to write into.
+        if (!result || entry.gone) {
+            return;
+        }
+        if ('childState' in result) {
+            store.set(ctx.executionId, layer.id, result.childState);
+        }
+        for (const item of itemSchemas.extend(layer.itemSchemas).parseMany(result.items ?? [])) {
+            log.append(item);
+        }
+    }
+    catch (e) {
+        store.diagnostic(layer.id, 'onParentUpdate', e);
+    }
+}
+//#endregion

package/dist/context/span-export.d.ts

@@ -0,0 +1,7 @@
+import type { Span, TraceExporter } from '@noetic-tools/types';
+/**
+ * Hands ended spans to `exporter` without letting it fail the traced work: a
+ * rejecting (or throwing) exporter is reported once as a warning and
+ * swallowed, so tracing never changes what a hook, step, or call returns.
+ */
+export declare function exportSpans(exporter: TraceExporter, spans: Span[]): Promise<void>;

package/dist/context/span-export.js

@@ -0,0 +1,13 @@
+/**
+ * Hands ended spans to `exporter` without letting it fail the traced work: a
+ * rejecting (or throwing) exporter is reported once as a warning and
+ * swallowed, so tracing never changes what a hook, step, or call returns.
+ */
+export async function exportSpans(exporter, spans) {
+    try {
+        await exporter.export(spans);
+    }
+    catch (error) {
+        console.warn('[noetic] trace export failed; the traced work is unaffected:', error);
+    }
+}

package/dist/index.d.ts

@@ -3,13 +3,13 @@
  * ContextLayer contract, lifecycle/budget/projection machinery, and built-in
  * layer implementations.
  */
-export type { ContextScope, ExecutionContext, ExecutionOutcome, LayerCallModelRequest, } from '@noetic-tools/types';
+export type { ContextScope, ExecutionContext, ExecutionOutcome, ExecutionSpan, LayerCallModelRequest, } from '@noetic-tools/types';
 export * from '@noetic-tools/types/contract';
 export * from './context/budget.js';
 export * from './context/cache-anchoring.js';
 export * from './context/exec-context-factory.js';
 export * from './context/function-call-utils.js';
-export { LAYER_HOOK_EVENT } from './context/hook-call.js';
+export { LAYER_HOOK_EVENT, LayerHookAttr } from './context/hook-call.js';
 export * from './context/layer-api.js';
 export * from './context/layer-lifecycle.js';
 export * from './context/layer-provides.js';
@@ -25,7 +25,9 @@ export * from './context/layers/steering.js';
 export * from './context/layers/task-state.js';
 export * from './context/layers/temporal.js';
 export * from './context/layers/tool-calls.js';
+export type { LiveChild } from './context/parent-updates.js';
 export * from './context/projector.js';
 export * from './context/scope.js';
+export * from './context/span-export.js';
 export * from './context/storage-batch.js';
 export * from './context/strip-unresolved.js';

package/dist/index.js

@@ -11,7 +11,7 @@ export * from './context/budget.js';
 export * from './context/cache-anchoring.js';
 export * from './context/exec-context-factory.js';
 export * from './context/function-call-utils.js';
-export { LAYER_HOOK_EVENT } from './context/hook-call.js';
+export { LAYER_HOOK_EVENT, LayerHookAttr } from './context/hook-call.js';
 export * from './context/layer-api.js';
 export * from './context/layer-lifecycle.js';
 export * from './context/layer-provides.js';
@@ -29,5 +29,6 @@ export * from './context/layers/temporal.js';
 export * from './context/layers/tool-calls.js';
 export * from './context/projector.js';
 export * from './context/scope.js';
+export * from './context/span-export.js';
 export * from './context/storage-batch.js';
 export * from './context/strip-unresolved.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/context",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Context layer system for Noetic agents: the ContextLayer contract, lifecycle, budget/projection machinery, and built-in layer implementations.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@noetic-tools/types": "^3.8.0",
+    "@noetic-tools/types": "^3.9.0",
     "zod": "^4.0.0"
   },
   "scripts": {