@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/capabilities/tools.js

@@ -1,18 +1,45 @@
+/**
+ * Core tool registry: the mechanism that turns registered tools into invoked tools.
+ *
+ * `ToolRegistry` owns identity, registration-time validation, cancellation, diagnostics,
+ * output parsing and success/failure bookkeeping. It deliberately knows nothing about
+ * visibility, authorization policy or domain metadata: those are App registrations, and
+ * `authorize` is called by the typed bridge in `tool-runtime.js`.
+ *
+ * `invoke` requires a synchronous tool; `invokeAsync` awaits thenables. Both reject an
+ * unknown tool and report through the ports bound at construction.
+ *
+ * Exports: `ToolRegistry`, `executeInvocation`, and the tool/invocation contracts.
+ */
 import { executionEvents } from '../execution/events.js';
-import { invocationId as nextInvocationId, invocationResult, toolInvocation } from '../utils/invocation.js';
+import { invocationId as nextInvocationId, invocationResult, toolInvocation, } from '../utils/invocation.js';
 import { synchronous } from '../utils/synchronous.js';
 import { awaitWithSignal, combineSignals } from '../utils/cancellation.js';
 import { diagnosticError } from '../diagnostics/index.js';
 import { registrationData } from '../utils/registration.js';
 import { NodeReports } from '../execution/reporting.js';
