@jini-ai/cms 0.1.0

package/dist/settings/types.d.ts

@@ -0,0 +1,125 @@
+import type { ISODateTime, JsonValue, UUID } from "../core/ports.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.d.ts.map

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

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/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/settings/types.ts"],"names":[],"mappings":"AAmCA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAW,CAAC"}

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

@@ -0,0 +1,41 @@
+import type { UUID } from "../core/ports.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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-tab-definitions.d.ts","sourceRoot":"","sources":["../../src/settings/ui-tab-definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAEL,KAAK,4BAA4B,EAElC,MAAM,yBAAyB,CAAC;AAGjC;;;;;;;;;;;;;;;GAeG;AAEH,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D,+BAA+B;AAC/B,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD,uBAAuB;AACvB,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAqHlD,MAAM,WAAW,mCAAmC;IAClD,kEAAkE;IAClE,iBAAiB,EAAE,IAAI,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,4BAA4B,EAClC,KAAK,EAAE,mCAAmC,GACzC,OAAO,CAAC,IAAI,CAAC,CAgBf"}

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

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

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

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

@@ -0,0 +1,314 @@
+import type { ClockPort, IdGeneratorPort, JsonValue, UUID } from "../core/ports.js";
+import type { PrincipalRepoPort } from "../identity/index.js";
+import type { SettingsRepoPort } from "./ports.js";
+import { type DefinitionInput } from "./settings.js";
+import { type SettingScope, type SettingValueSchema } from "./types.js";
+/**
+ * @file `SettingsWriteService` — the single write chokepoint (REQ-04).
+ *
+ * Purpose:
+ * The ONLY value/definition-mutation path. Repo write methods
+ * (`saveDefinition`/`save*Value`/`appendRevision`/`delete*Value`) must never
+ * be called from outside this file (Code Review enforces this as a file-
+ * boundary check).
+ *
+ * Every export here: `authorize()` first (fail-closed, INV-07) -> validate ->
+ * write value/definition row + revision in one transaction (INV-01).
+ *
+ * `deriveRequiredPermission` is the sole source of truth for the self-vs-
+ * other permission rule (behavior.spec.md §1.3) — closes Red-Team RT-003.
+ * REQ-13's target-principal check reuses `identity.PrincipalRepoPort`
+ * directly — no new port (closes RT-001/RT-002 at the implementation level).
+ */
+/** Matches `core/commands/command.ts`'s `AuthorizeFn` shape structurally — no import, kept decoupled. */
+export type AuthorizeFn = (params: {
+    principalId: UUID;
+    permission: string;
+    workspaceId: UUID;
+    entityType?: string;
+    entityId?: UUID;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+export interface SettingsWriteServiceDeps {
+    repo: SettingsRepoPort;
+    clock: ClockPort;
+    ids: IdGeneratorPort;
+    authorize: AuthorizeFn;
+    /** REQ-13 — reused directly from `identity`, not duplicated. */
+    principals: PrincipalRepoPort;
+}
+/**
+ * behavior.spec.md §1.3 / REQ-06 `[internal-invariant]` — the self-vs-other
+ * permission derivation. `targetPrincipalId` omitted or equal to the caller
+ * -> `settings.user.self.write`; any other principal -> `settings.user.write`.
+ * A divergence between this function and any other implementation of the
+ * rule is a fail-open authorization bug (Red-Team RT-003) — this is the only
+ * place the rule may be encoded.
+ *
+ * @complexity O(1), pure.
+ * @overallScore 100
+ */
+export declare function deriveRequiredPermission(input: {
+    scope: SettingScope;
+    targetPrincipalId?: UUID | undefined;
+    callerPrincipalId: UUID;
+}): string;
+export interface RegisterDefinitionsRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        definitions: DefinitionInput[];
+        callerPrincipalId: UUID;
+        /** The workspace the caller is authorizing in (always required — even platform-def registration is authorized within a workspace context). */
+        authWorkspaceId: UUID;
+    };
+}
+/** REQ-02/REQ-09 chokepoint write: authorize `settings.definitions.manage` -> validate -> write + revision, one per definition, each its own tx. */
+export declare function registerDefinitions(required: RegisterDefinitionsRequired): Promise<{
+    registered: string[];
+}>;
+export interface SetValueRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        scope: SettingScope;
+        value: JsonValue;
+        workspaceId?: UUID | undefined;
+        principalId?: UUID | undefined;
+        callerPrincipalId: UUID;
+        /**
+         * The ambient workspace to authorize the caller's grant in. Optional and
+         * additive: when omitted, falls back to `input.workspaceId ??
+         * input.callerPrincipalId`. Callers that DO have a real ambient workspace
+         * (every HTTP route in a single-workspace host) should pass it
+         * explicitly: for `scope=global` (no `workspaceId`), falling back to
+         * `callerPrincipalId` as a stand-in "workspace" id is nonsensical against
+         * the real `authorize()` (identity's own authorize looks the principal up
+         * by `{workspaceId, id}` — a bogus workspaceId means `findById` returns
+         * null and every request is denied `principal_disabled`, including the
+         * wildcard-owner).
+         */
+        authWorkspaceId?: UUID | undefined;
+        /**
+         * `deriveRequiredPermission` unconditionally derives `settings.workspace.write` for
+         * `scope: "workspace"` — a caller that already authorized a narrower, domain-specific
+         * permission at its own route layer (e.g. a comments module's `comments.configure`, an SEO
+         * module's `admin.seo.manage`) still hits this chokepoint's generic `settings.workspace.write`
+         * check and gets a masked 500 if it lacks that broader grant, even though its own domain
+         * permission is exactly what the feature's admin UI advertises as sufficient. Optional and
+         * additive: omitted, behavior is unchanged (every pre-existing caller still gets the
+         * scope-derived permission). When a domain-settings module supplies this, the chokepoint
+         * authorizes THIS permission instead of the scope-derived one — still a mandatory
+         * `authorize()` call before any write (INV-07 fail-closed discipline is not relaxed, only
+         * which permission string is checked).
+         */
+        requiredPermissionOverride?: string | undefined;
+    };
+}
+/** REQ-04/REQ-13 chokepoint write: authorize -> validate -> value + revision, same tx. */
+export declare function set(required: SetValueRequired): Promise<{
+    value: JsonValue;
+    revisionSeq: number;
+}>;
+export interface ClearValueRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        scope: SettingScope;
+        workspaceId?: UUID | undefined;
+        principalId?: UUID | undefined;
+        callerPrincipalId: UUID;
+        /** Set by `resetNamespace` when looping `clear()` in its own reset-authorized context (R3-01) — bypasses the inner authorize() re-check, still writes a normal revision. */
+        skipAuthorize?: boolean | undefined;
+        /** Set by a caller that has ALREADY opened a transaction around this write —
+         *  see `resetNamespace`. Explicit rather than an ambient depth counter,
+         *  because an ambient one cannot tell a genuine nesting from a concurrent
+         *  unrelated transaction and silently merges the two. */
+        skipTransaction?: boolean | undefined;
+        /** See `SetValueRequired.input.authWorkspaceId`'s doc. Optional/additive. */
+        authWorkspaceId?: UUID | undefined;
+    };
+}
+/** REQ-04/REQ-13 chokepoint write: authorize -> value + revision (state='cleared'), same tx. */
+export declare function clear(required: ClearValueRequired): Promise<{
+    revisionSeq: number;
+}>;
+export interface ResetNamespaceRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        scope: Exclude<SettingScope, never>;
+        workspaceId?: UUID | undefined;
+        principalId?: UUID | undefined;
+        callerPrincipalId: UUID;
+        /** See `SetValueRequired.input.authWorkspaceId`'s doc. Optional/additive. */
+        authWorkspaceId?: UUID | undefined;
+    };
+}
+/**
+ * EC-09/R3-01 — an explicit, human-invoked orchestrator: authorize
+ * the matching `settings.reset.*` permission once, then loop `clear()` for
+ * every setting in the namespace in the reset-authorized internal context
+ * (`skipAuthorize: true`) — the outer reset permission is sufficient on its
+ * own; each inner clear still emits its own `op='clear'` revision.
+ *
+ * `revisionSeqs` collects each inner `clear()` call's own `revisionSeq` so a
+ * host's admin HTTP route can surface the full contract without a second
+ * read. Existing callers that only read `.clearedCount` are unaffected.
+ */
+export declare function resetNamespace(required: ResetNamespaceRequired, keysInNamespace: string[]): Promise<{
+    clearedCount: number;
+    revisionSeqs: number[];
+}>;
+export interface RenameDefinitionRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        workspaceId: UUID | null;
+        newNamespace: string;
+        newKey: string;
+        callerPrincipalId: UUID;
+        /** The workspace the caller is authorizing in (see `registerDefinitions`' identical field). */
+        authWorkspaceId: UUID;
+    };
+}
+/**
+ * The rename mechanism (AC-09, EC-06): a same-tx pair —
+ * (1) UPDATE the active definition row's `(namespace,key)` to the new name,
+ * same `setting_id`/`version` (ledgered `op='alias'`); (2) INSERT a fresh v1
+ * alias marker at the OLD name pointing at the new name. Because identity
+ * never moves, value rows (keyed on `setting_id` only) stay attached.
+ *
+ * Sequential rename (A->B then B->C) retargets every prior marker pointing
+ * at the OLD name to the NEW name in the same tx. A rename target that
+ * itself resolves to an existing alias is rejected `ALIAS_DEPTH_EXCEEDED`
+ * (behavior.spec.md §7: "the rename target resolves to an alias").
+ *
+ * Never touches `schema`/`defaultValue`/`scopes` -- a pure rename can never
+ * trigger `RENAME_RETYPE_CONFLICT` by construction; that guard lives in
+ * `retypeDefinition` ("no rename+retype in one op").
+ */
+export declare function renameDefinition(required: RenameDefinitionRequired): Promise<{
+    settingId: string;
+    markerSettingId: string;
+}>;
+export interface RetypeDefinitionRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        workspaceId: UUID | null;
+        schema: SettingValueSchema;
+        defaultValue: JsonValue | null;
+        /** A total coercer id/tag (EC-08 registry in `settings.ts`) for reading values recorded under any prior version. */
+        coercionTag: string;
+        /**
+         * Present only to detect a combined rename+retype request;
+         * retype never actually moves `(namespace,key)` -- if provided and it
+         * differs from the current name while `schema` also differs, the whole
+         * op is rejected `RENAME_RETYPE_CONFLICT` rather than silently doing
+         * only the schema half.
+         */
+        newNamespace?: string | undefined;
+        newKey?: string | undefined;
+        callerPrincipalId: UUID;
+        authWorkspaceId: UUID;
+    };
+}
+/**
+ * The retype mechanism (AC-10, EC-05): a same-tx pair --
+ * (1) UPDATE the prior active version's `status` to `deprecated` FIRST (else
+ * the insert in step 2 collides with the one-active-row-per-slot
+ * invariant); (2) INSERT the new `version+1` row as `active`, same
+ * `setting_id`/`namespace`/`key`. Rejected unless every prior version
+ * (2..N) already carries a total coercer -- `coercionTag` is `null` only for
+ * version 1 by construction (`types.ts`), so this walks 2..N and requires
+ * each to be non-null.
+ */
+export declare function retypeDefinition(required: RetypeDefinitionRequired): Promise<{
+    settingId: string;
+    version: number;
+}>;
+export interface ReconcileDefinitionDefaultRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        workspaceId: UUID | null;
+        /** The default the SOURCE declares. Wins over a differing stored default. */
+        defaultValue: JsonValue;
+        callerPrincipalId: UUID;
+        authWorkspaceId: UUID;
+    };
+}
+/**
+ * Reconciles a stored `default_json` that has drifted from the default its
+ * source declares. Idempotent and a no-op when they already agree.
+ *
+ * Why this exists — the bug it closes:
+ * `ensure-definitions.ts` registers each definition once and then skips it
+ * forever (`if (existing) continue;`). That makes a changed `defaultValue` in
+ * SOURCE unreachable in any install that has already booted, for every
+ * settings-dialog tab a host registers this way. It can surface as a stored
+ * default staying "system" in the database while source says "light",
+ * rendering a settings panel with the wrong initial state — a visibly wrong
+ * value produced by entirely correct-looking source. The next occurrence
+ * could be a silently wrong default with no visual tell at all.
+ *
+ * Why `core`-only:
+ * `ownerKind` already encodes who owns a definition. `core` definitions
+ * configure a platform capability and are code-owned, so code is the authority
+ * on their default and may overwrite a drifted stored one. `site` and `theme`
+ * definitions are operator-owned — silently overwriting those would destroy a
+ * deliberate choice, so they are rejected rather than reconciled.
+ *
+ * Why this is NOT a `retype`:
+ * `retype` deprecates the active row and inserts `version+1` because a changed
+ * SCHEMA means every stored value needs a total coercer. A changed DEFAULT
+ * needs none — the schema is untouched, so every stored value stays valid and
+ * only the resolution of UNSET values moves. The row is therefore updated in
+ * place at the same version, and the paired revision carries the old and new
+ * default in `beforeJson`/`afterJson` so the change is auditable.
+ *
+ * @complexity O(1) — one definition lookup plus at most one row update and one
+ * revision append, in a single transaction.
+ */
+export declare function reconcileDefinitionDefault(required: ReconcileDefinitionDefaultRequired): Promise<{
+    settingId: string;
+    changed: boolean;
+}>;
+export interface DeprecateDefinitionRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        workspaceId: UUID | null;
+        callerPrincipalId: UUID;
+        authWorkspaceId: UUID;
+    };
+}
+export interface TombstoneDefinitionRequired {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        workspaceId: UUID | null;
+        callerPrincipalId: UUID;
+        authWorkspaceId: UUID;
+    };
+}
+/** Flips the active definition's status to `deprecated`, ledgered `op='deprecate'` -- same-tx, chokepoint-gated. */
+export declare function deprecateDefinition(required: DeprecateDefinitionRequired): Promise<{
+    settingId: string;
+    version: number;
+}>;
+/** Flips the active definition's status to `tombstone` (kills a core key), ledgered `op='tombstone'` -- same-tx, chokepoint-gated. */
+export declare function tombstoneDefinition(required: TombstoneDefinitionRequired): Promise<{
+    settingId: string;
+    version: number;
+}>;
+//# sourceMappingURL=write-service.d.ts.map