@jini-ai/core 0.6.15-rc.2 → 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/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/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

package/dist/redact.js

@@ -53,7 +53,16 @@ export const SECRET_SHAPE_PATTERNS = [
     { name: PEM_PATTERN_NAME, pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
 ];
 /** Broad token shapes for agent-failure text; consumers retain their plain [REDACTED] pipeline. */
-export const AGENT_FAILURE_SECRET_SHAPE_RE = /\b(?:AIza[\w-]+|AQ\.[\w.\/-]+|sk-[\w.-]+|gh[pousr]_[\w]+|github_pat_[\w]+|ya29\.[\w.-]+|eyJ[\w-]+\.[\w-]+(?:\.[\w-]+)?)/g;
+const AGENT_FAILURE_TOKEN_SHAPES = [
+    /AIza[\w-]+/, // Google API key
+    /AQ\.[\w.\/-]+/, // AI Studio key
+    /sk-[\w.-]+/, // OpenAI-style secret key
+    /gh[pousr]_\w+/, // GitHub token
+    /github_pat_\w+/, // GitHub fine-grained token
+    /ya29\.[\w.-]+/, // Google OAuth access token
+    /eyJ[\w-]+\.[\w-]+(?:\.[\w-]+)?/, // JWT
+];
+export const AGENT_FAILURE_SECRET_SHAPE_RE = new RegExp(`\\b(?:${AGENT_FAILURE_TOKEN_SHAPES.map((shape) => shape.source).join('|')})`, 'g');
 /**
  * Exact path SEGMENT names refused at any depth, matched case-insensitively against each segment
  * of the caller-supplied path (never a substring — a directory named `not-secrets-actually` is not
@@ -89,6 +98,12 @@ export const LOCAL_OWNER_PROXY_MARKER_HEADERS = [
 // Order matters: list specific rules before more general ones. Langfuse
 // keys (`sk-lf-...`) would otherwise be eaten by the generic `sk-...`
 // rule and labeled as a generic OpenAI-style key.
+// One IPv4 octet, 0-255, so junk shapes like 999.1.1.1 do not count.
+const IPV4_OCTET = '(?:25[0-5]|2[0-4]\\d|[01]?\\d?\\d)';
+// Optional +country code, then a bare or parenthesized area code, with optional separators.
+const PHONE_SEPARATOR = '[\\s.-]?';
+const PHONE_COUNTRY_CODE = /(?:\+?\d{1,3}[\s.-]?)?/;
+const PHONE_AREA_CODE = /(?:\(\d{3}\)|\d{3})/;
 const PATTERNS = [
     // Langfuse public/secret keys (pk-lf- / sk-lf-). Must run before the
     // generic sk- rule so the more specific label wins.
@@ -124,14 +139,16 @@ const PATTERNS = [
     // Bearer tokens in HTTP Authorization header copy/paste. We only match
     // the value, not the literal 'Bearer ', so the marker stays readable in
     // the redacted output ("Authorization: Bearer [REDACTED:bearer_token]").
-    { name: 'bearer_token', regex: /(?<=\bBearer\s+)[A-Za-z0-9._~+/-]{16,}={0,2}/g },
+    // The leading lookahead only lets the lookbehind run where a value can start, so a long
+    // whitespace run is not rescanned from every position inside it.
+    { name: 'bearer_token', regex: /(?=[A-Za-z0-9._~+/-])(?<=\bBearer\s+)[A-Za-z0-9._~+/-]{16,}={0,2}/g },
     // Alphabetic TLDs preserve versioned package paths in error stacks (e.g. pkg@1.2.3).
     { name: 'email', regex: /\b[\w.+-]+@(?:[\w-]+\.)+[A-Za-z]{2,}\b/g },
     // IPv4. Reject all-zero / 255.255.255.255-ish junk shapes by gating on
     // each octet being 0-255.
     {
         name: 'ipv4',
-        regex: /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d?\d)\b/g,
+        regex: new RegExp(`\\b(?:${IPV4_OCTET}\\.){3}${IPV4_OCTET}\\b`, 'g'),
     },
     // Phone numbers. Tight US-leaning shape; a global PII detector would
     // need a real lib. We keep this so US-based test prompts ('call me at
@@ -141,7 +158,7 @@ const PATTERNS = [
     // hashes and identifiers stay readable; separators within phones still match.
     {
         name: 'phone',
-        regex: /(?<![\w-])(?:\+?\d{1,3}[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}(?![\w-])/g,
+        regex: new RegExp(`(?<![\\w-])${PHONE_COUNTRY_CODE.source}${PHONE_AREA_CODE.source}${PHONE_SEPARATOR}\\d{3}${PHONE_SEPARATOR}\\d{4}(?![\\w-])`, 'g'),
     },
 ];
 // Credit card sweep is special: a naive 13-19 digit run matches a lot of
@@ -184,14 +201,18 @@ function isLuhnValid(digits) {
 const SECRET_LABELS = 'authorization|bearer|api[-_]?key|access[-_]?token|refresh[-_]?token|client[-_]?secret|password|secret|cookie';
 export const LABELED_SECRET_RE = new RegExp(`\\b(${SECRET_LABELS})\\b\\s*[:=]\\s*\\S+`, 'gi');
 export const OPAQUE_TOKEN_RE = /[A-Za-z0-9_-]{20,}/g;
-export const NON_SECRET_TOKEN_RE = /^(?:ERR-[0-9A-F]{4}(?:-[0-9A-F]{4}){3}|delegated-tool-calls|[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)$/;
+// Pattern parts, only ever used inside the anchored NON_SECRET_TOKEN_RE.
+const CORRELATION_ID = 'ERR-[0-9A-F]{4}(?:-[0-9A-F]{4}){3}';
+const UPPER_SNAKE_DIAGNOSTIC = '[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+';
+export const NON_SECRET_TOKEN_RE = new RegExp(`^(?:${CORRELATION_ID}|delegated-tool-calls|${UPPER_SNAKE_DIAGNOSTIC})$`);
 // Runtime markers must survive a second pass; the bounded sanitizer deliberately retains
 // its historical lowercase marker contract and uses the unmodified lexical vocabulary.
 // Reject a masked header/query value before matching, so a following field's credential
 // remains available to the global scan rather than being consumed beside the marker.
 const MASK_AWARE_LABELED_SECRET_RE = new RegExp(LABELED_SECRET_RE.source.replace(/\\S\+$/, "(?!Bearer\\s+\\[REDACTED:[^\\]]+\\](?:\\s|$))(?!\\[REDACTED:[^\\]]+\\][;&])(\\S+)"), LABELED_SECRET_RE.flags);
 // Provider failures also echo short bearer values. Exclude our own marker on subsequent passes.
-const SHORT_BEARER_RE = /(?<=Bearer\s+)[A-Za-z0-9_\-.+/=]+/gi;
+// The leading lookahead only lets the lookbehind run where a value can start (see bearer_token).
+const SHORT_BEARER_RE = /(?=[\w.+/=-])(?<=Bearer\s+)[\w.+/=-]+/gi;
 const PROVIDER_API_KEY_HEADER = /(x-api-key|api-key|x-goog-api-key)\s*[:=]\s*([^\s,;"']+)/gi;
 const PROVIDER_API_KEY_QUERY = /([?&]key=)([^&\s]+)/gi;
 // URL userinfo and signed query values have explicit credential context; unlike opaque runs,
@@ -205,7 +226,8 @@ const SIGNED_QUERY_RE = /([?&](?:signature|sig|x-amz-signature|x-goog-signature|
 // monkey) are masked too; over-masking a URL value is the cheaper failure. Empty values stay.
 // Match through a trailing fragment; only '&', quotes, parentheses or whitespace end the value.
 // Both name runs are bounded so a long separator-free run costs linear time, not quadratic.
-const URL_SECRET_PARAM_RE = /[?&#;]([\w.-]{0,128}?(?:token|key|secret|signature|sig|code|password|passwd|pwd|auth|authorization|credential)s?(?=[._=-])[\w.-]{0,128})=[^&\s"'<>()]+/gi;
+const URL_SECRET_WORDS = 'token|key|secret|signature|sig|code|password|passwd|pwd|auth|authorization|credential';
+const URL_SECRET_PARAM_RE = new RegExp(`[?&#;]([\\w.-]{0,128}?(?:${URL_SECRET_WORDS})s?(?=[._=-])[\\w.-]{0,128})=[^&\\s"'<>()]+`, 'gi');
 // A parameter the labeled rule already names (password, client_secret, ...) keeps that category.
 const LABELED_URL_PARAM_NAME_RE = new RegExp(`(?:^|[.-])(?:${SECRET_LABELS})$`, 'i');
 // Only an entire marker is already masked. A secret glued onto marker-like text still needs

package/dist/registration-kit.js

@@ -443,9 +443,7 @@ function registrationFor({ spec, id, handler }) {
 /** The tripwire: a catalog entry is either wired or recorded as deliberately unwired, never silently neither. */
 function assertEveryEntryIsWiredOrDeclared({ spec }, { unwiredToolIds } = {}) {
     for (const id of spec.catalog.keys()) {
-        if (id in spec.handlers)
-            continue;
-        if (unwiredToolIds?.has(id))
+        if (id in spec.handlers || unwiredToolIds?.has(id))
             continue;
         throw new Error(`tool-registrations: ${spec.domain} catalog entry '${id}' is neither wired nor declared unwired — wire a handler for it, or add it to that domain's unwired set with the reason recorded next to it`);
     }

package/dist/settings/agent-tools.js

@@ -43,6 +43,8 @@
  * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 import { AGENT_WRITABLE_PREFERENCE_IDS, AGENT_WRITABLE_PREFERENCES } from "./agent-writable-preferences.js";
+/** The side-effect class every settings write tool declares. */
+const MUTATES_DURABLE_STATE = "mutates-durable-state";
 /**
    * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
    * (a host's tool-registration layer refuses to wire any tool lacking one). Optional — the two bulk/schema
@@ -163,7 +165,7 @@ export function getSettingsAgentToolCatalog() {
         {
             name: "settings_set_ui_preference",
             description: "Sets one of the operator's own admin-UI preferences (interface language, theme, accent color, or notification sounds) and returns the stored value. Writes only to the calling operator's own user layer — it cannot target another operator, another scope, or any setting outside its fixed list. Use settings_get_effective to read current values first.",
-            sideEffects: "mutates-durable-state",
+            sideEffects: MUTATES_DURABLE_STATE,
             // The narrowest write grant in the system, and it is what this tool derives BECAUSE it never
             // names a target principal (`write-service.ts`'s `deriveRequiredPermission`). Declared here
             // to match; the handler does not pass this string, it lets the chokepoint derive it, so the
@@ -174,14 +176,14 @@ export function getSettingsAgentToolCatalog() {
         {
             name: "settings_set_value",
             description: "Sets one registered setting at workspace scope (default) or the caller's own user scope. Call settings_list_definitions for valid keys, schemas, scopes and confirmation policy. Returns {key, scope, previous, value, revisionSeq}; previous is the old override, or null if absent. Privacy, instructions and host-protected assistant settings need a human confirmation card; the agent cannot confirm itself. Rejects unknown/tombstoned keys, disallowed scopes, invalid values and missing permissions. Cannot write globally, target another operator, reset a namespace or change definitions.",
-            sideEffects: "mutates-durable-state",
+            sideEffects: MUTATES_DURABLE_STATE,
             authorization: { permission: "settings.workspace.write" },
             inputSchema: SET_VALUE_SCHEMA,
         },
         {
             name: "settings_clear_value",
             description: "Clears one setting override at workspace scope (default) or the caller's own user scope so the next layer/default applies. Use to put one setting back to its inherited value; not to reset a namespace or delete a definition. Returns {key, scope, previous, effective}; restore a non-null previous override with settings_set_value. Protected assistant settings require a human confirmation card. Rejects unknown/tombstoned keys, disallowed scopes and missing permissions; cannot target global or another operator's layer.",
-            sideEffects: "mutates-durable-state",
+            sideEffects: MUTATES_DURABLE_STATE,
             authorization: { permission: "settings.workspace.write" },
             inputSchema: CLEAR_VALUE_SCHEMA,
         },
@@ -190,7 +192,7 @@ export function getSettingsAgentToolCatalog() {
             // clears every value in an operator-named namespace at a scope in one call, irreversible.
             name: "settings_reset",
             description: "Resets every setting in a namespace to defaults at a scope. NEVER agent-callable — see file header.",
-            sideEffects: "mutates-durable-state",
+            sideEffects: MUTATES_DURABLE_STATE,
             authorization: { permission: "settings.reset.workspace" },
         },
         {
@@ -199,7 +201,7 @@ export function getSettingsAgentToolCatalog() {
             // every existing stored value for that key is interpreted platform-wide.
             name: "settings_register_definitions",
             description: "Registers, renames, retypes, deprecates, or tombstones setting definitions. NEVER agent-callable — see file header.",
-            sideEffects: "mutates-durable-state",
+            sideEffects: MUTATES_DURABLE_STATE,
             authorization: { permission: "settings.definitions.manage" },
         },
     ];

package/dist/settings/agent-value-write-tools.js

@@ -56,8 +56,11 @@ function snapshotJsonValue(toolId, input) {
         throw new ToolInputError({ message: `${toolId}: value must be valid JSON.` }, { cause });
     }
 }
+/** `typeof` results JSON cannot represent. */
+const NON_JSON_TYPES = new Set(["undefined", "function", "symbol"]);
 function rejectNonJson(_key, value) {
-    if (value === undefined || typeof value === "function" || typeof value === "symbol" || (typeof value === "number" && !Number.isFinite(value)))
+    const nonFiniteNumber = typeof value === "number" && !Number.isFinite(value);
+    if (NON_JSON_TYPES.has(typeof value) || nonFiniteNumber)
         throw new Error("not JSON");
     return value;
 }
@@ -70,7 +73,8 @@ async function resolveTarget(deps, target, isSet) {
         throw new DefinitionNotFoundError(`setting '${name}' was not found`);
     if (definition.status === "tombstone")
         throw new DefinitionTombstonedError(`setting '${name}' has been tombstoned`);
-    if ((definition.scopes & SCOPE_BIT[target.scope]) === 0)
+    const scopeAllowed = (definition.scopes & SCOPE_BIT[target.scope]) !== 0;
+    if (!scopeAllowed)
         throw new ScopeNotAllowedError(name);
     if (isSet && !validateValueAgainstSchema(definition.schema, target.value))
         throw new ValueValidationFailedError(`value for '${name}' does not match the definition schema`);
@@ -211,7 +215,7 @@ export function buildSettingsValueWriteHandler(deps, toolId) {
             return await applyWrite(deps, request, prepared);
         }
         catch (error) {
-            rethrowWriteError(error, toolId, target, permission);
+            return rethrowWriteError(error, toolId, target, permission);
         }
     };
 }

package/dist/settings/ensure-definitions.js

@@ -49,14 +49,16 @@ export async function ensureSettingDefinitions(deps, input) {
     };
     for (const def of input.definitions) {
         const existing = await resolveDefinitionRaw({ repo: deps.settingsRepo }, { namespace: target.namespace, key: def.key, workspaceId });
-        if (!existing)
+        if (!existing) {
             await registerMissingDefinition(target, def);
+            continue;
+        }
         // Core registration is once-only, but the DEFAULT is not. Without this, a
         // `defaultValue` changed in source is unreachable in any install that
         // has already booted — the stored `default_json` from first boot keeps
         // winning, for every settings-dialog tab. See `reconcileDefinitionDefault`
         // for the bug this closes.
-        else if (isReconcilableCoreSlot(existing, { ownerKind: target.ownerKind, namespace: target.namespace, key: def.key })) {
+        if (isReconcilableCoreSlot(existing, { ownerKind: target.ownerKind, namespace: target.namespace, key: def.key })) {
             await reconcileExistingCoreDefinition(target, def);
         }
     }

package/dist/settings/express/http-request.js

@@ -43,7 +43,8 @@ export function readValueMutation(body, operation) {
     const namespace = String(body.namespace ?? "");
     const key = String(body.key ?? "");
     const scope = body.scope;
-    const complete = namespace && key && SETTING_SCOPES.includes(scope) && (operation === "clear" || "valueJson" in body);
+    const hasValue = operation === "clear" || "valueJson" in body;
+    const complete = namespace && key && SETTING_SCOPES.includes(scope) && hasValue;
     return complete ? { namespace, key, scope } : null;
 }
 //# sourceMappingURL=http-request.js.map

package/dist/settings/express/http.js

@@ -177,12 +177,20 @@ export function registerSettingsRoutes(required, optional = {}) {
         const close = await openSettingsChangeStream({ request: req, response: res, workspaceId, principalId,
             changeFeed: required.changeFeed, authorize: required.authorize, permission: permissions.read, scheduler: required.scheduler,
             onClose: ({ close }) => { streams.delete(close); }, isDisposed: () => disposed }, optional);
-        if (disposed)
+        if (disposed) {
             close();
-        else if (!res.destroyed && !res.writableEnded)
+            return;
+        }
+        if (!res.destroyed && !res.writableEnded)
             streams.add(close);
     }));