-/** Mechanism only. Visibility, authorization, schemas and semantic metadata are host registrations. */
+/**
+ * Registry mechanism only: visibility, authorization policy, schemas and semantic metadata
+ * are host registrations. A registry is mutable until sealed and keeps its own call log.
+ */
 export class ToolRegistry {
+    /** Insertion order is the declaration order and is preserved by every enumeration below. */
     tools = new Map();
+    /** Sealing is one-way: a running stage must not add tools to the registry it executes. */
     sealed = false;
+    /** In-memory execution facts for this registry's lifetime, one entry per completed call. */
     executionEvents = [];
-    get events() { return Object.freeze([...this.executionEvents]); }
+    /** Frozen snapshot of the recorded execution facts. */
+    get events() {
+        return Object.freeze([...this.executionEvents]);
+    }
     diagnostics;
     ports;
+    /**
+     * @param options.execution Request-lifetime signal plus the diagnostics/observer source the
+     *   registry starts from.
+     * @param options.errors Factories for the unknown-tool error and for failure codes.
+     */
     constructor({ execution, errors } = {}) {
         this.ports = {
             signal: execution?.signal,
@@ -22,42 +49,137 @@ export class ToolRegistry {
         };
         this.diagnostics = this.ports.diagnostics;
     }
-    setDiagnostics(diagnostics) { this.diagnostics = diagnostics; }
+    /**
+     * Replace the diagnostics scope used by subsequent calls.
+     *
+     * Calls already in flight keep the scope they started with.
+     *
+     * @param diagnostics New diagnostics context, or undefined to stop emitting events.
+     */
+    setDiagnostics(diagnostics) {
+        this.diagnostics = diagnostics;
+    }
+    /**
+     * Register one executable tool.
+     *
+     * The stored entry is frozen and its parsers are bound to the tool, so later changes on the
+     * caller's object cannot alter validation or execution.
+     *
+     * @param tool Executable tool; `id` and `kind` must be non-empty, and the parse and execute
+     *   handlers must all be functions.
+     * @returns This registry, for chaining.
+     * @throws Error when the registry is sealed or the id is already registered.
+     * @throws TypeError when the tool shape is invalid.
+     */
     register(tool) {
         if (this.sealed)
             throw new Error('Tool registry is sealed');
         const { id, kind, description, parseInput, parseOutput, execute, debugSteps } = tool;
-        if (!id?.trim() || !kind?.trim() || ![parseInput, parseOutput, execute].every(value => typeof value === 'function'))
+        if (!id?.trim() ||
+            !kind?.trim() ||
+            ![parseInput, parseOutput, execute].every((value) => typeof value === 'function'))
             throw new TypeError('Invalid executable tool');
         if (this.tools.has(id))
             throw new Error(`Duplicate registered tool: ${id}`);
         const input = parseInput.bind(tool), output = parseOutput.bind(tool);
-        this.tools.set(id, Object.freeze({ ...registrationData(tool, ['id', 'kind', 'description', 'parseInput', 'parseOutput', 'execute', 'debugSteps']), id, kind, description,
-            debugSteps: debugSteps?.bind(tool), parseInput: input, parseOutput: output,
-            execute: execute.bind(tool) }));
+        this.tools.set(id, Object.freeze({
+            ...registrationData(tool, [
+                'id',
+                'kind',
+                'description',
+                'parseInput',
+                'parseOutput',
+                'execute',
+                'debugSteps',
+            ]),
+            id,
+            kind,
+            description,
+            debugSteps: debugSteps?.bind(tool),
+            parseInput: input,
+            parseOutput: output,
+            execute: execute.bind(tool),
+        }));
         return this;
     }
+    /**
+     * Invoke a registered tool synchronously.
+     *
+     * @param request Single request object carrying `toolId`, `input`, and optional signal and
+     *   diagnostics. Exactly one argument is accepted; the arity check is runtime-enforced
+     *   because callers may bypass the type system.
+     * @returns The tool result, with frozen invocation metadata.
+     * @throws TypeError when the request shape is wrong, the diagnostics belong to another run,
+     *   or the tool returns a promise.
+     * @throws Error when the tool is unknown or the tool itself fails; the abort reason
+     *   surfaces when the signal is cancelled.
+     */
     invoke(request) {
         const call = toolInvocation(request, arguments.length);
         return this.execute(call.toolId, call.input, false, call.diagnostics, call.signal);
     }
+    /**
+     * Invoke a registered tool and await its result.
+     *
+     * @param request Single request object, identical to `invoke`.
+     * @returns The tool result once the tool settles.
+     * @throws TypeError or Error under the same conditions as `invoke`; rejections from an
+     *   asynchronous tool are propagated unchanged.
+     */
     async invokeAsync(request) {
         const call = toolInvocation(request, arguments.length);
-        return await this.execute(call.toolId, call.input, true, call.diagnostics, call.signal);
+        return (await this.execute(call.toolId, call.input, true, call.diagnostics, call.signal));
     }
+    /**
+     * Run one call: validate, parse input, execute, parse output, then record the outcome.
+     *
+     * @param name Registered tool id.
+     * @param input Untrusted caller input, parsed before the tool sees it.
+     * @param asynchronous Whether promises returned by the tool are awaited.
+     * @param parentDiagnostics Scope the call is recorded under; defaults to the registry's.
+     * @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) {
-        if (this.diagnostics?.identity?.runId && parentDiagnostics?.identity?.runId && this.diagnostics.identity.runId !== parentDiagnostics.identity.runId)
+        // 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 &&
+            parentDiagnostics?.identity?.runId &&
+            this.diagnostics.identity.runId !== parentDiagnostics.identity.runId)
             throw new TypeError('Tool diagnostics must belong to the same run');
         const tool = this.tools.get(name);
         if (!tool)
             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 diagnostics = parentDiagnostics?.child(invocationId, { invocationId, nodeRole: 'invocation', definitionKind: 'tool', definitionId: name, nodeId: name, nodeName: name, nodeKind: 'tool', nodeDescription: tool.description?.slice(0, 1024), stageId: undefined, definitionRevision: undefined });
+        const diagnostics = parentDiagnostics?.child(invocationId, {
+            invocationId,
+            nodeRole: 'invocation',
+            definitionKind: 'tool',
+            definitionId: name,
+            nodeId: name,
+            nodeName: name,
+            nodeKind: 'tool',
+            // Cap the persisted description so an App-supplied string cannot inflate every record.
+            nodeDescription: tool.description?.slice(0, 1024),
+            // Tool calls are not stage-scoped; explicit undefined clears inherited span fields.
+            stageId: undefined,
+            definitionRevision: undefined,
+        });
         const reports = new NodeReports(diagnostics, signal, 'tool.result');
-        const reporting = { report: reports.report.bind(reports), createSubFlowLogger: reports.createSubFlowLogger.bind(reports) };
-        diagnostics?.emit('tool.call', () => ({ toolId: name, invocationId, ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}) }));
+        const reporting = {
+            report: reports.report.bind(reports),
+            createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
+        };
+        diagnostics?.emit('tool.call', () => ({
+            toolId: name,
+            invocationId,
+            ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}),
+        }));
         const started = Date.now();
+        // Track the phase for failure reports, so input or output parsing errors can be told
+        // apart from failures raised by the tool itself.
         let phase = 'input';
         const output = (value) => {
             signal.throwIfAborted();
@@ -71,28 +193,82 @@ export class ToolRegistry {
             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') });
+                    debug = reports.debug({
+                        subs: synchronous(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous'),
+                    });
                 }
                 catch (error) {
-                    debug = { usedModel: reports.debug().usedModel, subSteps: () => { throw 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;
+                        },
+                    };
                 }
             }
             signal.throwIfAborted();
             reports.close();
-            diagnostics?.emit('tool.result', () => ({ toolId: name, invocationId, status: 'success', ...(diagnostics?.enabled('tool.result', 'content') ? { value: result } : {}), durationMs: Date.now() - started }), debug);
-            this.executionEvents.push(Object.freeze({ ...diagnostics?.identity, toolId: name, invocationId, startedAtMs: started, kind: tool.kind, durationMs: Date.now() - started, status: 'success' }));
-            return invocationResult(result, { ...diagnostics?.identity, invocationId, toolId: name, startedAtMs: started, durationMs: Date.now() - started, status: 'success' });
+            diagnostics?.emit('tool.result', () => ({
+                toolId: name,
+                invocationId,
+                status: 'success',
+                ...(diagnostics?.enabled('tool.result', 'content') ? { value: result } : {}),
+                durationMs: Date.now() - started,
+            }), debug);
+            // Kept locally as well as emitted, so a run summary does not require a log consumer.
+            this.executionEvents.push(Object.freeze({
+                ...diagnostics?.identity,
+                toolId: name,
+                invocationId,
+                startedAtMs: started,
+                kind: tool.kind,
+                durationMs: Date.now() - started,
+                status: 'success',
+            }));
+            return invocationResult(result, {
+                ...diagnostics?.identity,
+                invocationId,
+                toolId: name,
+                startedAtMs: started,
+                durationMs: Date.now() - started,
+                status: 'success',
+            });
         };
         const fail = (error) => {
             reports.close();
-            diagnostics?.emit('rule.result', () => ({ tags: [name, phase], error: diagnosticError(error) }));
-            diagnostics?.emit('tool.result', () => ({ toolId: name, invocationId, status: signal.aborted ? 'cancelled' : 'error', ...(diagnostics?.enabled('tool.result', 'content') ? { error: diagnosticError(error) } : {}), durationMs: Date.now() - started }), reports.debug());
+            // Rule-level record carries the failing phase, which the tool result does not.
+            diagnostics?.emit('rule.result', () => ({
+                tags: [name, phase],
+                error: diagnosticError(error),
+            }));
+            diagnostics?.emit('tool.result', () => ({
+                toolId: name,
+                invocationId,
+                status: signal.aborted ? 'cancelled' : 'error',
+                ...(diagnostics?.enabled('tool.result', 'content')
+                    ? { error: diagnosticError(error) }
+                    : {}),
+                durationMs: Date.now() - started,
+            }), reports.debug());
             let errorCode = signal.aborted ? 'CANCELLED' : 'TOOL_ERROR';
             try {
                 errorCode = this.ports.errorCode?.(error) ?? errorCode;
             }
-            catch { /* Error decoration cannot replace the original failure. */ }
-            this.executionEvents.push(Object.freeze({ ...diagnostics?.identity, toolId: name, invocationId, startedAtMs: started, kind: tool.kind, durationMs: Date.now() - started, status: signal.aborted ? 'cancelled' : 'error', ...(errorCode ? { errorCode } : {}) }));
+            catch {
+                /* Error decoration cannot replace the original failure. */
+            }
+            this.executionEvents.push(Object.freeze({
+                ...diagnostics?.identity,
+                toolId: name,
+                invocationId,
+                startedAtMs: started,
+                kind: tool.kind,
+                durationMs: Date.now() - started,
+                status: signal.aborted ? 'cancelled' : 'error',
+                ...(errorCode ? { errorCode } : {}),
+            }));
             throw error;
         };
         try {
@@ -100,8 +276,16 @@ export class ToolRegistry {
             const parsed = synchronous(tool.parseInput(input), 'Tool input parsers must be synchronous');
             signal.throwIfAborted();
             phase = 'execute';
-            const value = tool.execute(parsed, { mode: asynchronous ? 'async' : 'sync', invocationId, signal, diagnostics, ...reporting });
+            const value = tool.execute(parsed, {
+                mode: asynchronous ? 'async' : 'sync',
+                invocationId,
+                signal,
+                diagnostics,
+                ...reporting,
+            });
             if (asynchronous)
+                // Async completions are routed to `fail` explicitly, so bookkeeping runs exactly once
+                // whether the tool settles immediately or later.
                 return awaitWithSignal(value, signal).then(output).then(succeed).catch(fail);
             return succeed(output(synchronous(value, 'Synchronous tools must not return a Promise')));
         }
@@ -109,19 +293,70 @@ export class ToolRegistry {
             return fail(error);
         }
     }
