@jini-ai/cms 0.1.0

package/dist/server/index.js

@@ -0,0 +1,28 @@
+/**
+ * @file `@jini-ai/cms/server` — the Node-bound half of the CMS capability.
+ *
+ * PLACEHOLDER. Nothing has been ported yet.
+ *
+ * ## What belongs here
+ *
+ * Concrete implementations of the ports declared in `../core`: SQLite/Postgres repositories,
+ * filesystem blob stores, image transformers — anything that imports `node:*` or a native
+ * dependency. This layer depends on `../core`; the reverse is a boundary violation.
+ *
+ * ## What does NOT belong here
+ *
+ * HTTP routing and request/response handling. The source repo's `src/server/**` is an Express
+ * composition root and is explicitly out of scope for this port — Jini already has
+ * `@jini-ai/http-kit` and `@jini-ai/server` for transport. Porting those routes here would
+ * reproduce exactly the coupling this package's layer split exists to prevent (see
+ * `../core/index.ts`'s header for the measurements).
+ *
+ * The name of this subpath is `/server` for consistency with `@jini-ai/admin`'s Node layer, which
+ * uses the same convention. It means "the Node-bound layer", not "the HTTP server".
+ */
+/**
+ * Layer marker — same rationale as `CMS_CORE_LAYER`, and delete it on the same terms: once a real
+ * adapter is exported from here, this has no purpose.
+ */
+export const CMS_SERVER_LAYER = 'server';
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAiB,CAAC"}

