@jini-ai/cms 0.3.11 → 0.4.0

package/dist/settings/tool-registrations.js

@@ -1,10 +1,15 @@
-import { buildDomainRegistrations, indexCatalogById, optionalString, requireInputRecord, requireNoInput, requireString, requireToolPermission, withSchemaOnRejection, } from "../core/tools/registration-kit.js";
+import { adaptLegacyAuthorize } from "../core/tools/index.js";
+import { buildSettingsValueWriteHandler } from "./agent-value-write-tools.js";
+import { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule } from "./agent-write-denylist.js";
+import { buildDomainRegistrations, indexCatalogById, optionalString, requireInputRecord, requireNoInput, requireString, withSchemaOnRejection } from "@jini-ai/core";
+import { requireToolPermission } from "../core/tools/index.js";
 import { getSettingsAgentToolCatalog } from "./agent-tools.js";
 import { AGENT_PREFERENCE_WRITE_SCOPE, AGENT_WRITABLE_PREFERENCE_IDS, resolveAgentWritablePreference, } from "./agent-writable-preferences.js";
 import { DefinitionNotFoundError, DefinitionTombstonedError, ScopeNotAllowedError, ValueValidationFailedError, } from "./errors.js";
-import { getEffective, resolveDefinition } from "./settings.js";
+import { getEffective, resolveDefinition, resolveDefinitionRaw } from "./settings.js";
+import { SCOPE_BIT } from "./types.js";
 import { set as setSettingValue } from "./write-service.js";
-const CATALOG_BY_ID = indexCatalogById(getSettingsAgentToolCatalog());
+const CATALOG_BY_ID = indexCatalogById({ catalog: getSettingsAgentToolCatalog() });
 /** Permission gating a read that names a DIFFERENT principal than the caller — mirrors a host's
  * own HTTP admin layer's equivalent constant (kept as a literal here per this file's header; the
  * two are data, not logic, so duplication carries no drift risk beyond a string comparison). */