+    /**
+     * Register several tools.
+     *
+     * @param tools Executable tools applied in iteration order.
+     * @returns This registry, for chaining.
+     * @throws Error or TypeError under the same conditions as `register`.
+     */
     registerAll(tools) {
         for (const tool of tools)
             this.register(tool);
         return this;
     }
-    get(name) { return this.tools.get(name); }
-    get definitions() { return Object.freeze([...this.tools.values()]); }
-    ids() { return Object.freeze([...this.tools.keys()]); }
-    entries() { return this.tools.entries(); }
-    require(id) { const tool = this.get(id); if (!tool)
-        throw this.ports.unavailable?.(id) ?? new Error(`Tool is not registered: ${id}`); return tool; }
-    has(name) { return this.tools.has(name); }
-    values() { return this.tools.values(); }
-    seal() { this.sealed = true; return this; }
+    /**
+     * @param name Tool id.
+     * @returns The registered tool, or undefined when absent.
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /** Frozen snapshot of the registered tools, in declaration order. */
+    get definitions() {
+        return Object.freeze([...this.tools.values()]);
+    }
+    /** Registered tool ids in declaration order. */
+    ids() {
+        return Object.freeze([...this.tools.keys()]);
+    }
+    /** Live iterator over `[id, tool]` pairs; it reflects only entries added before sealing. */
+    entries() {
+        return this.tools.entries();
+    }
+    /**
+     * @param id Tool id.
+     * @returns The registered tool.
+     * @throws Error when the tool is unknown; the App-supplied `unavailable` factory can
+     *   replace the default message.
+     */
+    require(id) {
+        const tool = this.get(id);
+        if (!tool)
+            throw this.ports.unavailable?.(id) ?? new Error(`Tool is not registered: ${id}`);
+        return tool;
+    }
+    /**
+     * @param name Tool id.
+     * @returns Whether the id is registered in this registry.
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /** Live iterator over the registered tools. */
+    values() {
+        return this.tools.values();
+    }
+    /**
+     * Close the registry to further registration.
+     *
+     * Sealing is idempotent and does not affect existing tools.
+     *
+     * @returns This registry.
+     */
+    seal() {
+        this.sealed = true;
+        return this;
+    }
 }
 export { executeInvocation } from './invocation.js';

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

