@jini-ai/core 0.4.7 → 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

@@ -0,0 +1,52 @@
+/**
+ * Keep the same tool ids plus one optional target input instead of a tool per resource:
+ * each tool keeps one permission, approval class, search entry and card. Hosts own target
+ * resolution; core knows nothing about their sites, registries or files.
+ *
+ * Writes refuse foreign targets rather than silently ignoring the unknown key. A handler
+ * that ignores unknown keys would otherwise write to the CURRENT target under the wrong label.
+ */
+import type { Principal } from './principal.js';
+import { type ToolHandler, type ToolRegistration } from './tool-registry.js';
+/** A host either keeps the current handler and principal or supplies both for a peer. */
+export type TargetResolution = 'current' | {
+    readonly handler: ToolHandler;
+    readonly principal: Principal;
+};
+/**
+ * Scope read-only registrations through host-supplied target ports and guard other tools
+ * against accidentally executing on the current target under a foreign target's name.
+ * @param required.registrations - Ordered tool catalog; registrations and schemas are never mutated.
+ * @param required.resolveTarget - Resolve a scoped read to the current handler or a peer handler and principal.
+ * @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.
+ * @example applyTargetScope({ registrations, resolveTarget, isCurrentTarget }, { param: 'workspace' });
+ */
+export declare function applyTargetScope(required: {
+    readonly registrations: readonly ToolRegistration[];
+    /** Called only for scoped tools with a named target. Throw to refuse with the host's message unchanged. */
+    resolveTarget(required: {
+        target: string;
+        toolId: string;
+        principal: Principal;
+    }): Promise<TargetResolution>;
+    /** Called only for unscoped tools (writes and host-excluded reads) with a named target. */
+    isCurrentTarget(required: {
+        target: string;
+    }): boolean | Promise<boolean>;
+}, optional?: {
+    readonly param?: string;
+    readonly describeParam?: string;
+    readonly refuseMessage?: string;
+    /** Narrows read-only tools; returning true can never scope a tool that is not read-only. */
+    readonly scoped?: (required: {
+        registration: ToolRegistration;
+    }) => boolean;
+}): ToolRegistration[];
+//# sourceMappingURL=target-scope.d.ts.map

package/dist/target-scope.js

@@ -0,0 +1,82 @@
+import { isNonArrayRecord } from './records.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 }))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Add an optional input only to supported object schemas; preserve other dialects unchanged. */
+function withTargetParam(schema, param, description) {
+    if (schema === undefined)
+        return { type: 'object', properties: { [param]: { type: 'string', description } } };
+    if (!isPlainObject(schema))
+        return schema;
+    if (!isPlainObject(schema.properties) && schema.type !== 'object')
+        return schema;
+    return { ...schema, properties: { ...(isPlainObject(schema.properties) ? schema.properties : {}), [param]: { type: 'string', description } } };
+}
+/**
+ * Scope read-only registrations through host-supplied target ports and guard other tools
+ * against accidentally executing on the current target under a foreign target's name.
+ * @param required.registrations - Ordered tool catalog; registrations and schemas are never mutated.
+ * @param required.resolveTarget - Resolve a scoped read to the current handler or a peer handler and principal.
+ * @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.
+ * @example applyTargetScope({ registrations, resolveTarget, isCurrentTarget }, { param: 'workspace' });
+ */
+export function applyTargetScope(required, optional = {}) {
+    const { param = 'site', describeParam = 'Optional target name. Omit to use the current target.', refuseMessage = 'This tool runs only on the current target.' } = optional;
+    return required.registrations.map(registration => {
+        const { descriptor } = registration;
+        const schema = { value: descriptor.inputSchema };
+        const properties = { value: isNonArrayRecord(schema) ? schema.value.properties : undefined };
+        if (isNonArrayRecord(properties) && Object.hasOwn(properties.value, param))
+            return registration;
+        const scoped = isReadOnlyTool({ descriptor }) && (optional.scoped?.({ registration }) ?? true);
+        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);
+                const target = ctx.input[param];
+                if (typeof target !== 'string')
+                    throw new ToolInputError({ message: `${param} must be a string` });
+                const { [param]: _target, ...input } = ctx.input;
+                if (!scoped) {
+                    if (!await required.isCurrentTarget({ target }))
+                        throw new ToolInputError({ message: refuseMessage });
+                    return registration.handler({ ...ctx, input }, options);
+                }
+                const peer = await required.resolveTarget({ target, toolId: descriptor.id, principal: ctx.principal });
+                if (peer === 'current')
+                    return registration.handler({ ...ctx, input }, options);
+                return peer.handler({ ...ctx, input, principal: peer.principal }, options);
+            },
+        };
+    });
+}
+//# sourceMappingURL=target-scope.js.map

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;