@@ -31,11 +36,7 @@ async function resolveOwnOrOtherPrincipalRead(routeDeps, required) {
     const target = requestedPrincipalId ?? callerPrincipalId;
     if (target === callerPrincipalId)
         return target;
-    await requireToolPermission(routeDeps, {
-        principalId: callerPrincipalId,
-        permission: CROSS_PRINCIPAL_SETTINGS_READ_PERMISSION,
-        entityType: "setting-value",
-    });
+    await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: callerPrincipalId, permission: CROSS_PRINCIPAL_SETTINGS_READ_PERMISSION }, { entityType: "setting-value" });
     return requestedPrincipalId;
 }
 function layerValueOf(record) {
@@ -79,11 +80,15 @@ function isPreferenceShapeRejection(error) {
 /**
  * This wiring layer's OWN risk classification, authored from what each handler below actually
  * calls. See `DerivedRiskByToolId` in the kit for why it is independent of the catalog's own
- * `sideEffects` declaration — and note that the four excluded writes appear NOWHERE here, which is
+ * `sideEffects` declaration — and note that the two excluded bulk/schema writes appear NOWHERE here, which is
  * itself the strongest of the guards: an unclassified id cannot be wired at all.
  */
 export const settingsDerivedRisk = new Map([
-    // -> settingsRepo.listActiveDefinitions() x2 (platform + this workspace): reads only.
+    // -> write-service.set(): one value override and one revision, with optional human confirmation.
+    ["settings_set_value", "mutates-durable-state"],
+    // -> write-service.clear(): one override marked cleared and one revision; no definition/delete.
+    ["settings_clear_value", "mutates-durable-state"],
+    // -> settingsRepo.listActiveDefinitions() x2 + resolveDefinitionRaw() for aliases: reads only.
     ["settings_list_definitions", "none"],
     // -> settingsRepo.listActiveDefinitions() x2 + getEffective() per key: reads only, no write path.
     ["settings_get_effective", "none"],
@@ -97,11 +102,6 @@ export const settingsDerivedRisk = new Map([
 ]);
 /** Settings catalog entries this pass does not wire, and why — see `agent-tools.ts`'s own per-entry comments for the full reasoning. */
 const UNWIRED_SETTINGS_TOOL_IDS = new Set([
-    // EXCLUDED BY DESIGN: generic "set any setting key" — a typical human admin UI for this domain
-    // is itself an uncurated free-text/raw-JSON editor, not a fixed named list (see agent-tools.ts
-    // file header).
-    "settings_set",
-    "settings_clear",
     // EXCLUDED BY DESIGN: bulk variant — clears every value in an operator-named namespace at a
     // scope in one call, irreversible.
     "settings_reset",
@@ -112,27 +112,44 @@ const UNWIRED_SETTINGS_TOOL_IDS = new Set([
 ]);
 export function buildSettingsRegistrations(routeDeps) {
     const handlers = {
+        settings_set_value: buildSettingsValueWriteHandler(routeDeps, "settings_set_value"),
+        settings_clear_value: buildSettingsValueWriteHandler(routeDeps, "settings_clear_value"),
         settings_list_definitions: async (ctx) => {
-            requireNoInput(ctx.input);
+            requireNoInput({ input: ctx.input });
             await routeDeps.settingsReady;
-            await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "settings.read.definitions", entityType: "setting-definition" });
+            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "settings.read.definitions" }, { entityType: "setting-definition" });
             const [platformDefs, siteDefs] = await Promise.all([
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: null }),
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: routeDeps.workspaceId }),
             ]);
-            const data = [...platformDefs, ...siteDefs]
-                .map((def) => ({ namespace: def.namespace, key: def.key, ownerKind: def.ownerKind, scopes: def.scopes, status: def.status, version: def.version }))
+            const deniedRules = [...AGENT_WRITE_DENIED_SETTINGS, ...(routeDeps.extraDeniedSettings ?? [])];
+            const confirmationRules = [...AGENT_WRITE_CONFIRMATION_SETTINGS, ...(routeDeps.extraConfirmationSettings ?? [])];
+            // Only aliases need an extra lookup. Their target's schema/scope and BOTH coordinates'
+            // key policies must agree with the write handler; dangling/tombstoned targets fail closed.
+            const data = (await Promise.all([...platformDefs, ...siteDefs].map(async (def) => {
+                const resolved = def.status === "alias"
+                    ? await resolveDefinitionRaw({ repo: routeDeps.settingsRepo }, { namespace: def.namespace, key: def.key, workspaceId: routeDeps.workspaceId })
+                    : def;
+                const coordinates = resolved ? [def, resolved] : [def];
+                const denied = coordinates.some((coordinate) => !!findAgentWriteRule(deniedRules, coordinate));
+                const confirmationRequired = coordinates.some((coordinate) => !!findAgentWriteRule(confirmationRules, coordinate));
+                const scopes = resolved?.scopes ?? def.scopes;
+                return { namespace: def.namespace, key: def.key, ownerKind: def.ownerKind, scopes, status: def.status, version: def.version,
+                    schema: resolved?.schema ?? def.schema,
+                    agentWritable: !!resolved && resolved.status !== "tombstone" && !denied && (!confirmationRequired || !!routeDeps.confirmWrite) && (scopes & (SCOPE_BIT.workspace | SCOPE_BIT.user)) !== 0,
+                    confirmationRequired };
+            })))
                 .sort((a, b) => a.namespace.localeCompare(b.namespace) || a.key.localeCompare(b.key));
             return { data };
         },
         settings_get_effective: async (ctx) => {
-            const input = requireInputRecord(ctx.input);
-            const namespace = requireString(input, "namespace");
+            const input = requireInputRecord({ input: ctx.input });
+            const namespace = requireString({ input: input, key: "namespace" });
             await routeDeps.settingsReady;
-            await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "settings.read", entityType: "setting-value" });
+            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "settings.read" }, { entityType: "setting-value" });
             const workspaceId = routeDeps.workspaceId;
             const principalId = await resolveOwnOrOtherPrincipalRead(routeDeps, {
-                requestedPrincipalId: optionalString(input, "principalId"),
+                requestedPrincipalId: optionalString({ input: input, key: "principalId" }),
                 callerPrincipalId: ctx.principal.id,
             });
             const [platformDefs, siteDefs] = await Promise.all([
@@ -149,14 +166,14 @@ export function buildSettingsRegistrations(routeDeps) {
             return { data };
         },
         settings_get_raw: async (ctx) => {
-            const input = requireInputRecord(ctx.input);
-            const namespace = requireString(input, "namespace");
-            const key = requireString(input, "key");
+            const input = requireInputRecord({ input: ctx.input });
+            const namespace = requireString({ input: input, key: "namespace" });
+            const key = requireString({ input: input, key: "key" });
             await routeDeps.settingsReady;
-            await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "settings.read.raw", entityType: "setting-value" });
+            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "settings.read.raw" }, { entityType: "setting-value" });
             const workspaceId = routeDeps.workspaceId;
             const principalId = await resolveOwnOrOtherPrincipalRead(routeDeps, {
-                requestedPrincipalId: optionalString(input, "principalId"),
+                requestedPrincipalId: optionalString({ input: input, key: "principalId" }),
                 callerPrincipalId: ctx.principal.id,
             });
             const definition = await resolveDefinition({ repo: routeDeps.settingsRepo }, { namespace, key, workspaceId });