package/dist/settings/agent-tools.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @file The Settings domain's agent-tool catalog, instantiating the naming/callability
+ * convention every other domain catalog in this package already uses.
+ *
+ * Purpose:
+ * A static, in-process catalog describing every agent-callable tool this domain exposes. Settings
+ * is, by design, a broad key/value surface — a typical human admin screen for it is an uncurated,
+ * free-text editor: the operator types ANY namespace string to load it and edits values through a
+ * raw-JSON textarea, with no schema-exposing endpoint feeding a typed control. There is no fixed,
+ * curated list of named settings on that surface to wire tools against.
+ *
+ * That disqualifies every GENERIC write in this domain from being wired here:
+ * - `SETTINGS_SET`/`SETTINGS_CLEAR` let a caller write/clear the value of any registered
+ *   namespace+key at any scope it can name — exactly the generic "set any setting key" tool this
+ *   dispatch's brief prohibits outright, regardless of the write path's own schema validation
+ *   (validation constrains VALUE shape, not WHICH key can be targeted).
+ *
+ * One curated write IS wired, and it is not a weaker `settings_set`: `ui-tab-definitions.ts`
+ * registers a fixed, statically-declared list, because the settings-dialog tabs need named keys to
+ * bind to. `SETTINGS_SET_UI_PREFERENCE` below wires a seven-key subset of that list
+ * (`agent-writable-preferences.ts`):
+ *
+ * - Its `setting` parameter is a JSON Schema `enum`, so WHICH key is targeted is constrained by
+ *   the same mechanism as everything else — the exact gap the paragraph above identifies. The
+ *   ledger's registered definition schema still bounds the VALUE, so both halves are covered.
+ * - It exposes no `scope` and no `principalId`. Every write is `scope: "user"` against the
+ *   caller's own principal, which derives `settings.user.self.write` — the narrowest write grant
+ *   in the system — and makes writing another operator's preferences unrepresentable rather than
+ *   merely unauthorized.
+ * - The keys are per-operator display preferences (locale, theme, accent, notification sounds),
+ *   each reversible in one call and visible in the admin UI the moment it changes.
+ *
+ * The generic setter stays excluded, permanently and for its original reason. Nothing above is
+ * evidence that the other three writes may now be wired:
+ * - `SETTINGS_RESET` is broader still: a single call clears every value in an operator-named
+ *   namespace at a scope — typically described in a host's own confirmation dialog as
+ *   irreversible.
+ * - `SETTINGS_REGISTER_DEFINITIONS` is schema-level, not value-level: it can rename/retype/
+ *   deprecate/tombstone the DEFINITION a key resolves through, changing how every existing stored
+ *   value for that key is interpreted platform-wide.
+ *
+ * Reads are a different risk class and are wired: `SETTINGS_LIST_DEFINITIONS`/
+ * `SETTINGS_GET_EFFECTIVE`/`SETTINGS_GET_RAW` cannot mutate anything, are gated by the same real
+ * `authorize()` permissions an admin UI's own reads use (including the cross-principal
+ * `settings.user.read` check), and cannot surface a secret value even in principle —
+ * `settings.ts`'s `validateDefinitionInput` unconditionally refuses `secret:true` at registration
+ * time (REQ-09/INV-08), so no secret setting can exist in this library's current state to leak.
+ *
+ * How it relates to a host:
+ * A host's tool-registration layer consumes this catalog to decide which tool names an agent
+ * session may even see; `authorize()` enforces the actual permission checks at call time — this
+ * module only declares the catalog shape, it performs no I/O and no enforcement itself.
+ *
+ * Architectural role:
+ * `settings` domain logic. Depends only on its own sibling `agent-writable-preferences.ts` (for
+ * the curated write's enum) — no I/O, no enforcement.
+ */
+export type AgentToolSideEffect = "none" | "mutates-durable-state" | "mints-token";
+export interface AgentToolDefinition {
+    name: string;
+    description: string;
+    sideEffects: AgentToolSideEffect;
+    authorization: {
+        permission: string;
+    };
+    /**
+     * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
+     * (a host's tool-registration layer refuses to wire any tool lacking one). Optional — the four
+     * write entries this file documents but never wires (see file header) carry no schema at all,
+     * since one is never published for a tool the model never sees.
+     */
+    inputSchema?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The Settings domain's fixed agent-tool catalog — the three reads, one curated write
+ * (`settings_set_ui_preference`), and four generic writes documented but deliberately never
+ * wired. See file header.
+ *
+ * @complexity O(1) — a fixed, statically-defined list.
+ * @overallScore 100
+ */
+export declare function getSettingsAgentToolCatalog(): AgentToolDefinition[];
+//# sourceMappingURL=agent-tools.d.ts.map

package/dist/settings/agent-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools.d.ts","sourceRoot":"","sources":["../../src/settings/agent-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAIH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,uBAAuB,GAAG,aAAa,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,mBAAmB,CAAC;IACjC,aAAa,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjD;AAyED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,IAAI,mBAAmB,EAAE,CAyEnE"}

package/dist/settings/agent-tools.js

@@ -0,0 +1,200 @@
+/**
+ * @file The Settings domain's agent-tool catalog, instantiating the naming/callability
+ * convention every other domain catalog in this package already uses.
+ *
+ * Purpose:
+ * A static, in-process catalog describing every agent-callable tool this domain exposes. Settings
+ * is, by design, a broad key/value surface — a typical human admin screen for it is an uncurated,
+ * free-text editor: the operator types ANY namespace string to load it and edits values through a
+ * raw-JSON textarea, with no schema-exposing endpoint feeding a typed control. There is no fixed,
+ * curated list of named settings on that surface to wire tools against.
+ *
+ * That disqualifies every GENERIC write in this domain from being wired here:
+ * - `SETTINGS_SET`/`SETTINGS_CLEAR` let a caller write/clear the value of any registered
+ *   namespace+key at any scope it can name — exactly the generic "set any setting key" tool this
+ *   dispatch's brief prohibits outright, regardless of the write path's own schema validation
+ *   (validation constrains VALUE shape, not WHICH key can be targeted).
+ *
+ * One curated write IS wired, and it is not a weaker `settings_set`: `ui-tab-definitions.ts`
+ * registers a fixed, statically-declared list, because the settings-dialog tabs need named keys to
+ * bind to. `SETTINGS_SET_UI_PREFERENCE` below wires a seven-key subset of that list
+ * (`agent-writable-preferences.ts`):
+ *
+ * - Its `setting` parameter is a JSON Schema `enum`, so WHICH key is targeted is constrained by
+ *   the same mechanism as everything else — the exact gap the paragraph above identifies. The
+ *   ledger's registered definition schema still bounds the VALUE, so both halves are covered.
+ * - It exposes no `scope` and no `principalId`. Every write is `scope: "user"` against the
+ *   caller's own principal, which derives `settings.user.self.write` — the narrowest write grant
+ *   in the system — and makes writing another operator's preferences unrepresentable rather than
+ *   merely unauthorized.
+ * - The keys are per-operator display preferences (locale, theme, accent, notification sounds),
+ *   each reversible in one call and visible in the admin UI the moment it changes.
+ *
+ * The generic setter stays excluded, permanently and for its original reason. Nothing above is
+ * evidence that the other three writes may now be wired:
+ * - `SETTINGS_RESET` is broader still: a single call clears every value in an operator-named
+ *   namespace at a scope — typically described in a host's own confirmation dialog as
+ *   irreversible.
+ * - `SETTINGS_REGISTER_DEFINITIONS` is schema-level, not value-level: it can rename/retype/
+ *   deprecate/tombstone the DEFINITION a key resolves through, changing how every existing stored
+ *   value for that key is interpreted platform-wide.
+ *
+ * Reads are a different risk class and are wired: `SETTINGS_LIST_DEFINITIONS`/
+ * `SETTINGS_GET_EFFECTIVE`/`SETTINGS_GET_RAW` cannot mutate anything, are gated by the same real
+ * `authorize()` permissions an admin UI's own reads use (including the cross-principal
+ * `settings.user.read` check), and cannot surface a secret value even in principle —
+ * `settings.ts`'s `validateDefinitionInput` unconditionally refuses `secret:true` at registration
+ * time (REQ-09/INV-08), so no secret setting can exist in this library's current state to leak.
+ *
+ * How it relates to a host:
+ * A host's tool-registration layer consumes this catalog to decide which tool names an agent
+ * session may even see; `authorize()` enforces the actual permission checks at call time — this
+ * module only declares the catalog shape, it performs no I/O and no enforcement itself.
+ *
+ * Architectural role:
+ * `settings` domain logic. Depends only on its own sibling `agent-writable-preferences.ts` (for
+ * the curated write's enum) — no I/O, no enforcement.
+ */
+import { AGENT_WRITABLE_PREFERENCE_IDS, AGENT_WRITABLE_PREFERENCES } from "./agent-writable-preferences.js";
+/** No arguments — `settings_list_definitions` takes none; it always enumerates the caller's own
+ * (boot-wired) workspace's site-owned partition plus the shared platform partition. */
+const NO_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: [],
+    properties: {},
+};
+/** Shared by `settings_get_effective`/`settings_get_raw`: naming a DIFFERENT principal than the
+ * caller requires `settings.user.read` (checked by the handler, not expressed in this schema). */
+const PRINCIPAL_ID_PROPERTY = {
+    type: "string",
+    description: "Read another principal's user-layer value instead of the caller's own. Requires the settings.user.read permission when it names a principal other than the caller. Omit to read the caller's own user layer.",
+};
+const GET_EFFECTIVE_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["namespace"],
+    properties: {
+        namespace: { type: "string", minLength: 1, description: "The settings namespace to enumerate, e.g. 'core.presentation'." },
+        principalId: PRINCIPAL_ID_PROPERTY,
+    },
+};
+const GET_RAW_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["namespace", "key"],
+    properties: {
+        namespace: { type: "string", minLength: 1, description: "The settings namespace the key belongs to, e.g. 'core.presentation'." },
+        key: { type: "string", minLength: 1, description: "The setting key within the namespace." },
+        principalId: PRINCIPAL_ID_PROPERTY,
+    },
+};
+/**
+ * Input schema for `settings_set_ui_preference`.
+ *
+ * The `enum` on `setting` is the load-bearing part and the reason this tool is wireable at all —
+ * it is what makes "which key" a schema-constrained choice rather than free text. Built from
+ * {@link AGENT_WRITABLE_PREFERENCE_IDS} rather than listed here, so the published schema and the
+ * handler's own allowlist check cannot disagree.
+ *
+ * `value` is typed only as "present". Constraining it here would mean restating seven different
+ * per-key schemas that the ledger already holds and already enforces inside the write chokepoint
+ * (`write-service.ts`'s `set()`), and a second copy that drifts is worse than no copy: it would
+ * reject values the ledger accepts, or — far worse — describe as acceptable a shape the ledger
+ * will refuse. The per-key hints below tell the model what to send; the ledger decides.
+ */
+const SET_UI_PREFERENCE_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["setting", "value"],
+    properties: {
+        setting: {
+            type: "string",
+            enum: AGENT_WRITABLE_PREFERENCE_IDS,
+            description: `The preference to set. Legal values and what each expects: ${AGENT_WRITABLE_PREFERENCES.map((p) => `${p.id} — ${p.valueHint}`).join(" | ")}`,
+        },
+        value: {
+            description: "The new value, matching the shape described for the chosen setting. Validated against that setting's registered schema; a mismatch is rejected and nothing is written.",
+        },
+    },
+};
+/**
+ * The Settings domain's fixed agent-tool catalog — the three reads, one curated write
+ * (`settings_set_ui_preference`), and four generic writes documented but deliberately never
+ * wired. See file header.
+ *
+ * @complexity O(1) — a fixed, statically-defined list.
+ * @overallScore 100
+ */
+export function getSettingsAgentToolCatalog() {
+    return [
+        {
+            name: "settings_list_definitions",
+            description: "Lists every active setting definition visible to this workspace (platform core/theme definitions plus this workspace's own site-owned definitions): namespace, key, owner kind, scope bitmask, status, and version. Metadata only — never a value.",
+            sideEffects: "none",
+            authorization: { permission: "settings.read.definitions" },
+            inputSchema: NO_INPUT_SCHEMA,
+        },
+        {
+            name: "settings_get_effective",
+            description: "Returns the effective (precedence-resolved: user, then workspace, then global, then default) value of every active setting registered in a namespace.",
+            sideEffects: "none",
+            authorization: { permission: "settings.read" },
+            inputSchema: GET_EFFECTIVE_SCHEMA,
+        },
+        {
+            name: "settings_get_raw",
+            description: "Returns the per-layer raw values (global, workspace, user, default) of one setting key, unresolved by precedence.",
+            sideEffects: "none",
+            authorization: { permission: "settings.read.raw" },
+            inputSchema: GET_RAW_SCHEMA,
+        },
+        {
+            name: "settings_set_ui_preference",
+            description: "Sets one of the operator's own admin-UI preferences (interface language, theme, accent color, or notification sounds) and returns the stored value. Writes only to the calling operator's own user layer — it cannot target another operator, another scope, or any setting outside its fixed list. Use settings_get_effective to read current values first.",
+            sideEffects: "mutates-durable-state",
+            // The narrowest write grant in the system, and it is what this tool derives BECAUSE it never
+            // names a target principal (`write-service.ts`'s `deriveRequiredPermission`). Declared here
+            // to match; the handler does not pass this string, it lets the chokepoint derive it, so the
+            // two cannot drift into a state where this file advertises a check that is not the one run.
+            authorization: { permission: "settings.user.self.write" },
+            inputSchema: SET_UI_PREFERENCE_SCHEMA,
+        },
+        {
+            // EXCLUDED BY DESIGN, never wired: see this file's header. Generic "set any setting key" —
+            // a typical human admin UI for this domain is an uncurated free-text/raw-JSON editor, not a
+            // fixed named list. `settings_set_ui_preference` above is the curated alternative and does
+            // NOT make this one wireable: the whole difference is that its target key is enum-bounded.
+            name: "settings_set",
+            description: "Sets a setting's value at a scope. NEVER agent-callable — see file header.",
+            sideEffects: "mutates-durable-state",
+            authorization: { permission: "settings.workspace.write" },
+        },
+        {
+            // EXCLUDED BY DESIGN, never wired: see this file's header. Same "generic key" exclusion as
+            // settings_set.
+            name: "settings_clear",
+            description: "Clears a setting's value at a scope, reverting it to default. NEVER agent-callable — see file header.",
+            sideEffects: "mutates-durable-state",
+            authorization: { permission: "settings.workspace.write" },
+        },
+        {
+            // EXCLUDED BY DESIGN, never wired: see this file's header. Bulk variant of settings_clear —
+            // clears every value in an operator-named namespace at a scope in one call, irreversible.
+            name: "settings_reset",
+            description: "Resets every setting in a namespace to defaults at a scope. NEVER agent-callable — see file header.",
+            sideEffects: "mutates-durable-state",
+            authorization: { permission: "settings.reset.workspace" },
+        },
+        {
+            // EXCLUDED BY DESIGN, never wired: see this file's header. Schema-level, not value-level —
+            // can rename/retype/deprecate/tombstone the definition a key resolves through, changing how
+            // every existing stored value for that key is interpreted platform-wide.
+            name: "settings_register_definitions",
+            description: "Registers, renames, retypes, deprecates, or tombstones setting definitions. NEVER agent-callable — see file header.",
+            sideEffects: "mutates-durable-state",
+            authorization: { permission: "settings.definitions.manage" },
+        },
+    ];
+}
+//# sourceMappingURL=agent-tools.js.map