@@ -1,5 +1,16 @@
 import type { BuiltContext, ContextFragment } from '../structs/context/fragments.js';
-/** Metadata remains program-side. Data never becomes a system instruction. */
+/**
+ * Build the model input from fragments.
+ *
+ * Metadata remains program-side: data never becomes a system instruction.
+ *
+ * @param fragments Fragments in carriage order; ids must be unique across the list.
+ * @param maxInputChars Total character budget for the resulting messages.
+ * @returns Messages, per-fragment usage and the measured input size.
+ * @throws Error when a fragment is invalid or duplicated, a user fragment carries a string
+ *   value, or two user fragments declare the same field.
+ * @throws ValidationError when a fragment or the assembled input exceeds its budget.
+ */
 export declare function assembleFragments(fragments: ContextFragment[], maxInputChars: number): BuiltContext;
 export { commonPrefixLength } from '../utils/text.js';
-export type { ContextTrust, ContextLifetime, ContextFragment, ContextFragmentUsage, BuiltContext } from '../structs/context/fragments.js';
+export type { ContextTrust, ContextLifetime, ContextFragment, ContextFragmentUsage, BuiltContext, } from '../structs/context/fragments.js';

package/dist/esm/context/assembly.js

@@ -1,8 +1,30 @@
+/**
+ * Assemble validated fragments into the messages sent to the model.
+ *
+ * The order is fixed: system text first, then one user message carrying structured fields as
+ * JSON. Fragment metadata stays program-side in `fragmentUsage` and never becomes an
+ * instruction. The finished message list is measured against the overall budget, so a caller
+ * sees the same character count a transport will deliver.
+ *
+ * Exports: `assembleFragments`, plus a shared text helper and the fragment types.
+ */
 import { validateContextFragment, validateContextBudget } from './fragments.js';
 import { ValidationError } from '../structs/errors.js';
