@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/context/fragments.js

@@ -1,28 +1,71 @@
 import { ValidationError } from '../structs/errors.js';
 import { breakWhile } from '../utils/rules.js';
-/** Validate one fragment before formatting. The shared set preserves registration order. */
+/**
+ * Validate one fragment and return the text it contributes to the model input.
+ *
+ * @param fragment Declaration to check.
+ * @param ids Optional accumulator of ids already seen. Callers validating a batch pass the
+ *   same set for every fragment so duplicates are detected across the whole input.
+ * @param checkBudget Whether this fragment's own `maxChars` is enforced. Disable only when the
+ *   same serialized text has already been checked against the identical limit.
+ * @returns The exact text the fragment contributes: the value when it is a string, otherwise
+ *   the JSON form used for structured fields.
+ * @throws Error when identity, trust, lifetime, role, the `maxChars` declaration or the value
+ *   shape is invalid, or when untrusted content is declared as a system instruction.
+ * @throws ValidationError when the serialized text exceeds `maxChars`; text is never truncated.
+ */
 export function validateContextFragment(fragment, ids = new Set(), checkBudget = true) {
-    if (!/^[a-z][a-zA-Z0-9:._-]*$/.test(fragment.id) || ids.has(fragment.id) || !fragment.sourceId
-        || !['instruction', 'server', 'user', 'tool'].includes(fragment.trust)
-        || !['configuration', 'turn', 'step'].includes(fragment.lifetime) || !['system', 'user'].includes(fragment.role)
-        || !Number.isSafeInteger(fragment.maxChars) || fragment.maxChars < 1)
+    // Ids are stable keys in usage records and protected-context errors, so they start with a
+    // lowercase letter and admit only characters that are safe in both positions.
+    if (!/^[a-z][a-zA-Z0-9:._-]*$/.test(fragment.id) ||
+        ids.has(fragment.id) ||
+        !fragment.sourceId ||
+        !['instruction', 'server', 'user', 'tool'].includes(fragment.trust) ||
+        !['configuration', 'turn', 'step'].includes(fragment.lifetime) ||
+        !['system', 'user'].includes(fragment.role) ||
+        !Number.isSafeInteger(fragment.maxChars) ||
+        fragment.maxChars < 1)
         throw new Error('Invalid context fragment');
+    // Consumed before the later checks: a failed fragment must not leave its id reusable by a
+    // retry through the same accumulator.
     ids.add(fragment.id);
-    if (fragment.role === 'system' && (fragment.trust === 'user' || fragment.trust === 'tool' || typeof fragment.value !== 'string'))
+    if (fragment.role === 'system' &&
+        (fragment.trust === 'user' || fragment.trust === 'tool' || typeof fragment.value !== 'string'))
         throw new Error('Untrusted context cannot become a system instruction');
-    if (typeof fragment.value !== 'string' && (!fragment.value || typeof fragment.value !== 'object' || Array.isArray(fragment.value)))
+    if (typeof fragment.value !== 'string' &&
+        (!fragment.value || typeof fragment.value !== 'object' || Array.isArray(fragment.value)))
         throw new Error('Invalid context value');
+    // Structured values are measured as the JSON text that will be sent, so the declared budget
+    // describes the payload rather than the in-memory object.
     const serialized = typeof fragment.value === 'string' ? fragment.value : JSON.stringify(fragment.value);
     if (checkBudget && serialized.length > fragment.maxChars)
-        throw new ValidationError([{ code: 'CONTEXT_BUDGET', message: `上下文片段 ${fragment.id} 超过预算；不截断原问题、约束与证据。` }]);
+        throw new ValidationError([
+            {
+                code: 'CONTEXT_BUDGET',
+                message: `上下文片段 ${fragment.id} 超过预算；不截断原问题、约束与证据。`,
+            },
+        ]);
     return serialized;
 }