package/dist/settings/agent-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools.js","sourceRoot":"","sources":["../../src/settings/agent-tools.ts"],"names":[],"mappings":"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"}

package/dist/settings/agent-writable-preferences.d.ts

@@ -0,0 +1,67 @@
+/**
+ * One agent-writable preference.
+ *
+ * `namespace`/`key` are the ledger coordinates; `id` is the dotted form published to the model.
+ * They are kept as separate fields rather than split from `id` at call time because a key may
+ * itself contain dots (`telemetry.metrics` in the withheld privacy set proves the split is not
+ * unambiguous), so deriving one from the other would be a latent bug the moment the allowlist grows.
+ */
+export interface AgentWritablePreference {
+    /** The dotted `namespace.key`, published in the tool's `setting` enum. */
+    readonly id: string;
+    readonly namespace: string;
+    readonly key: string;
+    /**
+     * Human-readable hint published alongside the enum, so a model knows what a legal value looks
+     * like without a round trip. NOT a validator — the ledger's registered definition schema is the
+     * only thing that accepts or rejects a value, and it is checked inside the write chokepoint.
+     */
+    readonly valueHint: string;
+}
+/**
+ * The scope every write through this surface uses.
+ *
+ * `user`, always, and never operator-selectable. All seven keys register `user | workspace`
+ * (`ui-tab-definitions.ts`'s `PER_OPERATOR_SCOPES` / `NOTIFICATIONS_SCOPES`), so `workspace` is
+ * reachable in principle — and deliberately not offered. A workspace-scoped write changes the
+ * inherited default for every operator who has no user-scoped row of their own, which is a write
+ * whose blast radius the caller cannot see. The user layer affects exactly one person, and
+ * `write-service.ts`'s `deriveRequiredPermission` gates it behind `settings.user.self.write`, the
+ * narrowest write grant in the system, only because the target principal is left unnamed.
+ */
+export declare const AGENT_PREFERENCE_WRITE_SCOPE: "user";
+/**
+ * Asserted by `__tests__/agent-writable-preferences.test.ts` against `ui-tab-definitions.ts`:
+ * every id below must correspond to a definition that is actually registered AND whose scope mask
+ * includes {@link SCOPE_BIT.user}. That test is the real guard on this file — an entry naming an
+ * unregistered key would otherwise fail only at call time, as a runtime `DefinitionNotFoundError`
+ * from inside the write chokepoint, on a tool the model had already been told it could call.
+ */
+export declare const AGENT_WRITABLE_PREFERENCES: readonly AgentWritablePreference[];
+/**
+ * The `setting` enum published in the tool's input schema.
+ *
+ * Derived from {@link AGENT_WRITABLE_PREFERENCES} rather than written out a second time: a
+ * hand-maintained copy is how an id ends up callable after being removed from the allowlist.
+ *
+ * @complexity O(n) once at module load.
+ */
+export declare const AGENT_WRITABLE_PREFERENCE_IDS: readonly string[];
+/**
+ * Resolves a model-supplied `setting` id to its ledger coordinates.
+ *
+ * Returns `undefined` for anything not on the allowlist — including ids the enum should already
+ * have rejected. The redundancy is the point: the enum lives in a schema a caller validates
+ * against, and this is the check that holds if that validation is ever bypassed, misconfigured, or
+ * outrun by a stale published descriptor. A curated allowlist that is enforced in only one place
+ * is enforced nowhere in particular.
+ *
+ * @param settingId - The dotted `namespace.key` from the tool input.
+ * @returns The matching preference, or `undefined` if it is not agent-writable.
+ * @complexity O(1).
+ * @overallScore 100
+ */
+export declare function resolveAgentWritablePreference(settingId: string): AgentWritablePreference | undefined;
+/** Re-exported so the drift test can assert the scope mask without reaching into `types.ts` itself. */
+export declare const AGENT_PREFERENCE_REQUIRED_SCOPE_BIT: 4;
+//# sourceMappingURL=agent-writable-preferences.d.ts.map