-/** Metadata remains program-side. Data never becomes a system instruction. */
+/**
+ * Build the model input from fragments.
+ *
+ * Metadata remains program-side: data never becomes a system instruction.
+ *
+ * @param fragments Fragments in carriage order; ids must be unique across the list.
+ * @param maxInputChars Total character budget for the resulting messages.
+ * @returns Messages, per-fragment usage and the measured input size.
+ * @throws Error when a fragment is invalid or duplicated, a user fragment carries a string
+ *   value, or two user fragments declare the same field.
+ * @throws ValidationError when a fragment or the assembled input exceeds its budget.
+ */
 export function assembleFragments(fragments, maxInputChars) {
     const ids = new Set();
+    // One merged object lets duplicate field names be rejected rather than silently overwritten.
     const fields = {};
     const system = [];
     const usage = [];
@@ -16,15 +38,34 @@ export function assembleFragments(fragments, maxInputChars) {
             for (const [key, value] of Object.entries(fragment.value)) {
                 if (Object.hasOwn(fields, key))
                     throw new Error(`Duplicate context field: ${key}`);
+                // defineProperty keeps names such as `__proto__` as own data instead of letting an
+                // assignment reach the object prototype.
                 Object.defineProperty(fields, key, { value, enumerable: true });
             }
         }
-        usage.push({ id: fragment.id, sourceId: fragment.sourceId, trust: fragment.trust, lifetime: fragment.lifetime,
-            chars: serialized.length, maxChars: fragment.maxChars });
+        usage.push({
+            id: fragment.id,
+            sourceId: fragment.sourceId,
+            trust: fragment.trust,
+            lifetime: fragment.lifetime,
+            chars: serialized.length,
+            maxChars: fragment.maxChars,
+        });
     }
-    const messages = [{ role: 'system', content: system.join('\n\n') }, { role: 'user', content: JSON.stringify(fields) }];
+    // Blank-line separation keeps independently declared instructions readable and attributable
+    // while still arriving as one system message.
+    const messages = [
+        { role: 'system', content: system.join('\n\n') },
+        { role: 'user', content: JSON.stringify(fields) },
+    ];
+    // Measured on the exact strings above, so the count matches what the transport will send.
     const inputChars = messages.reduce((sum, message) => sum + message.content.length, 0);
-    validateContextBudget(inputChars, maxInputChars, () => new ValidationError([{ code: 'CONTEXT_BUDGET', message: `上下文超过${maxInputChars}字符；不截断原问题、约束与证据。` }]));
+    validateContextBudget(inputChars, maxInputChars, () => new ValidationError([
+        {
+            code: 'CONTEXT_BUDGET',
+            message: `上下文超过${maxInputChars}字符；不截断原问题、约束与证据。`,
+        },
+    ]));
     return { messages, fragmentUsage: usage, inputChars, maxInputChars };
 }
 export { commonPrefixLength } from '../utils/text.js';

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

@@ -1,3 +1,25 @@
+/**
+ * Structural audit of context fragments before they are assembled.
+ *
+ * A plan may carry the trusted originals plus the fragments an App node produced. This check
+ * permits value rewrites for explicitly mutable fragments and rejects everything structural:
+ * added or removed fragments, changed trust, lifetime or budget, changed value type, changed
+ * field sets, and changes to system or instruction fragments.
+ *
+ * The guarantee is structural only. Whether a rewritten value is semantically faithful needs
+ * an App-side audit.
+ *
+ * Exports: `auditContextChange`.
+ */
 import type { ContextFragment } from '../structs/context/fragments.js';
-/** Structural audit only: semantic fidelity of a summary requires an application audit. */
+/**
+ * Compare trusted originals with the fragments about to be assembled.
+ *
+ * @param original Fragments captured before any App-side processing.
+ * @param current Fragments that will actually be assembled; same length as `original`.
+ * @param mutable Ids explicitly allowed to change value. Everything else is protected.
+ * @returns Nothing; a clean audit has no side effect.
+ * @throws ValidationError when the fragment list, its metadata, the value type or the field
+ *   set changed, or when a protected fragment was rewritten.
+ */
 export declare function auditContextChange(original: readonly ContextFragment[], current: readonly ContextFragment[], mutable: ReadonlySet<string>): void;

package/dist/esm/context/audit.js

@@ -1,19 +1,44 @@
 import { ValidationError } from '../structs/errors.js';
 import { breakWhile } from '../utils/rules.js';