-/** Core input-budget boundary; helpers may retain their existing error presentation. */
+/**
+ * Enforce the character budget of the whole model input.
+ *
+ * @param inputChars Characters that will be sent; must be a non-negative safe integer.
+ * @param maxInputChars Budget limit. `Infinity` is accepted as an explicit "no limit", which
+ *   is why it is allowed in place of a safe integer.
+ * @param exceeded Optional factory for the over-budget error. Support may pass one to keep its
+ *   own message; Core otherwise raises a `CONTEXT_BUDGET` ValidationError.
+ * @returns Nothing.
+ * @throws TypeError when either count is not a non-negative integer.
+ * @throws Error when the budget is exceeded: the `exceeded` result, or a ValidationError.
+ */
 export function validateContextBudget(inputChars, maxInputChars, exceeded) {
     breakWhile(!Number.isSafeInteger(inputChars) || inputChars < 0, () => new TypeError('Invalid context input size'));
     breakWhile(maxInputChars !== Infinity && (!Number.isSafeInteger(maxInputChars) || maxInputChars < 0), () => new TypeError('Invalid context budget'));
     if (inputChars > maxInputChars)
-        throw exceeded?.(maxInputChars)
-            ?? new ValidationError([{ code: 'CONTEXT_BUDGET', message: `Model input exceeds ${maxInputChars} characters` }]);
+        throw (exceeded?.(maxInputChars) ??
+            new ValidationError([
+                { code: 'CONTEXT_BUDGET', message: `Model input exceeds ${maxInputChars} characters` },
+            ]));
 }
 export { commonPrefixLength } from '../utils/text.js';

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

@@ -1,3 +1,15 @@
+/**
+ * Context surface: fragment trust, per-fragment budgets, message assembly, structural audit,
+ * the request-local journal and plan assembly.
+ *
+ * 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.
+ *
+ * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal`, the fragment helpers,
+ * and the evidence Kit helpers consumed alongside assembled context.
+ */
 export * from './fragments.js';
 export { assembleFragments } from './assembly.js';
 export * from './journal.js';

package/dist/esm/context/index.js

@@ -1,3 +1,15 @@
+/**
+ * Context surface: fragment trust, per-fragment budgets, message assembly, structural audit,
+ * the request-local journal and plan assembly.
+ *
+ * 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.
+ *
+ * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal`, the fragment helpers,
+ * and the evidence Kit helpers consumed alongside assembled context.
+ */
 export * from './fragments.js';
 export { assembleFragments } from './assembly.js';
 export * from './journal.js';

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