package/dist/settings/agent-writable-preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-writable-preferences.d.ts","sourceRoot":"","sources":["../../src/settings/agent-writable-preferences.ts"],"names":[],"mappings":"AAwDA;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,EAAG,MAAe,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,uBAAuB,EA6CxE,CAAC;AAMF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAAgD,CAAC;AAE5G;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAErG;AAED,uGAAuG;AACvG,eAAO,MAAM,mCAAmC,GAAiB,CAAC"}

package/dist/settings/agent-writable-preferences.js

@@ -0,0 +1,144 @@
+/**
+ * @file The curated list of setting keys an agent may write — the precondition
+ * `agent-tools.ts`'s header names.
+ *
+ * ## Why this file has to exist before any settings write can be wired
+ *
+ * The generic setter (`settings_set`) is excluded from agent callability because there is no fixed,
+ * curated list of named settings to wire tools against for a generic admin surface — an operator
+ * can type any namespace string and edit any value through a raw editor. `ui-tab-definitions.ts`
+ * changes that for one specific slice: it registers a fixed, statically-declared set of keys — each
+ * with a schema, a default, and a scope mask — because the settings-dialog tabs need named keys to
+ * bind to. This module is the subset of THAT list which is safe for an agent to write.
+ *
+ * The exclusion's sharpest objection was that schema validation "constrains the VALUE shape, not
+ * WHICH key is targeted". That is exactly right about the generic setter, and exactly what
+ * {@link AGENT_WRITABLE_PREFERENCE_IDS} fixes: it is published as a JSON Schema `enum`, so the
+ * targeted key is constrained by the same mechanism that constrains everything else in the tool
+ * surface. The two halves together are complete — this file bounds WHICH key, and the ledger's
+ * own registered definition schema bounds the VALUE (`write-service.ts`'s `set()` validates
+ * against it and rejects a mismatch before any write lands).
+ *
+ * So the generic setter stays excluded, permanently and for its original reason. This is the
+ * curated alternative that exclusion explicitly pointed at, not a relaxation of it.
+ *
+ * ## What is deliberately NOT here
+ *
+ * `ui-tab-definitions.ts` registers 12 keys. Five are withheld:
+ *
+ * - **`core.privacy.telemetry.metrics` / `telemetry.content` / `decisionAt` / `installationId`** —
+ *   a telemetry consent record whose entire purpose is to attest that a HUMAN decided. An agent
+ *   writing it would not be recording a decision, it would be manufacturing one, and `decisionAt`
+ *   is specifically the field the tab reads to know whether to stop asking. Withheld because the
+ *   value means something different depending on who wrote it — the one property a curated
+ *   allowlist cannot express.
+ * - **`core.instructions.custom`** — the custom instructions prepended to every admin-assistant
+ *   conversation. An agent writing this edits its own standing prompt for all future runs. That
+ *   may well be worth allowing later, but it is a self-modification question and not a display
+ *   preference, so it does not ride in on the same decision.
+ *
+ * Every key that IS here is a per-operator display preference: reversible in one call, scoped to
+ * the caller's own user layer, and visible in the admin UI the moment it changes — which is what
+ * makes the whole surface auditable by looking at it.
+ *
+ * ## Architectural role
+ *
+ * `settings` domain data. No I/O, no enforcement — `tool-registrations.ts` performs the
+ * `authorize()` call and the write. Kept as data rather than inlined into the catalog so the tool
+ * schema, the handler's dispatch, and the drift test all read the same source.
+ */
+import { SCOPE_BIT } from "./types.js";
+import { APPEARANCE_NAMESPACE, LANGUAGE_NAMESPACE, NOTIFICATIONS_NAMESPACE, } from "./ui-tab-definitions.js";
+/**
+ * The scope every write through this surface uses.
+ *
+ * `user`, always, and never operator-selectable. All seven keys register `user | workspace`
+ * (`ui-tab-definitions.ts`'s `PER_OPERATOR_SCOPES` / `NOTIFICATIONS_SCOPES`), so `workspace` is
+ * reachable in principle — and deliberately not offered. A workspace-scoped write changes the
+ * inherited default for every operator who has no user-scoped row of their own, which is a write
+ * whose blast radius the caller cannot see. The user layer affects exactly one person, and
+ * `write-service.ts`'s `deriveRequiredPermission` gates it behind `settings.user.self.write`, the
+ * narrowest write grant in the system, only because the target principal is left unnamed.
+ */
+export const AGENT_PREFERENCE_WRITE_SCOPE = "user";
+/**
+ * Asserted by `__tests__/agent-writable-preferences.test.ts` against `ui-tab-definitions.ts`:
+ * every id below must correspond to a definition that is actually registered AND whose scope mask
+ * includes {@link SCOPE_BIT.user}. That test is the real guard on this file — an entry naming an
+ * unregistered key would otherwise fail only at call time, as a runtime `DefinitionNotFoundError`
+ * from inside the write chokepoint, on a tool the model had already been told it could call.
+ */
+export const AGENT_WRITABLE_PREFERENCES = [
+    {
+        id: "core.language.locale",
+        namespace: LANGUAGE_NAMESPACE,
+        key: "locale",
+        valueHint: "A BCP-47 language code the admin UI ships a translation for, e.g. 'en' or 'es'. An unrecognized code is stored but selects no option in the UI.",
+    },
+    {
+        id: "core.appearance.theme",
+        namespace: APPEARANCE_NAMESPACE,
+        key: "theme",
+        valueHint: "One of 'system', 'light', or 'dark'.",
+    },
+    {
+        id: "core.appearance.accentColor",
+        namespace: APPEARANCE_NAMESPACE,
+        key: "accentColor",
+        valueHint: "A hex color, e.g. '#2563eb'. Malformed values are rejected at render time.",
+    },
+    {
+        id: "core.notifications.soundEnabled",
+        namespace: NOTIFICATIONS_NAMESPACE,
+        key: "soundEnabled",
+        valueHint: "Boolean — whether a sound plays when an assistant run finishes.",
+    },
+    {
+        id: "core.notifications.successSoundId",
+        namespace: NOTIFICATIONS_NAMESPACE,
+        key: "successSoundId",
+        valueHint: "Sound id for a successful run, e.g. 'ding'. An unknown id falls back to the default.",
+    },
+    {
+        id: "core.notifications.failureSoundId",
+        namespace: NOTIFICATIONS_NAMESPACE,
+        key: "failureSoundId",
+        valueHint: "Sound id for a failed run, e.g. 'buzz'. An unknown id falls back to the default.",
+    },
+    {
+        id: "core.notifications.desktopEnabled",
+        namespace: NOTIFICATIONS_NAMESPACE,
+        key: "desktopEnabled",
+        valueHint: "Boolean — the operator's INTENT to receive desktop notifications. The browser's own Notification permission is separate and not settable from here.",
+    },
+];
+const BY_ID = new Map(AGENT_WRITABLE_PREFERENCES.map((pref) => [pref.id, pref]));
+/**
+ * The `setting` enum published in the tool's input schema.
+ *
+ * Derived from {@link AGENT_WRITABLE_PREFERENCES} rather than written out a second time: a
+ * hand-maintained copy is how an id ends up callable after being removed from the allowlist.
+ *
+ * @complexity O(n) once at module load.
+ */
+export const AGENT_WRITABLE_PREFERENCE_IDS = AGENT_WRITABLE_PREFERENCES.map((p) => p.id);
+/**
+ * Resolves a model-supplied `setting` id to its ledger coordinates.
+ *
+ * Returns `undefined` for anything not on the allowlist — including ids the enum should already
+ * have rejected. The redundancy is the point: the enum lives in a schema a caller validates
+ * against, and this is the check that holds if that validation is ever bypassed, misconfigured, or
+ * outrun by a stale published descriptor. A curated allowlist that is enforced in only one place
+ * is enforced nowhere in particular.
+ *
+ * @param settingId - The dotted `namespace.key` from the tool input.
+ * @returns The matching preference, or `undefined` if it is not agent-writable.
+ * @complexity O(1).
+ * @overallScore 100
+ */
+export function resolveAgentWritablePreference(settingId) {
+    return BY_ID.get(settingId);
+}
+/** Re-exported so the drift test can assert the scope mask without reaching into `types.ts` itself. */
+export const AGENT_PREFERENCE_REQUIRED_SCOPE_BIT = SCOPE_BIT.user;
+//# sourceMappingURL=agent-writable-preferences.js.map