+/** Single code for every violation, so consumers can classify audit failures uniformly. */
 const fail = (message) => new ValidationError([{ code: 'CONTEXT_POLICY', message }]);
-/** Structural audit only: semantic fidelity of a summary requires an application audit. */
+/**
+ * Compare trusted originals with the fragments about to be assembled.
+ *
+ * @param original Fragments captured before any App-side processing.
+ * @param current Fragments that will actually be assembled; same length as `original`.
+ * @param mutable Ids explicitly allowed to change value. Everything else is protected.
+ * @returns Nothing; a clean audit has no side effect.
+ * @throws ValidationError when the fragment list, its metadata, the value type or the field
+ *   set changed, or when a protected fragment was rewritten.
+ */
 export function auditContextChange(original, current, mutable) {
+    // Fragments may be rewritten in place but not added or removed: assembly and audit both
+    // assume the same positions describe the same fragment.
     breakWhile(original.length !== current.length, fail('Context fragments cannot be added or removed'));
     for (const [index, before] of original.entries()) {
         const after = current[index];
+        // Metadata and value are compared separately: only the value may be rewritten, and only
+        // for ids the plan explicitly allows.
         const { value: _before, ...beforeMetadata } = before;
         const { value: _after, ...afterMetadata } = after;
-        breakWhile(Object.keys(beforeMetadata).length !== Object.keys(afterMetadata).length
-            || Object.entries(beforeMetadata).some(([key, value]) => afterMetadata[key] !== value), fail('Context identity, trust and budgets must be preserved'));
+        breakWhile(Object.keys(beforeMetadata).length !== Object.keys(afterMetadata).length ||
+            Object.entries(beforeMetadata).some(([key, value]) => afterMetadata[key] !== value), fail('Context identity, trust and budgets must be preserved'));
+        // A type change would alter how the fragment is serialized, so it is rejected before any
+        // value comparison is attempted.
         breakWhile(typeof before.value !== typeof after.value, fail('Context value type must be preserved'));
+        // String comparison captures both values and their key order; a reordered rewrite counts
+        // as a change, which is the conservative direction for an audit.
         const changed = JSON.stringify(before.value) !== JSON.stringify(after.value);
-        breakWhile(changed && (!mutable.has(before.id) || before.role === 'system' || before.trust === 'instruction'), fail(`Protected context changed: ${before.id}`));
-        if (changed && typeof before.value === 'object' && typeof after.value === 'object')
-            breakWhile(JSON.stringify(Object.keys(before.value).sort()) !== JSON.stringify(Object.keys(after.value).sort()), fail('Context fields must be preserved'));
+        breakWhile(changed &&
+            (!mutable.has(before.id) || before.role === 'system' || before.trust === 'instruction'), fail(`Protected context changed: ${before.id}`));
+        if (changed &&
+            before.value !== null &&
+            after.value !== null &&
+            typeof before.value === 'object' &&
+            typeof after.value === 'object')
+            // Only the field set is compared here; field order is not meaningful for context data.
+            breakWhile(JSON.stringify(Object.keys(before.value).sort()) !==
+                JSON.stringify(Object.keys(after.value).sort()), fail('Context fields must be preserved'));
     }
 }

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

@@ -1,7 +1,41 @@
+/**
+ * Per-fragment validation and the shared input budget.
+ *
+ * A fragment is the only way text enters model context: it declares where it came from
+ * (`sourceId`), how far it may be trusted, its lifetime, and a hard character budget. These
+ * checks run before concatenation, so an oversized or mistrusted fragment fails instead of
+ * being silently truncated or promoted into an instruction.
+ *
+ * Exports: `validateContextFragment`, `validateContextBudget`, and a shared text helper.
+ */
 import type { ContextFragment } from '../structs/context/fragments.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 declare function validateContextFragment(fragment: ContextFragment, ids?: Set<string>, checkBudget?: boolean): string;
-/** 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 declare function validateContextBudget(inputChars: number, maxInputChars: number, exceeded?: (limit: number) => Error): void;
 export { commonPrefixLength } from '../utils/text.js';
-export type { ContextTrust, ContextLifetime, ContextFragment, ContextFragmentUsage, BuiltContext } from '../structs/context/fragments.js';
+export type { ContextTrust, ContextLifetime, ContextFragment, ContextFragmentUsage, BuiltContext, } from '../structs/context/fragments.js';