-    return { dispose: () => { disposed = true; for (const close of streams)
-            close(); streams.clear(); } };
+    return {
+        dispose: () => {
+            disposed = true;
+            for (const close of streams)
+                close();
+            streams.clear();
+        },
+    };
 }
 //# sourceMappingURL=http.js.map

package/dist/settings/repo.memory.js

@@ -1,3 +1,5 @@
+/** Statuses a definition lookup can resolve to (everything but superseded rows). */
+const RESOLVABLE_STATUSES = new Set(["active", "alias", "tombstone"]);
 /**
  * @file In-memory adapter for `SettingsRepoPort` (the rule-of-two: in-memory + production adapters).
  *
@@ -45,7 +47,7 @@ export class InMemorySettingsRepo {
         return (this.definitions.find((d) => d.namespace === required.namespace &&
             d.key === required.key &&
             d.workspaceId === required.workspaceId &&
-            (d.status === "active" || d.status === "alias" || d.status === "tombstone")) ?? null);
+            RESOLVABLE_STATUSES.has(d.status)) ?? null);
     }
     async findDefinitionBySettingId(required) {
         const candidates = this.definitions.filter((d) => d.settingId === required.settingId);
@@ -122,7 +124,8 @@ export class InMemorySettingsRepo {
             v.settingId === required.settingId));
     }
     async appendRevision(record) {
-        const seq = this.nextSeq++;
+        const seq = this.nextSeq;
+        this.nextSeq += 1;
         this.revisions.push({ ...record, seq });
         return seq;
     }

package/dist/settings/settings.js

@@ -40,7 +40,8 @@ export function validateDefinitionInput(input) {
         };
     }
     // a site-owned def (workspace_id NOT NULL) may never declare the global scope bit. See docs/decisions/DR-003-settings-ledger-invariants.md.
-    if (input.workspaceId !== null && (input.scopes & SCOPE_BIT.global) !== 0) {
+    const declaresGlobalScope = (input.scopes & SCOPE_BIT.global) !== 0;
+    if (input.workspaceId !== null && declaresGlobalScope) {
         return {
             valid: false,
             error: new DefinitionInvalidError(
@@ -77,6 +78,9 @@ export function validateValueAgainstSchema(schema, value) {
             // registering feature's own write-path job — see
             // docs/decisions/settings-json-schema-variant.md.
             return true;
+        default:
+            // Unreachable for a typed schema; a stored row with an unknown type validates nothing.
+            return false;
     }
 }
 /** Identity-registry of total coercers keyed by `coercionTag`. `"identity"` is always registered. See docs/decisions/DR-003-settings-ledger-invariants.md. */

