@jangts/agent-core 0.1.1 → 0.2.1

package/dist/cjs/diagnostics/sub-flow.js

@@ -3,19 +3,77 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.payloadSnapshot = payloadSnapshot;
 exports.createSubFlowLogger = createSubFlowLogger;
 exports.readSubFlowLogger = readSubFlowLogger;
+/**
+ * Bounded, self-reported sub-flow logging.
+ *
+ * A node or tool may report the steps it believes it performed. Such reports are optional
+ * evidence, never proof of Core scheduling: they are marked `origin: 'reported'`, validated
+ * against a fixed field whitelist, and capped in count, text length and nested payload depth.
+ *
+ * Issued loggers are tracked in a module-private registry, so only the execution that created
+ * one can read it. A lookalike object with a `readAll` method is never accepted.
+ *
+ * Exports: `payloadSnapshot`, `createSubFlowLogger`, `readSubFlowLogger`.
+ */
 const rules_js_1 = require("../utils/rules.js");
 const invocation_js_1 = require("../utils/invocation.js");
 const debug_js_1 = require("../structs/debug.js");
+/**
+ * Registry of issued loggers: owner, diagnostic identity and reader for each instance. Kept
+ * private so a structurally identical object cannot impersonate a real logger.
+ */
 const instances = new WeakMap();
-const writeFields = ['name', 'kind', 'parentStepId', 'relatedDefinitionId', 'status', 'usedModel', 'startedAtMs', 'endedAtMs', 'nextStepIds', 'caseId', 'summary', 'payload'];
-const fixFields = ['status', 'usedModel', 'startedAtMs', 'endedAtMs', 'summary', 'payload', 'nextStepIds'];
-const textLimits = { name: 256, kind: 128, parentStepId: 256, relatedDefinitionId: 256, caseId: 256, summary: 1024 };
+/** Fields accepted by `write`; anything else is rejected so a declaration cannot smuggle state. */
+const writeFields = [
+    'name',
+    'kind',
+    'parentStepId',
+    'relatedDefinitionId',
+    'status',
+    'usedModel',
+    'startedAtMs',
+    'endedAtMs',
+    'nextStepIds',
+    'caseId',
+    'summary',
+    'payload',
+];
+/** Fields accepted by `fix`: identity and creation data are intentionally not patchable. */
+const fixFields = [
+    'status',
+    'usedModel',
+    'startedAtMs',
+    'endedAtMs',
+    'summary',
+    'payload',
+    'nextStepIds',
+];
+/** Per-field character caps, bounding what one reported step can add to a persisted record. */
+const textLimits = {
+    name: 256,
+    kind: 128,
+    parentStepId: 256,
+    relatedDefinitionId: 256,
+    caseId: 256,
+    summary: 1024,
+};
+/**
+ * Validate a step input: plain prototype, whitelisted keys, own data properties only.
+ *
+ * Property descriptors are inspected instead of values being read, so an accessor on the input
+ * cannot execute application code during validation.
+ */
 function fields(input, allowed) {
     (0, rules_js_1.breakWhile)(!input || Object.getPrototypeOf(input) !== Object.prototype, () => new TypeError('Sub-flow input must be a plain parameter object'));
-    (0, rules_js_1.breakWhile)(Reflect.ownKeys(input).some(key => typeof key !== 'string' || !allowed.includes(key)), () => new TypeError('Unknown sub-flow field'));
+    (0, rules_js_1.breakWhile)(Reflect.ownKeys(input).some((key) => typeof key !== 'string' || !allowed.includes(key)), () => new TypeError('Unknown sub-flow field'));
     for (const key of Reflect.ownKeys(input))
-        (0, rules_js_1.breakWhile)(!['payload', 'summary'].includes(String(key)) && !('value' in Object.getOwnPropertyDescriptor(input, key)), () => new TypeError('Sub-flow metadata must be plain data'));
+        (0, rules_js_1.breakWhile)(!['payload', 'summary'].includes(String(key)) &&
+            !('value' in Object.getOwnPropertyDescriptor(input, key)), () => new TypeError('Sub-flow metadata must be plain data'));
 }
