@jangts/agent-core 0.3.5 → 0.5.0

package/dist/esm/capabilities/tool-runtime.js

@@ -3,13 +3,14 @@
  *
  * A `ToolDefinition` is the App-facing declaration: a schema adapter plus authorize, execute
  * and parseOutput handlers. This module pins those handlers to their definition and adapts
- * them to the lower-level `ExecutableTool` contract, while keeping the synchronous and
+ * them to the lower-level `ErasedTool` contract, while keeping the synchronous and
  * asynchronous boundaries explicit: `invokeAsync` awaits authorization and execution,
  * `invoke` rejects a promise from either.
  *
  * Exports: `createToolRegistry`.
  */
 import { assertion, synchronous, isPromiseLike } from '../utils/synchronous.js';
+import { toolActive } from './tool-conditions.js';
 import { ToolRegistry } from './tools.js';
 /**
  * Run authorization and execution for one call, in that order.
@@ -18,16 +19,25 @@ import { ToolRegistry } from './tools.js';
  * violation instead of being silently ignored. Cancellation is checked before and after each
  * phase so an aborted request never produces a successful value.
  */
-function execute(definition, input, context, execution) {
+function execute(definition, input, context, execution, unavailable) {
     const { signal, mode, diagnostics, report, createSubFlowLogger } = execution;
     signal.throwIfAborted();
+    if (!toolActive(definition.active, context))
+        throw unavailable?.(definition.id) ?? new Error(`Tool is inactive: ${definition.id}`);
     // Re-check after the handler returned: work that completed during cancellation must not be
     // reported as a success.
     const complete = (value) => {
         signal.throwIfAborted();
         return value;
     };
-    const operation = { app: context, signal, diagnostics, report, createSubFlowLogger };
+    const operation = {
+        app: context,
+        signal,
+        diagnostics,
+        logger: execution.logger,
+        report,
+        createSubFlowLogger,
+    };
     const authorized = (result) => {
         assertion(result, 'Tool authorization must return void');
         signal.throwIfAborted();
@@ -58,6 +68,7 @@ function execute(definition, input, context, execution) {
  */
 export function createToolRegistry(definitions, context, options) {
     const registry = new ToolRegistry(options);
+    const unavailable = options.errors?.unavailable?.bind(options.errors);
     registry.registerAll(definitions.map((definition) => {
         // Every entry point pins the same canonical handlers, including callers
         // that use this creator directly rather than defineToolCatalog.
@@ -67,6 +78,9 @@ export function createToolRegistry(definitions, context, options) {
             kind,
             description,
             inputSchema,
+            active: typeof definition.active === 'function'
+                ? definition.active.bind(definition)
+                : definition.active,
             authorize: authorize.bind(definition),
             execute: handle.bind(definition),
             parseOutput: parseOutput.bind(definition),
@@ -80,7 +94,7 @@ export function createToolRegistry(definitions, context, options) {
             // definition cannot change what this registry validates.
             parseInput: inputSchema.parse.bind(inputSchema),
             parseOutput: bound.parseOutput,
-            execute: (input, execution) => execute(bound, input, context, execution),
+            execute: (input, execution) => execute(bound, input, context, execution, unavailable),
         };
     }));
     registry.seal();

package/dist/esm/capabilities/tools.d.ts

@@ -1,10 +1,10 @@
 import type { ToolResult } from '../structs/invocation.js';
-import type { ExecutableTool, RegisteredTool, ToolExecutionEvent, ToolRegistryPorts, ToolRegistryOptions, ToolInvocationRequest } from '../structs/capabilities/tools.js';
+import type { ErasedTool, RegisteredTool, ToolExecutionEvent, ToolRegistryPorts, ToolRegistryOptions, ToolInvocationRequest } from '../structs/capabilities/tools.js';
 /**
  * Registry mechanism only: visibility, authorization policy, schemas and semantic metadata
  * are host registrations. A registry is mutable until sealed and keeps its own call log.
  */
-export declare class ToolRegistry<Tool extends ExecutableTool = ExecutableTool> {
+export declare class ToolRegistry<Tool extends ErasedTool = ErasedTool> {
     /** Insertion order is the declaration order and is preserved by every enumeration below. */
     private readonly tools;
     /** Sealing is one-way: a running stage must not add tools to the registry it executes. */
@@ -117,6 +117,6 @@ export declare class ToolRegistry<Tool extends ExecutableTool = ExecutableTool>
      */
     seal(): this;
 }
-export type { ToolDefinition, ToolExecutionContext, ExecutableTool, RegisteredTool, ToolExecutionEvent, ToolRegistryPorts, ToolRegistryOptions, ToolInvocationRequest, } from '../structs/capabilities/tools.js';
+export type { ToolDefinition, ToolExecutionContext, ErasedTool, RegisteredTool, ToolExecutionEvent, ToolRegistryPorts, ToolRegistryOptions, ToolInvocationRequest, } from '../structs/capabilities/tools.js';
 export { executeInvocation } from './invocation.js';
 export type { InvocationHandler, ToolInvocationPorts, ToolJournal, } from '../structs/capabilities/invocation.js';

package/dist/esm/capabilities/tools.js

@@ -11,6 +11,7 @@
  *
  * Exports: `ToolRegistry`, `executeInvocation`, and the tool/invocation contracts.
  */
+import { nativeSubFlowSync, nativeSubFlowAsync } from '../diagnostics/native-sub-flow.js';
 import { executionEvents } from '../execution/events.js';
 import { invocationId as nextInvocationId, invocationResult, toolInvocation, } from '../utils/invocation.js';
 import { synchronous } from '../utils/synchronous.js';
@@ -116,7 +117,8 @@ export class ToolRegistry {
      */
     invoke(request) {
         const call = toolInvocation(request, arguments.length);
-        return this.execute(call.toolId, call.input, false, call.diagnostics, call.signal);
+        const callId = nextInvocationId();
+        return nativeSubFlowSync({ ...call, signal: combineSignals(this.ports.signal, call.signal), invocationId: callId }, 'tool', call.toolId, (scopedLogger) => this.execute(call.toolId, call.input, false, call.diagnostics, call.signal, scopedLogger, callId));
     }
     /**
      * Invoke a registered tool and await its result.
@@ -128,7 +130,8 @@ export class ToolRegistry {
      */
     async invokeAsync(request) {
         const call = toolInvocation(request, arguments.length);
-        return (await this.execute(call.toolId, call.input, true, call.diagnostics, call.signal));
+        const callId = nextInvocationId();
+        return nativeSubFlowAsync({ ...call, signal: combineSignals(this.ports.signal, call.signal), invocationId: callId }, 'tool', call.toolId, (scopedLogger) => this.execute(call.toolId, call.input, true, call.diagnostics, call.signal, scopedLogger, callId));
     }
     /**
      * Run one call: validate, parse input, execute, parse output, then record the outcome.
@@ -140,7 +143,7 @@ export class ToolRegistry {
      * @param requestSignal Per-call signal, combined with the request-lifetime signal.
      * @returns The frozen result on success; every failure path throws.
      */
-    execute(name, input, asynchronous, parentDiagnostics = this.diagnostics, requestSignal) {
+    execute(name, input, asynchronous, parentDiagnostics = this.diagnostics, requestSignal, logger, callId = nextInvocationId()) {
         // A tool call stays inside the run that invoked it: mixing two diagnostic trees would
         // produce records with two parents and break run-scoped correlation.
         if (this.diagnostics?.identity?.runId &&
@@ -152,7 +155,7 @@ export class ToolRegistry {
             throw this.ports.unavailable?.(name) ?? new Error(`Tool is not registered: ${name}`);
         // Either signal may cancel the call; combining them keeps both lifetimes effective.
         const signal = combineSignals(this.ports.signal, requestSignal);
-        const invocationId = nextInvocationId();
+        const invocationId = callId;
         const diagnostics = parentDiagnostics?.child(invocationId, {
             invocationId,
             nodeRole: 'invocation',
@@ -190,24 +193,15 @@ export class ToolRegistry {
         };
         const succeed = (result) => {
             signal.throwIfAborted();
-            let debug = reports.debug();
             if (tool.debugSteps && diagnostics?.enabled('tool.result', 'content')) {
                 try {
-                    debug = reports.debug({
-                        subs: synchronous(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous'),
-                    });
+                    synchronous(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous');
                 }
-                catch (error) {
-                    // Debug material is optional evidence: it must not turn a successful tool call into
-                    // a failure. Defer the error until a consumer actually asks for the sub-steps.
-                    debug = {
-                        usedModel: reports.debug().usedModel,
-                        subSteps: () => {
-                            throw error;
-                        },
-                    };
+                catch {
+                    diagnostics?.emit('node.progress', () => ({ reportError: 'INVALID_NODE_REPORT' }));
                 }
             }
+            const debug = reports.debug();
             signal.throwIfAborted();
             reports.close();
             diagnostics?.emit('tool.result', () => ({
@@ -277,6 +271,7 @@ export class ToolRegistry {
             signal.throwIfAborted();
             phase = 'execute';
             const value = tool.execute(parsed, {
+                logger,
                 mode: asynchronous ? 'async' : 'sync',
                 invocationId,
                 signal,

package/dist/esm/context/audit.js

@@ -32,13 +32,10 @@ export function auditContextChange(original, current, mutable) {
         const changed = JSON.stringify(before.value) !== JSON.stringify(after.value);
         breakWhile(changed &&
             (!mutable.has(before.id) || before.role === 'system' || before.trust === 'instruction'), fail(`Protected context changed: ${before.id}`));
-        if (changed &&
-            before.value !== null &&
-            after.value !== null &&
-            typeof before.value === 'object' &&
-            typeof after.value === 'object')
-            // Only the field set is compared here; field order is not meaningful for context data.
-            breakWhile(JSON.stringify(Object.keys(before.value).sort()) !==
-                JSON.stringify(Object.keys(after.value).sort()), fail('Context fields must be preserved'));
+        if (changed && typeof before.value === 'object' && typeof after.value === 'object')
+            // A null value carries no fields. Treat it as an empty field set so turning it into an
+            // object, or dropping an object back to null, is still rejected as a structural change.
+            breakWhile(JSON.stringify(Object.keys(before.value ?? {}).sort()) !==
+                JSON.stringify(Object.keys(after.value ?? {}).sort()), fail('Context fields must be preserved'));
     }
 }

package/dist/esm/context/index.d.ts

@@ -5,14 +5,13 @@
  * Core owns the guarantees here. A fragment declares its trust, lifetime and character
  * budget in one place; assembly validates those declarations and refuses to truncate;
  * auditing rejects structural change to protected fragments. Selection, ordering, compression
- * and model choice remain App-side nodes that run before this boundary.
+ * and model choice remain App-side nodes that run before this boundary. Optional Kit helpers
+ * such as evidence checks are imported from their own `/kits/*` entries, not from here.
  *
- * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal`, the fragment helpers,
- * and the evidence Kit helpers consumed alongside assembled context.
+ * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal` and the fragment helpers.
  */
 export * from './fragments.js';
 export { assembleFragments } from './assembly.js';
 export * from './journal.js';
-export * from '../kits/evidence.js';
 export type { ContextPlan } from '../structs/context/processing.js';
 export { assembleContextPlan } from './plan.js';

package/dist/esm/context/index.js

@@ -5,13 +5,12 @@
  * Core owns the guarantees here. A fragment declares its trust, lifetime and character
  * budget in one place; assembly validates those declarations and refuses to truncate;
  * auditing rejects structural change to protected fragments. Selection, ordering, compression
- * and model choice remain App-side nodes that run before this boundary.
+ * and model choice remain App-side nodes that run before this boundary. Optional Kit helpers
+ * such as evidence checks are imported from their own `/kits/*` entries, not from here.
  *
- * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal`, the fragment helpers,
- * and the evidence Kit helpers consumed alongside assembled context.
+ * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal` and the fragment helpers.
  */
 export * from './fragments.js';
 export { assembleFragments } from './assembly.js';
 export * from './journal.js';
-export * from '../kits/evidence.js';
 export { assembleContextPlan } from './plan.js';

package/dist/esm/diagnostics/index.d.ts

@@ -1,6 +1,7 @@
 import type { DiagnosticContext, CreateDiagnosticsOptions } from '../structs/diagnostics.js';
 export * from '../structs/diagnostics.js';
 export * from './catalog.js';
+export { SubFlowLogger, ScopedSubFlowLogger } from './sub-flow.js';
 export type * from '../structs/debug.js';
 export { reportedStepStatusCatalog, reportedStepStatuses } from '../structs/debug.js';
 /**

package/dist/esm/diagnostics/index.js

@@ -17,6 +17,7 @@ import { payloadSnapshot } from './sub-flow.js';
 import { breakWhile } from '../utils/rules.js';
 export * from '../structs/diagnostics.js';
 export * from './catalog.js';
+export { SubFlowLogger, ScopedSubFlowLogger } from './sub-flow.js';
 export { reportedStepStatusCatalog, reportedStepStatuses } from '../structs/debug.js';
 /**
  * Configure the optional log consumer of the shared execution fact source.
@@ -107,7 +108,7 @@ export function normalizeDiagnosticEvent(input) {
     // The count and size bounds match what the sub-flow logger enforces, so a record produced by
     // Core can never be rejected here; only hand-edited or foreign records can.
     if (!Array.isArray(steps) ||
-        steps.length > 256 ||
+        steps.length > 1024 ||
         new Set(steps.map((step) => step?.stepId)).size !== steps.length ||
         steps.some((step) => !step ||
             step.origin !== 'reported' ||
@@ -118,7 +119,15 @@ export function normalizeDiagnosticEvent(input) {
             !Number.isSafeInteger(step.sequence) ||
             step.sequence < 1 ||
             (step.status !== undefined && !reportedStepStatuses.includes(step.status)) ||
-            ['parentStepId', 'relatedDefinitionId', 'caseId', 'summary'].some((key) => step[key] !== undefined && typeof step[key] !== 'string') ||
+            [
+                'type',
+                'subnodeId',
+                'parentStepId',
+                'relatedDefinitionId',
+                'relatedInvocationId',
+                'caseId',
+                'summary',
+            ].some((key) => step[key] !== undefined && typeof step[key] !== 'string') ||
             (step.usedModel !== undefined && typeof step.usedModel !== 'boolean') ||
             (step.revision !== undefined &&
                 (!Number.isSafeInteger(step.revision) ||
@@ -133,6 +142,37 @@ export function normalizeDiagnosticEvent(input) {
             (!Number.isSafeInteger(raw.subStepsDropped) || Number(raw.subStepsDropped) < 0)) ||
         (raw.subStepsTruncated !== undefined && typeof raw.subStepsTruncated !== 'boolean'))
         throw new TypeError('Invalid reported diagnostic steps');
+    const originals = new Map();
+    let lastSequence = 0;
+    for (const step of steps) {
+        if (step.operation === undefined)
+            continue; // Historical projected snapshots remain readable.
+        breakWhile(!['write', 'fix'].includes(step.operation) || step.sequence <= lastSequence, () => new TypeError('Invalid sub-flow record order'));
+        lastSequence = step.sequence;
+        if (step.operation === 'write') {
+            breakWhile(step.targetStepId !== undefined || step.revision !== 1, () => new TypeError('Invalid sub-flow write record'));
+            originals.set(step.stepId, {
+                revision: 1,
+                subnodeId: step.subnodeId,
+                type: step.type,
+                relatedInvocationId: step.relatedInvocationId,
+            });
+        }
+        else {
+            const previous = originals.get(step.targetStepId);
+            breakWhile(previous === undefined ||
+                step.revision !== previous.revision + 1 ||
+                step.subnodeId !== previous.subnodeId ||
+                step.type !== previous.type ||
+                step.relatedInvocationId !== previous.relatedInvocationId, () => new TypeError('Invalid sub-flow fix reference'));
+            originals.set(step.targetStepId, {
+                revision: step.revision,
+                subnodeId: step.subnodeId,
+                type: step.type,
+                relatedInvocationId: step.relatedInvocationId,
+            });
+        }
+    }
     // Structural check only: the returned snapshot is discarded because the clone below already
     // produces the detached copy kept by the normalized record.
     for (const step of steps)
@@ -145,8 +185,14 @@ export function normalizeDiagnosticEvent(input) {
         breakWhile(progress !== undefined &&
             (!progress ||
                 !['write', 'fix'].includes(progress.operation) ||
+                ['type', 'subnodeId', 'relatedInvocationId'].some((key) => progress[key] !== undefined &&
+                    typeof progress[key] !== 'string') ||
                 typeof progress.stepId !== 'string' ||
                 !progress.stepId ||
+                (progress.targetStepId !== undefined &&
+                    (progress.operation !== 'fix' ||
+                        typeof progress.targetStepId !== 'string' ||
+                        !progress.targetStepId)) ||
                 !Number.isSafeInteger(progress.sequence) ||
                 progress.sequence < 1 ||
                 !Number.isSafeInteger(progress.revision) ||

package/dist/esm/diagnostics/native-sub-flow.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Optional fixed sub-flow records for native execution boundaries.
+ *
+ * Callers choose the logger explicitly. A full logger issues a scoped delegate for this call; already-scoped Kit contexts reuse
+ * their delegate. Neither path creates storage or changes execution and cancellation.
+ * Logging failures are isolated from the wrapped operation.
+ *
+ * Exports: nativeSubFlowCatalog, nativeSubFlowSync, nativeSubFlowAsync.
+ */
+import type { SubFlowLog, ScopedSubFlowLogger } from '../structs/debug.js';
+/** Fixed metadata shared by native producers; pure getters and formatters are not producers. */
+export declare const nativeSubFlowCatalog: {
+    readonly model: {
+        readonly name: "Model call";
+        readonly kind: "model";
+        readonly type: "model.call";
+    };
+    readonly tool: {
+        readonly name: "Tool call";
+        readonly kind: "tool";
+        readonly type: "tool.call";
+    };
+    readonly invocation: {
+        readonly name: "Invocation";
+        readonly kind: "invocation";
+        readonly type: "handler.call";
+    };
+    readonly retrieval: {
+        readonly name: "Retrieval";
+        readonly kind: "retrieval";
+        readonly type: "retrieval.run";
+    };
+    readonly task: {
+        readonly name: "Read answer evidence";
+        readonly kind: "retrieval";
+        readonly type: "evidence.read";
+    };
+    readonly check: {
+        readonly name: "Check answer";
+        readonly kind: "validation";
+        readonly type: "answer.check";
+    };
+    readonly output: {
+        readonly name: "Compose output";
+        readonly kind: "presentation";
+        readonly type: "output.compose";
+    };
+    readonly answer: {
+        readonly name: "Answer flow";
+        readonly kind: "answering";
+        readonly type: "answer.run";
+    };
+    readonly retry: {
+        readonly name: "Retry model proposal";
+        readonly kind: "recovery";
+        readonly type: "model.retry";
+    };
+    readonly context: {
+        readonly name: "Process context";
+        readonly kind: "context";
+        readonly type: "context.process";
+    };
+    readonly recovery: {
+        readonly name: "Recovery attempt";
+        readonly kind: "recovery";
+        readonly type: "recovery.try";
+    };
+    readonly delivery: {
+        readonly name: "Deliver result";
+        readonly kind: "delivery";
+        readonly type: "delivery.run";
+    };
+    readonly aggregation: {
+        readonly name: "Aggregate queries";
+        readonly kind: "retrieval";
+        readonly type: "queries.collect";
+    };
+    readonly knowledge: {
+        readonly name: "Read knowledge";
+        readonly kind: "retrieval";
+        readonly type: "knowledge.read";
+    };
+};
+type Producer = keyof typeof nativeSubFlowCatalog;
+type Context = {
+    readonly logger?: SubFlowLog;
+    readonly signal?: AbortSignal;
+    readonly invocationId?: string;
+};
+/** Preserve a synchronous boundary while pairing an optional write with one result revision. */
+export declare function nativeSubFlowSync<Value>(context: Context, producer: Producer, id: string, invoke: (logger?: ScopedSubFlowLogger) => Value): Value;
+/** Await the original operation without introducing another timeout or cancellation race. */
+export declare function nativeSubFlowAsync<Value>(context: Context, producer: Producer, id: string, invoke: (logger?: ScopedSubFlowLogger) => Value | PromiseLike<Value>): Promise<Value>;
+export {};

package/dist/esm/diagnostics/native-sub-flow.js

@@ -0,0 +1,101 @@
+import { SubFlowLogger, requireSubFlowLogger, bindNativeSubFlowLogger } from './sub-flow.js';
+/** Fixed metadata shared by native producers; pure getters and formatters are not producers. */
+export const nativeSubFlowCatalog = {
+    model: { name: 'Model call', kind: 'model', type: 'model.call' },
+    tool: { name: 'Tool call', kind: 'tool', type: 'tool.call' },
+    invocation: { name: 'Invocation', kind: 'invocation', type: 'handler.call' },
+    retrieval: { name: 'Retrieval', kind: 'retrieval', type: 'retrieval.run' },
+    task: { name: 'Read answer evidence', kind: 'retrieval', type: 'evidence.read' },
+    check: { name: 'Check answer', kind: 'validation', type: 'answer.check' },
+    output: { name: 'Compose output', kind: 'presentation', type: 'output.compose' },
+    answer: { name: 'Answer flow', kind: 'answering', type: 'answer.run' },
+    retry: { name: 'Retry model proposal', kind: 'recovery', type: 'model.retry' },
+    context: { name: 'Process context', kind: 'context', type: 'context.process' },
+    recovery: { name: 'Recovery attempt', kind: 'recovery', type: 'recovery.try' },
+    delivery: { name: 'Deliver result', kind: 'delivery', type: 'delivery.run' },
+    aggregation: { name: 'Aggregate queries', kind: 'retrieval', type: 'queries.collect' },
+    knowledge: { name: 'Read knowledge', kind: 'retrieval', type: 'knowledge.read' },
+};
+/** Start one fixed record; its revision is best-effort and never controls the operation. */
+function begin(context, producer, id) {
+    let logger;
+    try {
+        logger =
+            context.logger instanceof SubFlowLogger
+                ? bindNativeSubFlowLogger(context.logger, producer, id)
+                : context.logger;
+    }
+    catch {
+        /* A recording limit must not turn a valid operation into a failure. */
+    }
+    let step = -1;
+    try {
+        if (logger)
+            step = logger.write({
+                ...nativeSubFlowCatalog[producer],
+                relatedDefinitionId: id,
+                ...(context.invocationId === undefined
+                    ? {}
+                    : { relatedInvocationId: context.invocationId }),
+                status: 'running',
+            });
+    }
+    catch {
+        /* Optional recording must not change execution. */
+    }
+    return {
+        logger,
+        finish: (status) => {
+            try {
+                if (logger && step !== -1)
+                    logger.fix(step, { status });
+            }
+            catch {
+                /* A broken or detached logger cannot replace the operation result. */
+            }
+        },
+    };
+}
+/** Signal access is diagnostic metadata and cannot replace an operation failure. */
+function failureStatus(context) {
+    try {
+        return context.signal?.aborted ? 'cancelled' : 'error';
+    }
+    catch {
+        return 'error';
+    }
+}
+/** Preserve a synchronous boundary while pairing an optional write with one result revision. */
+export function nativeSubFlowSync(context, producer, id, invoke) {
+    if (producer === 'model' || producer === 'tool' || producer === 'invocation')
+        requireSubFlowLogger(context.logger);
+    if (!context.logger)
+        return invoke();
+    const { logger, finish } = begin(context, producer, id);
+    try {
+        const value = invoke(logger);
+        finish('success');
+        return value;
+    }
+    catch (error) {
+        finish(failureStatus(context));
+        throw error;
+    }
+}
+/** Await the original operation without introducing another timeout or cancellation race. */
+export async function nativeSubFlowAsync(context, producer, id, invoke) {
+    if (producer === 'model' || producer === 'tool' || producer === 'invocation')
+        requireSubFlowLogger(context.logger);
+    if (!context.logger)
+        return invoke();
+    const { logger, finish } = begin(context, producer, id);
+    try {
+        const value = await invoke(logger);
+        finish('success');
+        return value;
+    }
+    catch (error) {
+        finish(failureStatus(context));
+        throw error;
+    }
+}

package/dist/esm/diagnostics/sub-flow.d.ts

@@ -1,5 +1,12 @@
-import type { RecordedSubStep, SubFlowLogger, SubStepProgress, SubFlowValue } from '../structs/debug.js';
+import type { RecordedSubStep, SubFlowLog, SubFlowStepInput, SubFlowStepFix, SubStepProgress, SubFlowValue } from '../structs/debug.js';
 import type { DiagnosticIdentity } from '../structs/diagnostics.js';
+type Step = RecordedSubStep & Required<Pick<RecordedSubStep, 'createdAtMs' | 'revision' | 'status'>>;
+/** Validate a committed snapshot without consulting its logger or invoking App code. */
+export declare function captureSubFlowSnapshot(steps: readonly Readonly<RecordedSubStep>[] | undefined, identity?: Readonly<DiagnosticIdentity>): {
+    subSteps: readonly Readonly<RecordedSubStep>[];
+    subStepsDropped: number;
+    subStepsTruncated: boolean;
+};
 /**
  * Validate and deep-copy a reported payload.
  *
@@ -14,6 +21,48 @@ import type { DiagnosticIdentity } from '../structs/diagnostics.js';
  *   limits below.
  */
 export declare function payloadSnapshot(input: unknown): Readonly<Record<string, SubFlowValue>>;
+/** Stable diagnostic reasons; untrusted error text and caller payloads never reach the console. */
+declare const rejectionReasons: {
+    readonly inactive: "logger is detached or execution is cancelled";
+    readonly scope: "target does not belong to this subnode";
+    readonly target: "original write record was not found";
+    readonly fields: "input contains a forbidden field";
+    readonly transition: "status transition is not allowed";
+    readonly sealed: "an established fact cannot be overwritten";
+    readonly limit: "recording limit exceeded";
+    readonly input: "invalid input or result patch";
+};
+type RejectionReason = keyof typeof rejectionReasons;
+/** Unexported issuance token prevents constructing counterfeit full or scoped loggers. */
+declare const loggerToken: unique symbol;
+type Store = SubFlowLog & {
+    owns(stepId: string | -1, subnodeId: string): boolean;
+    isActive(): boolean;
+    nextNativeSubnodeId(kind: string, definitionId: string): string;
+    warn(operation: 'write' | 'fix', reason: RejectionReason): void;
+};
+/** Full execution-owned recorder. Owns its store and may issue restricted delegates. */
+export declare class SubFlowLogger implements SubFlowLog {
+    #private;
+    constructor(token: typeof loggerToken, store: Store);
+    write(input: SubFlowStepInput): string | -1;
+    fix(stepId: string | -1, patch: SubFlowStepFix): boolean;
+    readAll(): readonly Readonly<RecordedSubStep>[];
+    /** Issue a delegate for an App-owned logical group; no execution or scheduling is implied. */
+    fork(subnodeId: string): ScopedSubFlowLogger;
+}
+/** Non-inheriting delegate. Stores only the original logger and its bound subnode identity. */
+export declare class ScopedSubFlowLogger implements SubFlowLog {
+    #private;
+    constructor(token: typeof loggerToken, logger: SubFlowLogger, subnodeId: string);
+    write(input: Omit<SubFlowStepInput, 'subnodeId'>): string | -1;
+    fix(stepId: string | -1, patch: SubFlowStepFix): boolean;
+    readAll(): readonly Readonly<RecordedSubStep>[];
+}
+/** Runtime check complements nominal invocation types; scoped or forged inputs cannot invoke. */
+export declare function requireSubFlowLogger(logger: unknown): asserts logger is SubFlowLogger | undefined;
+/** Allocate a short node-local group; the owning node visit already supplies the namespace. */
+export declare function bindNativeSubFlowLogger(logger: SubFlowLogger, kind: string, definitionId: string): ScopedSubFlowLogger;
 /**
  * Create a logger bound to one active execution visit.
  *
@@ -22,14 +71,14 @@ export declare function payloadSnapshot(input: unknown): Readonly<Record<string,
  *
  * @param owner Object that owns the visit. `readSubFlowLogger` compares this identity before
  *   returning any step.
- * @param active Reports whether the visit is still open; a closed logger rejects writes.
+ * @param active Reports whether the visit is still open; a detached logger returns write=-1 and fix=false.
  * @param content Reports whether content-level detail is enabled. When false, summaries and
  *   payloads are dropped before anything is stored.
- * @param changed Called after each accepted write or fix with the progress delta to publish.
+ * @param changed Runtime receiver called after each accepted write/fix with its delta and immutable snapshot.
  * @param identity Diagnostic run and span the logger belongs to; used to reject cross-scope reads.
  * @returns A frozen logger instance.
  */
-export declare function createSubFlowLogger(owner: object, active: () => boolean, content: () => boolean, changed: (logger: SubFlowLogger, progress: SubStepProgress) => void, identity?: Readonly<DiagnosticIdentity>): SubFlowLogger;
+export declare function createSubFlowLogger(owner: object, active: () => boolean, content: () => boolean, changed: (logger: SubFlowLogger, progress: SubStepProgress, steps: readonly Step[]) => void, identity?: Readonly<DiagnosticIdentity>): SubFlowLogger;
 /**
  * Read the steps recorded by a logger issued by this module.
  *
@@ -44,3 +93,6 @@ export declare function createSubFlowLogger(owner: object, active: () => boolean
  *   belongs to another diagnostic scope.
  */
 export declare function readSubFlowLogger(input: unknown, owner?: object, identity?: Readonly<DiagnosticIdentity>): readonly Readonly<RecordedSubStep>[];
+/** Release execution callbacks while preserving the instance's immutable query history. */
+export declare function detachSubFlowLogger(logger: SubFlowLogger): void;
+export {};