@jini-ai/core 0.4.8 → 0.6.10

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

package/dist/settings/ensure-definitions.js

@@ -1,13 +1,14 @@
 import { resolveDefinitionRaw } from "./settings.js";
 import { SCOPE_BIT } from "./types.js";
-import { reconcileDefinitionDefault, registerDefinitions } from "./write-service.js";
+import { extendDefinitionScopes, reconcileDefinitionDefault, registerDefinitions } from "./write-service.js";
 /** Boot-time infra work is trusted by construction — mirrors every other
  *  `ensure*SettingDefinitions`'s identical shim. */
 const alwaysAllowBoot = async () => ({ allowed: true, reason: "system_boot" });
 /**
  * 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
@@ -31,71 +32,86 @@ const alwaysAllowBoot = async () => ({ allowed: true, reason: "system_boot" });
  * lookup plus at most one registration or default reconciliation.
  */
 export async function ensureSettingDefinitions(deps, input) {
-    const ownerKind = input.ownerKind ?? "core";
     const workspaceId = input.ownerKind === "site" ? input.workspaceId : null;
-    const authWorkspaceId = workspaceId ?? input.systemPrincipalId;
-    const writeDeps = {
-        repo: deps.settingsRepo,
-        clock: deps.clock,
-        ids: deps.ids,
-        authorize: alwaysAllowBoot,
-        principals: deps.principals,
+    const target = {
+        namespace: input.namespace,
+        ownerKind: input.ownerKind ?? "core",
+        workspaceId,
+        authWorkspaceId: workspaceId ?? input.systemPrincipalId,
+        systemPrincipalId: input.systemPrincipalId,
+        writeDeps: {
+            repo: deps.settingsRepo,
+            clock: deps.clock,
+            ids: deps.ids,
+            authorize: alwaysAllowBoot,
+            principals: deps.principals,
+        },
     };
     for (const def of input.definitions) {
-        const existing = await resolveDefinitionRaw({ repo: deps.settingsRepo }, { namespace: input.namespace, key: def.key, workspaceId });
-        if (existing) {
-            // Core registration is once-only, but the DEFAULT is not. Without this, a
-            // `defaultValue` changed in source is unreachable in any install that
-            // has already booted — the stored `default_json` from first boot keeps
-            // winning, for every settings-dialog tab. See `reconcileDefinitionDefault`
-            // for the bug this closes.
-            //
-            // Three slots are deliberately left alone rather than reconciled:
-            // a non-`active` row (deprecated/tombstoned) is not ours to rewrite; a
-            // non-`core` row is operator-owned; and a row whose identity differs
-            // from the slot we asked for means `resolveDefinitionRaw` followed an
-            // alias, so rewriting it would silently change a DIFFERENT definition's
-            // default. `reconcileDefinitionDefault` would throw on the first two —
-            // this skips them quietly because boot must not fail on them.
-            const isSameSlot = existing.namespace === input.namespace && existing.key === def.key;
-            if (ownerKind === "core" && existing.status === "active" && existing.ownerKind === "core" && isSameSlot) {
-                await reconcileDefinitionDefault({
-                    deps: writeDeps,
-                    input: {
-                        namespace: input.namespace,
-                        key: def.key,
-                        workspaceId: null,
-                        defaultValue: def.defaultValue,
-                        callerPrincipalId: input.systemPrincipalId,
-                        authWorkspaceId,
-                    },
-                });
-            }
-            continue;
+        const existing = await resolveDefinitionRaw({ repo: deps.settingsRepo }, { namespace: target.namespace, key: def.key, workspaceId });
+        if (!existing)
+            await registerMissingDefinition(target, def);
+        // Core registration is once-only, but the DEFAULT is not. Without this, a
+        // `defaultValue` changed in source is unreachable in any install that
+        // has already booted — the stored `default_json` from first boot keeps
+        // winning, for every settings-dialog tab. See `reconcileDefinitionDefault`
+        // for the bug this closes.
+        else if (isReconcilableCoreSlot(existing, { ownerKind: target.ownerKind, namespace: target.namespace, key: def.key })) {
+            await reconcileExistingCoreDefinition(target, def);
         }
-        await registerDefinitions({
-            deps: writeDeps,
-            input: {
-                callerPrincipalId: input.systemPrincipalId,
-                // Platform (core) definitions aren't scoped to any one workspace, but
-                // `registerDefinitions`'s authorization check still needs a workspace
-                // context to authorize against — the seeded workspace mirrors every
-                // other boot-time registrar's identical `authWorkspaceId` shape.
-                authWorkspaceId,
-                definitions: [
-                    {
-                        namespace: input.namespace,
-                        key: def.key,
-                        ownerKind,
-                        workspaceId,
-                        schema: def.schema,
-                        defaultValue: def.defaultValue,
-                        scopes: def.scopes ?? SCOPE_BIT.workspace,
-                        secret: false,
-                    },
-                ],
-            },
-        });
     }
 }
+/**
+ * Three slots are deliberately left alone rather than reconciled:
+ * a non-`active` row (deprecated/tombstoned) is not ours to rewrite; a
+ * non-`core` row is operator-owned; and a row whose identity differs
+ * from the slot we asked for means `resolveDefinitionRaw` followed an
+ * alias, so rewriting it would silently change a DIFFERENT definition's
+ * default. `reconcileDefinitionDefault` would throw on the first two —
+ * this skips them quietly because boot must not fail on them. A site
+ * target never reconciles: its stored default belongs to the site.
+ */
+function isReconcilableCoreSlot(existing, slot) {
+    const isSameSlot = existing.namespace === slot.namespace && existing.key === slot.key;
+    return slot.ownerKind === "core" && existing.status === "active" && existing.ownerKind === "core" && isSameSlot;
+}
+async function reconcileExistingCoreDefinition(target, def) {
+    const slot = {
+        namespace: target.namespace,
+        key: def.key,
+        workspaceId: null,
+        callerPrincipalId: target.systemPrincipalId,
+        authWorkspaceId: target.authWorkspaceId,
+    };
+    // Existing installations need newly declared personal layers too, not just fresh boots.
+    if (def.scopes !== undefined) {
+        await extendDefinitionScopes({ deps: target.writeDeps, input: { ...slot, scopes: def.scopes } });
+    }
+    await reconcileDefinitionDefault({ deps: target.writeDeps, input: { ...slot, defaultValue: def.defaultValue } });
+}
+async function registerMissingDefinition(target, def) {
+    await registerDefinitions({
+        deps: target.writeDeps,
+        input: {
+            callerPrincipalId: target.systemPrincipalId,
+            // Platform (core) definitions aren't scoped to any one workspace, but
+            // `registerDefinitions`'s authorization check still needs a workspace
+            // context to authorize against — the seeded workspace mirrors every
+            // other boot-time registrar's identical `authWorkspaceId` shape.
+            authWorkspaceId: target.authWorkspaceId,
+            definitions: [
+                {
+                    namespace: target.namespace,
+                    key: def.key,
+                    ownerKind: target.ownerKind,
+                    workspaceId: target.workspaceId,
+                    schema: def.schema,
+                    defaultValue: def.defaultValue,
+                    scopes: def.scopes ?? SCOPE_BIT.workspace,
+                    secret: false,
+                },
+            ],
+        },
+    });
+}
 //# sourceMappingURL=ensure-definitions.js.map

package/dist/settings/errors.d.ts

@@ -18,6 +18,19 @@ export declare class SecretNotSupportedError extends Error {
 }
 export declare class ValueValidationFailedError extends Error {
 }
+/**
+ * A scoped value changed since the caller's snapshot; read again before retrying.
+ * Both sequences refer to the addressed value row, never the ledger's global watermark.
+ * @example if (error instanceof SettingsRevisionConflictError) await refreshSnapshot();
+ */
+export declare class SettingsRevisionConflictError extends Error {
+    readonly expectedRevisionSeq: number;
+    readonly actualRevisionSeq: number;
+    constructor(required: {
+        expectedRevisionSeq: number;
+        actualRevisionSeq: number;
+    }, optional?: ErrorOptions);
+}
 export declare class RenameRetypeConflictError extends Error {
 }
 export declare class AliasDepthExceededError extends Error {

package/dist/settings/errors.js

@@ -18,6 +18,21 @@ export class SecretNotSupportedError extends Error {
 }
 export class ValueValidationFailedError extends Error {
 }
+/**
+ * A scoped value changed since the caller's snapshot; read again before retrying.
+ * Both sequences refer to the addressed value row, never the ledger's global watermark.
+ * @example if (error instanceof SettingsRevisionConflictError) await refreshSnapshot();
+ */
+export class SettingsRevisionConflictError extends Error {
+    expectedRevisionSeq;
+    actualRevisionSeq;
+    constructor(required, optional = {}) {
+        super(`Setting revision changed: expected ${required.expectedRevisionSeq}, found ${required.actualRevisionSeq}.`, optional);
+        this.name = "SettingsRevisionConflictError";
+        this.expectedRevisionSeq = required.expectedRevisionSeq;
+        this.actualRevisionSeq = required.actualRevisionSeq;
+    }
+}
 export class RenameRetypeConflictError extends Error {
 }
 export class AliasDepthExceededError extends Error {

package/dist/settings/express/cms-adapter.d.ts

@@ -1,7 +1,7 @@
 import { type SettingsWriteServiceDeps, type SettingsRepoPort } from "../index.js";
 import type { SettingsService, SettingsPermissions, SettingsChangeFeed } from "./contracts.js";
-/** Keep the CMS write chokepoint while translating its permission vocabulary to host policy. */
-/** Bind the CMS ledger and write chokepoint without copying their domain logic.
+/** Keep the CMS write chokepoint while translating its permission vocabulary to host policy.
+ * Bind the CMS ledger and write chokepoint without copying their domain logic.
  * Effective reads scan definitions and resolve each namespace key; mutations inherit CMS transactions/errors.
  * @complexity O(1) setup. Per operation: O(definitions + keys) reads, or O(batch size) writes.
  * @example createCmsSettingsService({ deps: cmsPorts, permissions });

package/dist/settings/express/cms-adapter.js

@@ -1,6 +1,6 @@
 import { getEffective, resolveDefinition, set, clear, resetNamespace, registerDefinitions, NON_REGISTER_DEFINITION_OPS, parseNonRegisterDefinitionOp, collectChangedNamespaces, } from "../index.js";
-/** Keep the CMS write chokepoint while translating its permission vocabulary to host policy. */
-/** Bind the CMS ledger and write chokepoint without copying their domain logic.
+/** Keep the CMS write chokepoint while translating its permission vocabulary to host policy.
+ * Bind the CMS ledger and write chokepoint without copying their domain logic.
  * Effective reads scan definitions and resolve each namespace key; mutations inherit CMS transactions/errors.
  * @complexity O(1) setup. Per operation: O(definitions + keys) reads, or O(batch size) writes.
  * @example createCmsSettingsService({ deps: cmsPorts, permissions });
@@ -76,35 +76,47 @@ async function applyDefinitions(required) {
     const toRegister = [];
     const applied = [];
     for (const raw of items) {
-        const item = raw;
-        const op = String(item.op ?? "register");
-        const namespace = String(item.namespace ?? "");
-        const key = String(item.key ?? "");
-        const ownerKind = item.ownerKind;
-        const workspaceId = ownerKind === "site" ? authWorkspaceId : null;
-        const defaultValue = (item.defaultJson ?? null);
-        if (op === "register") {
-            toRegister.push({ namespace, key, ownerKind, workspaceId, schema: item.schemaJson,
-                defaultValue, scopes: Number(item.scopes), secret: Boolean(item.secret ?? false) });
+        const item = parseDefinitionItem(raw, { authWorkspaceId });
+        if (item.op === "register") {
+            toRegister.push(toRegisterInput(item));
         }
         else {
-            const parsedOp = parseNonRegisterDefinitionOp({ op });
+            const parsedOp = parseNonRegisterDefinitionOp({ op: item.op });
             if (!parsedOp)
-                return { unknownOp: op };
-            const opItem = { namespace, key, ownerKind, workspaceId, defaultJson: defaultValue,
-                ...(item.newNamespace === undefined ? {} : { newNamespace: item.newNamespace }),
-                ...(item.newKey === undefined ? {} : { newKey: item.newKey }),
-                ...(item.schemaJson === undefined ? {} : { schemaJson: item.schemaJson }),
-                ...(item.coercionJson === undefined ? {} : { coercionJson: item.coercionJson }),
-            };
-            await NON_REGISTER_DEFINITION_OPS[parsedOp]({ ctx: { deps, callerPrincipalId, authWorkspaceId }, item: opItem });
+                return { unknownOp: item.op };
+            await NON_REGISTER_DEFINITION_OPS[parsedOp]({ ctx: { deps, callerPrincipalId, authWorkspaceId }, item: toOpItem(item) });
         }
-        applied.push({ key: `${namespace}.${key}`, op, status: "applied" });
+        applied.push({ key: `${item.namespace}.${item.key}`, op: item.op, status: "applied" });
     }
     if (toRegister.length)
         await registerDefinitions({ deps, input: { definitions: toRegister, callerPrincipalId, authWorkspaceId } });
     return { applied };
 }
+/** Site definitions live in the caller's workspace; every other owner is platform-wide. Pure, O(1). */
+function parseDefinitionItem(raw, context) {
+    const ownerKind = raw.ownerKind;
+    return {
+        op: String(raw.op ?? "register"),
+        namespace: String(raw.namespace ?? ""),
+        key: String(raw.key ?? ""),
+        ownerKind,
+        workspaceId: ownerKind === "site" ? context.authWorkspaceId : null,
+        defaultValue: (raw.defaultJson ?? null),
+        raw,
+    };
+}
+function toRegisterInput(item) {
+    const { namespace, key, ownerKind, workspaceId, defaultValue, raw } = item;
+    return { namespace, key, ownerKind, workspaceId, schema: raw.schemaJson,
+        defaultValue, scopes: Number(raw.scopes), secret: Boolean(raw.secret ?? false) };
+}
+/** Op-specific fields are forwarded only when present, so CMS defaults still apply to omitted ones. */
+const OPTIONAL_OP_FIELDS = ["newNamespace", "newKey", "schemaJson", "coercionJson"];
+function toOpItem(item) {
+    const { namespace, key, ownerKind, workspaceId, defaultValue, raw } = item;
+    const present = OPTIONAL_OP_FIELDS.filter((field) => raw[field] !== undefined).map((field) => [field, raw[field]]);
+    return { namespace, key, ownerKind, workspaceId, defaultJson: defaultValue, ...Object.fromEntries(present) };
+}
 /** Adapt the ledger through CMS tenant/principal disclosure rules, returning names and cursors only.
  * @complexity O(1) setup; collect is O(page size), with namespace lookup per visible revision.
  * @example createCmsSettingsChangeFeed({ repo });

package/dist/settings/express/http-request.d.ts

@@ -0,0 +1,33 @@
+import type { Request, Response } from "express";
+import type { SettingScope } from "../index.js";
+import type { SettingsHttpOptions, SettingsHttpRequired } from "./contracts.js";
+import { type SettingsErrorMapping } from "./shared.js";
+/**
+ * @file Request-level steps of the settings HTTP registrar (`http.ts`): the
+ * authentication gate, the failure envelope and value-write body parsing.
+ * Pure or response-only; no service, authorization or storage effects.
+ */
+export declare const SETTING_SCOPES: readonly string[];
+export declare function unauthenticated(res: Response): void;
+/** Readiness/principal failures preserve the authentication boundary's existing 401 envelope, so both collapse to null. */
+export declare function resolvePrincipal(required: Pick<SettingsHttpRequired, "ready" | "principalResolver">, context: {
+    request: Request;
+    response: Response;
+}): Promise<{
+    id: string;
+} | null>;
+/** Map a handler failure to its envelope, or end a response whose headers have already been sent. */
+export declare function failRequest(required: {
+    response: Response;
+    error: unknown;
+    mappings: readonly SettingsErrorMapping[];
+}, optional: SettingsHttpOptions): void;
+export type ValueMutationOperation = "set" | "clear";
+export declare const VALUE_MUTATION_REQUIRED: Record<ValueMutationOperation, string>;
+/** The fields a value write needs, or null when one is missing or the scope is unknown. Pure, O(1). */
+export declare function readValueMutation(body: Record<string, unknown>, operation: ValueMutationOperation): {
+    namespace: string;
+    key: string;
+    scope: SettingScope;
+} | null;
+//# sourceMappingURL=http-request.d.ts.map