@jini-ai/core 0.4.8 → 0.6.10

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

@@ -0,0 +1,49 @@
+import { respondToSettingsError } 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 const SETTING_SCOPES = ["global", "workspace", "user"];
+export function unauthenticated(res) {
+    res.status(401).json({ error: "unauthenticated", code: "UNAUTHENTICATED" });
+}
+/** Readiness/principal failures preserve the authentication boundary's existing 401 envelope, so both collapse to null. */
+export async function resolvePrincipal(required, context) {
+    try {
+        await required.ready;
+        return await required.principalResolver(context);
+    }
+    catch {
+        return null;
+    }
+}
+/** Map a handler failure to its envelope, or end a response whose headers have already been sent. */
+export function failRequest(required, optional) {
+    const { response, error, mappings } = required;
+    if (!response.headersSent) {
+        respondToSettingsError({ response, error, mappings });
+        return;
+    }
+    // Reporting cannot prevent ending a response whose headers have already been sent.
+    try {
+        optional.onError?.({ operation: "settings-request", error });
+    }
+    catch { /* Host diagnostics are best-effort. */ }
+    finally {
+        response.end();
+    }
+}
+export const VALUE_MUTATION_REQUIRED = {
+    set: "namespace, key, scope (global|workspace|user), and valueJson are required",
+    clear: "namespace, key, and scope (global|workspace|user) are required",
+};
+/** The fields a value write needs, or null when one is missing or the scope is unknown. Pure, O(1). */
+export function readValueMutation(body, operation) {
+    const namespace = String(body.namespace ?? "");
+    const key = String(body.key ?? "");
+    const scope = body.scope;
+    const complete = namespace && key && SETTING_SCOPES.includes(scope) && (operation === "clear" || "valueJson" in body);
+    return complete ? { namespace, key, scope } : null;
+}
+//# sourceMappingURL=http-request.js.map

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

@@ -1,6 +1,6 @@
 import type { SettingsHttpRequired, SettingsHttpOptions } from "./contracts.js";
-/** Mount all eight endpoints. The returned disposer closes active feeds and cancels their schedules. */
-/** Injected policy and services preserve the settings HTTP response envelopes.
+/** Mount all eight endpoints. The returned disposer closes active feeds and cancels their schedules.
+ * Injected policy and services preserve the settings HTTP response envelopes.
  * O(1) mounting; read/mutation work is delegated. Feed resources are bounded per connection.
  * @example registerSettingsRoutes({ app, workspaceId, ready, service, changeFeed, principalResolver, authorize, scheduler, routes, permissions });
  */

package/dist/settings/express/http.js

@@ -1,6 +1,7 @@
 import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, } from "../index.js";
-import { respondToSettingsError, resolveTargetWorkspaceId, resolveUserLayerReadTarget, settingsWritePermission } from "./shared.js";
+import { resolveTargetWorkspaceId, resolveUserLayerReadTarget, settingsWritePermission } from "./shared.js";
 import { openSettingsChangeStream } from "./stream.js";