package/dist/settings/agent-writable-preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-writable-preferences.js","sourceRoot":"","sources":["../../src/settings/agent-writable-preferences.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAuBjC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAe,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAuC;IAC5E;QACE,EAAE,EAAE,sBAAsB;QAC1B,SAAS,EAAE,kBAAkB;QAC7B,GAAG,EAAE,QAAQ;QACb,SAAS,EACP,iJAAiJ;KACpJ;IACD;QACE,EAAE,EAAE,uBAAuB;QAC3B,SAAS,EAAE,oBAAoB;QAC/B,GAAG,EAAE,OAAO;QACZ,SAAS,EAAE,sCAAsC;KAClD;IACD;QACE,EAAE,EAAE,6BAA6B;QACjC,SAAS,EAAE,oBAAoB;QAC/B,GAAG,EAAE,aAAa;QAClB,SAAS,EAAE,4EAA4E;KACxF;IACD;QACE,EAAE,EAAE,iCAAiC;QACrC,SAAS,EAAE,uBAAuB;QAClC,GAAG,EAAE,cAAc;QACnB,SAAS,EAAE,iEAAiE;KAC7E;IACD;QACE,EAAE,EAAE,mCAAmC;QACvC,SAAS,EAAE,uBAAuB;QAClC,GAAG,EAAE,gBAAgB;QACrB,SAAS,EAAE,sFAAsF;KAClG;IACD;QACE,EAAE,EAAE,mCAAmC;QACvC,SAAS,EAAE,uBAAuB;QAClC,GAAG,EAAE,gBAAgB;QACrB,SAAS,EAAE,kFAAkF;KAC9F;IACD;QACE,EAAE,EAAE,mCAAmC;QACvC,SAAS,EAAE,uBAAuB;QAClC,GAAG,EAAE,gBAAgB;QACrB,SAAS,EACP,qJAAqJ;KACxJ;CACF,CAAC;AAEF,MAAM,KAAK,GAAiD,IAAI,GAAG,CACjE,0BAA0B,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAC1D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAsB,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAE5G;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,8BAA8B,CAAC,SAAiB;IAC9D,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC;AAED,uGAAuG;AACvG,MAAM,CAAC,MAAM,mCAAmC,GAAG,SAAS,CAAC,IAAI,CAAC"}