package/dist/settings/tool-registrations.js

@@ -26,6 +26,14 @@ const CROSS_PRINCIPAL_SETTINGS_READ_PERMISSION = "settings.user.read";
  * @complexity O(1); at most one `authorize()` call (none for a self-read or no-op read).
  * @overallScore 100
  */
+/** Why a dotted key did not resolve to exactly one namespace/key pair. */
+function dottedKeyMismatchMessage(matches) {
+    if (matches.length === 0) {
+        return "settings_set_value: no registered namespace/key pair matches this dotted key. Call settings_list_definitions to see valid keys; send namespace and key explicitly.";
+    }
+    const candidates = matches.map(match => `namespace=${match.namespace}, key=${match.key}`).join("; ");
+    return `settings_set_value: dotted key is ambiguous (${candidates}). Send namespace and key explicitly.`;
+}
 async function resolveOwnOrOtherPrincipalRead(routeDeps, required) {
     const { requestedPrincipalId, callerPrincipalId } = required;
     // Defaults to the CALLER, never to `undefined`. `undefined` does not mean "the caller" to
@@ -271,9 +279,7 @@ export function buildSettingsRegistrations(routeDeps) {
                 await routeDeps.settingsUiTabsReady;
                 const matches = await findDottedKeySplits(routeDeps, input.key);
                 if (matches.length !== 1)
-                    throw new ToolInputError({ message: matches.length
-                            ? `settings_set_value: dotted key is ambiguous (${matches.map(match => `namespace=${match.namespace}, key=${match.key}`).join("; ")}). Send namespace and key explicitly.`
-                            : "settings_set_value: no registered namespace/key pair matches this dotted key. Call settings_list_definitions to see valid keys; send namespace and key explicitly." });
+                    throw new ToolInputError({ message: dottedKeyMismatchMessage(matches) });
                 return { input: { ...input, ...matches[0] }, notes: ["dotted key→namespace + key"] };
             } },
     }, { unwiredToolIds: UNWIRED_SETTINGS_TOOL_IDS });

