@jini-ai/core 0.4.8 → 0.4.9

package/dist/settings/settings.js

@@ -142,35 +142,36 @@ export function invalidateWorkspaceSettingsCache(_required, _optional = {}) {
  * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export async function resolveDefinitionRaw(deps, input) {
+    const found = await findInCallerOrPlatformPartition(deps.repo, input);
+    if (found?.status !== "alias")
+        return found ?? null;
+    const cursor = aliasTarget(found, input);
+    if (!cursor)
+        return null;
+    const target = await findInCallerOrPlatformPartition(deps.repo, cursor);
+    // An alias whose target is itself an alias is a chain deeper than one: absent.
+    return target?.status === "alias" ? null : target ?? null;
+}
+/** One alias hop only. A malformed target or a self-alias (the only cycle reachable in one hop)
+ * fails closed as absent (`null`) without a second lookup. The hop stays in the caller's workspace. O(1). */
+function aliasTarget(alias, input) {
+    if (alias.aliasOfNamespace == null || alias.aliasOfKey == null)
+        return null;
+    if (alias.aliasOfNamespace === input.namespace && alias.aliasOfKey === input.key)
+        return null;
+    return { namespace: alias.aliasOfNamespace, key: alias.aliasOfKey, workspaceId: input.workspaceId };
+}
+/** One coordinate lookup: the caller's partition, then the platform (null) partition. O(1) repo calls (at most two). */
+async function findInCallerOrPlatformPartition(repo, cursor) {
     // Namespace fencing makes `site.*` (non-null workspace_id) and. See docs/decisions/DR-003-settings-ledger-invariants.md.
     // `core.*`/`theme.*` (null workspace_id) disjoint by construction, so a
     // caller resolving inside a workspace context may still be asking for a
     // platform definition. Try the caller's own partition first, then fall
     // back to the platform (null) partition.
-    const visited = new Set();
-    let cursor = input;
-    for (let depth = 0; depth <= 1; depth++) {
-        const address = JSON.stringify([cursor.workspaceId, cursor.namespace, cursor.key]);
-        if (visited.has(address))
-            return null;
-        visited.add(address);
-        const found = (await deps.repo.findActiveDefinition(cursor)) ??
-            (cursor.workspaceId !== null
-                ? await deps.repo.findActiveDefinition({ ...cursor, workspaceId: null })
-                : null);
-        if (!found)
-            return null;
-        if (found.status !== "alias")
-            return found;
-        if (depth === 1 || found.aliasOfNamespace == null || found.aliasOfKey == null)
-            return null;
-        cursor = {
-            namespace: found.aliasOfNamespace,
-            key: found.aliasOfKey,
-            workspaceId: input.workspaceId,
-        };
-    }
-    return null;
+    const own = await repo.findActiveDefinition(cursor);
+    if (own || cursor.workspaceId === null)
+        return own;
+    return repo.findActiveDefinition({ ...cursor, workspaceId: null });
 }
 /**
  * The read-path resolver: typed-absent (`null`) for a tombstoned or
@@ -215,45 +216,38 @@ export async function getEffective(deps, input) {
     });
     if (!definition)
         return null;
-    const coerce = (value, defVersion) => {
-        if (defVersion === definition.version)
-            return value;
-        const coercer = coercers.get(definition.coercionTag ?? "identity") ?? coercers.get("identity");
-        return coercer({ value });
-    };
+    const hit = await firstSetLayer(deps.repo, definition.settingId, input.scopeContext);
+    if (hit)
+        return { value: coerceToVersion(definition, hit.record), sourceLayer: hit.sourceLayer, defVersion: definition.version };
+    return { value: definition.defaultValue, sourceLayer: "default", defVersion: definition.version };
+}
+/** A value stored under an older definition version is coerced in memory (no write-back). O(1). */
+function coerceToVersion(definition, record) {
+    if (record.defVersion === definition.version)
+        return record.valueJson;
+    const coercer = coercers.get(definition.coercionTag ?? "identity") ?? coercers.get("identity");
+    return coercer({ value: record.valueJson });
+}
+/**
+ * Precedence `user ?? workspace ?? global`; a `cleared` row is absent at its layer. The user layer
+ * needs both a workspace and a principal; the workspace layer needs a workspace.
+ * O(1): up to three repo reads, in precedence order, stopping at the first `set` row.
+ */
+async function firstSetLayer(repo, settingId, scope) {
     // Every layer read below goes straight to the repo. See this module's cache header for why there
     // is no per-layer cache wrapping these three calls.
-    if (input.scopeContext.workspaceId && input.scopeContext.principalId) {
-        const workspaceId = input.scopeContext.workspaceId;
-        const principalId = input.scopeContext.principalId;
-        const userValue = await deps.repo.getUserValue({ workspaceId, principalId, settingId: definition.settingId });
-        if (userValue && userValue.state === "set") {
-            return {
-                value: coerce(userValue.valueJson, userValue.defVersion),
-                sourceLayer: "user",
-                defVersion: definition.version,
-            };
-        }
+    const { workspaceId, principalId } = scope;
+    if (workspaceId && principalId) {
+        const user = await repo.getUserValue({ workspaceId, principalId, settingId });
+        if (user?.state === "set")
+            return { record: user, sourceLayer: "user" };
     }
-    if (input.scopeContext.workspaceId) {
-        const workspaceId = input.scopeContext.workspaceId;
-        const workspaceValue = await deps.repo.getWorkspaceValue({ workspaceId, settingId: definition.settingId });
-        if (workspaceValue && workspaceValue.state === "set") {
-            return {
-                value: coerce(workspaceValue.valueJson, workspaceValue.defVersion),
-                sourceLayer: "workspace",
-                defVersion: definition.version,
-            };
-        }
+    if (workspaceId) {
+        const workspace = await repo.getWorkspaceValue({ workspaceId, settingId });
+        if (workspace?.state === "set")
+            return { record: workspace, sourceLayer: "workspace" };
     }
-    const globalValue = await deps.repo.getGlobalValue(definition.settingId);
-    if (globalValue && globalValue.state === "set") {
-        return {
-            value: coerce(globalValue.valueJson, globalValue.defVersion),
-            sourceLayer: "global",
-            defVersion: definition.version,
-        };
-    }
-    return { value: definition.defaultValue, sourceLayer: "default", defVersion: definition.version };
+    const global = await repo.getGlobalValue(settingId);
+    return global?.state === "set" ? { record: global, sourceLayer: "global" } : null;
 }
 //# sourceMappingURL=settings.js.map

package/dist/settings/tool-registrations.d.ts

@@ -1,5 +1,4 @@
-import type { IdGenerator } from "../primitives/index.js";
-import type { Clock } from "../primitives/index.js";
+import type { Clock, IdGenerator } from "../primitives/index.js";
 /**
  * @file Settings tools: three reads and three bounded value writes. Bulk reset and definition
  * registration stay unwired. The generic tools reuse write-service authorization/validation and
@@ -12,7 +11,7 @@ import type { LegacyToolAuthorizeFn as AuthorizeFn } from "../tool-permissions.j
 import { type SettingsWriteConfirmation } from "./agent-value-write-tools.js";
 import { type AgentSettingWriteRule } from "./agent-write-denylist.js";
 import { type DerivedRiskByToolId } from "../registration-kit.js";
-import type { ToolExecutionOptions, ToolRegistration } from "../tool-registry.js";
+import { type ToolExecutionOptions, type ToolRegistration } from "../tool-registry.js";
 import type { SettingsPrincipalLookupPort } from "./principal-lookup.js";
 import type { SettingsRepoPort } from "./ports.js";
 import { set as setSettingValue } from "./write-service.js";

package/dist/settings/tool-registrations.js

@@ -1,7 +1,8 @@
 import { adaptLegacyAuthorize } from "../tool-permissions.js";
-import { buildSettingsValueWriteHandler } from "./agent-value-write-tools.js";
-import { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule } from "./agent-write-denylist.js";
+import { agentWriteRules, buildSettingsValueWriteHandler, toWriteDeps } from "./agent-value-write-tools.js";
+import { findAgentWriteRule } from "./agent-write-denylist.js";
 import { buildDomainRegistrations, indexCatalogById, optionalString, requireInputRecord, requireNoInput, requireString, withSchemaOnRejection } from "../registration-kit.js";
+import { ToolInputError } from "../tool-registry.js";
 import { requireToolPermission } from "../tool-permissions.js";
 import { getSettingsAgentToolCatalog } from "./agent-tools.js";
 import { AGENT_PREFERENCE_WRITE_SCOPE, AGENT_WRITABLE_PREFERENCE_IDS, resolveAgentWritablePreference, } from "./agent-writable-preferences.js";
@@ -42,25 +43,6 @@ async function resolveOwnOrOtherPrincipalRead(routeDeps, required) {
 function layerValueOf(record) {
     return record && record.state === "set" ? record.valueJson : null;
 }
-/**
- * Builds `write-service.ts`'s own five-field dep shape from `RouteDeps`.
- *
- * Deliberately duplicates a host's own HTTP admin layer's equivalent field-mapping helper rather
- * than importing it, for the reason this file's header already gives about
- * `resolveOwnOrOtherPrincipalRead`: this is domain-owned wiring, and importing from a host's HTTP
- * admin layer would invert the ports/adapters direction. It is a field mapping, not logic, so the
- * two copies carry no behavioral drift risk — and `write-service.ts` is the single chokepoint
- * either way, so a divergence here could only produce a missing dependency, which fails loudly.
- */
-function toWriteDeps(routeDeps) {
-    return {
-        repo: routeDeps.settingsRepo,
-        clock: routeDeps.clock,
-        ids: routeDeps.idGen,
-        authorize: routeDeps.authorize,
-        principals: routeDeps.principalRepo,
-    };
-}
 /**
  * Errors a DIFFERENT input would fix, for `withSchemaOnRejection`'s decoration.
  *
@@ -110,6 +92,49 @@ const UNWIRED_SETTINGS_TOOL_IDS = new Set([
     // platform-wide.
     "settings_register_definitions",
 ]);
+/**
+ * One `settings_list_definitions` row. Only aliases need an extra lookup. Their target's
+ * schema/scope and BOTH coordinates' key policies must agree with the write handler;
+ * dangling/tombstoned targets fail closed. O(r) in policy rules plus at most one alias resolution.
+ */
+async function describeDefinitionForAgent(routeDeps, rules, def) {
+    const resolved = def.status === "alias"
+        ? await resolveDefinitionRaw({ repo: routeDeps.settingsRepo }, { namespace: def.namespace, key: def.key, workspaceId: routeDeps.workspaceId })
+        : def;
+    const coordinates = resolved ? [def, resolved] : [def];
+    const matchesAny = (list) => coordinates.some((coordinate) => !!findAgentWriteRule(list, coordinate));
+    const denied = matchesAny(rules.denied);
+    const confirmationRequired = matchesAny(rules.confirmation);
+    const scopes = resolved?.scopes ?? def.scopes;
+    return { namespace: def.namespace, key: def.key, ownerKind: def.ownerKind, scopes, status: def.status, version: def.version,
+        schema: resolved?.schema ?? def.schema,
+        agentWritable: isAgentWritable({ resolved, denied, confirmationRequired, canConfirm: !!routeDeps.confirmWrite, scopes }),
+        confirmationRequired };
+}
+/** Mirrors the write handler's refusals: live target, not denied, confirmable when protected,
+ * and writable at workspace or user scope. O(1). */
+function isAgentWritable(facts) {
+    if (!facts.resolved || facts.resolved.status === "tombstone" || facts.denied)
+        return false;
+    if (facts.confirmationRequired && !facts.canConfirm)
+        return false;
+    return (facts.scopes & (SCOPE_BIT.workspace | SCOPE_BIT.user)) !== 0;
+}
+/** Every split point of a dotted key that names a live (non-tombstoned) definition.
+ * Leading/trailing dots are never split points. O(k) resolver calls for k dots. */
+async function findDottedKeySplits(routeDeps, dottedKey) {
+    const matches = [];
+    // Reuse the definition resolver, including workspace fencing and aliases; never split on a guess.
+    for (let index = 1; index < dottedKey.length - 1; index++) {
+        if (dottedKey[index] !== ".")
+            continue;
+        const candidate = { namespace: dottedKey.slice(0, index), key: dottedKey.slice(index + 1) };
+        const definition = await resolveDefinitionRaw({ repo: routeDeps.settingsRepo }, { ...candidate, workspaceId: routeDeps.workspaceId });
+        if (definition && definition.status !== "tombstone")
+            matches.push(candidate);
+    }
+    return matches;
+}
 export function buildSettingsRegistrations(routeDeps) {
     const handlers = {
         settings_set_value: buildSettingsValueWriteHandler(routeDeps, "settings_set_value"),
@@ -122,23 +147,8 @@ export function buildSettingsRegistrations(routeDeps) {
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: null }),
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: routeDeps.workspaceId }),
             ]);
