@jini-ai/cms 0.3.10 → 0.4.0

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

@@ -1,5 +1,5 @@
-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 SettingValueSchema } from "./types.js";
 /**
@@ -54,9 +54,9 @@ export interface SettingDefinitionSpec {
 }
 export interface EnsureSettingDefinitionsDeps {
     settingsRepo: SettingsRepoPort;
-    clock: ClockPort;
-    ids: IdGeneratorPort;
-    principals: PrincipalRepoPort;
+    clock: Clock;
+    ids: IdGenerator;
+    principals: SettingsPrincipalLookupPort;
 }
 export interface EnsureSettingDefinitionsInput {
     namespace: string;

package/dist/settings/errors.d.ts

@@ -12,6 +12,9 @@ export declare class DefinitionInvalidError extends Error {
 export declare class ScopeNotAllowedError extends Error {
 }
 export declare class SecretNotSupportedError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optional?: ErrorOptions);
 }
 export declare class ValueValidationFailedError extends Error {
 }
@@ -24,10 +27,13 @@ export declare class DefinitionTombstonedError extends Error {
 export declare class DefinitionNotFoundError extends Error {
 }
 export declare class PurgeRequiredError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optional?: ErrorOptions);
 }
 export declare class ForbiddenError extends Error {
 }
-/** REQ-13: the target `principalId` does not resolve to an active principal in the request's workspace (INV-09). */
+/** : the target `principalId` does not resolve to an active principal in the request's workspace. See docs/decisions/DR-003-settings-ledger-invariants.md. */
 export declare class PrincipalNotFoundError extends Error {
     readonly principalId: string;
     readonly workspaceId: string;

package/dist/settings/errors.js

@@ -12,6 +12,9 @@ export class DefinitionInvalidError extends Error {
 export class ScopeNotAllowedError extends Error {
 }
 export class SecretNotSupportedError extends Error {
+    constructor({ message }, optional = {}) {
+        super(message, optional);
+    }
 }
 export class ValueValidationFailedError extends Error {
 }
@@ -24,10 +27,13 @@ export class DefinitionTombstonedError extends Error {
 export class DefinitionNotFoundError extends Error {
 }
 export class PurgeRequiredError extends Error {
+    constructor({ message }, optional = {}) {
+        super(message, optional);
+    }
 }
 export class ForbiddenError extends Error {
 }
-/** REQ-13: the target `principalId` does not resolve to an active principal in the request's workspace (INV-09). */
+/** : the target `principalId` does not resolve to an active principal in the request's workspace. See docs/decisions/DR-003-settings-ledger-invariants.md. */
 export class PrincipalNotFoundError extends Error {
     principalId;
     workspaceId;

package/dist/settings/index.d.ts

@@ -23,7 +23,7 @@ export { type SettingDefinitionSpec, type EnsureSettingDefinitionsDeps, type Ens
 export { INSTRUCTIONS_NAMESPACE, NOTIFICATIONS_NAMESPACE, PRIVACY_NAMESPACE, APPEARANCE_NAMESPACE, LANGUAGE_NAMESPACE, type EnsureSettingsUiTabDefinitionsInput, ensureSettingsUiTabDefinitions, } from "./ui-tab-definitions.js";
 export { type AgentWritablePreference, AGENT_PREFERENCE_WRITE_SCOPE, AGENT_WRITABLE_PREFERENCES, AGENT_WRITABLE_PREFERENCE_IDS, resolveAgentWritablePreference, AGENT_PREFERENCE_REQUIRED_SCOPE_BIT, } from "./agent-writable-preferences.js";
 /** The agent-tool catalog for this domain. */
-export { getSettingsAgentToolCatalog, type AgentToolDefinition as SettingsAgentToolDefinition, type AgentToolSideEffect as SettingsAgentToolSideEffect, } from "./agent-tools.js";
+export { getSettingsAgentToolCatalog, } from "./agent-tools.js";
 /**
  * The agent-tool wiring for this domain.
  *
@@ -34,4 +34,7 @@ export { getSettingsAgentToolCatalog, type AgentToolDefinition as SettingsAgentT
 export { buildSettingsRegistrations, settingsDerivedRisk, type SettingsToolDeps, } from "./tool-registrations.js";
 /** The settings-dialog chrome copy (24 generic tab labels/subtitles), shared across every host. */
 export { SETTINGS_DIALOG_DICTIONARIES, translateSettingsDialog } from "./dictionaries/index.js";
+export { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule, type AgentSettingWriteRule } from "./agent-write-denylist.js";
+export type { SettingsWriteConfirmation, SettingsValueWriteToolId } from "./agent-value-write-tools.js";
+export type { SettingsPrincipalLookupPort } from "./principal-lookup.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/settings/index.js

@@ -33,4 +33,5 @@ export { getSettingsAgentToolCatalog, } from "./agent-tools.js";
 export { buildSettingsRegistrations, settingsDerivedRisk, } from "./tool-registrations.js";
 /** The settings-dialog chrome copy (24 generic tab labels/subtitles), shared across every host. */
 export { SETTINGS_DIALOG_DICTIONARIES, translateSettingsDialog } from "./dictionaries/index.js";
+export { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule } from "./agent-write-denylist.js";
 //# sourceMappingURL=index.js.map

package/dist/settings/ports.d.ts

@@ -1,19 +1,20 @@
-import type { UUID } from "../core/ports.js";
+import type { UUID } from "@jini-ai/core/primitives";
 import type { SettingDefinitionRecord, SettingRevisionRecord, SettingValueRecord } from "./types.js";
 /**
  * @file Port contract for the `settings` library.
  *
  * Purpose:
  * Dependency-inversion seam (port/adapter rule-of-two) for the 5 settings tables.
- * Deliberately does NOT declare a principal-lookup method — REQ-13's
- * target-principal check reuses `identity.PrincipalRepoPort.findById`
- * directly (reuse, not a new port).
+ * Persistence deliberately has no principal-lookup method: target-principal checks use
+ * the separate host-owned SettingsPrincipalLookupPort, keeping membership/status policy
+ * outside the settings persistence contract.
  *
  * `transaction` gives `write-service.ts`/`purge-service.ts` the same-tx
- * guarantee INV-01/INV-06 depend on (value/definition row + its revision row
+ * guarantee depend on (value/definition row + its revision row
  * must commit together, or not at all).
  *
  * Interfaces and types only — no feature logic.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export interface SettingsRepoPort {
     findActiveDefinition(required: {

package/dist/settings/principal-lookup.d.ts

@@ -0,0 +1,9 @@
+import type { Principal } from "@jini-ai/core";
+/** Resolve only an active principal in the requested workspace. The host owns status and membership policy. */
+export interface SettingsPrincipalLookupPort {
+    findActiveById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<Principal | null>;
+}
+//# sourceMappingURL=principal-lookup.d.ts.map

package/dist/settings/principal-lookup.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=principal-lookup.js.map

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

@@ -1,4 +1,4 @@
-import type { ClockPort, UUID } from "../core/ports.js";
+import type { Clock, UUID } from "@jini-ai/core/primitives";
 import type { SettingsRepoPort } from "./ports.js";
 import type { AuthorizeFn } from "./write-service.js";
 /**
@@ -8,7 +8,7 @@ import type { AuthorizeFn } from "./write-service.js";
  * A host's value-table FKs (`setting_values_workspace`/`_user` -> `workspaces`)
  * are typically `ON DELETE RESTRICT`, not `CASCADE` — a raw workspace delete
  * cannot silently drop value rows without a ledgered revision. This module is
- * the explicit, ledgered alternative that requires: `authorize()` once
+ * the explicit, ledgered alternative that requires: `authorize` once
  * -> enumerate every affected row -> append a redacted `op='purge'` revision
  * per row -> delete the row, all in ONE transaction. The `setting_revisions`
  * ledger itself is NEVER touched by a purge — only value rows are removed,
@@ -17,13 +17,14 @@ import type { AuthorizeFn } from "./write-service.js";
  *
  * Deviation from the outline's `SettingsWriteServiceDeps`: purge needs
  * neither `ids` (no new definition/value rows are created) nor `principals`
- * (REQ-13's target-principal check is a write-time guard; purge only removes
+ * ( target-principal check is a write-time guard; purge only removes
  * pre-existing rows, it never writes a new user-scope row for an unverified
  * principal) — so it declares its own smaller `PurgeServiceDeps`.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export interface PurgeServiceDeps {
     repo: SettingsRepoPort;
-    clock: ClockPort;
+    clock: Clock;
     authorize: AuthorizeFn;
 }
 export interface PurgeTenantSettingsRequired {

package/dist/settings/purge-service.js

@@ -1,3 +1,4 @@
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 import { ForbiddenError } from "./errors.js";
 import { invalidateWorkspaceSettingsCache } from "./settings.js";
 /**
@@ -18,7 +19,7 @@ export async function purgeTenantSettings(required) {
         throw new ForbiddenError(`principal '${input.callerPrincipalId}' is not authorized for 'settings.definitions.manage' (${authResult.reason})`);
     }
     const result = await deps.repo.transaction(async () => {
-        const now = deps.clock.nowIso();
+        const now = kernelNowIso({ clock: deps.clock });
         let purgedCount = 0;
         if (input.principalId) {
             const userValues = await deps.repo.listUserValues({
@@ -99,7 +100,7 @@ export async function purgeTenantSettings(required) {
         }
         return { purgedCount };
     });
-    invalidateWorkspaceSettingsCache(deps.repo, input.workspaceId, input.principalId);
+    invalidateWorkspaceSettingsCache({ repo: deps.repo, workspaceId: input.workspaceId }, { principalId: input.principalId });
     return result;
 }
 //# sourceMappingURL=purge-service.js.map

package/dist/settings/settings.d.ts

@@ -1,16 +1,17 @@
-import type { JsonValue } from "../core/ports.js";
+import type { JsonValue } from "@jini-ai/core/primitives";
 import { DefinitionInvalidError, SecretNotSupportedError } from "./errors.js";
 import type { SettingsRepoPort } from "./ports.js";
 import { type SettingDefinitionRecord, type SettingOwnerKind, type SettingScopeContext, type SettingValueSchema } from "./types.js";
 /**
  * @file The settings resolver + pure definition-registration validation
- * (REQ-02, REQ-03, REQ-09; "one evaluator").
+ * ("one evaluator").
  *
  * Purpose:
  * `validateDefinitionInput` is pure (no I/O) — the write-side chokepoint in
  * `write-service.ts` calls it before persisting. `getEffective`/`getLayer`/
  * `resolveDefinition` are read-only against `SettingsRepoPort`. Neither
  * mutates anything; every mutation goes through `write-service.ts`.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export interface DefinitionInput {
     namespace: string;
@@ -24,13 +25,14 @@ export interface DefinitionInput {
     secret: boolean;
 }
 /**
- * REQ-02/REQ-09/INV-05/INV-08 — the pure half of `registerDefinitions`.
+ * — the pure half of `registerDefinitions`.
  * Never throws; returns a discriminated result so the chokepoint decides how
  * to surface the failure (matches `ValueValidationFailedError`'s pattern of
  * keeping I/O out of validation).
  *
  * @complexity O(1) per definition.
  * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export declare function validateDefinitionInput(input: DefinitionInput): {
     valid: true;
@@ -39,7 +41,12 @@ export declare function validateDefinitionInput(input: DefinitionInput): {
     error: DefinitionInvalidError | SecretNotSupportedError;
 };
 export declare function validateValueAgainstSchema(schema: SettingValueSchema, value: JsonValue): boolean;
-export declare function registerCoercer(tag: string, fn: (value: JsonValue) => JsonValue): void;
+export declare function registerCoercer({ tag, fn }: {
+    tag: string;
+    fn: (required: {
+        value: JsonValue;
+    }) => JsonValue;
+}, _optional?: Record<string, never>): void;
 /**
  * Bumps the namespace's definition-cache epoch (lazy invalidation) — every
  * previously-cached definition-cache entry for this
@@ -64,13 +71,20 @@ export declare function invalidateDefinitionNamespaceCache(repo: SettingsRepoPor
  * reintroduces caching. Deleting the call site would remove the place that question is asked. A
  * cache added without restoring a purge hook is a tenant-teardown leak, so this stays as the seam.
  */
-export declare function invalidateWorkspaceSettingsCache(_repo: SettingsRepoPort, _workspaceId: string, _principalId?: string): void;
+export declare function invalidateWorkspaceSettingsCache(_required: {
+    repo: SettingsRepoPort;
+    workspaceId: string;
+}, _optional?: {
+    principalId?: string | undefined;
+}): void;
 /**
  * Follows an alias marker (depth <=1) to the current row and returns it as
  * stored — status intact, including `tombstone`. `resolveDefinition` (below)
- * is the read-path wrapper that collapses tombstone to typed-absent (EC-10);
+ * is the read-path wrapper that collapses tombstone to typed-absent;
  * `write-service.ts` uses this raw form directly so it can report
  * `DEFINITION_TOMBSTONED` distinctly from "not found".
+ * Malformed alias targets, cycles and chains deeper than one fail closed as absent.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export declare function resolveDefinitionRaw(deps: {
     repo: SettingsRepoPort;
@@ -103,7 +117,7 @@ export interface ResolvedSetting {
     defVersion: number;
 }
 /**
- * REQ-03/INV-02 — total for a live key: never throws, never returns
+ * — total for a live key: never throws, never returns
  * undefined. Precedence `user ?? workspace ?? global ?? default`. A
  * `cleared` row is treated as absent at that layer (behavior.spec §1.2).
  *
@@ -113,6 +127,7 @@ export interface ResolvedSetting {
  *
  * @complexity O(1) — up to 3 layer reads + 1 definition read.
  * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export declare function getEffective(deps: {
     repo: SettingsRepoPort;

package/dist/settings/settings.js

@@ -6,25 +6,31 @@ const NAMESPACE_FENCE = {
     site: (input) => input.namespace.startsWith("site.") && input.workspaceId !== null,
 };
 /**
- * REQ-02/REQ-09/INV-05/INV-08 — the pure half of `registerDefinitions`.
+ * — the pure half of `registerDefinitions`.
  * Never throws; returns a discriminated result so the chokepoint decides how
  * to surface the failure (matches `ValueValidationFailedError`'s pattern of
  * keeping I/O out of validation).
  *
  * @complexity O(1) per definition.
  * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export function validateDefinitionInput(input) {
     if (input.secret) {
         return {
             valid: false,
-            error: new SecretNotSupportedError("secret:true definitions are not supported in the core-only subset (REQ-09/INV-08)"),
+            error: new SecretNotSupportedError({
+                // See docs/decisions/DR-003-settings-ledger-invariants.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+                message: "secret:true definitions are not supported in the core-only subset",
+            }),
         };
     }
     if (!NAMESPACE_FENCE[input.ownerKind](input)) {
         return {
             valid: false,
-            error: new DefinitionInvalidError(`namespace '${input.namespace}' does not match the owner fence for owner_kind '${input.ownerKind}' (REQ-02)`),
+            error: new DefinitionInvalidError(
+            // See docs/decisions/DR-003-settings-ledger-invariants.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+            `namespace '${input.namespace}' does not match the owner fence for owner_kind '${input.ownerKind}'`),
         };
     }
     if (input.scopes < 1 || input.scopes > 7) {
@@ -33,19 +39,23 @@ export function validateDefinitionInput(input) {
             error: new DefinitionInvalidError(`scopes bitmask ${input.scopes} is out of range 1..7`),
         };
     }
-    // INV-05: a site-owned def (workspace_id NOT NULL) may never declare the global scope bit.
+    // a site-owned def (workspace_id NOT NULL) may never declare the global scope bit. See docs/decisions/DR-003-settings-ledger-invariants.md.
     if (input.workspaceId !== null && (input.scopes & SCOPE_BIT.global) !== 0) {
         return {
             valid: false,
-            error: new DefinitionInvalidError("a site-owned definition may not declare the global scope bit (INV-05)"),
+            error: new DefinitionInvalidError(
+            // See docs/decisions/DR-003-settings-ledger-invariants.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+            "a site-owned definition may not declare the global scope bit"),
         };
     }
     // Totality (behavior.spec §3): every non-secret def needs a non-null default so
-    // getEffective is always total (INV-02) and factory-reset is provably bootable.
+    // getEffective is always total and factory-reset is provably bootable. See docs/decisions/DR-003-settings-ledger-invariants.md.
     if (input.defaultValue === null) {
         return {
             valid: false,
-            error: new DefinitionInvalidError("non-secret definitions require a non-null default_json (totality, INV-02)"),
+            error: new DefinitionInvalidError(
+            // See docs/decisions/DR-003-settings-ledger-invariants.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+            "non-secret definitions require a non-null default_json (totality)"),
         };
     }
     return { valid: true };
@@ -69,9 +79,9 @@ export function validateValueAgainstSchema(schema, value) {
             return true;
     }
 }
-/** Identity-registry of total coercers keyed by `coercionTag` (EC-08). `"identity"` is always registered. */
-const coercers = new Map([["identity", (v) => v]]);
-export function registerCoercer(tag, fn) {
+/** Identity-registry of total coercers keyed by `coercionTag`. `"identity"` is always registered. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+const coercers = new Map([["identity", ({ value }) => value]]);
+export function registerCoercer({ tag, fn }, _optional = {}) {
     coercers.set(tag, fn);
 }
 const cacheByRepo = new WeakMap();
@@ -119,38 +129,48 @@ export function invalidateDefinitionNamespaceCache(repo, namespace) {
  * reintroduces caching. Deleting the call site would remove the place that question is asked. A
  * cache added without restoring a purge hook is a tenant-teardown leak, so this stays as the seam.
  */
-export function invalidateWorkspaceSettingsCache(_repo, _workspaceId, _principalId) {
+export function invalidateWorkspaceSettingsCache(_required, _optional = {}) {
     // Intentionally empty — see doc above. Do not delete without re-reading `purge-service.ts`.
 }
 /**
  * Follows an alias marker (depth <=1) to the current row and returns it as
  * stored — status intact, including `tombstone`. `resolveDefinition` (below)
- * is the read-path wrapper that collapses tombstone to typed-absent (EC-10);
+ * is the read-path wrapper that collapses tombstone to typed-absent;
  * `write-service.ts` uses this raw form directly so it can report
  * `DEFINITION_TOMBSTONED` distinctly from "not found".
+ * Malformed alias targets, cycles and chains deeper than one fail closed as absent.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export async function resolveDefinitionRaw(deps, input) {
-    // Namespace fencing (REQ-02) makes `site.*` (non-null workspace_id) and
+    // 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 found = (await deps.repo.findActiveDefinition(input)) ??
-        (input.workspaceId !== null
-            ? await deps.repo.findActiveDefinition({ ...input, workspaceId: null })
-            : null);
-    if (!found)
-        return null;
-    if (found.status === "alias") {
-        if (found.aliasOfNamespace == null || found.aliasOfKey == null)
+    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;
-        return resolveDefinitionRaw(deps, {
+        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 found;
+    return null;
 }
 /**
  * The read-path resolver: typed-absent (`null`) for a tombstoned or
@@ -175,7 +195,7 @@ export async function resolveDefinition(deps, input) {
     return resolved;
 }
 /**
- * REQ-03/INV-02 — total for a live key: never throws, never returns
+ * — total for a live key: never throws, never returns
  * undefined. Precedence `user ?? workspace ?? global ?? default`. A
  * `cleared` row is treated as absent at that layer (behavior.spec §1.2).
  *
@@ -185,6 +205,7 @@ export async function resolveDefinition(deps, input) {
  *
  * @complexity O(1) — up to 3 layer reads + 1 definition read.
  * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 export async function getEffective(deps, input) {
     const definition = await resolveDefinition(deps, {
@@ -198,7 +219,7 @@ export async function getEffective(deps, input) {
         if (defVersion === definition.version)
             return value;
         const coercer = coercers.get(definition.coercionTag ?? "identity") ?? coercers.get("identity");
-        return coercer(value);
+        return coercer({ value });
     };
     // 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.

package/dist/settings/tool-registrations.d.ts

@@ -1,54 +1,47 @@
+import type { IdGenerator } from "@jini-ai/core/primitives";
+import type { Clock } from "@jini-ai/core/primitives";
 /**
- * @file Settings' tool-registration wiring: maps the wireable subset of `agent-tools.ts`'s eight
- * catalog entries onto three reads and one curated write, as `ToolRegistration`s. See
- * `agent-tools.ts`'s own file header for why the four GENERIC write entries are documented but
- * deliberately never wired ({@link UNWIRED_SETTINGS_TOOL_IDS}), and why `settings_set_ui_preference`
- * is not one of them.
- *
- * The one write here is shaped so that its blast radius is a property of the code rather than of
- * the caller's restraint: its target key comes from a fixed enum
- * (`agent-writable-preferences.ts`), its scope is a constant, and it never names a principal — so
- * "write another operator's settings" and "write a key outside the list" are unrepresentable
- * inputs, not merely unauthorized ones.
- *
- * Authorization shape: `getEffective`/`resolveDefinition` (`settings.ts`) and a direct
- * `settingsRepo.listActiveDefinitions`/`getGlobalValue`/`getWorkspaceValue`/`getUserValue` read
- * carry no `authorize()` call of their own — a host's admin routes gate inline — so every handler
- * here calls the kit's `requireToolPermission` itself, mirroring those routes' identical checks.
- * `resolveOwnOrOtherPrincipalRead` below deliberately duplicates (rather than imports) any HTTP
- * admin layer's read-target resolution logic — this file is domain-owned wiring, and importing
- * logic from a host's HTTP admin layer would invert this library's ports/adapters direction
- * (features must not depend on a host's server/routes layer); the two are kept behaviorally
- * identical by inspection, the same discipline that logic's own host-side callers should apply.
+ * @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
+ * return the previous override. Key policy and the optional host confirmation port enforce the
+ * owner's 2026-10-01 decision: privacy/instructions/self-configuration require a human card.
+ * Direct reads supply their own permission checks; writes pre-check before reading undo values
+ * and the service repeats authorization at mutation time. No host HTTP/runtime imports.
  */
 import type { AuthorizeFn } from "../core/commands/command.js";
-import { type DerivedRiskByToolId, type ToolRegistration } from "../core/tools/registration-kit.js";
-import type { PrincipalRepoPort } from "../identity/index.js";
+import { type SettingsWriteConfirmation } from "./agent-value-write-tools.js";
+import { type AgentSettingWriteRule } from "./agent-write-denylist.js";
+import { type DerivedRiskByToolId, type ToolRegistration } from "@jini-ai/core";
+import type { SettingsPrincipalLookupPort } from "./principal-lookup.js";
 import type { SettingsRepoPort } from "./ports.js";
+import { set as setSettingValue } from "./write-service.js";
 /**
  * The exact slice of a host's route-deps bag Settings' tool handlers read. Declared structurally
  * (rather than importing any host's own route-deps type) so this module carries no back-edge into
  * a host's composition root. A host satisfies this structurally by passing its existing route deps
- * object; nothing there needs to change shape.
+ * object after binding kernel clock/IDs and an active, workspace-scoped principal lookup.
  */
 export interface SettingsToolDeps {
     authorize: AuthorizeFn;
     workspaceId: string;
-    clock: {
-        nowIso(): string;
-    };
-    idGen: {
-        newId(): string;
-    };
+    clock: Clock;
+    idGen: IdGenerator;
     settingsReady: Promise<void>;
     settingsUiTabsReady: Promise<void>;
     settingsRepo: SettingsRepoPort;
-    principalRepo: PrincipalRepoPort;
+    principalRepo: SettingsPrincipalLookupPort;
+    /** Host extensions: explicit deny or human-confirmation rules, never agent inputs. */
+    extraDeniedSettings?: readonly AgentSettingWriteRule[];
+    extraConfirmationSettings?: readonly AgentSettingWriteRule[];
+    /** Must obtain an authenticated human card decision; absent means protected keys fail closed. */
+    confirmWrite?: (request: SettingsWriteConfirmation) => Promise<boolean>;
+    /** Host's validation wrapper; defaults to the package's existing set chokepoint. */
+    setValue?: typeof setSettingValue;
 }
 /**
  * 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 declare const settingsDerivedRisk: DerivedRiskByToolId;