@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.5

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

@@ -0,0 +1,616 @@
+import { ConfigService } from '@nestjs/config';
+import type { SettingsPrisma } from '../data/settings-db';
+import { type ComposedPatchBody, type ComposedUpdateBody } from '../registry/compose';
+import { type SystemSettingsNamespace, type SystemSettingsNamespaceOf, type SystemSettingsNamespaceValue, type SystemSettingsValue } from '../registry/system-settings-namespace';
+import type { SystemSettingsNamespaces } from '../index';
+import { type ResolvedSettingsModuleOptions } from '../settings.options';
+/**
+ * What `GET`, `PUT` and `PATCH /api/system-settings` return (inside the
+ * `{ data }` envelope): every registered namespace, the derived session
+ * policy, the audit fields and the row version for `If-Match`.
+ *
+ * @stability stable
+ */
+export type SystemSettingsResponse = SystemSettingsValue & SystemSettingsResponseCore;
+/**
+ * The core fields of {@link SystemSettingsResponse}, around the namespaces.
+ *
+ * @stability stable
+ */
+export interface SystemSettingsResponseCore {
+    /** The session policy the token signer uses: derived configuration, never stored. */
+    security: {
+        /** The access token's lifetime, in minutes. */
+        jwtAccessTtlMinutes: number;
+        /** The refresh token's lifetime, in days. */
+        refreshTtlDays: number;
+    };
+    /** When the row last changed. */
+    updatedAt: Date;
+    /** Who last changed it, or `null`. */
+    updatedBy: {
+        /** The user's id. */
+        id: string;
+        /** The user's email. */
+        email: string;
+    } | null;
+    /** The row version. */
+    version: number;
+}
+/**
+ * The deployment-wide settings document: the one `system_settings` row
+ * (`key = 'global'`, `SettingsModuleOptions.systemRowKey`), validated
+ * namespace by namespace against the system namespace registry. `GET`, `PUT`
+ * and `PATCH /api/system-settings` go through it; every slice reads its own
+ * namespace through {@link SystemSettingsService.getNamespace}.
+ *
+ * Behaviour (moved unchanged from the reference app by #733): request bodies
+ * stay closed, the stored value is never narrowed (unknown keys are carried
+ * forward and reported in the log and the audit meta), a damaged stored value
+ * degrades field by field to the namespace defaults, a stale `If-Match` is a
+ * 409, and every write is audited.
+ *
+ * @stability stable
+ */
+export declare class SystemSettingsService {
+    private readonly prisma;
+    private readonly configService;
+    private readonly logger;
+    private readonly rowKey;
+    constructor(prisma: SettingsPrisma, configService: ConfigService, options?: ResolvedSettingsModuleOptions);
+    /**
+     * Load the 'global' row, creating it with defaults if it is missing.
+     *
+     * Extracted so the read path and the PATCH path share one definition of
+     * "the current row" — PATCH needs the RAW stored value (to see the keys the
+     * projection hides), not the projection, and before #130 it had no way to
+     * ask for it: it called `getSettings()` and could only ever see the modelled
+     * namespaces. That is not incidental to the bug, it IS the bug.
+     */
+    private loadOrCreateRow;
+    /**
+     * The ONE place this file is allowed to turn a JSONB value into an object.
+     *
+     * `system_settings.value` is a JSONB column: at runtime it can be a string,
+     * a number, a boolean, an array, SQL NULL or JSON `null`, no matter what
+     * Prisma's generated type or a hand-written cast claims. Every read below
+     * funnels through here so that "is this actually a plain object?" is asked
+     * once, in one way, instead of being assumed in some paths and checked in
+     * others — which is exactly the split that let #130's follow-up bug through
+     * (PUT checked, PATCH cast and dereferenced).
+     *
+     * Arrays are rejected along with primitives: an array IS an object to
+     * `typeof`, but treating one as a settings map would spread its indices in
+     * as keys, and `['a']` becoming `{ '0': 'a' }` in the row is data corruption
+     * dressed up as tolerance.
+     */
+    private asPlainObject;
+    /**
+     * Project a raw stored value down to the shape this code models, falling
+     * back to the seeded defaults for anything missing or of the wrong type.
+     *
+     * WHY THIS EXISTS (#130 follow-up). The rule the issue settled on is that a
+     * malformed stored value must not make settings unsavable: an admin whose
+     * row is `null`, or a string, or `{ notifications: 42 }`, must still be able
+     * to repair it through the API. `mergePreservingUnknown` and
+     * `collectUnknownKeys` were written to honour that and do; `patchSettings`
+     * never reached them, because it first did
+     * `row.value as unknown as SystemSettingsValue` and then read nested fields straight off it. A cast is
+     * not a check — it asserts a shape nobody verified — so a `null` row threw
+     * `TypeError: Cannot read properties of null` before a single defensive line
+     * ran. PUT was unaffected only because it happens never to
+     * touch the stored value except through the guarded helper.
+     *
+     * So there are no `as unknown as SystemSettingsValue` casts left in this
+     * file. Every read of the column goes through here, which means the type
+     * annotation is now earned rather than asserted.
+     *
+     * FIELD BY FIELD, NOT ALL-OR-NOTHING. A row where only `jobs` is corrupt
+     * keeps its good `notifications` value; a row that is wholly unusable yields
+     * `DEFAULT_SYSTEM_SETTINGS`. Degrading per field means a partially damaged
+     * row loses only the damaged part, and a PATCH over it writes the caller's
+     * changes on top of sane defaults — the same outcome PUT already produces.
+     *
+     * INVALID VALUES OF KNOWN KEYS ARE DROPPED, and that is not in tension with
+     * preserving unknown keys. A value of a KNOWN key that fails its schema
+     * cannot survive `systemSettingsSchema.parse` under any code path, so
+     * carrying it into `merged` would only convert the old TypeError into a
+     * ZodError and leave the row just as unrepairable. Genuinely unknown keys —
+     * top level or inside a closed namespace — are untouched here and still
+     * carried forward verbatim by `mergePreservingUnknown`, which reads the RAW
+     * value, not this projection.
+     */
+    private readKnownSettings;
+    /**
+     * The helpers a namespace's own `read` receives (`SettingsReadHelpers`).
+     * They stay here, in the service, and are lent rather than imported, so a
+     * declaration file never depends on this service.
+     */
+    private readonly readHelpers;
+    /**
+     * Project one stored namespace down to something its schema will accept,
+     * field by field, falling back to that namespace's defaults (#256).
+     *
+     * WHY A HELPER AND NOT FOUR MORE LADDERS. `notifications` is read by hand
+     * above because it is two fields; the four operations
+     * namespaces are twenty-three between them, and twenty-three hand-written
+     * `typeof x === 'number' ? x : DEFAULT...` lines is twenty-three chances to
+     * name the wrong default. This asks each field's own schema instead, so the
+     * check and the declaration cannot disagree — a bound tightened in
+     * `settings.schema.ts` tightens what survives a damaged row too, with nothing
+     * to update here.
+     *
+     * FIELD BY FIELD FOR THE REASON `readKnownSettings` IS: a row where one
+     * number is corrupt keeps every other value an operator set, rather than
+     * having the whole namespace snap back to the defaults. The granularity is
+     * one level — `jobs.history` is validated as a unit, so a bad
+     * `retentionDays` costs the `purgeEnabled` next to it. That is the same depth
+     * the merge and the preservation work at, and matching them is worth more
+     * than one extra level of salvage.
+     *
+     * THE FALLBACK IS CLONED, never handed out by reference:
+     * `DEFAULT_SYSTEM_SETTINGS` is a module-level constant, and returning its
+     * nested `history` object to a caller that merges into it and persists it is
+     * a mutation bug waiting on the first caller that does. Same rule
+     * `readDisabledEvents` follows for its array.
+     */
+    private readNamespace;
+    /**
+     * Project a stored string list down to something its namespace's schema
+     * will accept, entry by entry (#225; generalised by #733 from the
+     * `notifications.disabledEvents` reader, its first user).
+     *
+     * Same argument as "INVALID VALUES OF KNOWN KEYS ARE DROPPED" above, one
+     * level deeper: an entry that fails its pattern, or a list longer than the
+     * cap, would convert a repairable row into a ZodError and leave the admin
+     * unable to save anything at all. Dropping the unusable entries keeps the
+     * row repairable through the API.
+     *
+     * A fresh array every call, never a shared default: handing out the same
+     * array reference to be merged into and persisted is a mutation bug waiting
+     * on the first caller that pushes to it.
+     */
+    private readStringArray;
+    /**
+     * Collect the entries of `stored` whose keys are not in `knownKeys`.
+     *
+     * Defensive about the input type on purpose, via `asPlainObject`: anything
+     * that is not a plain object contributes no keys rather than throwing — a
+     * malformed row must not make settings unsavable, which is the failure mode
+     * this whole change exists to avoid.
+     */
+    private collectUnknownKeys;
+    /**
+     * Produce the object to persist: the validated known settings, with every
+     * unrecognised key of the currently stored value laid back underneath.
+     *
+     * Spread order is load-bearing. The unknown keys go FIRST so that `validated`
+     * always wins: if a key is known, the caller's (validated) value is
+     * authoritative and the stored one is replaced, which is what preserves the
+     * existing behaviour of every modelled namespace byte for byte. The unknown keys
+     * can only ever fill slots `validated` does not occupy.
+     *
+     * Returns the preserved paths alongside the value so the caller can put them
+     * in the log and the audit meta. That reporting is not decoration: #130's
+     * complaint is as much "nothing in the audit trail" as it is the data loss,
+     * and a key silently surviving is only marginally better than a key silently
+     * disappearing — either way nobody learns that this row holds something the
+     * code does not model.
+     */
+    private mergePreservingUnknown;
+    /**
+     * Report preserved keys once per write, on the log line and in the audit
+     * meta. Omitted entirely when there is nothing to report so the audit rows
+     * of a normal deployment (where the modelled namespaces are all there is) stay
+     * exactly as they were.
+     */
+    private reportPreserved;
+    /**
+     * The `security` block of the response: DERIVED CONFIGURATION, never stored.
+     *
+     * `systemSettingsResponseSchema` has always declared `security`, and both
+     * `docs/API.md` and `docs/ARCHITECTURE.md` document it — but nothing ever
+     * populated it, so the OpenAPI document at /api/docs advertised a key every
+     * response omitted and a generated client got a field that is permanently
+     * `undefined` (#148). Deleting the declaration was the smaller diff; it would
+     * also have shrunk a surface three places consistently promise, to match an
+     * omission. And the session policy is worth showing an admin: it is not a
+     * secret — any authenticated user can already read the `exp` claim of their
+     * own access token.
+     *
+     * IT IS NOT PART OF THE STORED VALUE, in any sense. `security` is absent from
+     * `systemSettingsSchema`, therefore from `SystemSettingsValue` and from
+     * `knownTopLevelKeys()`, and it plays no part in the machinery above: it
+     * never enters `system_settings.value`, never reaches `mergePreservingUnknown`
+     * and can be neither preserved nor clobbered. `version` and `If-Match` go on
+     * describing the stored row alone.
+     *
+     * IT IS READ-ONLY BY CONSTRUCTION AND NEEDS NO NEW GUARD. Both values are
+     * deploy-time configuration (`JWT_ACCESS_TTL_MINUTES`,
+     * `JWT_REFRESH_TTL_DAYS`), so ConfigService is the only honest source —
+     * reading them from the row would let a saved number disagree with the TTL
+     * the token signer actually uses, which is worse than not showing them.
+     * Nothing makes them look writable: neither `updateSystemSettingsSchema` (PUT)
+     * nor `patchSystemSettingsSchema` (PATCH) declares `security`, both are plain
+     * `z.object`s, and the global `ZodValidationPipe` strips unknown request keys
+     * — so a client that PUTs a `security` block has it discarded before this
+     * service is called.
+     *
+     * The defaults are `configuration.ts`'s own (15 and 14) deliberately: the
+     * response field is typed `z.number()`, and a config lookup that missed would
+     * otherwise put `undefined` where the contract promises a number — trading
+     * one broken promise for a subtler one.
+     */
+    private readSecurityPolicy;
+    /**
+     * The ONE projection from a settings row to `SystemSettingsResponseDto`.
+     *
+     * GET, PUT and PATCH all return this DTO and had each built the object by
+     * hand, which is how `security` could be declared in the response schema and
+     * missing from all three at once. Projecting through one helper means a field
+     * added here cannot be added to one path and forgotten in the other two.
+     */
+    private toResponse;
+    /**
+     * Get system settings
+     * Creates default if not found (should exist from seed)
+     *
+     * DELIBERATELY STILL A NARROW PROJECTION. Preserved-but-unknown keys are not
+     * surfaced here: the response is typed by `SystemSettingsResponseDto` and
+     * consumed by the admin UI, and leaking unmodelled storage into a public
+     * contract is a different (and worse) decision than not destroying it.
+     * Preservation is a safety net, not a read path — see the header.
+     */
+    getSettings(): Promise<SystemSettingsResponse>;
+    /**
+     * The deployment-wide browser-notification policy, read only (#226).
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for two reasons that both
+     * matter on the path that calls it (the notification dispatcher, on every
+     * event, plus two endpoints any authenticated user can reach):
+     *
+     *   1. IT DOES NOT CREATE THE ROW. `getSettings` goes through
+     *      `loadOrCreateRow`, which INSERTs when the row is missing. A read on a
+     *      fire-and-forget send path must not write — the same rule
+     *      `NotificationsService.loadRecipient` follows for `user_settings`, and
+     *      for the same reason: materialising a settings row as a side effect of
+     *      sending a notification is a write nobody asked for, on a path with no
+     *      caller left to report it to.
+     *   2. IT RETURNS ONLY THIS BLOCK. `GET /api/system-settings` is gated on
+     *      `system_settings:read`, which a Viewer does not hold, and widening
+     *      that permission so a Viewer's browser can learn whether toasts are
+     *      enabled would hand every account the whole settings blob.
+     *      `GET /api/notifications/config` exists precisely so the answer
+     *      can be published without the rest of the row; see its handler.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.notifications`
+     * through `readKnownSettings`, so a damaged row cannot make notifications
+     * undeliverable.
+     *
+     * @deprecated A thin alias of `getNamespace('notifications')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getNotificationsPolicy(): Promise<SystemSettingsNamespaceValue<'notifications'>>;
+    /**
+     * The persisted maintenance window, read only (#257, epic #254).
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for the two reasons
+     * `getNotificationsPolicy` above gives, and one more that is specific to this
+     * caller:
+     *
+     *   1. IT DOES NOT CREATE THE ROW. `getSettings` goes through
+     *      `loadOrCreateRow`, which INSERTs when the row is missing. This is read
+     *      by a GLOBAL GUARD on every request in the application; a read path
+     *      that can write is not acceptable there at all, and least of all
+     *      during a maintenance window, when the database may be exactly what is
+     *      being worked on.
+     *   2. IT RETURNS ONLY THIS BLOCK. The guard has no business seeing the
+     *      whole settings row, and neither has anything it might hand a value to.
+     *   3. IT IS ALLOWED TO THROW. `MaintenanceModeService.readPersisted` catches
+     *      it and degrades to its last known state — the restore swap (#285)
+     *      renames the live database, so "this read failed" is a NORMAL,
+     *      anticipated outcome there rather than a bug. Nothing is swallowed
+     *      here, so that caller can tell the difference.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.maintenance`
+     * through `readKnownSettings` — which means a damaged row reads as
+     * `enabled: false` and cannot take the application off the air by accident.
+     *
+     * @deprecated A thin alias of `getNamespace('maintenance')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getMaintenancePolicy(): Promise<SystemSettingsNamespaceValue<'maintenance'>>;
+    /**
+     * The job-queue policy — history retention and the stuck-job threshold
+     * (#263, epic #254).
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for the two reasons
+     * `getNotificationsPolicy` above gives, plus one that belongs to this
+     * caller specifically:
+     *
+     *   1. IT DOES NOT CREATE THE ROW. `getSettings` goes through
+     *      `loadOrCreateRow`, which INSERTs when the row is missing. Every
+     *      caller here is a background timer — the lease reaper every ten
+     *      minutes, the history-purge scheduler at midnight, the purge handler
+     *      itself — and a cron tick materialising a settings row is a write
+     *      nobody asked for, on a path with no request to attribute it to.
+     *   2. IT RETURNS ONLY THIS BLOCK. The reaper needs one integer and the
+     *      purge needs two values; neither has any business holding the whole
+     *      settings blob.
+     *   3. IT IS THE ONE READ PATH FOR THESE VALUES. `JobStuckService` and
+     *      `JobHistoryPurgeHandler` both call this rather than reaching into
+     *      `system_settings` themselves, so "where does the threshold come
+     *      from" has exactly one answer and a fork changing the storage shape
+     *      changes one method.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.jobs` through
+     * `readKnownSettings`, so a damaged row cannot leave dead leases unreaped
+     * or history ungoverned — it falls back to the shipped policy.
+     *
+     * @deprecated A thin alias of `getNamespace('jobs')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getJobsPolicy(): Promise<SystemSettingsNamespaceValue<'jobs'>>;
+    /**
+     * The worker-fleet policy — the stale window, the offline multiplier and the
+     * offline retention (#270, epic #254).
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for exactly the three
+     * reasons `getJobsPolicy` above gives, and read by exactly the callers that
+     * argument was written for:
+     *
+     *   1. IT DOES NOT CREATE THE ROW. Its callers are two background timers —
+     *      the stale-offline sweep every ten minutes and the offline prune
+     *      daily — plus the admin fleet read. A cron tick materialising a
+     *      settings row is a write nobody asked for on a path with no request
+     *      to attribute it to.
+     *   2. IT RETURNS ONLY THIS BLOCK. The sweep needs two integers and the
+     *      prune needs one; neither has any business holding the whole settings
+     *      blob.
+     *   3. IT IS THE ONE READ PATH FOR THESE VALUES. `NodeLifecycleService` is
+     *      the only caller and every consumer goes through it, so "which stale
+     *      window is this?" has exactly one answer. That matters more here than
+     *      anywhere else in this file, because the whole design of
+     *      `offlineStaleMultiplier` — a MULTIPLE of the stale window rather than
+     *      an independent duration — exists to stop the UI's "stale" pill and
+     *      the database's `offline` status from becoming two unrelated notions
+     *      of liveness. A second read path would reintroduce that drift by the
+     *      back door.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.nodes` through
+     * `readKnownSettings`, so a damaged row cannot strand a dead fleet at
+     * `online` forever — it falls back to the shipped policy.
+     *
+     * @deprecated A thin alias of `getNamespace('nodes')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getNodesPolicy(): Promise<SystemSettingsNamespaceValue<'nodes'>>;
+    /**
+     * The database-backup policy — schedule, retention, compression, the stale
+     * window and the storage-provider name (#281, epic #254).
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for exactly the three
+     * reasons `getJobsPolicy` above gives, and each of them bites harder here:
+     *
+     *   1. IT DOES NOT CREATE THE ROW. Its callers are #282's scheduler tick and
+     *      `DatabaseBackupRunnerService`'s three entry points (`queueBackup`,
+     *      `runQueuedBackup` and `startBackup`). A cron materialising a
+     *      settings row as a side effect of deciding whether to take a backup is
+     *      a write nobody asked for — and it would happen on every tick of a
+     *      deployment that has backups switched off.
+     *   2. IT RETURNS ONLY THIS BLOCK. The runner needs three numbers and a
+     *      provider name; handing it the whole settings blob widens what a
+     *      background process holds for no reason.
+     *   3. IT IS THE ONE READ PATH FOR THESE VALUES. `compressionLevel` reaches
+     *      `pg_dump`'s argv and `runStaleMinutes` becomes the dump's SIGKILL
+     *      deadline; a second read path is how the schedule an operator sees and
+     *      the schedule that runs start to differ.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.databaseBackup`
+     * through `readKnownSettings`, so a damaged row cannot be the reason a
+     * deployment stops taking backups — it falls back to the shipped policy.
+     *
+     * @deprecated A thin alias of `getNamespace('databaseBackup')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getDatabaseBackupPolicy(): Promise<SystemSettingsNamespaceValue<'databaseBackup'>>;
+    /**
+     * The object-storage provider configuration — provider, bucket, region,
+     * endpoint, account id and the ACCESS KEY ID (#373, epic #372).
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for the three reasons
+     * `getJobsPolicy` above gives, each of which applies at least as strongly:
+     *
+     *   1. IT DOES NOT CREATE THE ROW. `getSettings` goes through
+     *      `loadOrCreateRow`, which INSERTs when the row is missing. This is read
+     *      on the path that builds a storage client — an avatar download, an
+     *      upload, a node's presigned URL, a backup archive — and a read that
+     *      writes a settings row as a side effect of serving a file is a write
+     *      nobody asked for, on paths with no administrator anywhere near them.
+     *   2. IT RETURNS ONLY THIS BLOCK. A storage client needs six fields; it has
+     *      no business holding the maintenance window or the backup schedule.
+     *   3. IT IS THE ONE READ PATH FOR THESE VALUES. Every consumer goes through
+     *      here, so "which bucket is this deployment using?" has exactly one
+     *      answer. Since #377 removed `STORAGE_PROVIDER`/`S3_*` there is no
+     *      environment to take precedence over, so there is no precedence rule
+     *      left for a call site to get wrong.
+     *
+     * THIS RETURNS NO SECRET, AND CANNOT. The secret access key is not part of
+     * `SystemStorageValue` (there is a compile-time proof of that in
+     * `settings.schema.ts`); a caller that needs it asks `CredentialsService` for
+     * `(purpose 'storage', name 'default')` separately. Two reads, deliberately:
+     * it means the non-secret half can be logged, returned by the admin GET and
+     * kept in memory freely, while the secret half stays on the one path that
+     * decrypts it.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.storage` through
+     * `readKnownSettings` — which is the UNCONFIGURED state, not a guess at a
+     * bucket. A damaged row therefore reads as "storage is not configured", which
+     * is a legible failure, rather than as a half-built client pointed somewhere
+     * nobody chose.
+     *
+     * @deprecated A thin alias of `getNamespace('storage')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getStoragePolicy(): Promise<SystemSettingsNamespaceValue<'storage'>>;
+    /**
+     * The deployment-wide AI platform policy (#423, epic #419, umbrella #418):
+     * whether AI is enabled, the key policy, per-provider configuration, and
+     * the deployment-wide defaults a call cannot exceed.
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for the same three reasons
+     * `getStoragePolicy` above gives:
+     *
+     *   1. IT DOES NOT CREATE THE ROW. This is read on whatever path decides
+     *      whether a call may run at all (#427/#428/#431/#432) — a read that
+     *      writes a settings row as a side effect of that decision is a write
+     *      nobody asked for.
+     *   2. IT RETURNS ONLY THIS BLOCK. An AI call needs the AI policy; it has
+     *      no business holding the backup schedule or the maintenance window.
+     *   3. IT IS THE ONE READ PATH FOR THESE VALUES, so "is AI enabled, and
+     *      under which policy" has exactly one answer.
+     *
+     * THIS RETURNS NO API KEY, AND CANNOT — there is no such field on
+     * `SystemAiValue` (compile-time proof in `settings.schema.ts`). A caller's
+     * own key is `UserAiKey.secret`, read separately by whatever service
+     * decrypts it for one call.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.ai` through
+     * `readKnownSettings` — which is `enabled: false`, the safe direction for a
+     * capability nobody has finished wiring up yet.
+     *
+     * @deprecated A thin alias of `getNamespace('ai')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getAiPolicy(): Promise<SystemSettingsNamespaceValue<'ai'>>;
+    /**
+     * The deployment-wide telemetry policy (epic #528, story #533): whether
+     * telemetry is enabled, how long it is retained, the bounds an ad-hoc query
+     * is held to, and the AI assistant that may be pointed at it.
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for the same three reasons
+     * `getAiPolicy` above gives:
+     *
+     *   1. IT DOES NOT CREATE THE ROW. This is read on whatever path decides
+     *      whether telemetry is collected, queried, or handed to an assistant —
+     *      a read that writes a settings row as a side effect of that decision
+     *      is a write nobody asked for.
+     *   2. IT RETURNS ONLY THIS BLOCK. A telemetry consumer needs the telemetry
+     *      policy; it has no business holding the backup schedule or the AI
+     *      platform policy.
+     *   3. IT IS THE ONE READ PATH FOR THESE VALUES, so "is telemetry enabled,
+     *      and under which bounds" has exactly one answer.
+     *
+     * THIS RETURNS NO CREDENTIAL, AND CANNOT — there is no such field on
+     * `SystemTelemetryValue` (compile-time proof in `settings.schema.ts`). The
+     * assistant's provider key is resolved through `AiKeyResolver`, exactly as
+     * every other AI call resolves one.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.telemetry`
+     * through `readKnownSettings` — which is `enabled: false`, the safe
+     * direction for a capability a legacy row (written before this namespace
+     * existed) never opted into.
+     *
+     * @deprecated A thin alias of `getNamespace('telemetry')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getTelemetryPolicy(): Promise<SystemSettingsNamespaceValue<'telemetry'>>;
+    /**
+     * The retention policy (#681): one `{ enabled, days }` per governed table —
+     * the in-app inbox, the delivery log, the audit trail and AI runs.
+     *
+     * A NARROW ACCESSOR RATHER THAN `getSettings()`, for the reasons
+     * `getJobsPolicy` gives: its callers are the 01:00 retention cron and the
+     * four purge handlers, so it never creates the row (a cron tick must not
+     * materialise a settings row), it returns only this block, and it is the one
+     * read path for these values.
+     *
+     * Degrades exactly as every other read here does: a missing row, a `null`
+     * value or a malformed one yields `DEFAULT_SYSTEM_SETTINGS.retention`
+     * through `readKnownSettings`.
+     *
+     * @deprecated A thin alias of `getNamespace('retention')`, kept until every slice reads its namespace that way (#733).
+     * @stability stable
+     */
+    getRetentionPolicy(): Promise<SystemSettingsNamespaceValue<'retention'>>;
+    /**
+     * One namespace of the stored settings, read only (#677): the typed
+     * accessor for a namespace that has none of its own, an app namespace above
+     * all. Same contract as `getJobsPolicy` and its siblings: never creates the
+     * row, and a missing row, a `null` value or a malformed one yields the
+     * namespace's defaults through `readKnownSettings`.
+     *
+     * @param key - a registered namespace key, typed by `SystemSettingsNamespaces`.
+     * @returns the salvaged value of the namespace.
+     *
+     * @example
+     * ```ts
+     * const jobs = await systemSettings.getNamespace('jobs');
+     * ```
+     *
+     * @stability stable
+     */
+    getNamespace<K extends keyof SystemSettingsNamespaces>(key: K): Promise<SystemSettingsNamespaces[K]>;
+    /**
+     * One namespace of the stored settings, read only, typed by its own
+     * declaration (#865): the value type is the declaration's `storedSchema`
+     * output, so it needs no augmentation of `SystemSettingsNamespaces`. Same
+     * contract as the key overload. The namespace must be registered (the
+     * declaration itself, or one extended from it): reading one the registry
+     * does not hold would return nothing a caller could trust.
+     *
+     * @param declaration - the namespace's declaration, as registered.
+     * @returns the salvaged value of the namespace.
+     * @throws Error when no namespace with the declaration's key is registered.
+     *
+     * @example
+     * ```ts
+     * const notes = await systemSettings.getNamespace(NOTES_SYSTEM_SETTINGS); // NotesSettings
+     * ```
+     *
+     * @stability experimental
+     */
+    getNamespace<D extends Pick<SystemSettingsNamespace, 'key' | 'storedSchema'>>(declaration: D): Promise<SystemSettingsNamespaceOf<D>>;
+    /**
+     * One namespace of the stored settings by key, untyped: the read every typed
+     * accessor shares. Never creates the row; an unregistered key reads as
+     * `undefined`.
+     *
+     * @param key - the namespace key.
+     * @returns the salvaged value.
+     *
+     * @stability experimental
+     */
+    readNamespaceValue(key: string): Promise<unknown>;
+    /**
+     * The whole stored document, salvaged (every registered namespace, through
+     * the same field-by-field degradation), read only: never creates the row.
+     * `SettingsResolver` reads it once per resolution.
+     *
+     * @returns the salvaged value of every registered namespace.
+     *
+     * @stability experimental
+     */
+    readKnownValue(): Promise<SystemSettingsValue>;
+    /**
+     * Replace system settings (PUT)
+     */
+    replaceSettings(dto: ComposedUpdateBody, userId: string): Promise<SystemSettingsResponse>;
+    /**
+     * Partial update system settings (PATCH)
+     */
+    patchSettings(dto: ComposedPatchBody, userId: string, expectedVersion?: number): Promise<SystemSettingsResponse>;
+    /**
+     * Create audit event
+     */
+    private createAuditEvent;
+}
+//# sourceMappingURL=system-settings.service.d.ts.map

package/dist/settings/system-settings/system-settings.service.d.ts.map

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