-            const deniedRules = [...AGENT_WRITE_DENIED_SETTINGS, ...(routeDeps.extraDeniedSettings ?? [])];
-            const confirmationRules = [...(routeDeps.confirmationSettings ?? AGENT_WRITE_CONFIRMATION_SETTINGS), ...(routeDeps.extraConfirmationSettings ?? [])];
-            // Only aliases need an extra lookup. Their target's schema/scope and BOTH coordinates'
-            // key policies must agree with the write handler; dangling/tombstoned targets fail closed.
-            const data = (await Promise.all([...platformDefs, ...siteDefs].map(async (def) => {
-                const resolved = def.status === "alias"
-                    ? await resolveDefinitionRaw({ repo: routeDeps.settingsRepo }, { namespace: def.namespace, key: def.key, workspaceId: routeDeps.workspaceId })
-                    : def;
-                const coordinates = resolved ? [def, resolved] : [def];
-                const denied = coordinates.some((coordinate) => !!findAgentWriteRule(deniedRules, coordinate));
-                const confirmationRequired = coordinates.some((coordinate) => !!findAgentWriteRule(confirmationRules, coordinate));
-                const scopes = resolved?.scopes ?? def.scopes;
-                return { namespace: def.namespace, key: def.key, ownerKind: def.ownerKind, scopes, status: def.status, version: def.version,
-                    schema: resolved?.schema ?? def.schema,
-                    agentWritable: !!resolved && resolved.status !== "tombstone" && !denied && (!confirmationRequired || !!routeDeps.confirmWrite) && (scopes & (SCOPE_BIT.workspace | SCOPE_BIT.user)) !== 0,
-                    confirmationRequired };
-            })))
+            const rules = agentWriteRules(routeDeps);
+            const data = (await Promise.all([...platformDefs, ...siteDefs].map((def) => describeDefinitionForAgent(routeDeps, rules, def))))
                 .sort((a, b) => a.namespace.localeCompare(b.namespace) || a.key.localeCompare(b.key));
             return { data };
         },