package/dist/settings/write-service.js

@@ -154,15 +154,19 @@ async function assertTargetPrincipalInWorkspace(deps, input) {
  * The caller's enclosing transaction rolls the appended revision back on conflict.
  * @complexity At most one scoped value read; no reads when the option is omitted.
  */
+/** The one stored value the write addresses, at its own scope. */
+function readAddressedValue({ repo, settingId, input }) {
+    if (input.scope === "global")
+        return repo.getGlobalValue(settingId);
+    if (input.scope === "workspace")
+        return repo.getWorkspaceValue({ workspaceId: input.workspaceId, settingId });
+    return repo.getUserValue({ workspaceId: input.workspaceId, principalId: input.principalId ?? input.callerPrincipalId, settingId });
+}
 async function assertExpectedRevision(required, optional = {}) {
     if (optional.expectedRevisionSeq === undefined)
         return;
     const { repo, settingId, input } = required;
-    const current = input.scope === "global"
-        ? await repo.getGlobalValue(settingId)
-        : input.scope === "workspace"
-            ? await repo.getWorkspaceValue({ workspaceId: input.workspaceId, settingId })
-            : await repo.getUserValue({ workspaceId: input.workspaceId, principalId: input.principalId ?? input.callerPrincipalId, settingId });
+    const current = await readAddressedValue({ repo, settingId, input });
     const actualRevisionSeq = current?.seq ?? 0;
     if (actualRevisionSeq !== optional.expectedRevisionSeq) {
         throw new SettingsRevisionConflictError({ expectedRevisionSeq: optional.expectedRevisionSeq, actualRevisionSeq });
@@ -198,7 +202,7 @@ export async function set(required, optional = {}) {
         throw new ValueValidationFailedError(`value for '${input.namespace}.${input.key}' does not match the definition schema`);
     }
     await assertTargetPrincipalInWorkspace(deps, input);
-    const result = await deps.repo.transaction(async () => {
+    return deps.repo.transaction(async () => {
         const now = kernelNowIso({ clock: deps.clock });
         const revisionSeq = await deps.repo.appendRevision({
             entityKind: "value",
@@ -246,7 +250,6 @@ export async function set(required, optional = {}) {
         }
         return { value: input.value, revisionSeq };
     });
-    return result;
 }
 /**
  * Authorize -> cleared value + revision in one transaction; the optional concurrency guard has
@@ -327,8 +330,7 @@ export async function clear(required, optional = {}) {
     };
     // `skipTransaction` means an enclosing caller already owns the boundary, so
     // this write joins it and a later failure rolls this one back too.
-    const result = input.skipTransaction ? await runClear() : await deps.repo.transaction(runClear);
-    return result;
+    return input.skipTransaction ? runClear() : deps.repo.transaction(runClear);
 }
 /**
  * — an explicit, human-invoked orchestrator: authorize

package/dist/target-scope.js

@@ -65,7 +65,8 @@ export function applyTargetScope(required, optional = {}) {
                 const target = ctx.input[param];
                 if (typeof target !== 'string')
                     throw new ToolInputError({ message: `${param} must be a string` });
-                const { [param]: _target, ...input } = ctx.input;
+                const input = { ...ctx.input };
+                delete input[param];
                 if (!scoped) {
                     if (!await required.isCurrentTarget({ target }))
                         throw new ToolInputError({ message: refuseMessage });

package/dist/text/index.d.ts

@@ -1,4 +1,6 @@
 export { sanitizeUntrustedText, stripControlSequences } from './sanitize-untrusted-text.js';
 export type { SanitizeTextOptions } from './sanitize-untrusted-text.js';
 export { escapeHtml, escapeXml } from "./escape.js";
+export { trimChars, trimCharsEnd, trimCharsStart } from "../primitives/trim-chars.js";
+export { captureLineTail } from "./line-tail.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/text/index.js

@@ -1,3 +1,5 @@
 export { sanitizeUntrustedText, stripControlSequences } from './sanitize-untrusted-text.js';
 export { escapeHtml, escapeXml } from "./escape.js";
+export { trimChars, trimCharsEnd, trimCharsStart } from "../primitives/trim-chars.js";
+export { captureLineTail } from "./line-tail.js";
 //# sourceMappingURL=index.js.map

package/dist/text/line-tail.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file A linear-time stand-in for the regex tail `\s*(.+)$` / `\s+(.+)$`. In those spellings the
+ * whitespace run and `.+` can both match the same characters, so the engine backtracks
+ * quadratically on long whitespace runs. A leaf module with no imports.
+ */
+/**
+ * Returns what `(.+)` captures when `rest` is matched against `\s{minWhitespace,}(.+)$` from its
+ * start, or null when that pattern does not match. A whitespace-only `rest` captures its final
+ * character, exactly as the greedy regex gives back one character to `.+`.
+ * @complexity O(rest length).
+ */
+export declare function captureLineTail({ rest }: {
+    rest: string;
+}, { minWhitespace }?: {
+    minWhitespace?: 0 | 1;
+}): string | null;
+//# sourceMappingURL=line-tail.d.ts.map

package/dist/text/line-tail.js

@@ -0,0 +1,25 @@
+/**
+ * @file A linear-time stand-in for the regex tail `\s*(.+)$` / `\s+(.+)$`. In those spellings the
+ * whitespace run and `.+` can both match the same characters, so the engine backtracks
+ * quadratically on long whitespace runs. A leaf module with no imports.
+ */
+/** Characters `.` does not match without the `s` flag. */
+const LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
+/**
+ * Returns what `(.+)` captures when `rest` is matched against `\s{minWhitespace,}(.+)$` from its
+ * start, or null when that pattern does not match. A whitespace-only `rest` captures its final
+ * character, exactly as the greedy regex gives back one character to `.+`.
+ * @complexity O(rest length).
+ */
+export function captureLineTail({ rest }, { minWhitespace = 0 } = {}) {
+    const stripped = rest.trimStart();
+    if (stripped !== "") {
+        const leading = rest.length - stripped.length;
+        return leading >= minWhitespace && !LINE_TERMINATOR.test(stripped) ? stripped : null;
+    }
+    if (rest.length < minWhitespace + 1)
+        return null;
+    const last = rest.slice(-1);
+    return LINE_TERMINATOR.test(last) ? null : last;
+}
+//# sourceMappingURL=line-tail.js.map

package/dist/text/sanitize-untrusted-text.js

@@ -79,14 +79,16 @@ function escapeSequenceEnd(text, start) {
  */
 export function stripControlSequences({ text }) {
     let out = '';
-    for (let i = 0; i < text.length; i++) {
+    let i = 0;
+    while (i < text.length) {
         const code = text.charCodeAt(i);
         if (code === ESC) {
-            i = escapeSequenceEnd(text, i); // land on the last consumed byte; the loop's i++ steps past it
+            i = escapeSequenceEnd(text, i) + 1; // escapeSequenceEnd is the last consumed byte; step past it
             continue;
         }
         if (!isOtherControlCode(code))
             out += text[i];
+        i += 1;
     }
     return out;
 }
@@ -103,7 +105,34 @@ const DIAGNOSTIC_TOKENS = new Set([
  * @complexity O(n) in token length; pure. */
 function isIdentifierShaped({ token }) {
     return token.length <= 31 && /[a-z]/.test(token)
-        && /^(?:[a-z]{1,15}|[0-9]{1,15})(?:[-_](?:[a-z]{1,15}|[0-9]{1,15})){2,}$/.test(token);
+        && /^(?:[a-z]{1,15}|\d{1,15})(?:[-_](?:[a-z]{1,15}|\d{1,15})){2,}$/.test(token);
+}
+const isSpace = (char) => char !== undefined && /\s/.test(char);
+const LABEL_SEPARATORS = ':=';
+/** Replaces the value after a label's `:`/`=` with `[redacted]`, exactly as
+ * `match.replace(/([:=]\s*)\S+$/, '$1[redacted]')` does, without that pattern's quadratic
+ * backtracking. The value is the final non-space run; its separator is the `:`/`=` right before
+ * the spaces preceding it, else the first one inside the run. @complexity O(match length). */
+function redactLabeledValue(match) {
+    let valueStart = match.length;
+    while (valueStart > 0 && !isSpace(match[valueStart - 1]))
+        valueStart -= 1;
+    if (valueStart === match.length)
+        return match;
+    let gapStart = valueStart;
+    while (isSpace(match[gapStart - 1]))
+        gapStart -= 1;
+    const spacedSeparator = gapStart > 0 && gapStart < valueStart && LABEL_SEPARATORS.includes(match.charAt(gapStart - 1));
+    if (spacedSeparator)
+        return match.slice(0, valueStart) + '[redacted]';
+    return redactAfterInnerSeparator(match, valueStart);
+}
+function redactAfterInnerSeparator(match, valueStart) {
+    for (let i = valueStart; i < match.length - 1; i += 1) {
+        if (LABEL_SEPARATORS.includes(match.charAt(i)))
+            return match.slice(0, i + 1) + '[redacted]';
+    }
+    return match;
 }
 /** Mask credentials before preserving trusted IDs and UPPER_SNAKE diagnostics; redact opaque spans elsewhere.
  * `keepIdentifiers` additionally exempts identifier-shaped runs (see {@link isIdentifierShaped}).
@@ -113,7 +142,7 @@ function redactSecretLike({ text }, options = {}) {
     const keepOpaque = (match) => NON_SECRET_TOKEN_RE.test(match) || DIAGNOSTIC_TOKENS.has(match)
         || (options.keepIdentifiers === true && isIdentifierShaped({ token: match }));
     return redactSecrets({ input: text }, { redactPii: false, exactSecrets: options.exactSecrets ?? [] })
-        .replace(LABELED_SECRET_RE, match => match.replace(/([:=]\s*)\S+$/, '$1[redacted]'))
+        .replace(LABELED_SECRET_RE, match => redactLabeledValue(match))
         .replace(/\[REDACTED:[^\]\r\n]+\]/g, '[redacted]')
         // Trust whole dotted IDs so their components cannot become a general redaction bypass.
         .replace(/[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*/g, token => diagnosticToolIds.has(token) ? token

package/dist/tool-exposure.js

@@ -1,4 +1,4 @@
-const SAFE_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const SAFE_NAME = /^[A-Za-z_]\w{0,63}$/;
 const MAX_NAME_LENGTH = 64;
 /** A stable, non-security hash keeps transformed names independent of discovery order.
  * Collisions are still checked against the entire namespace, never trusted as unique. */
@@ -11,7 +11,7 @@ function nameHash(id) {
 function nameBase(id) {
     if (SAFE_NAME.test(id))
         return id;
-    const readable = id.replace(/[^A-Za-z0-9_]/g, '_');
+    const readable = id.replace(/\W/g, '_');
     return `tool_${readable.slice(0, 49)}_${nameHash(id)}`;
 }
 /** O(c) collision probes for c occupied alternatives; suffix space stays inside the wire limit. */
@@ -22,7 +22,8 @@ function assignName(index, id) {
     let candidate = base;
     let counter = 1;
     while (index.occupied.has(candidate)) {
-        const suffix = `_${counter++}`;
+        const suffix = `_${counter}`;
+        counter += 1;
         candidate = `${base.slice(0, MAX_NAME_LENGTH - suffix.length)}${suffix}`;
     }
     index.forward.set(id, candidate);
@@ -89,6 +90,14 @@ function pinDescriptor(descriptor) {
     }
 }
 /** Count and byte caps reject new entries without evicting any previously callable definition. */
+/** A tool that can join the snapshot (pinned), or why it is skipped. */
+function promotionCandidate(descriptor, snapshot, limits) {
+    if (!descriptor)
+        return { reason: 'not-found' };
+    const pinned = pinDescriptor(descriptor);
+    const reason = limitReason(snapshot, pinned.bytes, limits);
+    return reason ? { reason } : { pinned };
+}
 function limitReason(snapshot, bytes, limits) {
     if (snapshot.tools.length >= limits.maxTools)
         return 'tool-limit';
@@ -107,21 +116,16 @@ function promoteDescriptors(snapshot, toolIds, descriptors, names, limits) {
     for (const toolId of new Set(toolIds)) {
         if (published.has(toolId))
             continue;
-        const descriptor = available.get(toolId);
-        if (!descriptor) {
-            skipped.push({ toolId, reason: 'not-found' });
-            continue;
+        const candidate = promotionCandidate(available.get(toolId), { tools, schemaBytes, revision: snapshot.revision }, limits);
+        if ('reason' in candidate) {
+            skipped.push({ toolId, reason: candidate.reason });
         }
-        const pinned = pinDescriptor(descriptor);
-        const reason = limitReason({ tools, schemaBytes, revision: snapshot.revision }, pinned.bytes, limits);
-        if (reason) {
-            skipped.push({ toolId, reason });
-            continue;
+        else {
+            assignName(names, toolId);
+            tools.push({ wireName: names.forward.get(toolId), descriptor: candidate.pinned.descriptor });
+            schemaBytes += candidate.pinned.bytes;
+            added.push(toolId);
         }
-        assignName(names, toolId);
-        tools.push({ wireName: names.forward.get(toolId), descriptor: pinned.descriptor });
-        schemaBytes += pinned.bytes;
-        added.push(toolId);
     }
     let next = snapshot;
     if (added.length > 0)

package/dist/tool-input-normalization.d.ts

@@ -1,4 +1,3 @@
-import type { ToolRegistration } from './tool-registry.js';
 export { ToolInputNormalizationError } from './tool-input-errors.js';
 /** A value-free account of canonicalization; domain hooks use the same contract as the gate. */
 export interface NormalizedToolInput {
@@ -8,8 +7,17 @@ export interface NormalizedToolInput {
 export type ToolInputNormalizer = (required: {
     input: Readonly<Record<string, unknown>>;
 }, optional?: Record<string, never>) => NormalizedToolInput | Promise<NormalizedToolInput>;
+/** Only the registration facts consumed by normalization; carries no execution authority. */
+interface NormalizationRegistration {
+    readonly descriptor: {
+        readonly id: string;
+        readonly inputSchema?: unknown;
+    };
+    readonly invocationSchema?: unknown;
+    readonly normalizeInput?: ToolInputNormalizer;
+}
 /** Canonicalize one batch layer (including declared aliases) before merging; leave value conversion
- * and domain hooks for final normalization. Throws ToolInputError for collisions within this layer, never across
+ * and domain hooks for final normalization. Throws ToolInputError for differing colliding values within this layer, never across
  * layers. Uses the same bounded schema walk as normalizeToolInput.
  * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
  */
@@ -28,7 +36,7 @@ export declare function canonicalizeToolInputKeys({ input, schema }: {
  */
 export declare function normalizeToolInput({ input, registration }: {
     input: unknown;
-    registration: Pick<ToolRegistration, 'descriptor' | 'normalizeInput' | 'invocationSchema'>;
+    registration: NormalizationRegistration;
 }, _options?: Record<string, never>): Promise<NormalizedToolInput>;
 /** Keep result shapes intact and make rewrite notes visible in plain and MCP tool results. */
 export declare function withNormalizationNotes({ output, notes }: {

package/dist/tool-input-normalization.js

@@ -117,10 +117,14 @@ function unknownKeyError({ key, location, shape }, _options = {}) {
     const names = [...shape.names.filter(name => required.has(name)), ...shape.names.filter(name => !required.has(name))];
     const declared = names.map(name => `${name} (${required.has(name) ? 'required' : 'optional'})`).join(', ') || 'none';
     const hints = names.filter(name => nearMiss({ left: keyShape(key), right: keyShape(name) }));
-    const suggestion = hints.length ? ` Did you mean ${hints.map(name => `'${name}'`).join(', ')}?` : '';
+    const quotedHints = hints.map(name => `'${name}'`).join(', ');
+    const suggestion = hints.length ? ` Did you mean ${quotedHints}?` : '';
     return new ToolInputError({ message: `Unknown input '${location}'. Declared inputs: ${declared}.${suggestion} Resend with the declared name.` });
 }
-/** One key of an object: canonical rename + recursion, closed-schema refusal, or open pass-through. */
+/** One key of an object: canonical rename + recursion, closed-schema refusal, or open pass-through.
+ * Agreeing scalar aliases coalesce after coercion; differing values still fail without disclosure.
+ * @complexity The bounded child walk plus O(1) source/value checks.
+ */
 function normalizeEntry({ key, raw, shape, sources, step }) {
     const { path, depth, walk } = step;
     const location = path ? `${path}.${key}` : key;
@@ -131,13 +135,15 @@ function normalizeEntry({ key, raw, shape, sources, step }) {
         const childSchema = object(shape.schema.additionalProperties) ? shape.schema.additionalProperties : undefined;
         return [key, normalizeValue({ value: raw, schema: childSchema, step: { path: location, depth: depth + 1, walk } })];
     }
-    const previous = sources.get(target);
-    if (previous !== undefined)
-        throw new ToolInputError({ message: `Conflicting inputs '${previous}' and '${key}' both name '${target}'. Send only '${target}'.` });
-    sources.set(target, key);
     if (target !== key)
         walk.notes.push(`${location}→${target}`);
-    return [target, normalizeValue({ value: raw, schema: shape.properties[target], step: { path: `${path ? `${path}.` : ''}${target}`, depth: depth + 1, walk } })];
+    const parentPrefix = path ? `${path}.` : '';
+    const value = normalizeValue({ value: raw, schema: shape.properties[target], step: { path: `${parentPrefix}${target}`, depth: depth + 1, walk } });
+    const previous = sources.get(target);
+    if (previous !== undefined && !Object.is(previous.value, value))
+        throw new ToolInputError({ message: `Conflicting inputs '${previous.key}' and '${key}' both name '${target}'. Send only '${target}'.` });
+    sources.set(target, { key, value });
+    return [target, value];
 }
 function normalizeObject({ value, schema, step }) {
     const properties = object(schema.properties) ? schema.properties : {};
@@ -170,7 +176,7 @@ function walkRoot({ input, schema, notes, validateClosed, keysOnly }) {
     return normalizeValue({ value: input, schema, step: { path: '', depth: 0, walk: { notes, validateClosed, keysOnly } } });
 }
 /** Canonicalize one batch layer (including declared aliases) before merging; leave value conversion
- * and domain hooks for final normalization. Throws ToolInputError for collisions within this layer, never across
+ * and domain hooks for final normalization. Throws ToolInputError for differing colliding values within this layer, never across
  * layers. Uses the same bounded schema walk as normalizeToolInput.
  * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
  */

package/dist/tool-metadata-types.d.ts

@@ -7,6 +7,11 @@ export interface ToolApprovalMetadata {
     readonly rule?: string;
 }
 export interface ToolMetadata<A extends ToolApprovalMetadata = ToolApprovalMetadata> {
+    /** Human-facing action name and optional button verb; presentation only, never authority. */
+    readonly title?: string;
+    /** Plain-language consequence shown before approval; never used to classify or authorize. */
+    readonly summary?: string;
+    readonly actionVerb?: string;
     /** Installed guidance capabilities needed by a writer; independent of permission and risk. */
     readonly guidanceCapabilities?: readonly string[];
     readonly search?: {

package/dist/tool-registry.d.ts

@@ -163,6 +163,11 @@ export interface ToolExecutionContext {
 /** Optional handler ports supplied by the invoking transport. */
 export interface ToolExecutionOptions {
     readonly emitSurface?: SurfaceEmitter;
+    /** Reports the human wait to the executor so concurrent writes can be refused. This is
+     * notification only; it never supplies a confirmation decision or grants authority. */
+    readonly onApprovalStateChange?: (required: {
+        pending: boolean;
+    }, optional?: Record<string, never>) => void;
     /** Invoke through the same executor, retaining this call's principal, run, cancellation and
      * transport gates. Rejects on denial, failed confirmation, validation or execution failure.
      * A composition-owned registry may retain a source registration behind a derived catalog card.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.6.15-rc.2",
+  "version": "0.6.15",
   "description": "The Jini kernel: typed DI tokens, pack composition and lifecycle, the tool registry, redaction, and origin/API-token auth primitives. Zero dependencies.",
   "license": "Apache-2.0",
   "repository": {