@jini-ai/core 0.4.7 → 0.4.9

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/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

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/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