@@ -3,16 +3,47 @@ import type { ToolJournal, ToolJournalStart, ToolJournalFinish } from '../struct
 import type { ContextRecord } from '../structs/context/journal.js';
 /** Request-local context projection of execution receipts; not a separate persistent log store. */
 export declare class ContextJournal implements ToolJournal {
+    /** Append-only: `producerSequence` is derived from this length, so order is never rewritten. */
     private readonly records;
+    /** Duplicate invocation ids are rejected instead of overwriting earlier history. */
     private readonly invocationIds;
+    /** Open tool calls, so a result can only close a call that actually started. */
     private readonly toolCalls;
-    model({ stageId, value, invocation }: {
+    /**
+     * Record one model-produced value.
+     *
+     * @param options.stageId Stage that produced the value.
+     * @param options.value Value to record; deep-cloned on write.
+     * @param options.invocation Execution identity whose `invocationId` must not be in the journal.
+     * @returns Nothing.
+     * @throws Error when the invocation id was already recorded.
+     */
+    model({ stageId, value, invocation, }: {
         stageId: string;
         value: unknown;
         invocation: InvocationMetadata;
     }): void;
+    /**
+     * Open a tool call.
+     *
+     * @param request Tool id, input and optional invocation metadata. A supplied invocation id is
+     *   kept so Core records and the journal share one identity; otherwise a new id is generated.
+     * @returns The invocation id that must be used to finish the call.
+     * @throws Error when a call with that id is already recorded.
+     */
     beginTool({ toolId, input, invocation }: ToolJournalStart): string;
+    /**
+     * Close an open tool call with its outcome.
+     *
+     * @param request Invocation id, terminal status and result value; the value is cloned into
+     *   the record.
+     * @returns Nothing.
+     * @throws Error when the call is unknown or was already finished.
+     */
     finishTool({ invocationId, status, value }: ToolJournalFinish): void;
+    /**
+     * @returns A detached copy of every record, safe for the caller to mutate.
+     */
     snapshot(): readonly ContextRecord[];
 }
 export type { ContextRecord } from '../structs/context/journal.js';

package/dist/esm/context/journal.js

@@ -1,35 +1,112 @@
+/**
+ * Request-local journal of context-relevant execution receipts.
+ *
+ * It records what was produced (model values, tool inputs) and what came back (tool results),
+ * each stamped with a monotonic producer sequence so a snapshot replays in order. Values are
+ * deep-cloned on write and on read: a caller mutating its own object cannot retroactively
+ * change recorded history, and a snapshot is not a live window into the journal.
+ *
+ * This is a projection, not a persistent log store; storage and retention belong to the App.
+ *
+ * Exports: `ContextJournal` and the `ContextRecord` type.
+ */
 import { invocationId as nextInvocationId } from '../utils/invocation.js';
 /** Request-local context projection of execution receipts; not a separate persistent log store. */
 export class ContextJournal {
+    /** Append-only: `producerSequence` is derived from this length, so order is never rewritten. */
     records = [];
+    /** Duplicate invocation ids are rejected instead of overwriting earlier history. */
     invocationIds = new Set();
+    /** Open tool calls, so a result can only close a call that actually started. */
     toolCalls = new Map();
-    model({ stageId, value, invocation }) {
+    /**
+     * Record one model-produced value.
+     *
+     * @param options.stageId Stage that produced the value.
+     * @param options.value Value to record; deep-cloned on write.
+     * @param options.invocation Execution identity whose `invocationId` must not be in the journal.
+     * @returns Nothing.
+     * @throws Error when the invocation id was already recorded.
+     */
+    model({ stageId, value, invocation, }) {
         if (this.invocationIds.has(invocation.invocationId))
             throw new Error('Duplicate journal invocation');
-        this.records.push({ ...invocation, producerSequence: this.records.length + 1, occurredAtMs: Date.now(), type: 'model', stageId, value: structuredClone(value) });
+        this.records.push({
+            ...invocation,
+            // Derived from the append position, so the sequence stays gap-free without a counter.
+            producerSequence: this.records.length + 1,
+            occurredAtMs: Date.now(),
+            type: 'model',
+            stageId,
+            value: structuredClone(value),
+        });
         this.invocationIds.add(invocation.invocationId);
     }
+    /**
+     * Open a tool call.
+     *
+     * @param request Tool id, input and optional invocation metadata. A supplied invocation id is
+     *   kept so Core records and the journal share one identity; otherwise a new id is generated.
+     * @returns The invocation id that must be used to finish the call.
+     * @throws Error when a call with that id is already recorded.
+     */
     beginTool({ toolId, input, invocation }) {
         const invocationId = invocation?.invocationId ?? nextInvocationId();
         if (this.invocationIds.has(invocationId))
             throw new Error('Duplicate journal invocation');
-        const record = { ...invocation, invocationId, startedAtMs: invocation?.startedAtMs ?? Date.now(), durationMs: 0, producerSequence: this.records.length + 1, occurredAtMs: Date.now(), type: 'tool', toolId, input: structuredClone(input) };
+        const record = {
+            ...invocation,
+            invocationId,
+            startedAtMs: invocation?.startedAtMs ?? Date.now(),
+            durationMs: 0,
+            producerSequence: this.records.length + 1,
+            occurredAtMs: Date.now(),
+            type: 'tool',
+            toolId,
+            input: structuredClone(input),
+        };
         this.records.push(record);
         this.invocationIds.add(invocationId);
         this.toolCalls.set(invocationId, { record, finished: false });
         return invocationId;
     }
+    /**
+     * Close an open tool call with its outcome.
+     *
+     * @param request Invocation id, terminal status and result value; the value is cloned into
+     *   the record.
+     * @returns Nothing.
+     * @throws Error when the call is unknown or was already finished.
+     */
     finishTool({ invocationId, status, value }) {
         const entry = this.toolCalls.get(invocationId);
         if (!entry || entry.finished)
             throw new Error('Invalid tool receipt');
         const call = entry.record;
         const occurredAtMs = Date.now();
-        this.records.push({ invocationId, runId: call.runId, spanId: call.spanId, parentSpanId: call.parentSpanId, parentInvocationId: call.parentInvocationId,
-            startedAtMs: call.startedAtMs, durationMs: occurredAtMs - call.startedAtMs,
-            producerSequence: this.records.length + 1, occurredAtMs, type: 'tool-result', toolId: call.toolId, status, value: structuredClone(value) });
+        this.records.push({
+            invocationId,
+            runId: call.runId,
+            spanId: call.spanId,
+            parentSpanId: call.parentSpanId,
+            parentInvocationId: call.parentInvocationId,
+            startedAtMs: call.startedAtMs,
+            durationMs: occurredAtMs - call.startedAtMs,
+            producerSequence: this.records.length + 1,
+            occurredAtMs,
+            type: 'tool-result',
+            toolId: call.toolId,
+            status,
+            value: structuredClone(value),
+        });
+        // Kept after finishing, so a repeated finish is rejected instead of appending a second
+        // result for the same call.
         entry.finished = true;
     }
-    snapshot() { return structuredClone(this.records); }
+    /**
+     * @returns A detached copy of every record, safe for the caller to mutate.
+     */
+    snapshot() {
+        return structuredClone(this.records);
+    }
 }

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

@@ -1,4 +1,14 @@
 import type { ContextPlan } from '../structs/context/processing.js';
 import type { BuiltContext } from '../structs/context/fragments.js';
-/** Generic input assembly only. Reduction, grouping and model selection are App-side nodes. */
+/**
+ * Build the model input for a context plan.
+ *
+ * @param plan Fragments, their budget, optional protected user messages, and the optional
+ *   originals/allow-list used for the structural audit.
+ * @returns The assembled context, including appended user messages and the final character
+ *   count that was checked against the budget.
+ * @throws ValidationError when the audit fails, a fragment is invalid or over its budget, or
+ *   the combined input exceeds the budget.
+ * @throws Error when an additional message is not a user message.
+ */
 export declare function assembleContextPlan(plan: ContextPlan): BuiltContext;

package/dist/esm/context/plan.js

@@ -1,15 +1,43 @@
+/**
+ * Assembly of a `ContextPlan`: the Core-side step between App context processing and the
+ * model input budget.
+ *
+ * A plan may carry trusted originals and an explicit mutation allow-list; when it does, the
+ * current fragments are audited before assembly. Assembly itself only validates, merges and
+ * measures. Reduction, grouping and model selection happen in App-side nodes before this
+ * point.
+ *
+ * Exports: `assembleContextPlan`.
+ */
 import { auditContextChange } from './audit.js';
 import { breakWhile } from '../utils/rules.js';
 import { assembleFragments } from './assembly.js';
 import { validateContextBudget } from './fragments.js';
-/** Generic input assembly only. Reduction, grouping and model selection are App-side nodes. */
+/**
+ * Build the model input for a context plan.
+ *
+ * @param plan Fragments, their budget, optional protected user messages, and the optional
+ *   originals/allow-list used for the structural audit.
+ * @returns The assembled context, including appended user messages and the final character
+ *   count that was checked against the budget.
+ * @throws ValidationError when the audit fails, a fragment is invalid or over its budget, or
+ *   the combined input exceeds the budget.
+ * @throws Error when an additional message is not a user message.
+ */
 export function assembleContextPlan(plan) {
+    // Audit first: a structural violation must surface as a policy error rather than be masked
+    // by a later budget or field-merge failure on fragments the plan did not allow to change.
     if (plan.originalFragments)
         auditContextChange(plan.originalFragments, plan.fragments, new Set(plan.mutableFragmentIds ?? []));
     const context = assembleFragments([...plan.fragments], plan.maxInputChars);
+    // Detach caller-owned messages: the built context must not change if the plan object is
+    // reused or mutated after assembly.
     const additional = structuredClone([...(plan.additionalMessages ?? [])]);
-    breakWhile(additional.some(message => message.role !== 'user' || typeof message.content !== 'string'), 'Additional context must be user messages');
+    // Only user messages may be appended: the system instruction is fixed by the fragments above.
+    breakWhile(additional.some((message) => message.role !== 'user' || typeof message.content !== 'string'), 'Additional context must be user messages');
     context.messages.push(...additional);
+    // The per-fragment budget already passed; this re-check covers the appended messages, which
+    // are outside every fragment's limit.
     context.inputChars += additional.reduce((sum, message) => sum + message.content.length, 0);
     validateContextBudget(context.inputChars, context.maxInputChars);
     return context;

package/dist/esm/diagnostics/catalog.js

@@ -1,7 +1,15 @@
 export const coreEventCatalog = {
-    'node.progress': 'metadata', 'model.start': 'metadata',
-    'model.binding': 'metadata', 'model.prepare': 'content', 'model.output': 'content', 'model.parsed': 'content', 'model.end': 'metadata',
+    'node.progress': 'metadata',
+    'model.start': 'metadata',
+    'model.binding': 'metadata',
+    'model.prepare': 'content',
+    'model.output': 'content',
+    'model.parsed': 'content',
+    'model.end': 'metadata',
     'runtime.rejected': 'metadata',
-    'loop.event': 'metadata', 'workflow.event': 'metadata', 'tool.call': 'metadata', 'tool.result': 'metadata',
+    'loop.event': 'metadata',
+    'workflow.event': 'metadata',
+    'tool.call': 'metadata',
+    'tool.result': 'metadata',
     'rule.result': 'metadata',
 };

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

@@ -3,8 +3,36 @@ export * from '../structs/diagnostics.js';
 export * from './catalog.js';
 export type * from '../structs/debug.js';
 export { reportedStepStatusCatalog, reportedStepStatuses } from '../structs/debug.js';
-/** Configure the optional log consumer of the shared execution fact source. */
+/**
+ * Configure the optional log consumer of the shared execution fact source.
+ *
+ * @param options.output Log consumer. Without it, events are still observable but not persisted.
+ * @param options.observe Live observer applied to this scope and every child scope.
+ * @param options.runId Run identity; a random id is generated when omitted.
+ * @param options.spanId Root span id; defaults to `run`.
+ * @returns A diagnostic context whose children share the run, sequence and consumers.
+ */
 export declare function createDiagnostics(options?: CreateDiagnosticsOptions): DiagnosticContext;
+/**
+ * Convert a thrown value into a plain record suitable as a log payload.
+ *
+ * @param error Any thrown value. Non-Errors are reported as `NonError` with their string form
+ *   and no issue details.
+ * @returns A record with name, message, stack, code, issues and whatever boundary metadata was
+ *   recorded. It never throws: an uninspectable value becomes `UninspectableError`.
+ */
 export declare function diagnosticError(error: unknown): Record<string, unknown>;
-/** Validate the current envelope and return a detached record without interpreting payloads. */
+/**
+ * Validate a persisted diagnostic record and return a detached copy.
+ *
+ * Persisted data is untrusted, so the envelope version, event type, identity, ordering and the
+ * bounded sub-step shape are checked; the payload itself is not interpreted. The copy is deep
+ * cloned, so a store cannot hand back a record that later shares structure with the caller.
+ *
+ * @param input Candidate record, typically parsed JSON from a log store.
+ * @returns A normalized record with `subSteps`, `subStepsDropped` and `subStepsTruncated`
+ *   defaulted.
+ * @throws TypeError when the envelope, identity, node role or reported steps are invalid.
+ * @throws RangeError when a reported payload is too large or too deeply nested.
+ */
 export declare function normalizeDiagnosticEvent(input: unknown): import('../structs/diagnostics.js').CoreDiagnosticRecord;

package/dist/esm/diagnostics/index.js

@@ -1,3 +1,14 @@
+/**
+ * Core diagnostics surface: one execution fact source shared by live observers and an optional
+ * log consumer.
+ *
+ * `createDiagnostics` configures the consumer, `diagnosticError` turns an arbitrary thrown value
+ * into a loggable record, and `normalizeDiagnosticEvent` re-validates a persisted record before
+ * it is trusted. Payload visibility comes from the event catalog, and a failing consumer never
+ * changes execution.
+ *
+ * Exports: the factory and helpers above, the event catalog, and the diagnostic types.
+ */
 import { createEventScope } from '../execution/events.js';
 import { reportedStepStatuses } from '../structs/debug.js';
 import { getErrorInfo } from '../errors.js';
@@ -7,10 +18,26 @@ import { breakWhile } from '../utils/rules.js';
 export * from '../structs/diagnostics.js';
 export * from './catalog.js';
 export { reportedStepStatusCatalog, reportedStepStatuses } from '../structs/debug.js';
-/** Configure the optional log consumer of the shared execution fact source. */
+/**
+ * Configure the optional log consumer of the shared execution fact source.
+ *
+ * @param options.output Log consumer. Without it, events are still observable but not persisted.
+ * @param options.observe Live observer applied to this scope and every child scope.
+ * @param options.runId Run identity; a random id is generated when omitted.
+ * @param options.spanId Root span id; defaults to `run`.
+ * @returns A diagnostic context whose children share the run, sequence and consumers.
+ */
 export function createDiagnostics(options = {}) {
     return createEventScope(options);
 }
+/**
+ * Convert a thrown value into a plain record suitable as a log payload.
+ *
+ * @param error Any thrown value. Non-Errors are reported as `NonError` with their string form
+ *   and no issue details.
+ * @returns A record with name, message, stack, code, issues and whatever boundary metadata was
+ *   recorded. It never throws: an uninspectable value becomes `UninspectableError`.
+ */
 export function diagnosticError(error) {
     const info = getErrorInfo(error);
     let detail;
@@ -18,43 +45,96 @@ export function diagnosticError(error) {
         if (!(error instanceof Error))
             return { name: 'NonError', message: String(error) };
         const { name, message, stack, code } = error;
-        detail = { name, message, stack, code: code ?? (info.code === 'UNKNOWN_ERROR' ? undefined : info.code) };
+        detail = {
+            name,
+            message,
+            stack,
+            code: code ?? (info.code === 'UNKNOWN_ERROR' ? undefined : info.code),
+        };
     }
     catch {
-        detail = { name: 'UninspectableError', message: 'Error details unavailable', code: info.code === 'UNKNOWN_ERROR' ? undefined : info.code };
+        detail = {
+            name: 'UninspectableError',
+            message: 'Error details unavailable',
+            code: info.code === 'UNKNOWN_ERROR' ? undefined : info.code,
+        };
     }
-    return { ...detail, issues: info.issues,
+    return {
+        ...detail,
+        issues: info.issues,
         ...(info.stageId === undefined ? {} : { stageId: info.stageId }),
-        ...(info.isRetryable === undefined ? {} : { isRetryable: info.isRetryable }) };
+        ...(info.isRetryable === undefined ? {} : { isRetryable: info.isRetryable }),
+    };
 }
-/** Validate the current envelope and return a detached record without interpreting payloads. */
+/**
+ * Validate a persisted diagnostic record and return a detached copy.
+ *
+ * Persisted data is untrusted, so the envelope version, event type, identity, ordering and the
+ * bounded sub-step shape are checked; the payload itself is not interpreted. The copy is deep
+ * cloned, so a store cannot hand back a record that later shares structure with the caller.
+ *
+ * @param input Candidate record, typically parsed JSON from a log store.
+ * @returns A normalized record with `subSteps`, `subStepsDropped` and `subStepsTruncated`
+ *   defaulted.
+ * @throws TypeError when the envelope, identity, node role or reported steps are invalid.
+ * @throws RangeError when a reported payload is too large or too deeply nested.
+ */
 export function normalizeDiagnosticEvent(input) {
     if (!input || typeof input !== 'object')
         throw new TypeError('Invalid diagnostic record');
     const raw = input;
+    // The version gates the whole layout: an older record may use different fields, so it is
+    // rejected instead of best-effort coerced.
     if (raw.version !== 2)
         throw new TypeError('Unsupported diagnostic version');
     const { type, producerSequence, occurredAtMs } = raw;
-    if (typeof type !== 'string' || !Object.hasOwn(coreEventCatalog, type) || typeof raw.runId !== 'string' || !raw.runId
-        || typeof raw.spanId !== 'string' || !raw.spanId || !Number.isSafeInteger(producerSequence) || Number(producerSequence) < 1
-        || typeof occurredAtMs !== 'number' || !Number.isFinite(occurredAtMs) || !Object.hasOwn(raw, 'payload'))
+    if (typeof type !== 'string' ||
+        !Object.hasOwn(coreEventCatalog, type) ||
+        typeof raw.runId !== 'string' ||
+        !raw.runId ||
+        typeof raw.spanId !== 'string' ||
+        !raw.spanId ||
+        !Number.isSafeInteger(producerSequence) ||
+        Number(producerSequence) < 1 ||
+        typeof occurredAtMs !== 'number' ||
+        !Number.isFinite(occurredAtMs) ||
+        !Object.hasOwn(raw, 'payload'))
         throw new TypeError('Invalid diagnostic envelope');
     const { eventId } = raw;
     if (typeof eventId !== 'string' || !eventId)
         throw new TypeError('Invalid diagnostic event identity');
     const steps = raw.subSteps ?? [];
-    if (!Array.isArray(steps) || steps.length > 256 || new Set(steps.map(step => step?.stepId)).size !== steps.length
-        || steps.some(step => !step || step.origin !== 'reported' || typeof step.stepId !== 'string' || !step.stepId.trim()
-            || typeof step.name !== 'string' || typeof step.kind !== 'string' || !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')
-            || (step.usedModel !== undefined && typeof step.usedModel !== 'boolean')
-            || (step.revision !== undefined && (!Number.isSafeInteger(step.revision) || step.revision < 1 || !Number.isFinite(step.createdAtMs)))
-            || ['createdAtMs', 'startedAtMs', 'endedAtMs'].some(key => step[key] !== undefined && (typeof step[key] !== 'number' || !Number.isFinite(step[key]) || step[key] < 0))
-            || (step.nextStepIds !== undefined && (!Array.isArray(step.nextStepIds) || step.nextStepIds.some((id) => typeof id !== 'string'))))
-        || (raw.subStepsDropped !== undefined && (!Number.isSafeInteger(raw.subStepsDropped) || Number(raw.subStepsDropped) < 0))
-        || (raw.subStepsTruncated !== undefined && typeof raw.subStepsTruncated !== 'boolean'))
+    // 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 ||
+        new Set(steps.map((step) => step?.stepId)).size !== steps.length ||
+        steps.some((step) => !step ||
+            step.origin !== 'reported' ||
+            typeof step.stepId !== 'string' ||
+            !step.stepId.trim() ||
+            typeof step.name !== 'string' ||
+            typeof step.kind !== 'string' ||
+            !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') ||
+            (step.usedModel !== undefined && typeof step.usedModel !== 'boolean') ||
+            (step.revision !== undefined &&
+                (!Number.isSafeInteger(step.revision) ||
+                    step.revision < 1 ||
+                    !Number.isFinite(step.createdAtMs))) ||
+            ['createdAtMs', 'startedAtMs', 'endedAtMs'].some((key) => step[key] !== undefined &&
+                (typeof step[key] !== 'number' || !Number.isFinite(step[key]) || step[key] < 0)) ||
+            (step.nextStepIds !== undefined &&
+                (!Array.isArray(step.nextStepIds) ||
+                    step.nextStepIds.some((id) => typeof id !== 'string')))) ||
+        (raw.subStepsDropped !== undefined &&
+            (!Number.isSafeInteger(raw.subStepsDropped) || Number(raw.subStepsDropped) < 0)) ||
+        (raw.subStepsTruncated !== undefined && typeof raw.subStepsTruncated !== 'boolean'))
         throw new TypeError('Invalid reported diagnostic steps');
+    // 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)
         if (step.payload !== undefined)
             payloadSnapshot(step.payload);
@@ -62,19 +142,59 @@ export function normalizeDiagnosticEvent(input) {
     breakWhile(raw.usedModel !== undefined && typeof raw.usedModel !== 'boolean', () => new TypeError('Invalid reported model use'));
     if (type === 'node.progress') {
         const progress = raw.payload?.subStep;
-        breakWhile(progress !== undefined && (!progress || !['write', 'fix'].includes(progress.operation) || typeof progress.stepId !== 'string' || !progress.stepId
-            || !Number.isSafeInteger(progress.sequence) || progress.sequence < 1 || !Number.isSafeInteger(progress.revision) || progress.revision < 1
-            || !Number.isFinite(progress.createdAtMs) || progress.createdAtMs < 0 || !reportedStepStatuses.includes(progress.status)
-            || (progress.usedModel !== undefined && typeof progress.usedModel !== 'boolean')), () => new TypeError('Invalid reported sub-step progress'));
+        breakWhile(progress !== undefined &&
+            (!progress ||
+                !['write', 'fix'].includes(progress.operation) ||
+                typeof progress.stepId !== 'string' ||
+                !progress.stepId ||
+                !Number.isSafeInteger(progress.sequence) ||
+                progress.sequence < 1 ||
+                !Number.isSafeInteger(progress.revision) ||
+                progress.revision < 1 ||
+                !Number.isFinite(progress.createdAtMs) ||
+                progress.createdAtMs < 0 ||
+                !reportedStepStatuses.includes(progress.status) ||
+                (progress.usedModel !== undefined && typeof progress.usedModel !== 'boolean')), () => new TypeError('Invalid reported sub-step progress'));
     }
-    for (const key of ['parentSpanId', 'invocationId', 'parentInvocationId', 'workflowInvocationId', 'workflowNodeId', 'agentId', 'branchId', 'agentVersionId', 'parentBranchId', 'parentAgentVersionId', 'forkPointId', 'definitionId', 'definitionKind', 'definitionRevision', 'nodeId', 'nodeName', 'nodeKind', 'nodeDescription', 'stageId', 'modelId']) {
+    for (const key of [
+        'parentSpanId',
+        'invocationId',
+        'parentInvocationId',
+        'workflowInvocationId',
+        'workflowNodeId',
+        'agentId',
+        'branchId',
+        'agentVersionId',
+        'parentBranchId',
+        'parentAgentVersionId',
+        'forkPointId',
+        'definitionId',
+        'definitionKind',
+        'definitionRevision',
+        'nodeId',
+        'nodeName',
+        'nodeKind',
+        'nodeDescription',
+        'stageId',
+        'modelId',
+    ]) {
         if (raw[key] !== undefined && typeof raw[key] !== 'string')
             throw new TypeError('Invalid diagnostic identity');
     }
-    if (raw.nodeRole !== undefined && !['workflow-node', 'workflow-boundary', 'invocation', 'loop-step'].includes(String(raw.nodeRole)))
+    if (raw.nodeRole !== undefined &&
+        !['workflow-node', 'workflow-boundary', 'invocation', 'loop-step'].includes(String(raw.nodeRole)))
         throw new TypeError('Invalid diagnostic node role');
+    // Detached copy: the caller's object may be reused, frozen or backed by a store buffer.
     const copy = structuredClone(raw);
-    return { ...copy, version: 2, eventId, type, producerSequence, occurredAtMs,
-        subSteps: copy.subSteps ?? [], subStepsDropped: copy.subStepsDropped ?? 0,
-        subStepsTruncated: copy.subStepsTruncated ?? false };
+    return {
+        ...copy,
+        version: 2,
+        eventId,
+        type,
+        producerSequence,
+        occurredAtMs,
+        subSteps: copy.subSteps ?? [],
+        subStepsDropped: copy.subStepsDropped ?? 0,
+        subStepsTruncated: copy.subStepsTruncated ?? false,
+    };
 }