@@ -245,6 +255,21 @@ export function buildSettingsRegistrations(routeDeps) {
             return { setting: settingId, value: stored, scope: AGENT_PREFERENCE_WRITE_SCOPE, revisionSeq };
         },
     };
-    return buildDomainRegistrations({ domain: "settings", catalogModule: "settings/agent-tools.ts", catalog: CATALOG_BY_ID, handlers, derivedRisk: settingsDerivedRisk }, { unwiredToolIds: UNWIRED_SETTINGS_TOOL_IDS });
+    return buildDomainRegistrations({ domain: "settings", catalogModule: "settings/agent-tools.ts", catalog: CATALOG_BY_ID, handlers, derivedRisk: settingsDerivedRisk,
+        inputNormalizers: { settings_set_value: async ({ input }) => {
+                if (input.namespace !== undefined || typeof input.key !== "string" || !input.key.includes("."))
+                    return { input, notes: [] };
+                if (input.key.length > 512)
+                    throw new ToolInputError({ message: "settings_set_value: dotted key is too long. Send namespace and key separately." });
+                await routeDeps.settingsReady;
+                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." });
+                return { input: { ...input, ...matches[0] }, notes: ["dotted key→namespace + key"] };
+            } },
+    }, { unwiredToolIds: UNWIRED_SETTINGS_TOOL_IDS });
 }
 //# sourceMappingURL=tool-registrations.js.map

