@jini-ai/core 0.4.1 → 0.4.2

package/dist/settings/tool-registrations.js

@@ -0,0 +1,250 @@
+import { adaptLegacyAuthorize } from "../tool-permissions.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 "../registration-kit.js";
+import { requireToolPermission } from "../tool-permissions.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, resolveDefinitionRaw } from "./settings.js";
+import { SCOPE_BIT } from "./types.js";
+import { set as setSettingValue } from "./write-service.js";
+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). */
+const CROSS_PRINCIPAL_SETTINGS_READ_PERMISSION = "settings.user.read";
+/**
+ * Decides which principal's user layer a settings read tool may target — the tool-wiring twin of
+ * a host's own HTTP admin layer's equivalent read-target resolver (see this file's header for why
+ * it is duplicated rather than imported).
+ *
+ * @throws {ForbiddenError} (`core/commands`, via `requireToolPermission`) If `requestedPrincipalId`
+ * names a different principal than the caller and the caller lacks `settings.user.read`.
+ * @returns The principal id to read (`undefined` = skip the user layer entirely).
+ * @complexity O(1); at most one `authorize()` call (none for a self-read or no-op read).
+ * @overallScore 100
+ */
+async function resolveOwnOrOtherPrincipalRead(routeDeps, required) {
+    const { requestedPrincipalId, callerPrincipalId } = required;
+    // Defaults to the CALLER, never to `undefined`. `undefined` does not mean "the caller" to
+    // `getEffective` — it means "skip the user layer entirely" (`settings.ts`'s
+    // `if (workspaceId && principalId)` guard), so an omitted `principalId` would otherwise make
+    // every read tool report the workspace/global/default value while silently ignoring the
+    // operator's own — a read tool that cannot see the layer the operator is actually looking at
+    // does not fail loudly; it produces confident wrong answers.
+    const target = requestedPrincipalId ?? callerPrincipalId;
+    if (target === callerPrincipalId)
+        return target;
+    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) {
+    return record && record.state === "set" ? record.valueJson : null;
+}
+/**
+ * Builds `write-service.ts`'s own five-field dep shape from `RouteDeps`.
+ *
+ * Deliberately duplicates a host's own HTTP admin layer's equivalent field-mapping helper rather
+ * than importing it, for the reason this file's header already gives about
+ * `resolveOwnOrOtherPrincipalRead`: this is domain-owned wiring, and importing from a host's HTTP
+ * admin layer would invert the ports/adapters direction. It is a field mapping, not logic, so the
+ * two copies carry no behavioral drift risk — and `write-service.ts` is the single chokepoint
+ * either way, so a divergence here could only produce a missing dependency, which fails loudly.
+ */
+function toWriteDeps(routeDeps) {
+    return {
+        repo: routeDeps.settingsRepo,
+        clock: routeDeps.clock,
+        ids: routeDeps.idGen,
+        authorize: routeDeps.authorize,
+        principals: routeDeps.principalRepo,
+    };
+}
+/**
+ * Errors a DIFFERENT input would fix, for `withSchemaOnRejection`'s decoration.
+ *
+ * `ValueValidationFailedError` is the common one — the model sent a value of the wrong shape for
+ * the chosen setting, and republishing the schema (with its per-key value hints) lets it correct
+ * in one turn instead of guessing. The two definition errors are included because they are
+ * genuinely reachable from a bad `setting`: an id that passed the enum but names a definition this
+ * workspace has tombstoned. A `ForbiddenError` is deliberately absent — no input change fixes a
+ * missing grant, and decorating it would imply the call is worth retrying.
+ */
+function isPreferenceShapeRejection(error) {
+    return (error instanceof ValueValidationFailedError ||
+        error instanceof DefinitionNotFoundError ||
+        error instanceof DefinitionTombstonedError ||
+        error instanceof ScopeNotAllowedError);
+}
+/**
+ * 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 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([
+    // -> 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"],
+    // -> resolveDefinition() + settingsRepo.getGlobalValue/getWorkspaceValue/getUserValue: reads only.
+    ["settings_get_raw", "none"],
+    // -> write-service.set() at scope=user against the caller's own principal: writes a value row
+    // and a revision-ledger entry. Durable, and correctly classified as such even though every key
+    // it can reach is a reversible display preference — the classification describes what the
+    // handler DOES, not how much the operator would mind.
+    ["settings_set_ui_preference", "mutates-durable-state"],
+]);
+/** 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: bulk variant — clears every value in an operator-named namespace at a
+    // scope in one call, irreversible.
+    "settings_reset",
+    // EXCLUDED BY DESIGN: schema-level, not value-level — can rename/retype/deprecate/tombstone the
+    // definition a key resolves through, reinterpreting every existing stored value for that key
+    // platform-wide.
+    "settings_register_definitions",
+]);
+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({ input: ctx.input });
+            await routeDeps.settingsReady;
+            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 deniedRules = [...AGENT_WRITE_DENIED_SETTINGS, ...(routeDeps.extraDeniedSettings ?? [])];
+            const confirmationRules = [...(routeDeps.confirmationSettings ?? 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({ input: ctx.input });
+            const namespace = requireString({ input: input, key: "namespace" });
+            await routeDeps.settingsReady;
+            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: input, key: "principalId" }),
+                callerPrincipalId: ctx.principal.id,
+            });
+            const [platformDefs, siteDefs] = await Promise.all([
+                routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: null }),
+                routeDeps.settingsRepo.listActiveDefinitions({ workspaceId }),
+            ]);
+            const keys = new Set([...platformDefs, ...siteDefs].filter((d) => d.namespace === namespace).map((d) => d.key));
+            const data = [];
+            for (const key of keys) {
+                const resolved = await getEffective({ repo: routeDeps.settingsRepo }, { namespace, key, scopeContext: { workspaceId, principalId } });
+                if (resolved)
+                    data.push({ key, value: resolved.value, sourceLayer: resolved.sourceLayer, defVersion: resolved.defVersion });
+            }
+            return { data };
+        },
+        settings_get_raw: async (ctx) => {
+            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({ 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: input, key: "principalId" }),
+                callerPrincipalId: ctx.principal.id,
+            });
+            const definition = await resolveDefinition({ repo: routeDeps.settingsRepo }, { namespace, key, workspaceId });
+            if (!definition)
+                throw new Error(`definition '${namespace}.${key}' was not found`);
+            const [globalValue, workspaceValue, userValue] = await Promise.all([
+                routeDeps.settingsRepo.getGlobalValue(definition.settingId),
+                routeDeps.settingsRepo.getWorkspaceValue({ workspaceId, settingId: definition.settingId }),
+                principalId ? routeDeps.settingsRepo.getUserValue({ workspaceId, principalId, settingId: definition.settingId }) : Promise.resolve(null),
+            ]);
+            return {
+                key: `${namespace}.${key}`,
+                global: layerValueOf(globalValue),
+                workspace: layerValueOf(workspaceValue),
+                user: layerValueOf(userValue),
+                default: definition.defaultValue,
+            };
+        },
+        settings_set_ui_preference: async (ctx) => {
+            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
+            // an unlisted id through. Rejected BEFORE `settingsUiTabsReady` is awaited so an unlisted id
+            // cannot even be used to probe which definitions exist.
+            const preference = resolveAgentWritablePreference(settingId);
+            if (!preference) {
+                throw new Error(`'${settingId}' is not an agent-writable preference. Allowed: ${AGENT_WRITABLE_PREFERENCE_IDS.join(", ")}.`);
+            }
+            // `in` rather than a truthiness check: `false` and `0` are legitimate values here
+            // (`soundEnabled`, `desktopEnabled`), and rejecting them would make the two boolean
+            // preferences settable in one direction only.
+            if (!("value" in input)) {
+                throw new Error(`a 'value' is required to set '${settingId}'`);
+            }
+            const value = input.value;
+            // This tool's definitions are registered by `ensureSettingsUiTabDefinitions()` at boot, not
+            // by any legacy-migration promise a host might also cover — awaiting the wrong promise would
+            // make an early call fail with a spurious "definition was not found".
+            await routeDeps.settingsUiTabsReady;
+            // 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 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 ) 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: ({ 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 });
+}
+//# sourceMappingURL=tool-registrations.js.map

package/dist/settings/types.d.ts

@@ -0,0 +1,125 @@
+import type { ISODateTime, JsonValue, UUID } from "../primitives/index.js";
+/**
+ * @file Settings domain types.
+ *
+ * Purpose:
+ * Record shapes + the schema-validation vocabulary shared by `settings.ts`,
+ * `write-service.ts`, `purge-service.ts`, and both repo adapters. Interfaces
+ * and types only — no feature logic (mirrors `identity/types.ts`).
+ */
+export type SettingScope = "global" | "workspace" | "user";
+export type SettingOwnerKind = "core" | "site" | "theme";
+export type DefinitionStatus = "active" | "alias" | "deprecated" | "tombstone";
+export type ValueState = "set" | "cleared";
+export type RevisionEntityKind = "definition" | "value";
+export type RevisionOp = "register" | "alias" | "retype"
+/**
+ * A `core` definition's stored `default_json` was reconciled to the default
+ * its source declares (`write-service.ts`'s `reconcileDefinitionDefault`).
+ * Distinct from `retype`: the schema is unchanged, so no stored value needs
+ * coercion and the definition version does NOT advance. Only unset-value
+ * resolution changes.
+ */
+ | "redefault" | "deprecate" | "tombstone" | "set" | "clear" | "purge" | "coerce";
+/** Scope bitmask values: global=1, workspace=2, user=4. Legal range 1..7. */
+export declare const SCOPE_BIT: {
+    readonly global: 1;
+    readonly workspace: 2;
+    readonly user: 4;
+};
+/**
+ * A deliberately small, total value-schema vocabulary (Article III — this
+ * feature registers string/number/boolean/enum settings; a generic JSON
+ * Schema engine is not needed and would be speculative generality). Every
+ * variant is exhaustively validatable by `validateValue`.
+ */
+/**
+ * `{type:"json"}` is a deliberately narrow, scalar-ADJACENT exception to the
+ * "deliberately small" vocabulary above: it accepts any JSON value
+ * (object/array/scalar) and validates nothing about its internal shape —
+ * that is the registering feature's own write-path responsibility, never
+ * this ledger's job.
+ *
+ * Enforcement rule that must survive any refactor: Code Review must confirm
+ * that EVERY use is genuinely unbounded, list-shaped data with no scalar
+ * decomposition available — it is not a general escape hatch for fields that
+ * could be scalar-decomposed instead. The check is per-use, deliberately not
+ * a headcount. See `docs/decisions/settings-json-schema-variant.md` for the
+ * originating rationale and a related non-null-default invariant.
+ */
+export type SettingValueSchema = {
+    type: "string";
+    nullable?: boolean;
+} | {
+    type: "number";
+    nullable?: boolean;
+} | {
+    type: "boolean";
+    nullable?: boolean;
+} | {
+    type: "enum";
+    values: readonly string[];
+    nullable?: boolean;
+} | {
+    type: "json";
+    nullable?: boolean;
+};
+export interface SettingDefinitionRecord {
+    settingId: UUID;
+    version: number;
+    /** NULL = platform def (core/theme); non-null = site-owned. */
+    workspaceId: UUID | null;
+    namespace: string;
+    key: string;
+    ownerKind: SettingOwnerKind;
+    ownerId: string | null;
+    schema: SettingValueSchema;
+    defaultValue: JsonValue | null;
+    /** Bitmask over `SCOPE_BIT`, legal range 1..7. */
+    scopes: number;
+    secret: boolean;
+    status: DefinitionStatus;
+    aliasOfNamespace: string | null;
+    aliasOfKey: string | null;
+    /** Present only when `version > 1`; a total coercer id/tag for the prior version. */
+    coercionTag: string | null;
+    createdAt: ISODateTime;
+    updatedAt: ISODateTime;
+}
+export interface SettingValueRecord {
+    settingId: UUID;
+    scope: SettingScope;
+    /** Present for workspace/user scope; null for global. */
+    workspaceId: UUID | null;
+    /** Present for user scope only. */
+    principalId: UUID | null;
+    valueJson: JsonValue | null;
+    state: ValueState;
+    defVersion: number;
+    seq: number;
+    updatedBy: UUID;
+    updatedAt: ISODateTime;
+    originPluginId: string | null;
+}
+export interface SettingRevisionRecord {
+    seq: number;
+    entityKind: RevisionEntityKind;
+    settingId: UUID;
+    scope: SettingScope | null;
+    workspaceId: UUID | null;
+    principalId: UUID | null;
+    op: RevisionOp;
+    beforeJson: JsonValue | null;
+    afterJson: JsonValue | null;
+    defVersion: number;
+    actor: UUID;
+    originPluginId: string | null;
+    changeSetId: string | null;
+    createdAt: ISODateTime;
+}
+/** The context a resolver/write call is evaluated against. */
+export interface SettingScopeContext {
+    workspaceId?: UUID | undefined;
+    principalId?: UUID | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/settings/types.js

@@ -0,0 +1,3 @@
+/** Scope bitmask values: global=1, workspace=2, user=4. Legal range 1..7. */
+export const SCOPE_BIT = { global: 1, workspace: 2, user: 4 };
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,41 @@
+import type { UUID } from "../primitives/index.js";
+import { type EnsureSettingDefinitionsDeps } from "./ensure-definitions.js";
+/**
+ * @file Boot-time definition registration for the settings-dialog tabs that
+ * need nothing but ledger storage — Instructions, Notifications, and Privacy.
+ *
+ * These three sit together because they are the same shape of problem, not
+ * because they are the same domain: each is a `value` + `onChange` component
+ * from a shared UI library with no async port, so the entire host-side cost
+ * is "register some keys and map them". A tab that needs real backend work
+ * (routes, a port) should keep its own module rather than accreting into
+ * this one.
+ *
+ * All three read and write through the generic settings ledger routes a host
+ * exposes, gated by the ledger's own scope-derived `settings.workspace.write`
+ * check. There is no bespoke get/set service and no per-tab permission — the
+ * reason the shared `ensureSettingDefinitions` helper exists.
+ */
+/** Custom instructions applied to every admin-assistant conversation. */
+export declare const INSTRUCTIONS_NAMESPACE = "core.instructions";
+/** Completion-sound and desktop-notification preferences. */
+export declare const NOTIFICATIONS_NAMESPACE = "core.notifications";
+/** Telemetry consent state. */
+export declare const PRIVACY_NAMESPACE = "core.privacy";
+/** Theme choice and accent color for the settings-dialog surface. */
+export declare const APPEARANCE_NAMESPACE = "core.appearance";
+/** Admin UI locale. */
+export declare const LANGUAGE_NAMESPACE = "core.language";
+export interface EnsureSettingsUiTabDefinitionsInput {
+    /** The trusted boot-time actor these writes are attributed to. */
+    systemPrincipalId: UUID;
+}
+/**
+ * Idempotently registers the Instructions, Notifications, and Privacy
+ * definitions. Safe to call on every boot.
+ *
+ * @complexity O(n) in the total number of definitions (9), each a
+ * skip-if-registered check plus at most one `registerDefinitions` call.
+ */
+export declare function ensureSettingsUiTabDefinitions(deps: EnsureSettingDefinitionsDeps, input: EnsureSettingsUiTabDefinitionsInput): Promise<void>;
+//# sourceMappingURL=ui-tab-definitions.d.ts.map

package/dist/settings/ui-tab-definitions.js

@@ -0,0 +1,148 @@
+import { ensureSettingDefinitions, } from "./ensure-definitions.js";
+import { SCOPE_BIT } from "./types.js";
+/**
+ * @file Boot-time definition registration for the settings-dialog tabs that
+ * need nothing but ledger storage — Instructions, Notifications, and Privacy.
+ *
+ * These three sit together because they are the same shape of problem, not
+ * because they are the same domain: each is a `value` + `onChange` component
+ * from a shared UI library with no async port, so the entire host-side cost
+ * is "register some keys and map them". A tab that needs real backend work
+ * (routes, a port) should keep its own module rather than accreting into
+ * this one.
+ *
+ * All three read and write through the generic settings ledger routes a host
+ * exposes, gated by the ledger's own scope-derived `settings.workspace.write`
+ * check. There is no bespoke get/set service and no per-tab permission — the
+ * reason the shared `ensureSettingDefinitions` helper exists.
+ */
+/** Custom instructions applied to every admin-assistant conversation. */
+export const INSTRUCTIONS_NAMESPACE = "core.instructions";
+/** Completion-sound and desktop-notification preferences. */
+export const NOTIFICATIONS_NAMESPACE = "core.notifications";
+/** Telemetry consent state. */
+export const PRIVACY_NAMESPACE = "core.privacy";
+/** Theme choice and accent color for the settings-dialog surface. */
+export const APPEARANCE_NAMESPACE = "core.appearance";
+/** Admin UI locale. */
+export const LANGUAGE_NAMESPACE = "core.language";
+/**
+ * "No consent decision recorded yet", which a host's UI layer may spell as
+ * `privacyDecisionAt: null`.
+ *
+ * A literal `null` default is not registrable (see `SettingDefinitionSpec.
+ * defaultValue` — non-secret definitions reject a null default outright), so
+ * this needs a sentinel. `0` is safe rather than merely convenient: the field
+ * is epoch milliseconds, and 0 is 1970-01-01, which cannot be a real decision
+ * timestamp for software that did not exist then. The tab uses this exact
+ * distinction — an unset value renders the first-run consent prompt, a set one
+ * renders the "decided" state — so collapsing the two would silently re-prompt
+ * an operator who has already chosen.
+ */
+const NO_DECISION_SENTINEL = 0;
+/**
+ * "No installation id", which a host's UI layer may spell as
+ * `installationId: null` (its meaning: telemetry sharing is fully declined).
+ * `""` is not a legal id — the tab generates opaque non-empty strings — so it
+ * cannot collide with a real one.
+ */
+const NO_INSTALLATION_ID_SENTINEL = "";
+const INSTRUCTIONS_DEFINITIONS = [
+    // A host's `InstructionsTab` may collapse an all-empty textarea to `undefined` rather than `''`
+    // (its `onChange` contract), so the adapter maps that back to this empty-string default instead
+    // of storing a distinguishable "explicitly emptied" state the tab cannot itself produce.
+    { key: "custom", schema: { type: "string" }, defaultValue: "" },
+];
+/**
+ * Notification preferences are the one genuinely PER-OPERATOR surface in this
+ * set, so they register `SCOPE_BIT.user` alongside `workspace` and the adapter
+ * writes at user scope. Two admins sharing a workspace should not fight over
+ * whether a completion sound plays on the other's machine — unlike a tab
+ * whose backing resource is genuinely shared workspace state.
+ *
+ * The `workspace` bit stays in the mask so an operator with no user-scoped row
+ * still inherits a workspace-level default rather than falling all the way
+ * back to the registered one.
+ */
+const NOTIFICATIONS_SCOPES = SCOPE_BIT.user | SCOPE_BIT.workspace;
+const NOTIFICATIONS_DEFINITIONS = [
+    { key: "soundEnabled", schema: { type: "boolean" }, defaultValue: false, scopes: NOTIFICATIONS_SCOPES },
+    // Free-form strings rather than an enum: sound ids are plain strings upstream and the catalog is
+    // owned by a host's UI library. Pinning an enum here would make a package-side catalog addition
+    // fail validation on an already-registered definition, which is a worse failure than accepting an
+    // id the catalog no longer lists (the tab falls back to its own default for an unknown id).
+    { key: "successSoundId", schema: { type: "string" }, defaultValue: "ding", scopes: NOTIFICATIONS_SCOPES },
+    { key: "failureSoundId", schema: { type: "string" }, defaultValue: "buzz", scopes: NOTIFICATIONS_SCOPES },
+    // Desktop notifications also need the BROWSER's Notification permission,
+    // which is per-browser and not ours to store. This flag is only the
+    // operator's intent; the tab reconciles it against the live permission.
+    { key: "desktopEnabled", schema: { type: "boolean" }, defaultValue: false, scopes: NOTIFICATIONS_SCOPES },
+];
+const PRIVACY_DEFINITIONS = [
+    // Both telemetry categories default OFF. A "consent state" type may type them optional, but
+    // "unset" is carried by `decisionAt` instead — an operator who has decided has a timestamp, and
+    // these two then mean exactly what they say.
+    { key: "telemetry.metrics", schema: { type: "boolean" }, defaultValue: false },
+    { key: "telemetry.content", schema: { type: "boolean" }, defaultValue: false },
+    { key: "installationId", schema: { type: "string" }, defaultValue: NO_INSTALLATION_ID_SENTINEL },
+    { key: "decisionAt", schema: { type: "number" }, defaultValue: NO_DECISION_SENTINEL },
+];
+/**
+ * Appearance and Language are per-OPERATOR, same reasoning as Notifications:
+ * which theme one admin looks at, and which language they read, are not
+ * properties of the workspace. The `workspace` bit stays in the mask so an
+ * operator with no user-scoped row still inherits a workspace default.
+ */
+const PER_OPERATOR_SCOPES = SCOPE_BIT.user | SCOPE_BIT.workspace;
+const APPEARANCE_DEFINITIONS = [
+    // Defaults to LIGHT rather than "system" here — a host whose surrounding admin UI is
+    // light-only would put a dark panel inside a light app for every operator on a dark-mode
+    // machine if this defaulted to following the OS. "system" stays selectable; a host can
+    // override this default at its own registration call site if its UI has a real dark variant.
+    {
+        key: "theme",
+        schema: { type: "enum", values: ["system", "light", "dark"] },
+        defaultValue: "light",
+        scopes: PER_OPERATOR_SCOPES,
+    },
+    // Free-form string rather than an enum over a swatch palette: a host's UI may ship a color
+    // picker, so any `#rrggbb` is reachable, and its own accent-color normalizer already rejects
+    // malformed values at render time. Pinning an enum here would reject a legitimate custom color
+    // at the ledger.
+    {
+        key: "accentColor",
+        schema: { type: "string" },
+        defaultValue: "#2563eb",
+        scopes: PER_OPERATOR_SCOPES,
+    },
+];
+const LANGUAGE_DEFINITIONS = [
+    // A BCP-47-ish code, not an enum. The catalog of real locales is a host's own i18n concern, not
+    // this library's; the tab takes a host-supplied `LocaleOption[]` and an unknown stored code
+    // simply selects nothing rather than failing a ledger write.
+    { key: "locale", schema: { type: "string" }, defaultValue: "en", scopes: PER_OPERATOR_SCOPES },
+];
+/**
+ * Idempotently registers the Instructions, Notifications, and Privacy
+ * definitions. Safe to call on every boot.
+ *
+ * @complexity O(n) in the total number of definitions (9), each a
+ * skip-if-registered check plus at most one `registerDefinitions` call.
+ */
+export async function ensureSettingsUiTabDefinitions(deps, input) {
+    const namespaces = [
+        { namespace: INSTRUCTIONS_NAMESPACE, definitions: INSTRUCTIONS_DEFINITIONS },
+        { namespace: NOTIFICATIONS_NAMESPACE, definitions: NOTIFICATIONS_DEFINITIONS },
+        { namespace: PRIVACY_NAMESPACE, definitions: PRIVACY_DEFINITIONS },
+        { namespace: APPEARANCE_NAMESPACE, definitions: APPEARANCE_DEFINITIONS },
+        { namespace: LANGUAGE_NAMESPACE, definitions: LANGUAGE_DEFINITIONS },
+    ];
+    for (const { namespace, definitions } of namespaces) {
+        await ensureSettingDefinitions(deps, {
+            namespace,
+            definitions,
+            systemPrincipalId: input.systemPrincipalId,
+        });
+    }
+}
+//# sourceMappingURL=ui-tab-definitions.js.map