package/dist/settings/change-feed.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @file Decides which ledger revisions a given caller may be TOLD about, and which namespaces that
+ * implies. Kept as pure logic here so a host's transport layer (an SSE/polling route, a websocket
+ * push) can be tested without an HTTP server or a clock.
+ *
+ * ## Why a change feed exists at all
+ *
+ * A settings write made in one process is invisible to an already-rendered admin tab in another.
+ * That is true for a background daemon (a separate OS process) and equally true for a second
+ * browser tab, another operator, or a background job. The revision ledger is the one place every
+ * write lands regardless of who made it, and its `seq` is a monotonic autoincrement in shared
+ * storage — so polling it is cross-process by construction, needing no IPC and no message broker.
+ *
+ * ## The disclosure rule
+ *
+ * A subscriber must not learn that settings it cannot read have changed. Even a bare namespace name
+ * is a signal — "someone else's preferences just changed" is information the caller was never
+ * granted. {@link isRevisionVisibleTo} is therefore an allowlist, not a denylist: an unrecognized
+ * scope is withheld rather than passed through, so a future scope added to `SettingScope` is
+ * invisible until someone decides what it should mean here.
+ *
+ * Nothing in the emitted payload carries a VALUE. Subscribers receive namespace names and re-read
+ * through the ordinary authorized read path, which is what keeps this module's responsibility
+ * narrow: it decides who hears that something moved, never what it moved to.
+ */
+import type { SettingRevisionRecord } from "./types.js";
+/** The caller a change feed is being filtered for. */
+export interface ChangeFeedViewer {
+    /** The workspace whose admin surface is subscribed. */
+    workspaceId: string;
+    /** The subscribing principal — the only one whose user-layer changes are disclosed. */
+    principalId: string;
+}
+/**
+ * Whether `revision` may be disclosed to `viewer`.
+ *
+ * - **`global`** — platform-wide values every workspace resolves through. Disclosed.
+ * - **`workspace`** — disclosed only for the viewer's own workspace (tenant scoping).
+ * - **`user`** — disclosed only when the viewer IS the target principal. Another operator's
+ *   preference changing is not the viewer's business, and telling them would leak both that the
+ *   other principal exists and that they are active right now.
+ * - **definition revisions** (`entityKind: 'definition'`, which carry `scope: null`) — these
+ *   retype, rename, deprecate, or tombstone a definition, changing how every stored value for that
+ *   key is interpreted. Workspace-scoped by the definition's own `workspaceId`, with `null` meaning
+ *   a platform definition visible to all.
+ *
+ * @complexity O(1).
+ * @overallScore 100
+ */
+export declare function isRevisionVisibleTo(revision: SettingRevisionRecord, viewer: ChangeFeedViewer): boolean;
+/** One batch of visible changes, plus the cursor a subscriber resumes from. */
+export interface ChangeFeedBatch {
+    /** Namespaces to re-read, de-duplicated. Empty when nothing visible changed. */
+    namespaces: string[];
+    /** The highest `seq` examined — advanced even when nothing was visible, so a stream of writes the
+     *  viewer cannot see does not make it re-examine them forever. */
+    cursor: number;
+}
+/**
+ * Reduces raw revisions into the namespaces `viewer` should re-read.
+ *
+ * `resolveNamespace` returns `null` for a revision whose definition can no longer be resolved (a
+ * tombstoned or since-deleted setting). Those advance the cursor but emit nothing: there is no
+ * namespace to name, and inventing one would send subscribers chasing a key that is gone.
+ *
+ * @param revisions - Ledger rows, ascending by `seq`.
+ * @param viewer - The subscriber to filter for.
+ * @param resolveNamespace - Maps a `settingId` to its namespace, or `null` if unresolvable.
+ * @returns The namespaces to refresh and the cursor to resume from.
+ * @complexity O(n) in `revisions`, plus one `resolveNamespace` per visible revision.
+ * @overallScore 100
+ */
+export declare function collectChangedNamespaces(revisions: readonly SettingRevisionRecord[], viewer: ChangeFeedViewer, resolveNamespace: (settingId: string) => Promise<string | null>): Promise<ChangeFeedBatch>;
+//# sourceMappingURL=change-feed.d.ts.map

package/dist/settings/change-feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-feed.d.ts","sourceRoot":"","sources":["../../src/settings/change-feed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,qBAAqB,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAgBtG;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;sEACkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,SAAS,qBAAqB,EAAE,EAC3C,MAAM,EAAE,gBAAgB,EACxB,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAC9D,OAAO,CAAC,eAAe,CAAC,CAY1B"}