+import { failRequest, readValueMutation, resolvePrincipal, SETTING_SCOPES, unauthenticated, VALUE_MUTATION_REQUIRED } from "./http-request.js";
 const VALUE_ERRORS = [
     { matches: (e) => e instanceof PrincipalNotFoundError, status: 404, code: "PRINCIPAL_NOT_FOUND" },
     { matches: (e) => e instanceof DefinitionNotFoundError, status: 404, code: "DEFINITION_NOT_FOUND" },
@@ -18,7 +19,6 @@ const DEFINITION_ERRORS = [
     { matches: (e) => e instanceof ForbiddenError, status: 403, code: "FORBIDDEN" },
 ];
 const RESET_ERRORS = VALUE_ERRORS.filter((m) => m.code === "FORBIDDEN");
-const scopes = ["global", "workspace", "user"];
 function validation(res, error) {
     res.status(400).json({ error, code: "VALIDATION_ERROR" });
 }
@@ -29,8 +29,8 @@ function denied(res, principalId, permission, reason) {
 function bodyOf(req) {
     return req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
 }
-/** Mount all eight endpoints. The returned disposer closes active feeds and cancels their schedules. */
-/** Injected policy and services preserve the settings HTTP response envelopes.
+/** Mount all eight endpoints. The returned disposer closes active feeds and cancels their schedules.
+ * Injected policy and services preserve the settings HTTP response envelopes.
  * O(1) mounting; read/mutation work is delegated. Feed resources are bounded per connection.
  * @example registerSettingsRoutes({ app, workspaceId, ready, service, changeFeed, principalResolver, authorize, scheduler, routes, permissions });
  */
@@ -47,36 +47,16 @@ export function registerSettingsRoutes(required, optional = {}) {
             res.status(404).json({ error: "workspace was not found" });
             return;
         }
-        let principal;
-        try {
-            await required.ready;
-            principal = await required.principalResolver({ request: req, response: res });
-        }
-        catch {
-            // Readiness/principal failures preserve the authentication boundary's existing 401 envelope.
-            res.status(401).json({ error: "unauthenticated", code: "UNAUTHENTICATED" });
-            return;
-        }
+        const principal = await resolvePrincipal(required, { request: req, response: res });
         if (!principal) {
-            res.status(401).json({ error: "unauthenticated", code: "UNAUTHENTICATED" });
+            unauthenticated(res);
             return;
         }
         try {
             await handler(req, res, principal.id);
         }
         catch (error) {
-            if (res.headersSent) {
-                // Reporting cannot prevent ending a response whose headers have already been sent.
-                try {
-                    optional.onError?.({ operation: "settings-request", error });
-                }
-                catch { /* Host diagnostics are best-effort. */ }
-                finally {
-                    res.end();
-                }
-            }
-            else
-                respondToSettingsError({ response: res, error, mappings });
+            failRequest({ response: res, error, mappings }, optional);
         }
     };
     const check = async (res, principalId, permission, entityType) => {
@@ -152,13 +132,12 @@ export function registerSettingsRoutes(required, optional = {}) {
     }, DEFINITION_ERRORS));
     const mutate = (operation) => async (req, res, callerPrincipalId) => {
         const body = bodyOf(req);
-        const namespace = String(body.namespace ?? "");
-        const key = String(body.key ?? "");
-        const scope = body.scope;
-        if (!namespace || !key || !scopes.includes(scope) || (operation === "set" && !("valueJson" in body))) {
-            validation(res, operation === "set" ? "namespace, key, scope (global|workspace|user), and valueJson are required" : "namespace, key, and scope (global|workspace|user) are required");
+        const fields = readValueMutation(body, operation);
+        if (!fields) {
+            validation(res, VALUE_MUTATION_REQUIRED[operation]);
             return;
         }
+        const { namespace, key, scope } = fields;
         const target = resolveTargetWorkspaceId({ workspaceId, input: { bodyWorkspaceId: body.workspaceId, scope } });
         if (!target.ok) {
             validation(res, target.error);
@@ -178,7 +157,7 @@ export function registerSettingsRoutes(required, optional = {}) {
         const body = bodyOf(req);
         const namespace = String(body.namespace ?? "");
         const scope = body.scope;
-        if (!namespace || !scopes.includes(scope)) {
+        if (!namespace || !SETTING_SCOPES.includes(scope)) {
             validation(res, "namespace and scope (global|workspace|user) are required");
             return;
         }
@@ -198,12 +177,10 @@ export function registerSettingsRoutes(required, optional = {}) {
         const close = await openSettingsChangeStream({ request: req, response: res, workspaceId, principalId,
             changeFeed: required.changeFeed, authorize: required.authorize, permission: permissions.read, scheduler: required.scheduler,
             onClose: ({ close }) => { streams.delete(close); }, isDisposed: () => disposed }, optional);
-        if (close) {
-            if (disposed)
-                close();
-            else if (!res.destroyed && !res.writableEnded)
-                streams.add(close);
-        }
+        if (disposed)
+            close();
+        else if (!res.destroyed && !res.writableEnded)
+            streams.add(close);
     }));
     return { dispose: () => { disposed = true; for (const close of streams)
             close(); streams.clear(); } };

package/dist/settings/express/stream.d.ts

@@ -14,8 +14,8 @@ interface StreamRequired {
     }) => void;
     isDisposed: () => boolean;
 }
-/** Starts after HTTP authorization. All scheduling and storage are injected. */
-/** Poll with bounded pages, tenant-scoped ids and retryable reads; close cancels all schedules.
+/** Starts after HTTP authorization. All scheduling and storage are injected.
+ * Poll with bounded pages, tenant-scoped ids and retryable reads; close cancels all schedules.
  * O(page size) per tick and O(1) connection state; repository effects live behind the feed port.
  * Invalid scheduler intervals/page sizes throw RangeError before opening; initial read errors propagate.
  */

package/dist/settings/express/stream.js

@@ -1,29 +1,16 @@
-/** Starts after HTTP authorization. All scheduling and storage are injected. */
-/** Poll with bounded pages, tenant-scoped ids and retryable reads; close cancels all schedules.
+/** Starts after HTTP authorization. All scheduling and storage are injected.
+ * Poll with bounded pages, tenant-scoped ids and retryable reads; close cancels all schedules.
  * O(page size) per tick and O(1) connection state; repository effects live behind the feed port.
  * Invalid scheduler intervals/page sizes throw RangeError before opening; initial read errors propagate.
  */
 export async function openSettingsChangeStream(required, optional = {}) {
     const { request, response, workspaceId, principalId, changeFeed, scheduler } = required;
-    const pageSize = optional.revisionPageSize ?? 200;
-    const intervals = [optional.pollIntervalMs ?? 1_000, optional.keepaliveIntervalMs ?? 25_000, optional.reauthorizeIntervalMs ?? 30_000];
-    if (!Number.isSafeInteger(pageSize) || pageSize <= 0 || intervals.some((n) => !Number.isFinite(n) || n <= 0)) {
-        throw new RangeError("settings feed page size and intervals must be positive");
-    }
+    const { pageSize, pollIntervalMs, keepaliveIntervalMs, reauthorizeIntervalMs } = readStreamTimings(optional);
     let closed = false;
     let ticking = false;
     let checkingAuthorization = false;
     const cancellations = [];
-    const reportError = (operation, error) => {
-        // Reporting is best-effort: a host hook must never turn recovery into an unhandled rejection.
-        try {
-            if (optional.onError)
-                optional.onError({ operation, error });
-            else
-                console.error(`[settings] change feed ${operation} failed`, error);
-        }
-        catch { /* Diagnostic failures cannot interrupt stream cleanup or retries. */ }
-    };
+    const reportError = createErrorReporter(optional);
     const recover = (operation, effect) => {
         try {
             effect();
@@ -52,18 +39,15 @@ export async function openSettingsChangeStream(required, optional = {}) {
     response.on("close", close);
     try {
         const head = await changeFeed.head({});
-        if (closed || required.isDisposed() || response.destroyed || response.writableEnded) {
+        const gone = () => closed || required.isDisposed() || response.destroyed || response.writableEnded;
+        if (gone()) {
             close();
             return close;
         }
-        const resumeFrom = Number(request.headers["last-event-id"]);
-        let cursor = Number.isFinite(resumeFrom) && resumeFrom >= 0 ? Math.min(resumeFrom, head) : head;
+        let cursor = resumeCursor({ lastEventId: request.headers["last-event-id"], head });
         let lastEmittedId = cursor;
         const viewer = { workspaceId, principalId };
-        response.writeHead(200, {
-            "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform",
-            ...(request.httpVersionMajor < 2 ? { Connection: "keep-alive" } : {}), "X-Accel-Buffering": "no",
-        });
+        response.writeHead(200, sseHeaders({ httpVersionMajor: request.httpVersionMajor }));
         const tick = async () => {
             if (closed || ticking)
                 return;
@@ -116,8 +100,8 @@ export async function openSettingsChangeStream(required, optional = {}) {
             else
                 cancellations.push(cancel);
         };
-        schedule(intervals[0], () => { void tick(); });
-        schedule(intervals[1], () => {
+        schedule(pollIntervalMs, () => { void tick(); });
+        schedule(keepaliveIntervalMs, () => {
             if (closed)
                 return;
             try {
@@ -128,7 +112,7 @@ export async function openSettingsChangeStream(required, optional = {}) {
                 close();
             }
         });
-        schedule(intervals[2], () => { void reauthorize(); });
+        schedule(reauthorizeIntervalMs, () => { void reauthorize(); });
         if (!closed)
             response.write(": connected\n\n");
         return close;
@@ -144,4 +128,42 @@ export async function openSettingsChangeStream(required, optional = {}) {
         throw error;
     }
 }
+/** Fill the documented defaults, then refuse any non-positive page size or interval before an effect. Pure. */
+function readStreamTimings(optional) {
+    const timings = {
+        pageSize: optional.revisionPageSize ?? 200,
+        pollIntervalMs: optional.pollIntervalMs ?? 1_000,
+        keepaliveIntervalMs: optional.keepaliveIntervalMs ?? 25_000,
+        reauthorizeIntervalMs: optional.reauthorizeIntervalMs ?? 30_000,
+    };
+    const intervals = [timings.pollIntervalMs, timings.keepaliveIntervalMs, timings.reauthorizeIntervalMs];
+    if (!Number.isSafeInteger(timings.pageSize) || timings.pageSize <= 0 || intervals.some((n) => !Number.isFinite(n) || n <= 0)) {
+        throw new RangeError("settings feed page size and intervals must be positive");
+    }
+    return timings;
+}
+function createErrorReporter(optional) {
+    return (operation, error) => {
+        // Reporting is best-effort: a host hook must never turn recovery into an unhandled rejection.
+        try {
+            if (optional.onError)
+                optional.onError({ operation, error });
+            else
+                console.error(`[settings] change feed ${operation} failed`, error);
+        }
+        catch { /* Diagnostic failures cannot interrupt stream cleanup or retries. */ }
+    };
+}
+/** A client's Last-Event-ID resumes at or before the ledger head; a missing or unusable id starts at head. Pure. */
+function resumeCursor(required) {
+    const resumeFrom = Number(required.lastEventId);
+    return Number.isFinite(resumeFrom) && resumeFrom >= 0 ? Math.min(resumeFrom, required.head) : required.head;
+}
+/** HTTP/2 forbids the Connection header; HTTP/1 needs it to keep the stream open. Pure. */
+function sseHeaders(required) {
+    return {
+        "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform",
+        ...(required.httpVersionMajor < 2 ? { Connection: "keep-alive" } : {}), "X-Accel-Buffering": "no",
+    };
+}
 //# sourceMappingURL=stream.js.map

package/dist/settings/index.d.ts

@@ -11,11 +11,11 @@
  * `SettingsRepoPort` this barrel exports.
  */
 export { SCOPE_BIT, type SettingScope, type SettingOwnerKind, type DefinitionStatus, type ValueState, type RevisionEntityKind, type RevisionOp, type SettingValueSchema, type SettingDefinitionRecord, type SettingValueRecord, type SettingRevisionRecord, type SettingScopeContext, } from "./types.js";
-export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
+export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, SettingsRevisionConflictError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
 export type { SettingsRepoPort } from "./ports.js";
 export { InMemorySettingsRepo } from "./repo.memory.js";
 export { type DefinitionInput, validateDefinitionInput, validateValueAgainstSchema, registerCoercer, invalidateDefinitionNamespaceCache, invalidateWorkspaceSettingsCache, resolveDefinitionRaw, resolveDefinition, type ResolvedSetting, getEffective, } from "./settings.js";
-export { type AuthorizeFn, type SettingsWriteServiceDeps, deriveRequiredPermission, type RegisterDefinitionsRequired, registerDefinitions, type SetValueRequired, set, type ClearValueRequired, clear, type ResetNamespaceRequired, resetNamespace, type RenameDefinitionRequired, renameDefinition, type RetypeDefinitionRequired, retypeDefinition, type ReconcileDefinitionDefaultRequired, reconcileDefinitionDefault, type DeprecateDefinitionRequired, deprecateDefinition, type TombstoneDefinitionRequired, tombstoneDefinition, } from "./write-service.js";
+export { type AuthorizeFn, type SettingsWriteServiceDeps, deriveRequiredPermission, type RegisterDefinitionsRequired, registerDefinitions, type SetValueRequired, type SettingsValueWriteOptions, set, type ClearValueRequired, clear, type ResetNamespaceRequired, resetNamespace, type RenameDefinitionRequired, renameDefinition, type RetypeDefinitionRequired, retypeDefinition, type ReconcileDefinitionDefaultRequired, reconcileDefinitionDefault, type DeprecateDefinitionRequired, deprecateDefinition, type TombstoneDefinitionRequired, tombstoneDefinition, } from "./write-service.js";
 export { type PurgeServiceDeps, type PurgeTenantSettingsRequired, purgeTenantSettings, } from "./purge-service.js";
 export { type ChangeFeedViewer, isRevisionVisibleTo, type ChangeFeedBatch, collectChangedNamespaces, } from "./change-feed.js";
 export { type DefinitionOpRequestItem, type DefinitionOpContext, type DefinitionOpHandler, NON_REGISTER_DEFINITION_OP_NAMES, type NonRegisterDefinitionOp, parseNonRegisterDefinitionOp, NON_REGISTER_DEFINITION_OPS, } from "./definitions-dispatch.js";

package/dist/settings/index.js

@@ -11,7 +11,7 @@
  * `SettingsRepoPort` this barrel exports.
  */
 export { SCOPE_BIT, } from "./types.js";
-export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
+export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, SettingsRevisionConflictError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
 export { InMemorySettingsRepo } from "./repo.memory.js";
 export { validateDefinitionInput, validateValueAgainstSchema, registerCoercer, invalidateDefinitionNamespaceCache, invalidateWorkspaceSettingsCache, resolveDefinitionRaw, resolveDefinition, getEffective, } from "./settings.js";
 export { deriveRequiredPermission, registerDefinitions, set, clear, resetNamespace, renameDefinition, retypeDefinition, reconcileDefinitionDefault, deprecateDefinition, tombstoneDefinition, } from "./write-service.js";

package/dist/settings/ports.d.ts

@@ -68,7 +68,13 @@ export interface SettingsRepoPort {
         principalId: UUID;
         settingId: UUID;
     }): Promise<void>;
-    /** Appends a revision and returns its assigned `seq` (used to stamp the paired value row). */
+    /**
+     * Appends a revision and returns its assigned `seq` (used to stamp the paired value row).
+     * Inside a transaction, serialize revision writers until that enclosing transaction ends:
+     * `set`/`clear` compare the stored value's seq AFTER this call, so the lock must cover the
+     * comparison and value save too. SQLite's write transaction and Postgres's transaction-scoped
+     * ledger lock provide this; memory refuses overlapping transactions.
+     */
     appendRevision(record: Omit<SettingRevisionRecord, "seq">): Promise<number>;
     listRevisions(required: {
         settingId: UUID;

package/dist/settings/repo.memory.js

@@ -179,8 +179,11 @@ export class InMemorySettingsRepo {
             nextSeq: this.nextSeq,
         };
         this.inTransaction = true;
+        // No `finally`: the flag is released on both exits explicitly (V8 coverage counts the
+        // unreachable continuation after a catch-block `throw` inside try/finally as a missed branch).
+        let result;
         try {
-            return await fn();
+            result = await fn();
         }
         catch (error) {
             this.definitions = snapshot.definitions;
@@ -189,11 +192,11 @@ export class InMemorySettingsRepo {
             this.userValues = snapshot.userValues;
             this.revisions = snapshot.revisions;
             this.nextSeq = snapshot.nextSeq;
-            throw error;
-        }
-        finally {
             this.inTransaction = false;
+            throw error;
         }
+        this.inTransaction = false;
+        return result;
     }
 }
 //# sourceMappingURL=repo.memory.js.map

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";