@jini-ai/core 0.6.15-rc.1 → 0.6.15

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @jini-ai/core
 
+## 0.6.15
+
+### Minor Changes
+
+- Export async WebCrypto `canonicalArgumentDigest` from `@jini-ai/core/records`, reusing
+  `canonicalJson` for identical plugin and host SHA-256 hex digests. Canonical JSON now
+  sorts keys recursively by Unicode code point and throws `CanonicalJsonError` for
+  non-JSON values and cycles; undefined object properties remain omitted.
+
+  MCP approval fingerprints reuse the core serializer. Existing ordinary JSON
+  fingerprints retain their bytes; non-JSON schemas now fail instead of colliding
+  with valid JSON, and astral object keys follow the shared code-point ordering.
+
+- Export generic tool-contributor, derived-contributor and paired-registry contracts
+  from the existing contribution-registry owner without coupling core to host surfaces.
+
 ## 0.6.13
 
 ### Patch Changes

package/README.md

@@ -100,6 +100,7 @@ Tool handlers receive required execution context first and optional `{ emitSurfa
 | subpath | what's behind it |
 |---|---|
 | `./fetch` | Framework-neutral query contracts and `FetchQueryCache`; inject transport callbacks, `Clock`, scheduler and connectivity/focus ports. No React, DOM or TanStack dependency. |
+| `./records` | `canonicalJson({ value })`, async WebCrypto `canonicalArgumentDigest({ args }, { crypto? })`, and `CanonicalJsonError`; recursively sorted Unicode code-point keys, strict JSON validation, and lowercase SHA-256 hex. |
 | `.` | The public surface above: tokens, packs, daemon composition, tool registry (descriptors only), principal, redact, auth primitives. |
 | `./composition` | **Not part of the public contract.** Exposes `authorizeToolInvocation` (resolves a registry's tool and runs its authorization gate — a security-sensitive value export, but one that only ever hands back a handler alongside an `'allow'` decision) plus type-only `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` re-derivation helpers. Its sole intended consumers are `@jini-ai/daemon`'s `ToolExecutor` and `@jini-ai/server`'s `createLocalNodeDaemon`. Node's resolver will happily let any consumer import it — the boundary is enforced by `scripts/check-engine-boundaries.ts`, not by the exports map — so external adopters should treat it as off-limits regardless. |
 

package/dist/approval.d.ts

@@ -15,11 +15,13 @@ export type ApprovalAnswer = {
     reason: 'declined' | 'expired' | 'abandoned';
 };
 /** The decision reducer shared by parked tool calls and the browser's explicit reply transport.
- * An answer never revives an aborted operation. Transport failures propagate without an effect. */
+ * An answer never revives an aborted operation. Transport failures propagate without an effect.
+ * @param optional.onApprovalStateChange Reports only the human wait, released on every outcome.
+ * @complexity O(1) local time/space plus the injected human transport's wait. */
 export declare function resolveApproval({ signal, askHuman }: {
     signal: AbortSignal;
     askHuman: () => Promise<ApprovalAnswer>;
-}, _optional?: {}): Promise<ApprovalAnswer>;
+}, { onApprovalStateChange }?: Pick<ToolExecutionOptions, 'onApprovalStateChange'>): Promise<ApprovalAnswer>;
 export interface RememberedApprovalPort {
     has(required: {
         ctx: ToolExecutionContext;

package/dist/approval.js

@@ -2,19 +2,23 @@ import { humanConfirmedHandler, requireInputRecord } from './registration-kit.js
 import { ToolInputError } from './tool-registry.js';
 import { isNonArrayRecord } from './records.js';
 /** The decision reducer shared by parked tool calls and the browser's explicit reply transport.
- * An answer never revives an aborted operation. Transport failures propagate without an effect. */
-export async function resolveApproval({ signal, askHuman }, _optional = {}) {
+ * An answer never revives an aborted operation. Transport failures propagate without an effect.
+ * @param optional.onApprovalStateChange Reports only the human wait, released on every outcome.
+ * @complexity O(1) local time/space plus the injected human transport's wait. */
+export async function resolveApproval({ signal, askHuman }, { onApprovalStateChange } = {}) {
     if (signal.aborted)
         return { confirmed: false, reason: 'abandoned' };
     let abandon;
     const aborted = new Promise(resolve => { abandon = () => resolve({ confirmed: false, reason: 'abandoned' }); });
     signal.addEventListener('abort', abandon, { once: true });
     try {
+        onApprovalStateChange?.({ pending: true });
         const answer = await Promise.race([askHuman(), aborted]);
         return signal.aborted ? { confirmed: false, reason: 'abandoned' } : answer;
     }
     finally {
         signal.removeEventListener('abort', abandon);
+        onApprovalStateChange?.({ pending: false });
     }
 }
 /** The confirmer is always the run's own delegating principal, as a user. */
@@ -38,7 +42,7 @@ export function createApprovalHandler(steps, { remembered } = {}) {
     /** Ask the host transport; record the choice and any reusable grant only on an explicit yes. */
     const askFresh = async ({ prepared, plan }, options = {}) => {
         const { ctx } = prepared;
-        const answer = await resolveApproval({ signal: ctx.signal, askHuman: () => steps.askHuman({ ctx, description: plan.description }, options) });
+        const answer = await resolveApproval({ signal: ctx.signal, askHuman: () => steps.askHuman({ ctx, description: plan.description }, options) }, options);
         if (ctx.signal.aborted)
             return abandoned(prepared);
         if (answer.confirmed !== true)

package/dist/batch-tool-inputs.js

@@ -26,7 +26,13 @@ export function batchOutcomeFor({ output }, _options = {}) {
     if (!isPlainObject(output) || output.batch !== true || !Array.isArray(output.results) || output.results.length === 0)
         return undefined;
     const failed = output.results.filter(item => isPlainObject(item) && item.ok === false).length;
-    return failed === 0 ? 'completed' : failed === output.results.length ? 'error' : 'partial_failure';
+    return outcomeFor({ failed, total: output.results.length });
+}
+/** No failure completes the batch, all failing is an error, anything between is partial. */
+function outcomeFor({ failed, total }) {
+    if (failed === 0)
+        return 'completed';
+    return failed === total ? 'error' : 'partial_failure';
 }
 /** A JSON object: not null, not an array. */
 function isPlainObject(value) {
@@ -54,7 +60,8 @@ export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
     }
     const maxItems = tool.maxItems ?? DEFAULT_MAX_BATCH_ITEMS;
     const requiredFields = schema.required ?? [];
-    const { required: _required, ...rest } = schema;
+    const rest = { ...schema };
+    delete rest.required;
     const needs = requiredFields.length > 0 ? ` Each item needs ${requiredFields.join(", ")} (inside each item).` : "";
     const items = {
         type: "array",
@@ -119,7 +126,7 @@ function batchItemResult({ index, output, notes }, _options = {}) {
  */
 function summarizeBatchResults({ results }, _options = {}) {
     const succeeded = results.filter((result) => result.ok).length;
-    const outcome = succeeded === results.length ? 'completed' : succeeded === 0 ? 'error' : 'partial_failure';
+    const outcome = outcomeFor({ failed: results.length - succeeded, total: results.length });
     return { batch: true, outcome, ...(succeeded === 0 ? { isError: true } : {}), total: results.length, succeeded, failed: results.length - succeeded, results };
 }
 /**

package/dist/contribution-registry.d.ts

@@ -1,3 +1,26 @@
+import type { DerivedRiskByToolId } from './registration-kit.js';
+import type { ToolRegistration } from './tool-registry.js';
+/** A domain owns its builder and risk classification; the host binds dependencies and surfaces. */
+export interface ToolContributor<TDeps, TSurfaces> {
+    readonly domain: string;
+    readonly build: (deps: TDeps, surfaces: TSurfaces) => ToolRegistration[];
+    readonly risk: DerivedRiskByToolId;
+}
+/** Post-processing sees the domain registrations; ordering and collision checks belong to the host. */
+export interface DerivedToolContributor<TDeps, TSurfaces> {
+    readonly domain: string;
+    readonly derive: (input: {
+        readonly registrations: readonly ToolRegistration[];
+        readonly routeDeps: TDeps;
+        readonly surfaces: TSurfaces;
+    }) => ToolRegistration[];
+    readonly risk: DerivedRiskByToolId;
+}
+/** The two ordered registries belong to one composition root, never shared across workspaces. */
+export interface ToolContributions<TDeps, TSurfaces> {
+    readonly contributors: ContributionRegistry<ToolContributor<TDeps, TSurfaces>>;
+    readonly derivedContributors: ContributionRegistry<DerivedToolContributor<TDeps, TSurfaces>>;
+}
 /** Replace-by-key registry for host-owned contributions; no singleton or execution surface. */
 export interface ContributionRegistry<TContribution> {
     register(required: {

package/dist/fetch/cache.d.ts

@@ -110,6 +110,7 @@ export declare class FetchQueryCache {
     invalidate({ prefix }: {
         prefix: QueryKey;
     }): void;
+    private reloadInvalidated;
     onFocus(): void;
     /** Execute a read/write once connectivity returns; failures are not retried.
      * @param required.run Operation to invoke online.

package/dist/fetch/cache.js

@@ -16,7 +16,9 @@ const browserScheduler = {
 // Normalize unknown promise rejections once so consumers receive Error without repeating
 // the same narrowing boilerplate at every read and write call site.
 export function toQueryError(value) {
-    return value instanceof Error ? value : new Error(typeof value === 'string' && value.trim() ? value : 'request failed');
+    if (value instanceof Error)
+        return value;
+    return new Error(typeof value === 'string' && value.trim() ? value : 'request failed');
 }
 /** One provider-owned cache. Requests are shared by structural primitive keys.
  * Failed reads retain earlier data; replacement writes supersede older requests.
@@ -162,12 +164,17 @@ export class FetchQueryCache {
             const pendingRead = entry.pendingRead;
             entry.pending = undefined;
             entry.pendingRead = undefined;
-            if (entry.observers.size)
-                this.refresh(entry);
-            // An awaiting loader still needs an answer even if no observer is mounted.
-            else if (pendingRead)
-                void this.load({ entry, ...pendingRead });
+            this.reloadInvalidated(entry, pendingRead);
+        }
+    }
+    reloadInvalidated(entry, pendingRead) {
+        if (entry.observers.size) {
+            this.refresh(entry);
+            return;
         }
+        // An awaiting loader still needs an answer even if no observer is mounted.
+        if (pendingRead)
+            void this.load({ entry, ...pendingRead });
     }
     onFocus() {
         for (const entry of this.entries.values()) {
@@ -249,7 +256,8 @@ export class FetchQueryCache {
     }
     scheduleEviction(entry) {
         this.cancelEviction(entry);
-        if (this.disposed || entry.listeners.size || entry.observers.size || entry.pending || !Number.isFinite(entry.retention))
+        const inUse = entry.listeners.size > 0 || entry.observers.size > 0 || Boolean(entry.pending);
+        if (this.disposed || inUse || !Number.isFinite(entry.retention))
             return;
         entry.eviction = this.scheduler.schedule({ callback: () => this.entries.delete(JSON.stringify(entry.key)), delayMs: entry.retention });
     }

package/dist/index.d.ts

@@ -17,7 +17,8 @@ export * from './tool-tokens.js';
 export * from './tool-exposure.js';
 export * from './gated-mutations.js';
 export * from './model-facing-tool-errors.js';
-export * from './contribution-registry.js';
+export { createContributionRegistry } from './contribution-registry.js';
+export type { ContributionRegistry, ToolContributor, DerivedToolContributor, ToolContributions } from './contribution-registry.js';
 export * from './provider-registry.js';
 export * from './object-store.js';
 export * from './naming.js';

package/dist/index.js

@@ -14,7 +14,7 @@ export * from './tool-tokens.js';
 export * from './tool-exposure.js';
 export * from './gated-mutations.js';
 export * from './model-facing-tool-errors.js';
-export * from './contribution-registry.js';
+export { createContributionRegistry } from './contribution-registry.js';
 export * from './provider-registry.js';
 export * from './object-store.js';
 export * from './naming.js';

package/dist/origin-validation.js

@@ -134,7 +134,13 @@ function parseDottedQuad(host) {
 }
 /** RFC 1918 (10/8, 172.16/12, 192.168/16) or link-local (169.254/16), from the first two octets. */
 function isPrivateIpv4Prefix([a, b]) {
-    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    if (a === 10)
+        return true;
+    if (a === 172)
+        return b >= 16 && b <= 31;
+    if (a === 192)
+        return b === 168;
+    return a === 169 && b === 254;
 }
 /** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16).
  * Implements the dev-browser LAN allow-list, not SSRF blocking. Use @jini-ai/platform/net
@@ -152,17 +158,12 @@ export function isIpLiteralHostname({ hostname }) {
         return true;
     return parseDottedQuad(host) !== undefined;
 }
+const LOOPBACK_OR_UNSPECIFIED_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0', '::']);
 /** Whether `hostname` is loopback, unspecified, or a private-LAN address.
  * Implements the dev-browser LAN allow-list, not SSRF blocking (@jini-ai/platform/net). */
 export function isLoopbackOrPrivateLanHost({ hostname }) {
     const host = String(hostname || '').toLowerCase();
-    return (host === 'localhost' ||
-        host === '127.0.0.1' ||
-        host === '::1' ||
-        host === '[::1]' ||
-        host === '0.0.0.0' ||
-        host === '::' ||
-        isPrivateIpv4({ hostname: host }));
+    return LOOPBACK_OR_UNSPECIFIED_HOSTS.has(host) || isPrivateIpv4({ hostname: host });
 }
 /** Whether a request's `Host` header names a locally-served or explicitly allow-listed host. */
 export function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowedOrigins }) {

package/dist/primitives/index.d.ts

@@ -8,4 +8,5 @@ export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';
 export * from './tasks.js';
+export { trimChars, trimCharsEnd, trimCharsStart } from './trim-chars.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/primitives/index.js

@@ -7,4 +7,5 @@ export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';
 export * from './tasks.js';
+export { trimChars, trimCharsEnd, trimCharsStart } from './trim-chars.js';
 //# sourceMappingURL=index.js.map

package/dist/primitives/paths.js

@@ -1,3 +1,4 @@
+import { trimCharsEnd } from './trim-chars.js';
 /** Root of an already `/`-separated Windows path: a drive root (`C:/`) or a UNC share root. */
 function windowsRoot(path) {
     return /^[A-Za-z]:\//.exec(path)?.[0] ?? /^\/\/[^/]+\/[^/]+(?:\/|$)/.exec(path)?.[0];
@@ -22,7 +23,7 @@ function normalizeAbsolutePath(value, separator) {
     const prefix = (windows ? windowsRoot(path) : undefined) ?? (path.startsWith('/') ? '/' : undefined);
     if (!prefix)
         throw new RangeError('pathContains requires resolved absolute paths');
-    return prefix.replace(/\/+$/, '') + '/' + resolveSegments(path.slice(prefix.length)).join('/');
+    return trimCharsEnd({ text: prefix, chars: '/' }) + '/' + resolveSegments(path.slice(prefix.length)).join('/');
 }
 /**
  * Check lexical containment using whole directory segments, including equality.

package/dist/primitives/sse.js

@@ -33,13 +33,14 @@ function createRecordDecoder() {
             let value = colon === -1 ? '' : line.slice(colon + 1);
             if (value.startsWith(' '))
                 value = value.slice(1);
+            // The field names are distinct, so at most one of these applies; retry/unknown fields do not
+            // belong to per-record interpretation.
             if (field === 'event')
                 event = value;
-            else if (field === 'data')
+            if (field === 'data')
                 dataLines.push(value);
-            else if (field === 'id')
+            if (field === 'id')
                 id = value;
-            // retry/unknown fields do not belong to per-record interpretation.
         },
         take() {
             const frame = { event, data: dataLines.join('\n'), dataLines, ...(id !== undefined ? { id } : {}) };

package/dist/primitives/trim-chars.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file Linear-time trimming of an arbitrary character set from either end of a string. The regex
+ * spellings these replace (`s.replace(/\/+$/, '')`, `s.replace(/^-+|-+$/g, '')`) backtrack
+ * quadratically on long runs of the trimmed character that do not reach the end, because the
+ * engine retries the `+` run from every start position. A leaf module with no imports.
+ */
+/** Strips every trailing character contained in `chars` (a set of single UTF-16 units).
+ *  Same result as `text.replace(/[chars]+$/, '')`. @complexity O(text length). */
+export declare function trimCharsEnd({ text, chars }: {
+    text: string;
+    chars: string;
+}): string;
+/** Strips every leading character contained in `chars`. Same result as
+ *  `text.replace(/^[chars]+/, '')`. @complexity O(text length). */
+export declare function trimCharsStart({ text, chars }: {
+    text: string;
+    chars: string;
+}): string;
+/** Strips `chars` from both ends. Same result as `text.replace(/^[chars]+|[chars]+$/g, '')`.
+ *  @complexity O(text length). */
+export declare function trimChars({ text, chars }: {
+    text: string;
+    chars: string;
+}): string;
+//# sourceMappingURL=trim-chars.d.ts.map

package/dist/primitives/trim-chars.js

@@ -0,0 +1,28 @@
+/**
+ * @file Linear-time trimming of an arbitrary character set from either end of a string. The regex
+ * spellings these replace (`s.replace(/\/+$/, '')`, `s.replace(/^-+|-+$/g, '')`) backtrack
+ * quadratically on long runs of the trimmed character that do not reach the end, because the
+ * engine retries the `+` run from every start position. A leaf module with no imports.
+ */
+/** Strips every trailing character contained in `chars` (a set of single UTF-16 units).
+ *  Same result as `text.replace(/[chars]+$/, '')`. @complexity O(text length). */
+export function trimCharsEnd({ text, chars }) {
+    let end = text.length;
+    while (end > 0 && chars.includes(text.charAt(end - 1)))
+        end -= 1;
+    return text.slice(0, end);
+}
+/** Strips every leading character contained in `chars`. Same result as
+ *  `text.replace(/^[chars]+/, '')`. @complexity O(text length). */
+export function trimCharsStart({ text, chars }) {
+    let start = 0;
+    while (start < text.length && chars.includes(text.charAt(start)))
+        start += 1;
+    return text.slice(start);
+}
+/** Strips `chars` from both ends. Same result as `text.replace(/^[chars]+|[chars]+$/g, '')`.
+ *  @complexity O(text length). */
+export function trimChars({ text, chars }) {
+    return trimCharsStart({ text: trimCharsEnd({ text, chars }), chars });
+}
+//# sourceMappingURL=trim-chars.js.map

package/dist/records.d.ts

@@ -1,4 +1,4 @@
-/** @file Pure object-shape predicates shared by tool input readers and render-time decoders. */
+/** @file Object-shape predicates and canonical JSON shared by tool readers and request digests. */
 /** Accept any non-null object, including arrays; never sanitizes or reads properties.
  * @complexity O(1) time and space.
  * @example isRecord({ value: [] }); // true
@@ -45,14 +45,37 @@ export declare function deleteMapRecord<Key, Row extends object>({ records, key,
     key: Key;
     fields: Partial<Row>;
 }, _optional?: Record<string, never>): void;
+/** Invalid canonical JSON input. Messages never include argument contents. */
+export declare class CanonicalJsonError extends TypeError {
+    constructor(required: {
+        readonly message: string;
+    });
+}
 /**
- * Canonical JSON: object keys sorted, `undefined` members dropped, array order kept, so equal
- * JSON-like values serialize identically regardless of key order (fingerprints, request digests).
- * Objects serialize by own enumerable keys only, so a Date or Map becomes `{}`: pass JSON-like values.
- * @complexity O(n log n) time over n object keys, O(n) space.
+ * Canonical JSON: recursively sort object keys by Unicode code point, omit undefined object
+ * properties, and preserve array order. Uses JSON scalar escaping without invoking toJSON hooks.
+ * @param required.value JSON input; shared references are allowed. Does not mutate input.
+ * @throws CanonicalJsonError for non-JSON values (including array holes) and cycles.
+ * @complexity O(s + sum(k log k * l)) time for s output bytes, k keys per object and key length l;
+ * O(s * d) worst-case space for nesting depth d, including intermediate strings and recursion.
  * @example canonicalJson({ value: { b: 1, a: 2 } }); // '{"a":2,"b":1}'
  */
 export declare function canonicalJson(required: {
     readonly value: unknown;
-}, _optional?: {}): string;
+}, _optional?: Record<string, never>): string;
+/**
+ * SHA-256 lowercase hex over canonical UTF-8 tool arguments, shared by plugins and host gates.
+ * @param required.args JSON arguments; validation completes before hashing starts.
+ * @param optional.crypto Host WebCrypto port; defaults to the runtime's global WebCrypto.
+ * @returns An asynchronous digest, usable in browsers and Node without Node imports.
+ * @throws CanonicalJsonError for invalid arguments; WebCrypto failures propagate.
+ * @complexity Canonical serialization cost plus O(s) hashing time and space for s UTF-8 bytes.
+ */
+export declare function canonicalArgumentDigest(required: {
+    readonly args: unknown;
+}, { crypto }?: {
+    readonly crypto?: {
+        readonly subtle: Pick<typeof globalThis.crypto.subtle, 'digest'>;
+    };
+}): Promise<string>;
 //# sourceMappingURL=records.d.ts.map

package/dist/records.js

@@ -1,4 +1,4 @@
-/** @file Pure object-shape predicates shared by tool input readers and render-time decoders. */
+/** @file Object-shape predicates and canonical JSON shared by tool readers and request digests. */
 /** Accept any non-null object, including arrays; never sanitizes or reads properties.
  * @complexity O(1) time and space.
  * @example isRecord({ value: [] }); // true
@@ -43,23 +43,113 @@ export function deleteMapRecord({ records, key, fields }, _optional = {}) {
     if (record && matchesRecordFields({ record, fields }))
         records.delete(key);
 }
+/** Invalid canonical JSON input. Messages never include argument contents. */
+export class CanonicalJsonError extends TypeError {
+    constructor(required) {
+        super(required.message);
+        this.name = 'CanonicalJsonError';
+    }
+}
+/** Compare Unicode code points, including astral characters; UTF-16 sort differs above U+FFFF.
+ * @complexity O(l) time and space for the combined key length l.
+ */
+function compareJsonKeys(left, right) {
+    const a = Array.from(left);
+    const b = Array.from(right);
+    for (let index = 0; index < Math.min(a.length, b.length); index++) {
+        const difference = a[index].codePointAt(0) - b[index].codePointAt(0);
+        if (difference !== 0)
+            return difference;
+    }
+    return a.length - b.length;
+}
+/** Serialize JSON scalars without JSON.stringify's lossy non-JSON fallbacks.
+ * @throws CanonicalJsonError for unsupported types or non-finite numbers.
+ * @complexity O(s) time and space for s serialized characters.
+ */
+function canonicalScalar(value) {
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return JSON.stringify(value);
+        case 'number':
+            if (Number.isFinite(value))
+                return JSON.stringify(value);
+            throw new CanonicalJsonError({ message: 'Canonical JSON requires finite numbers.' });
+        default:
+            throw new CanonicalJsonError({ message: 'Canonical JSON requires JSON values.' });
+    }
+}
+/** Serialize own enumerable JSON fields; class instances must not silently collapse to {}.
+ * @throws CanonicalJsonError for non-JSON objects or enumerable symbol keys.
+ * @complexity O(k log k * l + s) time and O(s + k * l) space, plus recursive children.
+ */
+function canonicalObject(value, ancestors) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new CanonicalJsonError({ message: 'Canonical JSON requires plain objects or arrays.' });
+    }
+    if (Object.getOwnPropertySymbols(value).some(key => Object.prototype.propertyIsEnumerable.call(value, key))) {
+        throw new CanonicalJsonError({ message: 'Canonical JSON requires string object keys.' });
+    }
+    const record = value;
+    // Object keys are unique, so comparing their code points gives a total order here.
+    const members = Object.keys(record).sort(compareJsonKeys).flatMap(key => {
+        const child = record[key];
+        if (child === undefined)
+            return [];
+        return [`${JSON.stringify(key)}:${canonicalValue(child, ancestors)}`];
+    });
+    return `{${members.join(',')}}`;
+}
+/** Track only active ancestors: repeated references are JSON, back-edges are cycles.
+ * @throws CanonicalJsonError for cycles or non-JSON children.
+ * @complexity O(s + sum(k log k * l)) time; O(s * d) worst-case space for depth d.
+ */
+function canonicalValue(value, ancestors) {
+    if (value === null)
+        return 'null';
+    if (typeof value !== 'object')
+        return canonicalScalar(value);
+    if (ancestors.has(value))
+        throw new CanonicalJsonError({ message: 'Canonical JSON does not support cycles.' });
+    ancestors.add(value);
+    try {
+        if (!Array.isArray(value))
+            return canonicalObject(value, ancestors);
+        // Read every index: holes must fail, and a custom iterator must not change the argument order.
+        const children = [];
+        for (let index = 0; index < value.length; index++)
+            children.push(canonicalValue(value[index], ancestors));
+        return `[${children.join(',')}]`;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
 /**
- * Canonical JSON: object keys sorted, `undefined` members dropped, array order kept, so equal
- * JSON-like values serialize identically regardless of key order (fingerprints, request digests).
- * Objects serialize by own enumerable keys only, so a Date or Map becomes `{}`: pass JSON-like values.
- * @complexity O(n log n) time over n object keys, O(n) space.
+ * Canonical JSON: recursively sort object keys by Unicode code point, omit undefined object
+ * properties, and preserve array order. Uses JSON scalar escaping without invoking toJSON hooks.
+ * @param required.value JSON input; shared references are allowed. Does not mutate input.
+ * @throws CanonicalJsonError for non-JSON values (including array holes) and cycles.
+ * @complexity O(s + sum(k log k * l)) time for s output bytes, k keys per object and key length l;
+ * O(s * d) worst-case space for nesting depth d, including intermediate strings and recursion.
  * @example canonicalJson({ value: { b: 1, a: 2 } }); // '{"a":2,"b":1}'
  */
 export function canonicalJson(required, _optional = {}) {
-    const { value } = required;
-    if (Array.isArray(value))
-        return `[${value.map(item => canonicalJson({ value: item })).join(',')}]`;
-    if (value !== null && typeof value === 'object') {
-        const record = value;
-        const members = Object.keys(record).filter(key => record[key] !== undefined).sort()
-            .map(key => `${JSON.stringify(key)}:${canonicalJson({ value: record[key] })}`);
-        return `{${members.join(',')}}`;
-    }
-    return JSON.stringify(value) ?? 'null';
+    return canonicalValue(required.value, new Set());
+}
+/**
+ * SHA-256 lowercase hex over canonical UTF-8 tool arguments, shared by plugins and host gates.
+ * @param required.args JSON arguments; validation completes before hashing starts.
+ * @param optional.crypto Host WebCrypto port; defaults to the runtime's global WebCrypto.
+ * @returns An asynchronous digest, usable in browsers and Node without Node imports.
+ * @throws CanonicalJsonError for invalid arguments; WebCrypto failures propagate.
+ * @complexity Canonical serialization cost plus O(s) hashing time and space for s UTF-8 bytes.
+ */
+export async function canonicalArgumentDigest(required, { crypto = globalThis.crypto } = {}) {
+    const json = canonicalJson({ value: required.args });
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(json));
+    return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('');
 }
 //# sourceMappingURL=records.js.map

package/dist/redact.d.ts

@@ -38,7 +38,6 @@ export interface SecretShapePattern {
 }
 export declare const PEM_PATTERN_NAME = "PEM private key block";
 export declare const SECRET_SHAPE_PATTERNS: readonly SecretShapePattern[];
-/** Broad token shapes for agent-failure text; consumers retain their plain [REDACTED] pipeline. */
 export declare const AGENT_FAILURE_SECRET_SHAPE_RE: RegExp;
 /**
  * Exact path SEGMENT names refused at any depth, matched case-insensitively against each segment