@jini-ai/core 0.4.0 → 0.4.2

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

@@ -0,0 +1,320 @@
+import type { Clock, IdGenerator, JsonValue, UUID } from "../primitives/index.js";
+import type { SettingsPrincipalLookupPort } from "./principal-lookup.js";
+import type { SettingsRepoPort } from "./ports.js";
+import { type DefinitionInput } from "./settings.js";
+import { type SettingScope, type SettingValueSchema } from "./types.js";
+/**
+ * @file `SettingsWriteService` — the single write chokepoint.
+ *
+ * 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) -> validate ->
+ * write value/definition row + revision in one transaction.
+ *
+ * `deriveRequiredPermission` is the sole source of truth for the self-vs-
+ * other permission rule (behavior.spec.md §1.3) — closes Red-Team.
+ * target-principal checks use a host-supplied active-principal lookup over core Principal;
+ * identity and membership policy remain at the host boundary.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+/** Matches `core/commands/command.ts`'s `AuthorizeFn` shape structurally — no import, kept decoupled. */
+export type AuthorizeFn = (params: {
+    principalId: UUID;
+    permission: string;
+    workspaceId: UUID;
+    entityType?: string;
+    entityId?: UUID;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+export interface SettingsWriteServiceDeps {
+    repo: SettingsRepoPort;
+    clock: Clock;
+    ids: IdGenerator;
+    authorize: AuthorizeFn;
+    /** Host lookup must hide disabled and out-of-workspace principals. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+    principals: SettingsPrincipalLookupPort;
+}
+/**
+ * behavior.spec.md §1.3 / `[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 ) — this is the only
+ * place the rule may be encoded.
+ *
+ * @complexity O(1), pure.
+ * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function deriveRequiredPermission(input: {
+    scope: SettingScope;
+    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;
+    };
+}
+/** chokepoint write: authorize `settings.definitions.manage` -> validate -> write + revision, one per definition, each its own tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+export declare function registerDefinitions(required: RegisterDefinitionsRequired): Promise<{
+    registered: string[];
+}>;
+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 ( fail-closed discipline is not relaxed, only
+         * which permission string is checked).
+     * See docs/decisions/DR-003-settings-ledger-invariants.md.
+     */
+        requiredPermissionOverride?: string | undefined;
+    };
+}
+/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+export declare function set(required: SetValueRequired): Promise<{
+    value: JsonValue;
+    revisionSeq: number;
+}>;
+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 — bypasses the inner authorize re-check, still writes a normal revision. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+        skipAuthorize?: boolean | undefined;
+        /** Set by a caller that has ALREADY opened a transaction around this write —
+         *  see `resetNamespace`. Explicit rather than an ambient depth counter,
+         *  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;
+    };
+}
+/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+export declare function clear(required: ClearValueRequired): Promise<{
+    revisionSeq: number;
+}>;
+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;
+    };
+}
+/**
+ * — 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.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+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 : 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").
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+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 ( registry in `settings.ts`) for reading values recorded under any prior version. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+        coercionTag: string;
+        /**
+         * Present only to detect a combined rename+retype request;
+         * 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 : 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.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+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