package/dist/settings/write-service.d.ts

@@ -239,6 +239,25 @@ export declare function retypeDefinition(required: RetypeDefinitionRequired): Pr
     settingId: string;
     version: number;
 }>;
+/** Add source-declared scopes to a core definition without moving or rewriting existing values.
+ * Boot uses this when a workspace preference gains a personal override. Scope removal is a
+ * separate migration decision: this operation only adds bits and preserves definition identity.
+ * @throws DefinitionInvalidError for operator-owned definitions or invalid scope bits.
+ * @complexity O(1), one definition transaction and cache invalidation.
+ * @example await extendDefinitionScopes({ deps, input: { namespace, key, workspaceId: null,
+ *   scopes: SCOPE_BIT.user, callerPrincipalId, authWorkspaceId } });
+ */
+export declare function extendDefinitionScopes({ deps, input }: {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        workspaceId: UUID | null;
+        scopes: number;
+        callerPrincipalId: UUID;
+        authWorkspaceId: UUID;
+    };
+}, _options?: {}): Promise<void>;
 export interface ReconcileDefinitionDefaultRequired {
     deps: SettingsWriteServiceDeps;
     input: {

package/dist/settings/write-service.js

@@ -416,6 +416,11 @@ export async function renameDefinition(required) {
     const { deps, input } = required;
     await authorizeDefinitionsManage(deps, input.callerPrincipalId, input.authWorkspaceId);
     const current = await resolveActiveDefinitionOrThrow(deps, input, "rename");
+    // A dispatched `rename` item that omits its target arrives here as `""` (see definitions-dispatch);
+    // without this guard the definition was silently moved to the empty name `.`.
+    if (!input.newNamespace || !input.newKey) {
+        throw new DefinitionInvalidError("rename requires a non-empty newNamespace and newKey");
+    }
     if (input.namespace === input.newNamespace && input.key === input.newKey) {
         throw new DefinitionInvalidError("rename requires newNamespace/newKey to differ from the current name");
     }
@@ -564,6 +569,35 @@ export async function retypeDefinition(required) {
     invalidateDefinitionNamespaceCache(deps.repo, input.namespace);
     return result;
 }
+/** Add source-declared scopes to a core definition without moving or rewriting existing values.
+ * Boot uses this when a workspace preference gains a personal override. Scope removal is a
+ * separate migration decision: this operation only adds bits and preserves definition identity.
+ * @throws DefinitionInvalidError for operator-owned definitions or invalid scope bits.
+ * @complexity O(1), one definition transaction and cache invalidation.
+ * @example await extendDefinitionScopes({ deps, input: { namespace, key, workspaceId: null,
+ *   scopes: SCOPE_BIT.user, callerPrincipalId, authWorkspaceId } });
+ */
+export async function extendDefinitionScopes({ deps, input }, _options = {}) {
+    await authorizeDefinitionsManage(deps, input.callerPrincipalId, input.authWorkspaceId);
+    const current = await resolveActiveDefinitionOrThrow(deps, input, "extend the scopes of");
+    const validBits = SCOPE_BIT.global | SCOPE_BIT.workspace | SCOPE_BIT.user;
+    if (current.ownerKind !== "core" || !Number.isInteger(input.scopes) || input.scopes <= 0 || input.scopes > validBits) {
+        throw new DefinitionInvalidError("Only core definitions can gain valid source-declared scope bits");
+    }
+    const scopes = current.scopes | input.scopes;
+    if (scopes === current.scopes)
+        return;
+    await deps.repo.transaction(async () => {
+        const now = kernelNowIso({ clock: deps.clock });
+        await deps.repo.saveDefinition({ ...current, scopes, updatedAt: now });
+        // Re-registration of metadata, not a value/schema change; retain the existing revision vocabulary.
+        await deps.repo.appendRevision({ entityKind: "definition", settingId: current.settingId,
+            scope: null, workspaceId: current.workspaceId, principalId: null, op: "register",
+            beforeJson: { scopes: current.scopes }, afterJson: { scopes }, defVersion: current.version,
+            actor: input.callerPrincipalId, originPluginId: null, changeSetId: null, createdAt: now });
+    });
+    invalidateDefinitionNamespaceCache(deps.repo, input.namespace);
+}
 /**
  * Reconciles a stored `default_json` that has drifted from the default its
  * source declares. Idempotent and a no-op when they already agree.

package/dist/target-scope.d.ts

@@ -21,6 +21,8 @@ export type TargetResolution = 'current' | {
  * @param required.isCurrentTarget - Check whether an unscoped tool names the current target.
  * @param optional - Target input name, schema description, refusal text and a narrowing scope predicate.
  * @returns A new array in the same order, preserving tools that already own the target input.
+ * Unscoped targets are also checked by normalizeInput, before policy or approval planning;
+ * the handler retains its check for direct handler callers.
  * @throws ToolInputError from a wrapped handler for a non-string target or a refused foreign target.
  * Host port errors propagate unchanged from the wrapped handler.
  * @complexity O(n) over registrations, plus copying supported schemas' top-level properties.

package/dist/target-scope.js

@@ -1,5 +1,6 @@
 import { isNonArrayRecord } from './records.js';
-import { isReadOnlyTool, ToolInputError } from './tool-registry.js';
+import { isReadOnlyTool } from './tool-registry.js';
+import { ToolInputError } from './tool-input-errors.js';
 /** Narrow the shared record predicate to ordinary or null-prototype objects, excluding instances. */
 function isPlainObject(value) {
     if (!isNonArrayRecord({ value }))
@@ -25,6 +26,8 @@ function withTargetParam(schema, param, description) {
  * @param required.isCurrentTarget - Check whether an unscoped tool names the current target.
  * @param optional - Target input name, schema description, refusal text and a narrowing scope predicate.
  * @returns A new array in the same order, preserving tools that already own the target input.
+ * Unscoped targets are also checked by normalizeInput, before policy or approval planning;
+ * the handler retains its check for direct handler callers.
  * @throws ToolInputError from a wrapped handler for a non-string target or a refused foreign target.
  * Host port errors propagate unchanged from the wrapped handler.
  * @complexity O(n) over registrations, plus copying supported schemas' top-level properties.
@@ -39,10 +42,23 @@ export function applyTargetScope(required, optional = {}) {
         if (isNonArrayRecord(properties) && Object.hasOwn(properties.value, param))
             return registration;
         const scoped = isReadOnlyTool({ descriptor }) && (optional.scoped?.({ registration }) ?? true);
-        const inputSchema = scoped ? withTargetParam(descriptor.inputSchema, param, describeParam) : descriptor.inputSchema;
+        const inputSchema = withTargetParam(descriptor.inputSchema, param, describeParam);
         return {
             ...registration,
             descriptor: inputSchema === descriptor.inputSchema ? descriptor : { ...descriptor, inputSchema },
+            normalizeInput: async ({ input }, options) => {
+                const normalized = registration.normalizeInput ? await registration.normalizeInput({ input }, options) : { input, notes: [] };
+                // Target refusal precedes policy and confirmation, including each merged plan item.
+                // Keep the key intact: downstream gates must authorize exactly this target.
+                if (!scoped && isPlainObject(normalized.input) && Object.hasOwn(normalized.input, param)) {
+                    const target = normalized.input[param];
+                    if (typeof target !== 'string')
+                        throw new ToolInputError({ message: `${param} must be a string` });
+                    if (!await required.isCurrentTarget({ target }))
+                        throw new ToolInputError({ message: refuseMessage });
+                }
+                return normalized;
+            },
             handler: async (ctx, options) => {
                 if (!isPlainObject(ctx.input) || !Object.hasOwn(ctx.input, param))
                     return registration.handler(ctx, options);

package/dist/text/escape.js

@@ -13,11 +13,11 @@ const XML_ENTITIES = { ...HTML_ENTITIES, "'": "'" };
 const SPECIAL = /[&<>"']/g;
 /** Escapes `& < > " '` for HTML text or a quoted attribute value. @complexity O(text length). */
 export function escapeHtml({ text }, _optional = {}) {
-    return text.replace(SPECIAL, (char) => HTML_ENTITIES[char] ?? char);
+    return text.replace(SPECIAL, (char) => HTML_ENTITIES[char]);
 }
 /** {@link escapeHtml} with the XML named entity `&apos;` for the apostrophe (sitemap and feed XML).
  *  @complexity O(text length). */
 export function escapeXml({ text }, _optional = {}) {
-    return text.replace(SPECIAL, (char) => XML_ENTITIES[char] ?? char);
+    return text.replace(SPECIAL, (char) => XML_ENTITIES[char]);
 }
 //# sourceMappingURL=escape.js.map

package/dist/text/sanitize-untrusted-text.d.ts

@@ -8,6 +8,9 @@ export declare function stripControlSequences({ text }: {
     text: string;
 }): string;
 export interface SanitizeTextOptions {
+    /** Exact IDs from trusted registration metadata, never inferred from error text or arguments.
+     * Credential rules still run first; prefixes and glued suffixes are never exempted. */
+    diagnosticToolIds?: readonly string[];
     /** Maximum output length; longer input is truncated with a trailing marker. Defaults to 500. */
     maxLength?: number;
 }
@@ -15,6 +18,8 @@ export interface SanitizeTextOptions {
  * Strip terminal control sequences, redact anything that looks like a secret, and cap the
  * length of `text` — the one function every boundary that surfaces daemon/network-derived text
  * to stderr/stdout should route through first.
+ * Trusted diagnosticToolIds exempt complete IDs (including dots) only, after credential masking.
+ * @complexity O(n + t) local time/space for n text bytes and t trusted ID bytes.
  */
 export declare function sanitizeUntrustedText({ text }: {
     text: string;

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

@@ -1,4 +1,4 @@
-import { LABELED_SECRET_RE, OPAQUE_TOKEN_RE, NON_SECRET_TOKEN_RE } from "../redact.js";
+import { redactSecrets, LABELED_SECRET_RE, OPAQUE_TOKEN_RE, NON_SECRET_TOKEN_RE } from "../redact.js";
 /**
  * @module redact
  *
@@ -39,6 +39,38 @@ function isOtherControlCode(code) {
         return true; // C1 controls
     return false;
 }
+/** True when position `j` starts an OSC terminator: BEL, or ST (`ESC \\`). */
+function isOscTerminatorAt(text, j) {
+    const code = text.charCodeAt(j);
+    return code === BEL || (code === ESC && text.charCodeAt(j + 1) === BACKSLASH);
+}
+/** Index of a CSI's final byte at or after `from`, or `text.length` when the CSI is truncated. */
+function csiEnd(text, from) {
+    let j = from;
+    while (j < text.length && !isCsiFinalByte(text.charCodeAt(j)))
+        j++;
+    return j;
+}
+/** Index of the last code unit of an OSC body starting at `from`: the BEL, the `\\` of ST, or the
+ * final code unit when the OSC is never terminated. */
+function oscEnd(text, from) {
+    let j = from;
+    while (j < text.length && !isOscTerminatorAt(text, j))
+        j++;
+    // charCodeAt past the end is NaN, so a truncated OSC never matches BEL here.
+    if (text.charCodeAt(j) === BEL)
+        return j;
+    return Math.min(j + 1, text.length - 1);
+}
+/** Index of the last code unit consumed by the escape sequence whose ESC sits at `start`. */
+function escapeSequenceEnd(text, start) {
+    const next = text.charCodeAt(start + 1);
+    if (next === CSI_OPEN)
+        return csiEnd(text, start + 2);
+    if (next === OSC_OPEN)
+        return oscEnd(text, start + 2);
+    return start; // bare ESC (or an unrecognized ESC-prefixed byte): drop just the ESC byte
+}
 /**
  * Strip ANSI/terminal escape sequences (CSI `ESC [ ... final-byte`, OSC `ESC ] ... BEL-or-ST`,
  * and bare ESC-prefixed bytes) plus other C0/C1 control characters from `text`. Written as an
@@ -50,53 +82,41 @@ export function stripControlSequences({ text }) {
     for (let i = 0; i < text.length; i++) {
         const code = text.charCodeAt(i);
         if (code === ESC) {
-            const next = text.charCodeAt(i + 1);
-            if (next === CSI_OPEN) {
-                let j = i + 2;
-                while (j < text.length && !isCsiFinalByte(text.charCodeAt(j)))
-                    j++;
-                i = j; // land on the final byte; the outer loop's i++ steps past it
-                continue;
-            }
-            if (next === OSC_OPEN) {
-                let j = i + 2;
-                while (j < text.length &&
-                    text.charCodeAt(j) !== BEL &&
-                    !(text.charCodeAt(j) === ESC && text.charCodeAt(j + 1) === BACKSLASH)) {
-                    j++;
-                }
-                if (j < text.length && text.charCodeAt(j) === BEL)
-                    i = j;
-                else
-                    i = Math.min(j + 1, text.length - 1);
-                continue;
-            }
-            continue; // bare ESC (or an unrecognized ESC-prefixed byte): drop just the ESC byte
-        }
-        if (isOtherControlCode(code))
+            i = escapeSequenceEnd(text, i); // land on the last consumed byte; the loop's i++ steps past it
             continue;
-        out += text[i];
+        }
+        if (!isOtherControlCode(code))
+            out += text[i];
     }
     return out;
 }
-// A labeled credential (`Authorization: ...`, `api-key=...`) has everything after the label
-// redacted. A bare run of 20+ base64url/hex-alphabet characters is treated as a possible
-// opaque token/secret and redacted outright, even with no label.
-/** Redact labeled credentials and long opaque-token-looking substrings from `text`. */
-function redactSecretLike({ text }) {
-    return text
-        .replace(LABELED_SECRET_RE, (match) => match.replace(/\S+$/, '[redacted]'))
-        .replace(OPAQUE_TOKEN_RE, (match) => (NON_SECRET_TOKEN_RE.test(match) ? match : '[redacted]'));
+/** Exact diagnostic vocabulary only: unknown spellings and glued suffixes remain opaque. */
+const DIAGNOSTIC_TOKENS = new Set([
+    'additionalProperties', 'additionalItems', 'unevaluatedProperties', 'unevaluatedItems',
+    'dependentRequired', 'dependentSchemas', 'exclusiveMinimum', 'exclusiveMaximum',
+    'minContains', 'maxContains', 'patternProperties', 'propertyNames', 'prefixItems',
+    'contentEncoding', 'contentMediaType', 'contentSchema',
+]);
+/** Mask credentials before preserving complete trusted IDs and UPPER_SNAKE diagnostics; redact opaque spans elsewhere. */
+function redactSecretLike({ text, diagnosticToolIds }) {
+    return redactSecrets({ input: text }, { redactPii: false })
+        .replace(LABELED_SECRET_RE, match => match.replace(/([:=]\s*)\S+$/, '$1[redacted]'))
+        .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
+        : token.replace(OPAQUE_TOKEN_RE, match => NON_SECRET_TOKEN_RE.test(match) || DIAGNOSTIC_TOKENS.has(match) ? match : '[redacted]'));
 }
 /**
  * Strip terminal control sequences, redact anything that looks like a secret, and cap the
  * length of `text` — the one function every boundary that surfaces daemon/network-derived text
  * to stderr/stdout should route through first.
+ * Trusted diagnosticToolIds exempt complete IDs (including dots) only, after credential masking.
+ * @complexity O(n + t) local time/space for n text bytes and t trusted ID bytes.
  */
 export function sanitizeUntrustedText({ text }, options = {}) {
     const requestedLength = options.maxLength ?? DEFAULT_MAX_EXCERPT_LENGTH;
     const maxLength = Number.isFinite(requestedLength) ? Math.max(0, Math.floor(requestedLength)) : DEFAULT_MAX_EXCERPT_LENGTH;
-    const sanitized = redactSecretLike({ text: stripControlSequences({ text }) });
+    const sanitized = redactSecretLike({ text: stripControlSequences({ text }), diagnosticToolIds: new Set(options.diagnosticToolIds) });
     if (sanitized.length <= maxLength)
         return sanitized;
     // The marker is part of the output budget, including when the budget cannot fit the full marker.