@jini-ai/core 0.4.7 → 0.4.9

package/dist/registration-kit.d.ts

@@ -140,14 +140,16 @@ export declare function requireInputRecord(required: {
     input: unknown;
 }, _optional?: Record<string, never>): Record<string, unknown>;
 /**
- * Reads a required non-empty string, with received-key hints when the field is missing.
- * @throws {ToolInputError} If the field is missing, empty, or not a string.
+ * Reads a required string, non-empty by default; allowEmpty supports literal text deletion.
+ * @throws {ToolInputError} If the field is missing, not a string, or empty without allowEmpty.
  * @complexity O(k) for k input keys on a missing-field rejection; otherwise O(1).
  */
 export declare function requireString(required: {
     input: Record<string, unknown>;
     key: string;
-}, _optional?: Record<string, never>): string;
+}, { allowEmpty }?: {
+    allowEmpty?: boolean;
+}): string;
 export declare function requireNumber(requiredArgs: {
     input: Record<string, unknown>;
     key: string;
@@ -261,7 +263,7 @@ export declare function decorateWithSchema(params: {
 }): Error;
 /**
  * Build-time gate on a single tool's risk metadata: refuses to wire a tool whose declared
- * `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
+ * authorization permission is missing, whose `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
  * whose id that layer has not classified at all, or whose `actorClassRule` needs a human confirmer
  * its handler does not ask for.
  *
@@ -327,6 +329,7 @@ export declare function buildDomainRegistrations(spec: {
     catalogModule: string;
     catalog: ReadonlyMap<string, AgentToolDefinition>;
     handlers: Record<string, ToolHandler>;
+    inputNormalizers?: Readonly<Record<string, import('./tool-input-normalization.js').ToolInputNormalizer>>;
     derivedRisk: DerivedRiskByToolId;
     /** Host vocabulary and reviewed action policy; risk remains independently checked above. */
     metadata?: import('./tool-metadata.js').ToolMetadataById;

package/dist/registration-kit.js

@@ -124,43 +124,37 @@ function missingFieldHint(required, _optional = {}) {
     }
     return hint;
 }
+/** The refusal for a required field: the expected kind, plus received-key hints only when the key is absent. */
+function requiredFieldError(required, _optional = {}) {
+    const { input, key, kind } = required;
+    const hint = input[key] === undefined ? missingFieldHint({ input }) : "";
+    return new ToolInputError({ message: `'${key}' (${kind}) is required${hint}` });
+}
 /**
- * Reads a required non-empty string, with received-key hints when the field is missing.
- * @throws {ToolInputError} If the field is missing, empty, or not a string.
+ * Reads a required string, non-empty by default; allowEmpty supports literal text deletion.
+ * @throws {ToolInputError} If the field is missing, not a string, or empty without allowEmpty.
  * @complexity O(k) for k input keys on a missing-field rejection; otherwise O(1).
  */
-export function requireString(required, _optional = {}) {
+export function requireString(required, { allowEmpty = false } = {}) {
     const { input, key } = required;
     const value = input[key];
-    if (typeof value !== "string" || value.length === 0) {
-        let message = `'${key}' (non-empty string) is required`;
-        if (value === undefined)
-            message += missingFieldHint({ input });
-        throw new ToolInputError({ message });
-    }
+    if (typeof value !== "string" || (!allowEmpty && value.length === 0))
+        throw requiredFieldError({ input, key, kind: allowEmpty ? "string" : "non-empty string" });
     return value;
 }
 export function requireNumber(requiredArgs, optionalArgs = {}) {
     const { input, key } = requiredArgs;
     const value = input[key];
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-        let message = `'${key}' (number) is required`;
-        if (value === undefined)
-            message += missingFieldHint({ input });
-        throw new ToolInputError({ message });
-    }
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw requiredFieldError({ input, key, kind: "number" });
     return value;
 }
 export function requireObject(requiredArgs, optionalArgs = {}) {
     const { input, key } = requiredArgs;
     const value = input[key];
     const candidate = { value };
-    if (!isRecord(candidate) || Array.isArray(candidate.value)) {
-        let message = `'${key}' (object) is required`;
-        if (value === undefined)
-            message += missingFieldHint({ input });
-        throw new ToolInputError({ message });
-    }
+    if (!isRecord(candidate) || Array.isArray(candidate.value))
+        throw requiredFieldError({ input, key, kind: "object" });
     return candidate.value;
 }
 export function optionalString(required, _optional = {}) {
@@ -319,7 +313,7 @@ export function decorateWithSchema(params) {
 // ---------------------------------------------------------------------------
 /**
  * Build-time gate on a single tool's risk metadata: refuses to wire a tool whose declared
- * `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
+ * authorization permission is missing, whose `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
  * whose id that layer has not classified at all, or whose `actorClassRule` needs a human confirmer
  * its handler does not ask for.
  *
@@ -339,17 +333,34 @@ export function decorateWithSchema(params) {
  */
 export function assertToolIsWirable(params, optional = {}) {
     const { toolId, catalogEntry } = params;
-    const derived = params.derivedRisk.get(toolId);
+    if (!hasDeclaredPermission({ catalogEntry })) {
+        throw new Error(`tool-registrations: '${toolId}' must declare an authorization permission before wiring`);
+    }
+    assertRiskIsCorroborated({ toolId, catalogEntry, derivedRisk: params.derivedRisk });
+    if (needsHumanConfirmer({ catalogEntry }) && !isHumanConfirmedHandler({ handler: optional.handler })) {
+        throw new Error(`tool-registrations: '${toolId}' declares actorClassRule '${catalogEntry.actorClassRule}', which needs a human confirmer — build its handler with humanConfirmedHandler so a human answers through the host's confirmation transport (see ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT)`);
+    }
+}
+/** A non-blank string permission; a malformed catalog (no authorization object) counts as none. */
+function hasDeclaredPermission({ catalogEntry }) {
+    const permission = catalogEntry.authorization?.permission;
+    return typeof permission === "string" && permission.trim().length > 0;
+}
+/** Refuses an unclassified tool, then a declaration the wiring layer's own classification contradicts. */
+function assertRiskIsCorroborated({ toolId, catalogEntry, derivedRisk }) {
+    const derived = derivedRisk.get(toolId);
     if (!derived) {
         throw new Error(`tool-registrations: '${toolId}' has no entry in DERIVED_RISK_BY_TOOL_ID — classify what its handler actually does before wiring it (unknown operations are refused, never assumed safe)`);
     }
     if (derived !== catalogEntry.sideEffects) {
         throw new Error(`tool-registrations: '${toolId}' declares sideEffects '${catalogEntry.sideEffects}' but this layer derives '${derived}' from what its handler calls — reconcile the two rather than trusting the declaration`);
     }
-    const needsHuman = catalogEntry.actorClassRule && ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT.has(catalogEntry.actorClassRule);
-    if (needsHuman && !(optional.handler && HUMAN_CONFIRMED_HANDLERS.has(optional.handler))) {
-        throw new Error(`tool-registrations: '${toolId}' declares actorClassRule '${catalogEntry.actorClassRule}', which needs a human confirmer — build its handler with humanConfirmedHandler so a human answers through the host's confirmation transport (see ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT)`);
-    }
+}
+function needsHumanConfirmer({ catalogEntry }) {
+    return catalogEntry.actorClassRule !== undefined && ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT.has(catalogEntry.actorClassRule);
+}
+function isHumanConfirmedHandler({ handler }) {
+    return handler !== undefined && HUMAN_CONFIRMED_HANDLERS.has(handler);
 }
 /**
  * Turns one domain's handler map into `ToolRegistration`s, applying every build-time gate the
@@ -388,48 +399,56 @@ export function assertToolIsWirable(params, optional = {}) {
  * @overallScore 100
  */
 export function buildDomainRegistrations(spec, optional = {}) {
-    const registrations = [];
-    for (const [id, handler] of Object.entries(spec.handlers)) {
-        const catalogEntry = spec.catalog.get(id);
-        if (!catalogEntry) {
-            throw new Error(`tool-registrations: ${spec.domain} catalog has no entry named '${id}' — ${spec.catalogModule} drifted`);
-        }
-        assertToolIsWirable({ toolId: id, catalogEntry, derivedRisk: spec.derivedRisk }, { handler });
-        if (!catalogEntry.inputSchema) {
-            throw new Error(`tool-registrations: wired tool '${id}' publishes no inputSchema — add one to its entry in ${spec.catalogModule} so the model gets a contract, or leave the tool unwired`);
-        }
-        const metadata = catalogEntry.metadata ?? toolMetadataFor({ toolId: id, metadata: spec.metadata });
-        registrations.push({
-            descriptor: {
-                id,
-                description: catalogEntry.description,
-                inputSchema: catalogEntry.inputSchema,
-                ...(metadata ? { metadata } : {}),
-                // The ONE place a domain's declared risk becomes the descriptor flag every read-only gate
-                // reads (`@jini-ai/core`'s `isReadOnlyTool`). Placed here rather than in each domain's
-                // `tool-registrations.ts` for the same reason the drift tripwire is: twelve copies of this
-                // line is twelve chances for one to say something different. Change what counts as
-                // read-only and every domain follows.
-                //
-                // Safe to derive from the declaration only because `assertToolIsWirable` has ALREADY run
-                // two lines above and refused any tool whose declared `sideEffects` disagrees with the
-                // wiring layer's own `DERIVED_RISK_BY_TOOL_ID` classification — so by this point the
-                // declaration has been independently corroborated, and a catalog entry cannot make itself
-                // read-only by editing one word.
-                readOnly: catalogEntry.sideEffects === "none",
-            },
-            handler,
-            policy: { authorize: () => "allow" },
-        });
+    const registrations = Object.entries(spec.handlers).map(([id, handler]) => registrationFor({ spec, id, handler }));
+    assertEveryEntryIsWiredOrDeclared({ spec }, optional);
+    return registrations;
+}
+/** One wired tool: every build-time gate first, then the descriptor/handler/policy triple. */
+function registrationFor({ spec, id, handler }) {
+    const catalogEntry = spec.catalog.get(id);
+    if (!catalogEntry) {
+        throw new Error(`tool-registrations: ${spec.domain} catalog has no entry named '${id}' — ${spec.catalogModule} drifted`);
+    }
+    assertToolIsWirable({ toolId: id, catalogEntry, derivedRisk: spec.derivedRisk }, { handler });
+    if (!catalogEntry.inputSchema) {
+        throw new Error(`tool-registrations: wired tool '${id}' publishes no inputSchema — add one to its entry in ${spec.catalogModule} so the model gets a contract, or leave the tool unwired`);
     }
+    const metadata = catalogEntry.metadata ?? toolMetadataFor({ toolId: id, metadata: spec.metadata });
+    const normalizeInput = spec.inputNormalizers?.[id];
+    return {
+        descriptor: {
+            id,
+            description: catalogEntry.description,
+            inputSchema: catalogEntry.inputSchema,
+            ...(metadata ? { metadata } : {}),
+            // The ONE place a domain's declared risk becomes the descriptor flag every read-only gate
+            // reads (`@jini-ai/core`'s `isReadOnlyTool`). Placed here rather than in each domain's
+            // `tool-registrations.ts` for the same reason the drift tripwire is: twelve copies of this
+            // line is twelve chances for one to say something different. Change what counts as
+            // read-only and every domain follows.
+            //
+            // Safe to derive from the declaration only because `assertToolIsWirable` has ALREADY run
+            // two lines above and refused any tool whose declared `sideEffects` disagrees with the
+            // wiring layer's own `DERIVED_RISK_BY_TOOL_ID` classification — so by this point the
+            // declaration has been independently corroborated, and a catalog entry cannot make itself
+            // read-only by editing one word.
+            readOnly: catalogEntry.sideEffects === "none",
+            sideEffects: catalogEntry.sideEffects,
+        },
+        handler,
+        ...(normalizeInput ? { normalizeInput } : {}),
+        policy: { authorize: () => "allow" },
+    };
+}
+/** 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 (optional.unwiredToolIds?.has(id))
+        if (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`);
     }
-    return registrations;
 }
 /**
  * Folds every domain's risk slice into the one map the assistant-level

package/dist/settings/agent-value-write-tools.d.ts

@@ -1,6 +1,8 @@
 import { type ToolExecutionContext, type ToolHandler } from "../tool-registry.js";
 import type { JsonValue } from "../primitives/index.js";
+import { type AgentSettingWriteRule } from "./agent-write-denylist.js";
 import type { SettingsToolDeps } from "./tool-registrations.js";
+import { type SettingsWriteServiceDeps } from "./write-service.js";
 export type SettingsValueWriteToolId = "settings_set_value" | "settings_clear_value";
 /** Host-only port. This request is never an agent input and only the host's authenticated
  * human transport or a persisted human identity grant may answer it. Model input never authorizes it. */
@@ -14,6 +16,23 @@ export interface SettingsWriteConfirmation {
     value?: JsonValue;
     reason: string;
 }
+/** The effective agent-write key policy: package denials plus host extensions (never agent input),
+ * and the host's confirmation policy (replacing the package defaults) plus host extensions. O(r). */
+export declare function agentWriteRules(deps: SettingsToolDeps): {
+    denied: AgentSettingWriteRule[];
+    confirmation: AgentSettingWriteRule[];
+};
+/**
+ * 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 `tool-registrations.ts`'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.
+ */
+export declare function toWriteDeps(routeDeps: SettingsToolDeps): SettingsWriteServiceDeps;
 /** Builds one value-write handler. Effects: authorize -> raw read -> optional human card ->
  * service write -> result. The service rechecks authorization and performs its normal transaction.
  * @complexity O(value size + rule count) plus bounded repository calls and a human wait.

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

@@ -1,51 +1,65 @@
-import { adaptLegacyAuthorize } from "../tool-permissions.js";
+import { adaptLegacyAuthorize, ForbiddenError as PermissionDeniedError, requireToolPermission } from "../tool-permissions.js";
 import { ToolInputError } from "../tool-registry.js";
-import { ForbiddenError as PermissionDeniedError } from "../tool-permissions.js";
-import { requireToolPermission } from "../tool-permissions.js";
 import { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule } from "./agent-write-denylist.js";
 import { DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, ScopeNotAllowedError, ValueValidationFailedError } from "./errors.js";
 import { getEffective, resolveDefinitionRaw, validateValueAgainstSchema } from "./settings.js";
 import { SCOPE_BIT } from "./types.js";
 import { clear, deriveRequiredPermission, set } from "./write-service.js";
+const WRITE_FIELDS = {
+    settings_set_value: ["namespace", "key", "value", "scope"],
+    settings_clear_value: ["namespace", "key", "scope"],
+};
 /** Strict boundary, including direct handler calls. JSON is cloned before the first await
- * so a held-open card cannot consent to a value later changed by the caller. O(input size). */
+ * so a held-open card cannot consent to a value later changed by the caller. O(input size).
+ * Refusal order: non-object, unexpected field, namespace, key, scope, missing value, non-JSON value. */
 function parseTarget(toolId, raw) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
-        throw new ToolInputError({ message: `${toolId}: input must be an object containing namespace and key.` });
-    const input = raw;
-    const fields = toolId === "settings_set_value" ? ["namespace", "key", "value", "scope"] : ["namespace", "key", "scope"];
+    const input = requireInputObject(toolId, raw);
+    const fields = WRITE_FIELDS[toolId];
     const extra = Object.keys(input).find((key) => !fields.includes(key));
     if (extra)
         throw new ToolInputError({ message: `${toolId}: unexpected input '${extra}'. Only ${fields.join(", ")} are accepted; the caller's own user layer is the only user target.` });
-    for (const field of ["namespace", "key"]) {
-        if (typeof input[field] !== "string" || !input[field].trim())
-            throw new ToolInputError({ message: `${toolId}: '${field}' must be a non-empty string. Call settings_list_definitions to see valid keys.` });
-    }
-    const namespace = input.namespace;
-    const key = input.key;
-    const scope = input.scope === undefined ? "workspace" : input.scope;
-    if (scope !== "workspace" && scope !== "user")
-        throw new ToolInputError({ message: `${toolId}: scope must be 'workspace' or 'user'; global settings are not writable by this tool.` });
+    const namespace = requireCoordinate(toolId, input, "namespace");
+    const key = requireCoordinate(toolId, input, "key");
+    const scope = parseScope(toolId, input.scope);
     if (toolId === "settings_clear_value")
         return { namespace, key, scope };
+    return { namespace, key, scope, value: snapshotJsonValue(toolId, input) };
+}
+function requireInputObject(toolId, raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new ToolInputError({ message: `${toolId}: input must be an object containing namespace and key.` });
+    return raw;
+}
+function requireCoordinate(toolId, input, field) {
+    const value = input[field];
+    if (typeof value !== "string" || !value.trim())
+        throw new ToolInputError({ message: `${toolId}: '${field}' must be a non-empty string. Call settings_list_definitions to see valid keys.` });
+    return value;
+}
+/** Omitted means workspace; anything other than workspace/user (including null and global) is refused. */
+function parseScope(toolId, raw) {
+    const scope = raw === undefined ? "workspace" : raw;
+    if (scope !== "workspace" && scope !== "user")
+        throw new ToolInputError({ message: `${toolId}: scope must be 'workspace' or 'user'; global settings are not writable by this tool.` });
+    return scope;
+}
+function snapshotJsonValue(toolId, input) {
     if (!("value" in input))
         throw new ToolInputError({ message: `${toolId}: a JSON 'value' is required.` });
     // The executor validates JSON input too. The round trip protects direct callers and isolates
     // the snapshot; values JSON would silently change (NaN, undefined, functions) are rejected.
-    let serialized;
+    // A serialization that yields nothing makes JSON.parse throw, so it is refused the same way.
     try {
-        serialized = JSON.stringify(input.value, (_key, value) => {
-            if (value === undefined || typeof value === "function" || typeof value === "symbol" || (typeof value === "number" && !Number.isFinite(value)))
-                throw new Error("not JSON");
-            return value;
-        });
+        return JSON.parse(JSON.stringify(input.value, rejectNonJson));
     }
-    catch {
-        throw new ToolInputError({ message: `${toolId}: value must be valid JSON.` });
+    catch (cause) {
+        throw new ToolInputError({ message: `${toolId}: value must be valid JSON.` }, { cause });
     }
-    if (serialized === undefined)
-        throw new ToolInputError({ message: `${toolId}: value must be valid JSON.` });
-    return { namespace, key, scope, value: JSON.parse(serialized) };
+}
+function rejectNonJson(_key, value) {
+    if (value === undefined || typeof value === "function" || typeof value === "symbol" || (typeof value === "number" && !Number.isFinite(value)))
+        throw new Error("not JSON");
+    return value;
 }
 /** Definition/scope/value preflight for readable refusal before any card. O(1) repository
  * lookups plus alias resolution and schema validation, with no writes. */
@@ -68,17 +82,24 @@ function readLayer(deps, target, settingId, principalId) {
     const base = { workspaceId: deps.workspaceId, settingId };
     return target.scope === "user" ? deps.settingsRepo.getUserValue({ ...base, principalId }) : deps.settingsRepo.getWorkspaceValue(base);
 }
+/** The effective agent-write key policy: package denials plus host extensions (never agent input),
+ * and the host's confirmation policy (replacing the package defaults) plus host extensions. O(r). */
+export function agentWriteRules(deps) {
+    return {
+        denied: [...AGENT_WRITE_DENIED_SETTINGS, ...(deps.extraDeniedSettings ?? [])],
+        confirmation: [...(deps.confirmationSettings ?? AGENT_WRITE_CONFIRMATION_SETTINGS), ...(deps.extraConfirmationSettings ?? [])],
+    };
+}
 /** Fail closed on host-denied keys, including a protected target reached through an alias.
  * Returns a confirmation rule if either coordinate needs one; O(r) in fixed policy rules. */
 function writePolicy(deps, toolId, target, definition) {
     const targets = definition ? [target, definition] : [target];
-    const denied = [...AGENT_WRITE_DENIED_SETTINGS, ...(deps.extraDeniedSettings ?? [])];
+    const { denied, confirmation } = agentWriteRules(deps);
     for (const coordinate of targets) {
         const rule = findAgentWriteRule(denied, coordinate);
         if (rule)
             throw new ToolInputError({ message: `${toolId}: '${coordinate.namespace}.${coordinate.key}' can't be changed by the assistant: ${rule.reason}. The owner can change it in Settings.` });
     }
-    const confirmation = [...(deps.confirmationSettings ?? AGENT_WRITE_CONFIRMATION_SETTINGS), ...(deps.extraConfirmationSettings ?? [])];
     for (const coordinate of targets) {
         const rule = findAgentWriteRule(confirmation, coordinate);
         if (rule)
@@ -89,15 +110,84 @@ function writePolicy(deps, toolId, target, definition) {
 /** Maps expected caller-fixable errors; infrastructure failures remain untouched. O(1). */
 function rethrowWriteError(error, toolId, target, permission) {
     if (error instanceof DefinitionNotFoundError || error instanceof DefinitionTombstonedError)
-        throw new ToolInputError({ message: `${toolId}: ${error.message}. Call settings_list_definitions to see valid keys.` });
+        throw new ToolInputError({ message: `${toolId}: ${error.message}. Call settings_list_definitions to see valid keys.` }, { cause: error });
     if (error instanceof ScopeNotAllowedError)
-        throw new ToolInputError({ message: `${toolId}: '${target.namespace}.${target.key}' can't be set ${target.scope === "user" ? "per-user" : "at workspace scope"}. Call settings_list_definitions to see allowed scopes.` });
+        throw new ToolInputError({ message: `${toolId}: '${target.namespace}.${target.key}' can't be set ${target.scope === "user" ? "per-user" : "at workspace scope"}. Call settings_list_definitions to see allowed scopes.` }, { cause: error });
     if (error instanceof ValueValidationFailedError)
-        throw new ToolInputError({ message: `${toolId}: ${error.message}. Call settings_list_definitions and use a value matching the setting's schema.` });
+        throw new ToolInputError({ message: `${toolId}: ${error.message}. Call settings_list_definitions and use a value matching the setting's schema.` }, { cause: error });
     if (error instanceof ForbiddenError || error instanceof PermissionDeniedError)
-        throw new ToolInputError({ message: `${toolId}: permission '${permission}' is required. Ask the owner to grant it before retrying.` });
+        throw new ToolInputError({ message: `${toolId}: permission '${permission}' is required. Ask the owner to grant it before retrying.` }, { cause: error });
     throw error;
 }
+/**
+ * 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 `tool-registrations.ts`'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.
+ */
+export function toWriteDeps(routeDeps) {
+    return {
+        repo: routeDeps.settingsRepo,
+        clock: routeDeps.clock,
+        ids: routeDeps.idGen,
+        authorize: routeDeps.authorize,
+        principals: routeDeps.principalRepo,
+    };
+}
+/** Cancellation is checked at each step that precedes a card or a write. O(1). */
+function assertRunActive(ctx, toolId) {
+    if (ctx.signal.aborted)
+        throw new ToolInputError({ message: `${toolId}: the run ended before the change could be applied. Nothing was changed.` });
+}
+/** Effects: policy -> readiness -> authorize -> definition preflight -> raw read. No writes. */
+async function prepareWrite(deps, request) {
+    const { ctx, toolId, target, permission } = request;
+    assertRunActive(ctx, toolId);
+    writePolicy(deps, toolId, target);
+    await Promise.all([deps.settingsReady, deps.settingsUiTabsReady]);
+    await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: deps.authorize }), workspaceId: deps.workspaceId, principalId: ctx.principal.id, permission }, { entityType: "setting-value" });
+    const definition = await resolveTarget(deps, target, toolId === "settings_set_value");
+    const rule = writePolicy(deps, toolId, target, definition);
+    const layer = await readLayer(deps, target, definition.settingId, ctx.principal.id);
+    const previous = layer?.state === "set" ? structuredClone(layer.valueJson) : null;
+    return { definition, rule, layer, previous };
+}
+/** Opens the host's human card for a protected key, then proves nothing changed while it was open.
+ * Fails closed without a confirmation port, on any answer but `true`, and on a stale definition or layer. */
+async function confirmProtectedWrite(deps, request, prepared, options) {
+    const { ctx, toolId, target } = request;
+    const { definition, layer, previous, rule } = prepared;
+    const isSet = toolId === "settings_set_value";
+    if (!deps.confirmWrite)
+        throw new ToolInputError({ message: `${toolId}: '${rule.namespace}.${rule.key}' requires a human confirmation card: ${rule.reason}. The owner can change it in Settings.` });
+    const confirmed = await deps.confirmWrite({ ctx, toolId, namespace: rule.namespace, key: rule.key, scope: target.scope, previous: structuredClone(previous), ...(isSet ? { value: structuredClone(target.value) } : {}), reason: rule.reason }, options);
+    if (confirmed !== true)
+        throw new ToolInputError({ message: `${toolId}: the human did not confirm the change. Nothing was changed.` });
+    const current = await resolveTarget(deps, target, isSet);
+    const currentLayer = await readLayer(deps, target, current.settingId, ctx.principal.id);
+    if (current.settingId !== definition.settingId || current.version !== definition.version || currentLayer?.seq !== layer?.seq)
+        throw new ToolInputError({ message: `${toolId}: this setting changed while the confirmation card was open. Read it again and request a new confirmation. Nothing was changed by this call.` });
+}
+/** The service write itself; `write-service.ts` rechecks authorization inside its transaction. */
+async function applyWrite(deps, request, prepared) {
+    const { ctx, toolId, target } = request;
+    const { definition, previous } = prepared;
+    const writeDeps = toWriteDeps(deps);
+    // Resolved coordinates preserve host validators even when the request named an alias.
+    const input = { namespace: definition.namespace, key: definition.key, scope: target.scope, workspaceId: deps.workspaceId, callerPrincipalId: ctx.principal.id, authWorkspaceId: deps.workspaceId };
+    const key = `${target.namespace}.${target.key}`;
+    if (toolId === "settings_set_value") {
+        const result = await (deps.setValue ?? set)({ deps: writeDeps, input: { ...input, value: target.value } });
+        return { key, scope: target.scope, previous, value: result.value, revisionSeq: result.revisionSeq };
+    }
+    await clear({ deps: writeDeps, input });
+    const effective = await getEffective({ repo: deps.settingsRepo }, { namespace: definition.namespace, key: definition.key, scopeContext: { workspaceId: deps.workspaceId, principalId: ctx.principal.id } });
+    return { key, scope: target.scope, previous, effective: effective?.value ?? null };
+}
 /** Builds one value-write handler. Effects: authorize -> raw read -> optional human card ->
  * service write -> result. The service rechecks authorization and performs its normal transaction.
  * @complexity O(value size + rule count) plus bounded repository calls and a human wait.
@@ -109,45 +199,16 @@ export function buildSettingsValueWriteHandler(deps, toolId) {
         ctx = { ...ctx, principal: { ...ctx.principal }, run: { ...ctx.run } };
         const target = parseTarget(toolId, ctx.input);
         const permission = deriveRequiredPermission({ scope: target.scope, callerPrincipalId: ctx.principal.id });
-        const isSet = toolId === "settings_set_value";
+        const request = { ctx, toolId, target, permission };
         try {
-            if (ctx.signal.aborted)
-                throw new ToolInputError({ message: `${toolId}: the run ended before the change could be applied. Nothing was changed.` });
-            writePolicy(deps, toolId, target);
-            await Promise.all([deps.settingsReady, deps.settingsUiTabsReady]);
-            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: deps.authorize }), workspaceId: deps.workspaceId, principalId: ctx.principal.id, permission }, { entityType: "setting-value" });
-            const definition = await resolveTarget(deps, target, isSet);
-            const rule = writePolicy(deps, toolId, target, definition);
-            const layer = await readLayer(deps, target, definition.settingId, ctx.principal.id);
-            const previous = layer?.state === "set" ? structuredClone(layer.valueJson) : null;
+            const prepared = await prepareWrite(deps, request);
             // Cancellation may have arrived during readiness, authorization or the raw read.
             // Check before opening a card so a finished run cannot leave a new exchange waiting.
-            if (ctx.signal.aborted)
-                throw new ToolInputError({ message: `${toolId}: the run ended before the change could be applied. Nothing was changed.` });
-            if (rule) {
-                if (!deps.confirmWrite)
-                    throw new ToolInputError({ message: `${toolId}: '${rule.namespace}.${rule.key}' requires a human confirmation card: ${rule.reason}. The owner can change it in Settings.` });
-                const confirmed = await deps.confirmWrite({ ctx, toolId, namespace: rule.namespace, key: rule.key, scope: target.scope, previous: structuredClone(previous), ...(isSet ? { value: structuredClone(target.value) } : {}), reason: rule.reason }, options);
-                if (confirmed !== true)
-                    throw new ToolInputError({ message: `${toolId}: the human did not confirm the change. Nothing was changed.` });
-                const current = await resolveTarget(deps, target, isSet);
-                const currentLayer = await readLayer(deps, target, current.settingId, ctx.principal.id);
-                if (current.settingId !== definition.settingId || current.version !== definition.version || currentLayer?.seq !== layer?.seq)
-                    throw new ToolInputError({ message: `${toolId}: this setting changed while the confirmation card was open. Read it again and request a new confirmation. Nothing was changed by this call.` });
-            }
-            if (ctx.signal.aborted)
-                throw new ToolInputError({ message: `${toolId}: the run ended before the change could be applied. Nothing was changed.` });
-            const writeDeps = { repo: deps.settingsRepo, clock: deps.clock, ids: deps.idGen, authorize: deps.authorize, principals: deps.principalRepo };
-            // Resolved coordinates preserve host validators even when the request named an alias.
-            const input = { namespace: definition.namespace, key: definition.key, scope: target.scope, workspaceId: deps.workspaceId, callerPrincipalId: ctx.principal.id, authWorkspaceId: deps.workspaceId };
-            const key = `${target.namespace}.${target.key}`;
-            if (isSet) {
-                const result = await (deps.setValue ?? set)({ deps: writeDeps, input: { ...input, value: target.value } });
-                return { key, scope: target.scope, previous, value: result.value, revisionSeq: result.revisionSeq };
-            }
-            await clear({ deps: writeDeps, input });
-            const effective = await getEffective({ repo: deps.settingsRepo }, { namespace: definition.namespace, key: definition.key, scopeContext: { workspaceId: deps.workspaceId, principalId: ctx.principal.id } });
-            return { key, scope: target.scope, previous, effective: effective?.value ?? null };
+            assertRunActive(ctx, toolId);
+            if (prepared.rule)
+                await confirmProtectedWrite(deps, request, { ...prepared, rule: prepared.rule }, options);
+            assertRunActive(ctx, toolId);
+            return await applyWrite(deps, request, prepared);
         }
         catch (error) {
             rethrowWriteError(error, toolId, target, permission);

package/dist/settings/ensure-definitions.d.ts

@@ -44,7 +44,8 @@ export interface SettingDefinitionSpec<Key extends string = string> {
      * Bitmask over `SCOPE_BIT`. Defaults to `workspace`, which is what most
      * settings-dialog tabs want: one operator's choice shouldn't silently
      * become every workspace's. Pass `SCOPE_BIT.user` (or a mask including it)
-     * for a genuinely per-operator preference.
+     * for a genuinely per-operator preference. On existing core definitions, explicitly
+     * declared bits are added at boot; existing scopes and value rows are preserved.
      */
     scopes?: number;
 }
@@ -73,7 +74,8 @@ export type EnsureSettingDefinitionsInput = SettingDefinitionsInput & ({
 /**
  * Idempotently registers every definition in `input.definitions` under
  * `input.namespace`, and reconciles the stored default of any that already
- * exist to the default source declares. Safe to call on every boot.
+ * exist to the default source declares. Explicit core scope bits are added without removing
+ * existing scopes or moving stored values. Safe to call on every boot.
  *
  * The reconcile half matters as much as the register half: registration is
  * once-only, so without it a `defaultValue` edited in source never reaches an