@@ -176,8 +193,8 @@ export function buildSettingsRegistrations(routeDeps) {
             };
         },
         settings_set_ui_preference: async (ctx) => {
-            const input = requireInputRecord(ctx.input);
-            const settingId = requireString(input, "setting");
+            const input = requireInputRecord({ input: ctx.input });
+            const settingId = requireString({ input: input, key: "setting" });
             // Re-checked here even though the published schema carries the same enum. See
             // `agent-writable-preferences.ts` on why: the enum is enforced by a caller's descriptor
             // validation, and this is the check that still holds if a stale or bypassed descriptor lets
@@ -201,40 +218,33 @@ export function buildSettingsRegistrations(routeDeps) {
             // No `requireToolPermission` call here, unlike every read above. That is deliberate and is
             // the opposite of the reads' situation: the read paths carry no `authorize()` of their own,
             // so this layer must supply it, whereas `write-service.set()` IS the authorization
-            // chokepoint (INV-07) and derives the permission itself from the scope and target. Adding a
+            // chokepoint and derives the permission itself from the scope and target. Adding a. See docs/decisions/DR-003-settings-ledger-invariants.md.
             // pre-check would mean this file naming a permission string that the chokepoint might later
             // derive differently — the exact fail-open drift `deriveRequiredPermission`'s own header
-            // (Red-Team RT-003) says must not be duplicated. Omitting `principalId` is what makes the
+            // (Red-Team ) says must not be duplicated. Omitting `principalId` is what makes the. See docs/decisions/DR-003-settings-ledger-invariants.md.
             // derived permission `settings.user.self.write`.
             const { value: stored, revisionSeq } = await withSchemaOnRejection({
                 toolId: "settings_set_ui_preference",
                 catalog: CATALOG_BY_ID,
-                isShapeRejection: isPreferenceShapeRejection,
-            }, () => setSettingValue({
-                deps: toWriteDeps(routeDeps),
-                input: {
-                    namespace: preference.namespace,
-                    key: preference.key,
-                    scope: AGENT_PREFERENCE_WRITE_SCOPE,
-                    value,
-                    workspaceId: routeDeps.workspaceId,
-                    // `principalId` is deliberately NOT passed. `write-service.set()` falls back to
-                    // `callerPrincipalId` for a user-scoped write, so the caller's own layer is the only
-                    // reachable target — and the self-vs-other permission derivation sees a self-write.
-                    callerPrincipalId: ctx.principal.id,
-                    authWorkspaceId: routeDeps.workspaceId,
-                },
-            }));
+                isShapeRejection: ({ error }) => isPreferenceShapeRejection(error), fn: () => setSettingValue({
+                    deps: toWriteDeps(routeDeps),
+                    input: {
+                        namespace: preference.namespace,
+                        key: preference.key,
+                        scope: AGENT_PREFERENCE_WRITE_SCOPE,
+                        value,
+                        workspaceId: routeDeps.workspaceId,
+                        // `principalId` is deliberately NOT passed. `write-service.set()` falls back to
+                        // `callerPrincipalId` for a user-scoped write, so the caller's own layer is the only
+                        // reachable target — and the self-vs-other permission derivation sees a self-write.
+                        callerPrincipalId: ctx.principal.id,
+                        authWorkspaceId: routeDeps.workspaceId,
+                    },
+                })
+            });
             return { setting: settingId, value: stored, scope: AGENT_PREFERENCE_WRITE_SCOPE, revisionSeq };
         },
     };
