@jangts/agent-core 0.2.5 → 0.3.6

package/dist/cjs/support/decorators/pool.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelPool = exports.agentPool = exports.workflowPool = exports.fragmentPool = exports.toolPool = exports.nodePool = exports.definitionKinds = void 0;
+exports.registerDefinition = registerDefinition;
+/**
+ * One process-realm definition registry per kind. The shared symbol makes ESM/CJS copies
+ * consume the same stores; consumers receive frozen read-only views, never pool factories.
+ */
+const protocol_registry_js_1 = require("../../utils/protocol-registry.js");
+/** Enumerable categories drive allocation and lookup; no additional runtime dispatch layer. */
+exports.definitionKinds = ['node', 'tool', 'fragment', 'workflow', 'agent', 'model'];
+const sharedKey = Symbol.for('@jangts/agent-core/decorator-roots/v2');
+const realm = globalThis;
+/** Allocate once per realm, including when another module format initialized the roots first. */
+function sharedPools() {
+    const existing = realm[sharedKey];
+    if (existing) {
+        if (existing.version !== 2 || exports.definitionKinds.some((kind) => !existing.stores[kind]))
+            throw new TypeError('Incompatible decorator root registry');
+        return existing;
+    }
+    const stores = Object.fromEntries(exports.definitionKinds.map((kind) => [kind, new Map()]));
+    const pools = Object.freeze({ version: 2, stores: Object.freeze(stores) });
+    Object.defineProperty(globalThis, sharedKey, { value: pools });
+    return pools;
+}
+/** Namespace is an exact, nonblank key; no trimming, fallback or hierarchy is applied. */
+function namespace(value) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError('Decorator namespace must be a nonempty string');
+    return value;
+}
+/** Preflight every destination so a conflict never leaves partial multi-namespace registration. */
+function registerDefinition(kind, definition, ns = 'default') {
+    if (typeof definition.id !== 'string' || !definition.id.trim())
+        throw new TypeError('Invalid decorator definition id');
+    const requested = typeof ns === 'string' ? [ns] : ns;
+    if (!Array.isArray(requested) || requested.length === 0)
+        throw new TypeError('Decorator ns must be a namespace or a nonempty namespace array');
+    const names = [...new Set(requested.map(namespace))];
+    const store = sharedPools().stores[kind];
+    for (const name of names) {
+        if (store.get(name)?.has(definition.id))
+            throw new Error(`Duplicate ${kind} definition: ${definition.id} (ns: ${name})`);
+    }
+    for (const name of names) {
+        let entries = store.get(name);
+        if (!entries)
+            store.set(name, (entries = new protocol_registry_js_1.ProtocolRegistry()));
+        entries.set(definition.id, definition);
+    }
+}
+/** Root reads never instantiate or execute definitions; array results are immutable snapshots. */
+function reader(kind) {
+    const store = sharedPools().stores[kind];
+    return Object.freeze({
+        get(id, ns = 'default') {
+            return store.get(namespace(ns))?.get(id);
+        },
+        getAll(ns = 'default') {
+            return Object.freeze([...(store.get(namespace(ns))?.values() ?? [])]);
+        },
+        pick(ids, ns = 'default') {
+            const entries = store.get(namespace(ns));
+            const selected = new protocol_registry_js_1.ProtocolRegistry();
+            for (const id of ids) {
+                const definition = entries?.get(id);
+                if (!definition)
+                    throw new TypeError(`Unknown ${kind} definition: ${id} (ns: ${ns})`);
+                selected.set(id, definition);
+            }
+            return Object.freeze([...selected.values()]);
+        },
+    });
+}
+/** Decorated nodes; ids are unique within each namespace. */
+exports.nodePool = reader('node');
+/** Decorated tools; namespaces isolate otherwise identical ids. */
+exports.toolPool = reader('tool');
+/** Decorated fragment configurations; use the original builder to assemble them. */
+exports.fragmentPool = reader('fragment');
+/** Decorated workflow definitions; execution still belongs to the original Engine. */
+exports.workflowPool = reader('workflow');
+/** Decorated Engine options; request-specific App contracts are supplied on typed reads. */
+exports.agentPool = reader('agent');
+/** Decorated Runner options; reading does not create a Runner or spend model calls. */
+exports.modelPool = reader('model');

package/dist/cjs/support/decorators/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/utils/invocation.js

@@ -46,6 +46,7 @@ function toolInvocation(request, arity) {
         throw new TypeError('Use one tool request with toolId and input');
     }
     return {
+        logger: request.logger,
         toolId: request.toolId,
         input: request.input,
         diagnostics: request.diagnostics,

package/dist/esm/capabilities/invocation.js

@@ -8,6 +8,7 @@
  *
  * Exports: `executeInvocation` and the invocation contracts re-exported at the bottom.
  */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { invocationId } from '../utils/invocation.js';
 import { synchronous } from '../utils/synchronous.js';
 import { diagnosticError } from '../diagnostics/index.js';
@@ -28,12 +29,30 @@ import { NodeReports } from '../execution/reporting.js';
  *   signal checks.
  */
 export function executeInvocation(invocation, input, context, ports = {}) {
+    let logger;
+    try {
+        logger = ports.logger?.(context);
+    }
+    catch {
+        /* Optional recording cannot block execution. */
+    }
+    const callId = invocationId();
+    return nativeSubFlowSync({
+        logger,
+        invocationId: callId,
+        get signal() {
+            return ports.signal?.(context);
+        },
+    }, 'invocation', invocation.id, (scopedLogger) => runInvocation(invocation, input, context, ports, scopedLogger, callId));
+}
+/** Execute the existing synchronous lifecycle without changing journal or error precedence. */
+function runInvocation(invocation, input, context, ports, logger, executionId = invocationId()) {
     const toolId = invocation.id;
     // Identify the call before touching the ports: journal and diagnostics records cannot be
     // reconciled with an anonymous handler.
     if (!toolId?.trim())
         throw new TypeError('Invalid invocation handler identity');
-    const journal = ports.journal?.(context), id = invocationId(), startedAtMs = Date.now();
+    const journal = ports.journal?.(context), id = executionId, startedAtMs = Date.now();
     const diagnostics = ports.diagnostics?.(context)?.child(id, {
         invocationId: id,
         nodeRole: 'invocation',
@@ -64,6 +83,7 @@ export function executeInvocation(invocation, input, context, ports = {}) {
         // The helper rejects a promise and drains its rejection: a handler that turns async must
         // fail here instead of escaping as an unhandled rejection.
         synchronous(invocation.call(input, context, {
+            logger,
             mode: 'sync',
             invocationId: id,
             signal: signal ?? new AbortController().signal,

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

@@ -27,7 +27,14 @@ function execute(definition, input, context, execution) {
         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();

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/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 {};