+/**
+ * Check a fully built step: text caps, status vocabulary, time ordering, and the rules tying
+ * timestamps to planned and terminal statuses.
+ */
 function validate(step) {
     for (const [key, limit] of Object.entries(textLimits)) {
         const value = step[key];
@@ -25,15 +83,33 @@ function validate(step) {
     (0, rules_js_1.breakWhile)(step.usedModel !== undefined && typeof step.usedModel !== 'boolean', () => new TypeError('Invalid sub-flow usedModel'));
     for (const time of [step.startedAtMs, step.endedAtMs])
         (0, rules_js_1.breakWhile)(time !== undefined && (!Number.isFinite(time) || time < 0), () => new TypeError('Invalid sub-flow time'));
-    (0, rules_js_1.breakWhile)(step.startedAtMs !== undefined && step.endedAtMs !== undefined && step.endedAtMs < step.startedAtMs, () => new TypeError('Invalid sub-flow time order'));
+    (0, rules_js_1.breakWhile)(step.startedAtMs !== undefined &&
+        step.endedAtMs !== undefined &&
+        step.endedAtMs < step.startedAtMs, () => new TypeError('Invalid sub-flow time order'));
     (0, rules_js_1.breakWhile)(step.endedAtMs !== undefined && !debug_js_1.reportedStepStatusCatalog[step.status].terminal, () => new TypeError('Only terminal sub-flow steps have an end time'));
     (0, rules_js_1.breakWhile)(['planned', 'skipped'].includes(step.status) && step.startedAtMs !== undefined, () => new TypeError('A planned or skipped sub-flow step has not started'));
-    (0, rules_js_1.breakWhile)(step.nextStepIds !== undefined && (!Array.isArray(step.nextStepIds) || step.nextStepIds.length > 64 || new Set(step.nextStepIds).size !== step.nextStepIds.length
-        || step.nextStepIds.some(id => typeof id !== 'string' || !id.trim() || id.length > 256)), () => new TypeError('Invalid sub-flow successors'));
+    (0, rules_js_1.breakWhile)(step.nextStepIds !== undefined &&
+        (!Array.isArray(step.nextStepIds) ||
+            step.nextStepIds.length > 64 ||
+            new Set(step.nextStepIds).size !== step.nextStepIds.length ||
+            step.nextStepIds.some((id) => typeof id !== 'string' || !id.trim() || id.length > 256)), () => new TypeError('Invalid sub-flow successors'));
 }
-/** Reject accessors, services, cycles and non-JSON values without evaluating application getters. */
+/**
+ * Validate and deep-copy a reported payload.
+ *
+ * Accessors, class instances, cycles and non-JSON values are rejected without evaluating
+ * application getters, so a payload can neither run code nor alias live state. Accepted data is
+ * frozen.
+ *
+ * @param input Object to snapshot. It must be a plain object, not an array.
+ * @returns A deeply frozen JSON-shaped copy.
+ * @throws TypeError when the value is not plain JSON data, contains a getter, or is cyclic.
+ * @throws RangeError when node count, nesting depth, string length or array length exceeds the
+ *   limits below.
+ */
 function payloadSnapshot(input) {
     let nodes = 0;
+    // Ancestors rather than all visited nodes: a shared subtree is fine, a cycle is not.
     const ancestors = new Set();
     const copy = (value, depth) => {
         (0, rules_js_1.breakWhile)(++nodes > 4096 || depth > 16, () => new RangeError('Sub-flow payload is too complex'));
@@ -42,7 +118,11 @@ function payloadSnapshot(input) {
             return value;
         if (typeof value === 'number' && Number.isFinite(value))
             return value;
-        (0, rules_js_1.breakWhile)(!value || typeof value !== 'object' || (typeof value === 'object' && value !== null && ancestors.has(value)) || (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype), () => new TypeError('Sub-flow payload must contain JSON data'));
+        (0, rules_js_1.breakWhile)(!value ||
+            typeof value !== 'object' ||
+            (typeof value === 'object' && value !== null && ancestors.has(value)) ||
+            // Only plain objects survive: a class instance may hide lazy state behind getters.
+            (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype), () => new TypeError('Sub-flow payload must contain JSON data'));
         (0, rules_js_1.breakWhile)(Array.isArray(value) && value.length > 4096, () => new RangeError('Sub-flow payload array is too large'));
         const data = value;
         ancestors.add(data);
@@ -51,21 +131,43 @@ function payloadSnapshot(input) {
             if (Array.isArray(value) && key === 'length')
                 continue;
             const field = Object.getOwnPropertyDescriptor(value, key);
-            (0, rules_js_1.breakWhile)(typeof key !== 'string' || !('value' in field) || !field.enumerable || (Array.isArray(value) && !/^(0|[1-9]\d*)$/.test(key)), () => new TypeError('Sub-flow payload must contain plain data fields'));
+            (0, rules_js_1.breakWhile)(typeof key !== 'string' ||
+                !('value' in field) ||
+                !field.enumerable ||
+                // Array keys must be canonical indices; extra or sparse keys cannot survive JSON.
+                (Array.isArray(value) && !/^(0|[1-9]\d*)$/.test(key)), () => new TypeError('Sub-flow payload must contain plain data fields'));
             Object.defineProperty(result, key, { value: copy(field.value, depth + 1), enumerable: true });
         }
         ancestors.delete(data);
-        return Array.isArray(value) ? Object.freeze(Array.from({ length: value.length }, (_, i) => result[i] ?? null)) : Object.freeze(result);
+        return Array.isArray(value)
+            ? Object.freeze(Array.from({ length: value.length }, (_, i) => result[i] ?? null))
+            : Object.freeze(result);
     };
     (0, rules_js_1.breakWhile)(!input || Array.isArray(input) || Object.getPrototypeOf(input) !== Object.prototype, () => new TypeError('Sub-flow payload must be an object'));
     return copy(input, 0);
 }
+/**
+ * Merge a payload patch into a recorded payload without replacing recorded facts.
+ *
+ * Nested objects merge recursively; an existing leaf must keep its value. A mismatch is
+ * rejected rather than overwritten, because a fix may add results but not rewrite history.
+ */
 function fill(previous, patch) {
     const result = { ...previous };
     for (const [key, value] of Object.entries(patch)) {
         if (!Object.hasOwn(previous, key))
-            Object.defineProperty(result, key, { value, enumerable: true, configurable: true, writable: true });
-        else if (value && previous[key] && typeof value === 'object' && typeof previous[key] === 'object' && !Array.isArray(value) && !Array.isArray(previous[key])) {
+            Object.defineProperty(result, key, {
+                value,
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        else if (value &&
+            previous[key] &&
+            typeof value === 'object' &&
+            typeof previous[key] === 'object' &&
+            !Array.isArray(value) &&
+            !Array.isArray(previous[key])) {
             result[key] = fill(previous[key], value);
         }
         else
@@ -73,87 +175,185 @@ function fill(previous, patch) {
     }
     return Object.freeze(result);
 }
-/** Internal constructor; only active execution contexts issue logger instances. */
+/**
+ * Create a logger bound to one active execution visit.
+ *
+ * Only execution contexts inside this package should call it: the resulting object is the sole
+ * way to append reported steps to the current record.
+ *
+ * @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 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 identity Diagnostic run and span the logger belongs to; used to reject cross-scope reads.
+ * @returns A frozen logger instance.
+ */
 function createSubFlowLogger(owner, active, content, changed, identity) {
     class Logger {
         #steps = Object.freeze([]);
         #changes = 0;
-        constructor() { instances.set(this, { owner, identity, read: () => this.#steps }); Object.freeze(this); }
-        #assertActive() { (0, rules_js_1.breakWhile)(!active(), () => new TypeError('Sub-flow logger belongs to a closed execution')); }
+        constructor() {
+            instances.set(this, { owner, identity, read: () => this.#steps });
+            Object.freeze(this);
+        }
+        #assertActive() {
+            // A logger that outlived its execution would append evidence to a finished request.
+            (0, rules_js_1.breakWhile)(!active(), () => new TypeError('Sub-flow logger belongs to a closed execution'));
+        }
         #save(step, operation) {
             this.#assertActive();
-            const next = operation === 'write' ? [...this.#steps, step] : this.#steps.map(item => item.stepId === step.stepId ? step : item);
-            (0, rules_js_1.breakWhile)(step.nextStepIds?.some(id => !next.some(item => item.stepId === id)), () => new TypeError('Sub-flow successors must belong to this logger'));
+            // A fix replaces the step with the same id in place; a write always appends.
+            const next = operation === 'write'
+                ? [...this.#steps, step]
+                : this.#steps.map((item) => (item.stepId === step.stepId ? step : item));
+            // Successors must resolve inside this logger, otherwise the recorded graph would have
+            // dangling edges.
+            (0, rules_js_1.breakWhile)(step.nextStepIds?.some((id) => !next.some((item) => item.stepId === id)), () => new TypeError('Sub-flow successors must belong to this logger'));
+            // The step and size caps equal the persisted-record limits; the change cap bounds
+            // write/fix churn even when the final step count stays small.
             (0, rules_js_1.breakWhile)(next.length > 256 || this.#changes >= 1024 || JSON.stringify(next).length > 65536, () => new RangeError('Sub-flow log limit exceeded'));
             this.#steps = Object.freeze(next);
             this.#changes++;
-            changed(this, { operation, stepId: step.stepId, sequence: step.sequence, revision: step.revision, createdAtMs: step.createdAtMs, status: step.status, ...(step.usedModel === undefined ? {} : { usedModel: step.usedModel }) });
+            changed(this, {
+                operation,
+                stepId: step.stepId,
+                sequence: step.sequence,
+                revision: step.revision,
+                createdAtMs: step.createdAtMs,
+                status: step.status,
+                ...(step.usedModel === undefined ? {} : { usedModel: step.usedModel }),
+            });
         }
         write(input) {
             this.#assertActive();
             fields(input, writeFields);
             (0, rules_js_1.breakWhile)(input.nextStepIds !== undefined && !Array.isArray(input.nextStepIds), () => new TypeError('Invalid sub-flow successors'));
             const now = Date.now(), status = input.status === undefined ? 'planned' : input.status;
-            const step = { origin: 'reported', stepId: (0, invocation_js_1.invocationId)(), sequence: this.#steps.length + 1, revision: 1, createdAtMs: now,
-                name: input.name, kind: input.kind, status,
+            // Timestamps are derived from the status: a running or terminal step gets a start time,
+            // a terminal step also an end time, using the caller's value when one is supplied.
+            const step = {
+                origin: 'reported',
+                stepId: (0, invocation_js_1.invocationId)(),
+                sequence: this.#steps.length + 1,
+                revision: 1,
+                createdAtMs: now,
+                name: input.name,
+                kind: input.kind,
+                status,
                 ...(input.parentStepId === undefined ? {} : { parentStepId: input.parentStepId }),
-                ...(input.relatedDefinitionId === undefined ? {} : { relatedDefinitionId: input.relatedDefinitionId }),
+                ...(input.relatedDefinitionId === undefined
+                    ? {}
+                    : { relatedDefinitionId: input.relatedDefinitionId }),
                 ...(input.caseId === undefined ? {} : { caseId: input.caseId }),
                 ...(input.usedModel === undefined ? {} : { usedModel: input.usedModel }),
-                ...(input.startedAtMs === undefined && status !== 'running' ? {} : { startedAtMs: input.startedAtMs ?? now }),
-                ...(input.endedAtMs === undefined && !debug_js_1.reportedStepStatusCatalog[status]?.terminal ? {} : { endedAtMs: input.endedAtMs ?? now }),
-                ...(input.nextStepIds === undefined ? {} : { nextStepIds: Object.freeze([...input.nextStepIds]) }),
+                ...(input.startedAtMs === undefined && status !== 'running'
+                    ? {}
+                    : { startedAtMs: input.startedAtMs ?? now }),
+                ...(input.endedAtMs === undefined && !debug_js_1.reportedStepStatusCatalog[status]?.terminal
+                    ? {}
+                    : { endedAtMs: input.endedAtMs ?? now }),
+                ...(input.nextStepIds === undefined
+                    ? {}
+                    : { nextStepIds: Object.freeze([...input.nextStepIds]) }),
             };
             if (content()) {
+                // Summaries and payloads are omitted entirely when content logging is off, so a
+                // metadata-only consumer never receives them.
                 if (input.summary !== undefined)
                     Object.assign(step, { summary: input.summary });
                 if (input.payload !== undefined)
                     Object.assign(step, { payload: payloadSnapshot(input.payload) });
             }
             validate(step);
-            (0, rules_js_1.breakWhile)(step.parentStepId && !this.#steps.some(item => item.stepId === step.parentStepId), () => new TypeError('Sub-flow parent must belong to this logger'));
+            (0, rules_js_1.breakWhile)(step.parentStepId && !this.#steps.some((item) => item.stepId === step.parentStepId), () => new TypeError('Sub-flow parent must belong to this logger'));
             this.#save(Object.freeze(step), 'write');
             return step.stepId;
         }
         fix(stepId, patch) {
             this.#assertActive();
             fields(patch, fixFields);
-            const previous = this.#steps.find(step => step.stepId === stepId);
+            const previous = this.#steps.find((step) => step.stepId === stepId);
+            // The assertion above only satisfies the type checker; this check rejects an unknown id.
             (0, rules_js_1.breakWhile)(!previous, () => new TypeError('Unknown sub-flow step'));
             const terminal = debug_js_1.reportedStepStatusCatalog[previous.status].terminal;
+            // A terminal step is sealed: its outcome, model use and timestamps cannot be rewritten.
             (0, rules_js_1.breakWhile)(terminal && patch.status !== undefined && patch.status !== previous.status, () => new TypeError('Terminal sub-flow status is sealed'));
-            (0, rules_js_1.breakWhile)(terminal && previous.usedModel !== undefined && patch.usedModel !== undefined && previous.usedModel !== patch.usedModel, () => new TypeError('Terminal sub-flow model use is sealed'));
+            (0, rules_js_1.breakWhile)(terminal &&
+                previous.usedModel !== undefined &&
+                patch.usedModel !== undefined &&
+                previous.usedModel !== patch.usedModel, () => new TypeError('Terminal sub-flow model use is sealed'));
             (0, rules_js_1.breakWhile)(previous.usedModel === true && patch.usedModel === false, () => new TypeError('Cannot undo reported model use'));
-            (0, rules_js_1.breakWhile)(patch.status !== undefined && patch.status !== previous.status && !debug_js_1.reportedStepStatusCatalog[previous.status].next.includes(patch.status), () => new TypeError('Invalid sub-flow status transition'));
+            (0, rules_js_1.breakWhile)(patch.status !== undefined &&
+                patch.status !== previous.status &&
+                // Transitions are catalog-driven; a terminal status has no successors at all.
+                !debug_js_1.reportedStepStatusCatalog[previous.status].next.includes(patch.status), () => new TypeError('Invalid sub-flow status transition'));
             for (const key of ['startedAtMs', 'endedAtMs'])
                 (0, rules_js_1.breakWhile)(previous[key] !== undefined && patch[key] !== undefined && patch[key] !== previous[key], () => new TypeError('Cannot overwrite a sub-flow time'));
             const status = patch.status ?? previous.status;
-            (0, rules_js_1.breakWhile)(patch.nextStepIds !== undefined && (!Array.isArray(patch.nextStepIds) || (previous.nextStepIds !== undefined && JSON.stringify(previous.nextStepIds) !== JSON.stringify(patch.nextStepIds))), () => new TypeError('Cannot overwrite sub-flow successors'));
-            const step = { ...previous, revision: previous.revision + 1, status,
-                ...(patch.nextStepIds === undefined ? {} : { nextStepIds: Object.freeze([...patch.nextStepIds]) }),
+            (0, rules_js_1.breakWhile)(patch.nextStepIds !== undefined &&
+                (!Array.isArray(patch.nextStepIds) ||
+                    (previous.nextStepIds !== undefined &&
+                        JSON.stringify(previous.nextStepIds) !== JSON.stringify(patch.nextStepIds))), () => new TypeError('Cannot overwrite sub-flow successors'));
+            // A start time is auto-stamped only when the step becomes running and had none; an end
+            // time is added once the status becomes terminal.
+            const step = {
+                ...previous,
+                revision: previous.revision + 1,
+                status,
+                ...(patch.nextStepIds === undefined
+                    ? {}
+                    : { nextStepIds: Object.freeze([...patch.nextStepIds]) }),
                 ...(patch.usedModel === undefined ? {} : { usedModel: patch.usedModel }),
-                ...(patch.startedAtMs === undefined && !(status === 'running' && previous.startedAtMs === undefined) ? {} : { startedAtMs: patch.startedAtMs ?? Date.now() }),
-                ...(patch.endedAtMs === undefined && (!debug_js_1.reportedStepStatusCatalog[status]?.terminal || previous.endedAtMs !== undefined) ? {} : { endedAtMs: patch.endedAtMs ?? Date.now() }),
+                ...(patch.startedAtMs === undefined &&
+                    !(status === 'running' && previous.startedAtMs === undefined)
+                    ? {}
+                    : { startedAtMs: patch.startedAtMs ?? Date.now() }),
+                ...(patch.endedAtMs === undefined &&
+                    (!debug_js_1.reportedStepStatusCatalog[status]?.terminal || previous.endedAtMs !== undefined)
+                    ? {}
+                    : { endedAtMs: patch.endedAtMs ?? Date.now() }),
             };
             if (content()) {
+                // A fix may add a summary once and fill missing payload fields, but it cannot replace
+                // a summary or a recorded payload value.
                 if (patch.summary !== undefined) {
                     (0, rules_js_1.breakWhile)(previous.summary !== undefined && previous.summary !== patch.summary, () => new TypeError('Cannot overwrite a sub-flow summary'));
                     Object.assign(step, { summary: patch.summary });
                 }
                 if (patch.payload !== undefined)
-                    Object.assign(step, { payload: fill(previous.payload ?? {}, payloadSnapshot(patch.payload)) });
+                    Object.assign(step, {
+                        payload: fill(previous.payload ?? {}, payloadSnapshot(patch.payload)),
+                    });
             }
             validate(step);
             this.#save(Object.freeze(step), 'fix');
         }
-        readAll() { return this.#steps; }
+        readAll() {
+            return this.#steps;
+        }
     }
     return new Logger();
 }
-/** Never call a lookalike's readAll method. */
+/**
+ * Read the steps recorded by a logger issued by this module.
+ *
+ * The instance is resolved through the private registry, so a lookalike's `readAll` method is
+ * never called and a logger cannot be borrowed across executions.
+ *
+ * @param input Candidate logger; must be an instance created by `createSubFlowLogger`.
+ * @param owner Expected owning execution visit. Omit to accept any owner.
+ * @param identity Expected run and span. Omit to accept any diagnostic scope.
+ * @returns The recorded steps in write order, as an immutable list shared with the logger.
+ * @throws TypeError when the value is not a registered logger, belongs to another owner, or
+ *   belongs to another diagnostic scope.
+ */
 function readSubFlowLogger(input, owner, identity) {
     const instance = input && typeof input === 'object' ? instances.get(input) : undefined;
-    (0, rules_js_1.breakWhile)(!instance || (owner !== undefined && owner !== instance.owner), () => new TypeError('Expected this execution\'s SubFlowLogger instance'));
-    (0, rules_js_1.breakWhile)(identity && (instance.identity?.runId !== identity.runId || instance.identity?.spanId !== identity.spanId), () => new TypeError('Sub-flow logger belongs to another diagnostic scope'));
+    (0, rules_js_1.breakWhile)(!instance || (owner !== undefined && owner !== instance.owner), () => new TypeError("Expected this execution's SubFlowLogger instance"));
+    (0, rules_js_1.breakWhile)(identity &&
+        (instance.identity?.runId !== identity.runId ||
+            instance.identity?.spanId !== identity.spanId), () => new TypeError('Sub-flow logger belongs to another diagnostic scope'));
     return instance.read();
 }

package/dist/cjs/errors.js

@@ -2,11 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordErrorContext = recordErrorContext;
 exports.getErrorInfo = getErrorInfo;
+/**
+ * Error metadata boundary: records which execution stage produced a failure and exposes a
+ * stable, read-only view of it for diagnostics.
+ *
+ * The original thrown value is never wrapped or replaced, so App code keeps its own error
+ * identity and stack. Annotations live in a side table keyed by reference, which works for
+ * frozen Errors and DOMException instances whose properties cannot be added.
+ *
+ * Exports: `recordErrorContext` (annotate at a boundary) and `getErrorInfo` (inspect).
+ */
 const errors_js_1 = require("./structs/errors.js");
 // Side metadata preserves App error identity, including frozen Errors and DOMException.
 const contexts = new WeakMap();
 const reference = (value) => value !== null && (typeof value === 'object' || typeof value === 'function');
-/** Internal boundary annotation. Re-throws retain the originating stage and provider details. */
+/**
+ * Attach boundary metadata to a thrown value without changing that value.
+ *
+ * The earliest recorded stage stays authoritative on re-throw, so a failure is attributed
+ * to the stage that first caught it rather than to the boundary that merely relays it.
+ * Codes and retryability may still be filled in by an outer boundary that knows more.
+ *
+ * @param error Value being propagated. Non-object values are ignored: identity is tracked
+ *   by reference, so primitives cannot carry annotations.
+ * @param context Boundary annotations to merge into the existing entry, if any.
+ * @returns The same reference, allowing `throw recordErrorContext(error, ctx)`.
+ */
 function recordErrorContext(error, context) {
     if (reference(error)) {
         const previous = contexts.get(error);
@@ -15,34 +36,86 @@ function recordErrorContext(error, context) {
     }
     return error;
 }
-/** Inspect external metadata inside the guarded diagnostic boundary below. */
+/**
+ * Read classification metadata from an arbitrary thrown value.
+ *
+ * Returns normalized issues plus a primary code. `isRetryable` is left undefined when the
+ * error neither states it nor makes a final classification, so callers do not mistake
+ * "unknown" for "retryable".
+ */
 function inspectError(error) {
-    const source = reference(error) ? error : {};
+    const source = reference(error)
+        ? error
+        : {};
     const reportedIssues = source.issues;
+    // Structured issues win over the older `errors` array, so an error carrying both is not
+    // reported twice. Only the array shape is accepted; any other value falls through.
     const reportedErrors = Array.isArray(reportedIssues) ? undefined : source.errors;
-    const raw = Array.isArray(reportedIssues) ? reportedIssues : Array.isArray(reportedErrors) ? reportedErrors : [];
-    const issues = raw.flatMap(value => {
+    const raw = Array.isArray(reportedIssues)
+        ? reportedIssues
+        : Array.isArray(reportedErrors)
+            ? reportedErrors
+            : [];
+    const issues = raw.flatMap((value) => {
         if (!value || typeof value !== 'object')
             return [];
         const { code, message, path: reportedPath, checkId } = value;
         if (typeof code !== 'string')
             return [];
-        const pathItems = typeof reportedPath === 'string' ? [reportedPath] : Array.isArray(reportedPath) ? Array.from(reportedPath) : undefined;
-        const path = pathItems?.every((part) => typeof part === 'string' || typeof part === 'number') ? pathItems : undefined;
-        return [{ code, message: typeof message === 'string' ? message : code,
+        const pathItems = typeof reportedPath === 'string'
+            ? [reportedPath]
+            : Array.isArray(reportedPath)
+                ? Array.from(reportedPath)
+                : undefined;
+        const path = pathItems?.every((part) => typeof part === 'string' || typeof part === 'number')
+            ? pathItems
+            : undefined;
+        return [
+            {
+                code,
+                message: typeof message === 'string' ? message : code,
                 ...(path === undefined ? {} : { path: Object.freeze(path) }),
-                ...(typeof checkId === 'string' ? { checkId } : {}) }];
+                ...(typeof checkId === 'string' ? { checkId } : {}),
+            },
+        ];
     });
     const code = source.code;
+    // A string `code` or a structured issue is already a usable classification, so the error
+    // `name` is only consulted as a last resort.
     const name = typeof code === 'string' || issues.length ? undefined : source.name;
-    const fallback = typeof code === 'string' ? code : issues[0]?.code
-        ?? (name === 'AbortError' ? 'CANCELLED' : name === 'TimeoutError' ? 'TIMEOUT' : 'UNKNOWN_ERROR');
+    // DOMException exposes cancellation through `name` rather than `code`; the mapping keeps
+    // cancellation and timeout distinguishable from genuine failures.
+    const fallback = typeof code === 'string'
+        ? code
+        : (issues[0]?.code ??
+            (name === 'AbortError'
+                ? 'CANCELLED'
+                : name === 'TimeoutError'
+                    ? 'TIMEOUT'
+                    : 'UNKNOWN_ERROR'));
     const retryable = source.isRetryable;
-    const isRetryable = typeof retryable === 'boolean' ? retryable
-        : error instanceof errors_js_1.BudgetError || error instanceof errors_js_1.ValidationError || issues.length || ['CANCELLED', 'TIMEOUT', 'BUDGET'].includes(fallback) ? false : undefined;
+    // Retryability stays unknown unless the error reports it or it is provably final:
+    // budget, validation, issue-bearing and cancellation failures must not be retried.
+    const isRetryable = typeof retryable === 'boolean'
+        ? retryable
+        : error instanceof errors_js_1.BudgetError ||
+            error instanceof errors_js_1.ValidationError ||
+            issues.length ||
+            ['CANCELLED', 'TIMEOUT', 'BUDGET'].includes(fallback)
+            ? false
+            : undefined;
     return { code: fallback, issues, isRetryable };
 }
-/** A local diagnostic view; hostile metadata must never replace the original failure. */
+/**
+ * Produce a frozen diagnostic view of any thrown value.
+ *
+ * Inspection is guarded: an exotic error (revoked proxy, throwing getter, null prototype)
+ * degrades to `UNKNOWN_ERROR` instead of raising a second failure while handling the first.
+ *
+ * @param error Any thrown value, including non-Error values such as strings.
+ * @returns Frozen info. `codes` lists every known code with the primary one first; optional
+ *   fields are omitted rather than emitted as `undefined`. `cause` is the original value.
+ */
 function getErrorInfo(error) {
     const context = reference(error) ? contexts.get(error) : undefined;
     let view;
@@ -53,9 +126,18 @@ function getErrorInfo(error) {
         view = { code: 'UNKNOWN_ERROR', issues: [] };
     }
     const { code: fallback, issues } = view;
-    const codes = Object.freeze([...(context?.codes ?? (issues.length ? issues.map(issue => issue.code) : [fallback]))]);
+    // Recorded codes describe the boundary where the error was first captured and outrank
+    // codes inferred from the current shape, which may already have been flattened.
+    const codes = Object.freeze([
+        ...(context?.codes ?? (issues.length ? issues.map((issue) => issue.code) : [fallback])),
+    ]);
     const isRetryable = context?.isRetryable ?? view.isRetryable;
-    return Object.freeze({ code: codes[0] ?? fallback, codes, issues: Object.freeze(issues.map(issue => Object.freeze(issue))),
+    return Object.freeze({
+        code: codes[0] ?? fallback,
+        codes,
+        issues: Object.freeze(issues.map((issue) => Object.freeze(issue))),
         ...(context?.stageId === undefined ? {} : { stageId: context.stageId }),
-        ...(isRetryable === undefined ? {} : { isRetryable }), cause: error });
+        ...(isRetryable === undefined ? {} : { isRetryable }),
+        cause: error,
+    });
 }

package/dist/cjs/execution/branch.js

@@ -2,12 +2,28 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.snapshotBranch = snapshotBranch;
 const rules_js_1 = require("../utils/rules.js");
-/** Core identity contract, also used by App-side Family storage adapters. */
+/**
+ * Validate and freeze a branch identity.
+ *
+ * Required ids identify the branch itself; optional ids describe the fork origin. Ids are
+ * bounded in length so they remain usable as keys in App storage.
+ *
+ * @param source - Branch identity supplied by the host or generated by the engine.
+ * @returns A frozen identity with the same field set.
+ * @throws Error When a required id is missing or any id is blank or too long.
+ */
 function snapshotBranch(source) {
     (0, rules_js_1.breakWhile)(!source, 'Invalid branch identity');
     const { agentId, branchId, agentVersionId, parentBranchId, parentAgentVersionId, forkPointId } = source;
     const valid = (id) => typeof id === 'string' && !!id.trim() && id.length <= 200;
-    (0, rules_js_1.breakWhile)(![agentId, branchId, agentVersionId].every(valid)
-        || [parentBranchId, parentAgentVersionId, forkPointId].some(id => id !== undefined && !valid(id)), 'Invalid branch identity');
-    return Object.freeze({ agentId, branchId, agentVersionId, parentBranchId, parentAgentVersionId, forkPointId });
+    (0, rules_js_1.breakWhile)(![agentId, branchId, agentVersionId].every(valid) ||
+        [parentBranchId, parentAgentVersionId, forkPointId].some((id) => id !== undefined && !valid(id)), 'Invalid branch identity');
+    return Object.freeze({
+        agentId,
+        branchId,
+        agentVersionId,
+        parentBranchId,
+        parentAgentVersionId,
+        forkPointId,
+    });
 }