-    return buildDomainRegistrations({
-        domain: "settings",
-        catalogModule: "settings/agent-tools.ts",
-        catalog: CATALOG_BY_ID,
-        handlers,
-        derivedRisk: settingsDerivedRisk,
-        unwiredToolIds: UNWIRED_SETTINGS_TOOL_IDS,
-    });
+    return buildDomainRegistrations({ domain: "settings", catalogModule: "settings/agent-tools.ts", catalog: CATALOG_BY_ID, handlers, derivedRisk: settingsDerivedRisk }, { unwiredToolIds: UNWIRED_SETTINGS_TOOL_IDS });
 }
 //# sourceMappingURL=tool-registrations.js.map

package/dist/settings/types.d.ts

@@ -1,4 +1,4 @@
-import type { ISODateTime, JsonValue, UUID } from "../core/ports.js";
+import type { ISODateTime, JsonValue, UUID } from "@jini-ai/core/primitives";
 /**
  * @file Settings domain types.
  *

package/dist/settings/ui-tab-definitions.d.ts

@@ -1,4 +1,4 @@
-import type { UUID } from "../core/ports.js";
+import type { UUID } from "@jini-ai/core/primitives";
 import { type EnsureSettingDefinitionsDeps } from "./ensure-definitions.js";
 /**
  * @file Boot-time definition registration for the settings-dialog tabs that

package/dist/settings/write-service.d.ts

@@ -1,10 +1,10 @@
-import type { ClockPort, IdGeneratorPort, JsonValue, UUID } from "../core/ports.js";
-import type { PrincipalRepoPort } from "../identity/index.js";
+import type { Clock, IdGenerator, JsonValue, UUID } from "@jini-ai/core/primitives";
+import type { SettingsPrincipalLookupPort } from "./principal-lookup.js";
 import type { SettingsRepoPort } from "./ports.js";
 import { type DefinitionInput } from "./settings.js";
 import { type SettingScope, type SettingValueSchema } from "./types.js";
 /**
- * @file `SettingsWriteService` — the single write chokepoint (REQ-04).
+ * @file `SettingsWriteService` — the single write chokepoint.
  *
  * Purpose:
  * The ONLY value/definition-mutation path. Repo write methods
@@ -12,13 +12,14 @@ import { type SettingScope, type SettingValueSchema } from "./types.js";
  * be called from outside this file (Code Review enforces this as a file-
  * boundary check).
  *
- * Every export here: `authorize()` first (fail-closed, INV-07) -> validate ->
- * write value/definition row + revision in one transaction (INV-01).
+ * Every export here: `authorize` first (fail-closed) -> validate ->
+ * write value/definition row + revision in one transaction.
  *
  * `deriveRequiredPermission` is the sole source of truth for the self-vs-
- * other permission rule (behavior.spec.md §1.3) — closes Red-Team RT-003.
- * REQ-13's target-principal check reuses `identity.PrincipalRepoPort`
- * directly — no new port (closes RT-001/RT-002 at the implementation level).
+ * other permission rule (behavior.spec.md §1.3) — closes Red-Team.
+ * target-principal checks use a host-supplied active-principal lookup over core Principal;
+ * identity and membership policy remain at the host boundary.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 /** Matches `core/commands/command.ts`'s `AuthorizeFn` shape structurally — no import, kept decoupled. */
 export type AuthorizeFn = (params: {
@@ -33,22 +34,23 @@ export type AuthorizeFn = (params: {
 }>;
 export interface SettingsWriteServiceDeps {
     repo: SettingsRepoPort;
-    clock: ClockPort;
-    ids: IdGeneratorPort;
+    clock: Clock;
+    ids: IdGenerator;
     authorize: AuthorizeFn;
-    /** REQ-13 — reused directly from `identity`, not duplicated. */
-    principals: PrincipalRepoPort;
+    /** Host lookup must hide disabled and out-of-workspace principals. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+    principals: SettingsPrincipalLookupPort;
 }
 /**
- * behavior.spec.md §1.3 / REQ-06 `[internal-invariant]` — the self-vs-other
+ * behavior.spec.md §1.3 / `[internal-invariant]` — the self-vs-other
  * permission derivation. `targetPrincipalId` omitted or equal to the caller
  * -> `settings.user.self.write`; any other principal -> `settings.user.write`.
  * A divergence between this function and any other implementation of the
- * rule is a fail-open authorization bug (Red-Team RT-003) — this is the only
+ * rule is a fail-open authorization bug (Red-Team ) — this is the only
  * place the rule may be encoded.
  *
  * @complexity O(1), pure.
  * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export declare function deriveRequiredPermission(input: {
     scope: SettingScope;
@@ -64,7 +66,7 @@ export interface RegisterDefinitionsRequired {
         authWorkspaceId: UUID;
     };
 }
-/** REQ-02/REQ-09 chokepoint write: authorize `settings.definitions.manage` -> validate -> write + revision, one per definition, each its own tx. */
+/** chokepoint write: authorize `settings.definitions.manage` -> validate -> write + revision, one per definition, each its own tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
 export declare function registerDefinitions(required: RegisterDefinitionsRequired): Promise<{
     registered: string[];
 }>;
@@ -101,13 +103,14 @@ export interface SetValueRequired {
          * additive: omitted, behavior is unchanged (every pre-existing caller still gets the
          * scope-derived permission). When a domain-settings module supplies this, the chokepoint
          * authorizes THIS permission instead of the scope-derived one — still a mandatory
-         * `authorize()` call before any write (INV-07 fail-closed discipline is not relaxed, only
+         * `authorize` call before any write ( fail-closed discipline is not relaxed, only
          * which permission string is checked).
-         */
+     * See docs/decisions/DR-003-settings-ledger-invariants.md.
+     */
         requiredPermissionOverride?: string | undefined;
     };
 }
-/** REQ-04/REQ-13 chokepoint write: authorize -> validate -> value + revision, same tx. */
+/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
 export declare function set(required: SetValueRequired): Promise<{
     value: JsonValue;
     revisionSeq: number;
@@ -121,7 +124,7 @@ export interface ClearValueRequired {
         workspaceId?: UUID | undefined;
         principalId?: UUID | undefined;
         callerPrincipalId: UUID;
-        /** Set by `resetNamespace` when looping `clear()` in its own reset-authorized context (R3-01) — bypasses the inner authorize() re-check, still writes a normal revision. */
+        /** Set by `resetNamespace` when looping `clear` in its own reset-authorized context — bypasses the inner authorize re-check, still writes a normal revision. See docs/decisions/DR-003-settings-ledger-invariants.md. */
         skipAuthorize?: boolean | undefined;
         /** Set by a caller that has ALREADY opened a transaction around this write —
          *  see `resetNamespace`. Explicit rather than an ambient depth counter,
@@ -132,7 +135,7 @@ export interface ClearValueRequired {
         authWorkspaceId?: UUID | undefined;
     };
 }
-/** REQ-04/REQ-13 chokepoint write: authorize -> value + revision (state='cleared'), same tx. */
+/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
 export declare function clear(required: ClearValueRequired): Promise<{
     revisionSeq: number;
 }>;
@@ -149,15 +152,16 @@ export interface ResetNamespaceRequired {
     };
 }
 /**
- * EC-09/R3-01 — an explicit, human-invoked orchestrator: authorize
- * the matching `settings.reset.*` permission once, then loop `clear()` for
+ * — an explicit, human-invoked orchestrator: authorize
+ * the matching `settings.reset.*` permission once, then loop `clear` for
  * every setting in the namespace in the reset-authorized internal context
  * (`skipAuthorize: true`) — the outer reset permission is sufficient on its
  * own; each inner clear still emits its own `op='clear'` revision.
  *
- * `revisionSeqs` collects each inner `clear()` call's own `revisionSeq` so a
+ * `revisionSeqs` collects each inner `clear` call's own `revisionSeq` so a
  * host's admin HTTP route can surface the full contract without a second
  * read. Existing callers that only read `.clearedCount` are unaffected.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export declare function resetNamespace(required: ResetNamespaceRequired, keysInNamespace: string[]): Promise<{
     clearedCount: number;
@@ -177,7 +181,7 @@ export interface RenameDefinitionRequired {
     };
 }
 /**
- * The rename mechanism (AC-09, EC-06): a same-tx pair —
+ * The rename mechanism : a same-tx pair —
  * (1) UPDATE the active definition row's `(namespace,key)` to the new name,
  * same `setting_id`/`version` (ledgered `op='alias'`); (2) INSERT a fresh v1
  * alias marker at the OLD name pointing at the new name. Because identity
@@ -191,6 +195,7 @@ export interface RenameDefinitionRequired {
  * Never touches `schema`/`defaultValue`/`scopes` -- a pure rename can never
  * trigger `RENAME_RETYPE_CONFLICT` by construction; that guard lives in
  * `retypeDefinition` ("no rename+retype in one op").
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export declare function renameDefinition(required: RenameDefinitionRequired): Promise<{
     settingId: string;
@@ -204,7 +209,7 @@ export interface RetypeDefinitionRequired {
         workspaceId: UUID | null;
         schema: SettingValueSchema;
         defaultValue: JsonValue | null;
-        /** A total coercer id/tag (EC-08 registry in `settings.ts`) for reading values recorded under any prior version. */
+        /** A total coercer id/tag ( registry in `settings.ts`) for reading values recorded under any prior version. See docs/decisions/DR-003-settings-ledger-invariants.md. */
         coercionTag: string;
         /**
          * Present only to detect a combined rename+retype request;
@@ -220,7 +225,7 @@ export interface RetypeDefinitionRequired {
     };
 }
 /**
- * The retype mechanism (AC-10, EC-05): a same-tx pair --
+ * The retype mechanism : a same-tx pair --
  * (1) UPDATE the prior active version's `status` to `deprecated` FIRST (else
  * the insert in step 2 collides with the one-active-row-per-slot
  * invariant); (2) INSERT the new `version+1` row as `active`, same
@@ -228,6 +233,7 @@ export interface RetypeDefinitionRequired {
  * (2..N) already carries a total coercer -- `coercionTag` is `null` only for
  * version 1 by construction (`types.ts`), so this walks 2..N and requires
  * each to be non-null.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export declare function retypeDefinition(required: RetypeDefinitionRequired): Promise<{
     settingId: string;

package/dist/settings/write-service.js

@@ -1,16 +1,18 @@
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, ValueValidationFailedError, } from "./errors.js";
 import { invalidateDefinitionNamespaceCache, resolveDefinitionRaw, validateDefinitionInput, validateValueAgainstSchema, } from "./settings.js";
 import { SCOPE_BIT } from "./types.js";
 /**
- * behavior.spec.md §1.3 / REQ-06 `[internal-invariant]` — the self-vs-other
+ * behavior.spec.md §1.3 / `[internal-invariant]` — the self-vs-other
  * permission derivation. `targetPrincipalId` omitted or equal to the caller
  * -> `settings.user.self.write`; any other principal -> `settings.user.write`.
  * A divergence between this function and any other implementation of the
- * rule is a fail-open authorization bug (Red-Team RT-003) — this is the only
+ * rule is a fail-open authorization bug (Red-Team ) — this is the only
  * place the rule may be encoded.
  *
  * @complexity O(1), pure.
  * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export function deriveRequiredPermission(input) {
     if (input.scope === "global")
@@ -20,7 +22,7 @@ export function deriveRequiredPermission(input) {
     const isSelf = input.targetPrincipalId == null || input.targetPrincipalId === input.callerPrincipalId;
     return isSelf ? "settings.user.self.write" : "settings.user.write";
 }
-/** REQ-02/REQ-09 chokepoint write: authorize `settings.definitions.manage` -> validate -> write + revision, one per definition, each its own tx. */
+/** chokepoint write: authorize `settings.definitions.manage` -> validate -> write + revision, one per definition, each its own tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
 export async function registerDefinitions(required) {
     const { deps, input } = required;
     const authResult = await deps.authorize({
@@ -38,7 +40,7 @@ export async function registerDefinitions(required) {
         if (!validation.valid)
             throw validation.error;
         await deps.repo.transaction(async () => {
-            const now = deps.clock.nowIso();
+            const now = kernelNowIso({ clock: deps.clock });
             const settingId = deps.ids.newId();
             await deps.repo.saveDefinition({
                 settingId,
@@ -128,10 +130,11 @@ function assertTargetWorkspaceMatchesAuth(input) {
         `but the write targets workspace '${input.workspaceId}'`);
 }
 /**
- * REQ-13/INV-09 — for scope=user writes targeting another principal, verify
+ * — for scope=user writes targeting another principal, verify
  * that principal resolves to an active user whose own `workspace_id` equals
  * the request's `workspaceId` (structural scoping — a principal
  * belongs to exactly one workspace, not a membership join).
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 async function assertTargetPrincipalInWorkspace(deps, input) {
     if (input.scope !== "user")
@@ -140,12 +143,12 @@ async function assertTargetPrincipalInWorkspace(deps, input) {
         return;
     if (!input.workspaceId)
         return;
-    const principal = await deps.principals.findById({ workspaceId: input.workspaceId, id: input.principalId });
-    if (!principal || principal.status === "disabled") {
+    const principal = await deps.principals.findActiveById({ workspaceId: input.workspaceId, id: input.principalId });
+    if (!principal) {
         throw new PrincipalNotFoundError(`principal '${input.principalId}' was not found in workspace '${input.workspaceId}'`, input.principalId, input.workspaceId);
     }
 }
-/** REQ-04/REQ-13 chokepoint write: authorize -> validate -> value + revision, same tx. */
+/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
 export async function set(required) {
     const { deps, input } = required;
     const permission = input.requiredPermissionOverride ??
@@ -171,7 +174,7 @@ export async function set(required) {
     }
     await assertTargetPrincipalInWorkspace(deps, input);
     const result = await deps.repo.transaction(async () => {
-        const now = deps.clock.nowIso();
+        const now = kernelNowIso({ clock: deps.clock });
         const revisionSeq = await deps.repo.appendRevision({
             entityKind: "value",
             settingId: definition.settingId,
@@ -219,7 +222,7 @@ export async function set(required) {
     });
     return result;
 }
-/** REQ-04/REQ-13 chokepoint write: authorize -> value + revision (state='cleared'), same tx. */
+/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
 export async function clear(required) {
     const { deps, input } = required;
     if (!input.skipAuthorize) {
@@ -243,7 +246,7 @@ export async function clear(required) {
     const definition = await resolveScopedDefinitionOrThrow(deps, input);
     await assertTargetPrincipalInWorkspace(deps, input);
     const runClear = async () => {
-        const now = deps.clock.nowIso();
+        const now = kernelNowIso({ clock: deps.clock });
         const revisionSeq = await deps.repo.appendRevision({
             entityKind: "value",
             settingId: definition.settingId,
@@ -295,15 +298,16 @@ export async function clear(required) {
     return result;
 }
 /**
- * EC-09/R3-01 — an explicit, human-invoked orchestrator: authorize
- * the matching `settings.reset.*` permission once, then loop `clear()` for
+ * — an explicit, human-invoked orchestrator: authorize
+ * the matching `settings.reset.*` permission once, then loop `clear` for
  * every setting in the namespace in the reset-authorized internal context
  * (`skipAuthorize: true`) — the outer reset permission is sufficient on its
  * own; each inner clear still emits its own `op='clear'` revision.
  *
- * `revisionSeqs` collects each inner `clear()` call's own `revisionSeq` so a
+ * `revisionSeqs` collects each inner `clear` call's own `revisionSeq` so a
  * host's admin HTTP route can surface the full contract without a second
  * read. Existing callers that only read `.clearedCount` are unaffected.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export async function resetNamespace(required, keysInNamespace) {
     const { deps, input } = required;
@@ -392,7 +396,7 @@ async function resolveActiveDefinitionOrThrow(deps, input, verb) {
     return current;
 }
 /**
- * The rename mechanism (AC-09, EC-06): a same-tx pair —
+ * The rename mechanism : a same-tx pair —
  * (1) UPDATE the active definition row's `(namespace,key)` to the new name,
  * same `setting_id`/`version` (ledgered `op='alias'`); (2) INSERT a fresh v1
  * alias marker at the OLD name pointing at the new name. Because identity
@@ -406,6 +410,7 @@ async function resolveActiveDefinitionOrThrow(deps, input, verb) {
  * Never touches `schema`/`defaultValue`/`scopes` -- a pure rename can never
  * trigger `RENAME_RETYPE_CONFLICT` by construction; that guard lives in
  * `retypeDefinition` ("no rename+retype in one op").
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export async function renameDefinition(required) {
     const { deps, input } = required;
@@ -426,7 +431,7 @@ export async function renameDefinition(required) {
         throw new DefinitionInvalidError(`rename target '${input.newNamespace}.${input.newKey}' is already in use`);
     }
     const result = await deps.repo.transaction(async () => {
-        const now = deps.clock.nowIso();
+        const now = kernelNowIso({ clock: deps.clock });
         // Step 1: move the active row to the new name -- same setting_id, same version.
         await deps.repo.saveDefinition({ ...current, namespace: input.newNamespace, key: input.newKey, updatedAt: now });
         // Sequential rename: retarget every prior marker pointing at the OLD name to the NEW name.
@@ -488,7 +493,7 @@ export async function renameDefinition(required) {
     return result;
 }
 /**
- * The retype mechanism (AC-10, EC-05): a same-tx pair --
+ * The retype mechanism : a same-tx pair --
  * (1) UPDATE the prior active version's `status` to `deprecated` FIRST (else
  * the insert in step 2 collides with the one-active-row-per-slot
  * invariant); (2) INSERT the new `version+1` row as `active`, same
@@ -496,6 +501,7 @@ export async function renameDefinition(required) {
  * (2..N) already carries a total coercer -- `coercionTag` is `null` only for
  * version 1 by construction (`types.ts`), so this walks 2..N and requires
  * each to be non-null.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export async function retypeDefinition(required) {
     const { deps, input } = required;
@@ -514,7 +520,7 @@ export async function retypeDefinition(required) {
         }
     }
     const result = await deps.repo.transaction(async () => {
-        const now = deps.clock.nowIso();
+        const now = kernelNowIso({ clock: deps.clock });
         const newVersion = current.version + 1;
         // Step 1: deprecate the prior active version first.
         await deps.repo.saveDefinition({ ...current, status: "deprecated", updatedAt: now });
@@ -606,7 +612,7 @@ export async function reconcileDefinitionDefault(required) {
         throw new ValueValidationFailedError(`cannot reconcile the default of '${input.namespace}.${input.key}': the source default does not satisfy the definition's own schema (type '${current.schema.type}')`);
     }
     await deps.repo.transaction(async () => {
-        const now = deps.clock.nowIso();
+        const now = kernelNowIso({ clock: deps.clock });
         await deps.repo.saveDefinition({ ...current, defaultValue: input.defaultValue, updatedAt: now });
         await deps.repo.appendRevision({
             entityKind: "definition",
@@ -638,7 +644,7 @@ async function transitionDefinitionStatus(deps, input, target) {
     await authorizeDefinitionsManage(deps, input.callerPrincipalId, input.authWorkspaceId);
     const current = await resolveActiveDefinitionOrThrow(deps, input, target.revisionOp);
     const result = await deps.repo.transaction(async () => {
-        const now = deps.clock.nowIso();
+        const now = kernelNowIso({ clock: deps.clock });
         await deps.repo.saveDefinition({ ...current, status: target.status, updatedAt: now });
         await deps.repo.appendRevision({
             entityKind: "definition",