@endora-commerce/platform 0.100.0

package/dist/kernel/settings/setting-value.entity.d.ts

@@ -0,0 +1,23 @@
+import { OptionalProps } from '@mikro-orm/core';
+import { Setting } from './setting.entity.js';
+import { SalesChannel } from '../sales-channels/sales-channel.entity.js';
+/**
+ * SettingValue — feature 004 / data-model.md.
+ *
+ * Per-(setting, sales_channel) admin override. Resolution order from
+ * SettingsService: this row's value if present, otherwise the owning
+ * Setting's `defaultValue` (R-3).
+ *
+ * `updatedAt` backs the `If-Match` ETag pattern (R-6 / FR-012); admins must
+ * round-trip the timestamp from a prior GET to commit a write.
+ */
+export declare class SettingValue {
+    [OptionalProps]?: 'id' | 'createdAt' | 'updatedAt';
+    id: string;
+    setting: Setting;
+    salesChannel: SalesChannel;
+    value: unknown;
+    createdAt: Date;
+    updatedAt: Date;
+}
+//# sourceMappingURL=setting-value.entity.d.ts.map

package/dist/kernel/settings/setting-value.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setting-value.entity.d.ts","sourceRoot":"","sources":["../../../src/kernel/settings/setting-value.entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,aAAa,EAId,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAEzE;;;;;;;;;GASG;AACH,qBAGa,YAAY;IACvB,CAAC,aAAa,CAAC,CAAC,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC;IAGnD,EAAE,EAAE,MAAM,CAAgB;IAI1B,OAAO,EAAG,OAAO,CAAC;IAIlB,YAAY,EAAG,YAAY,CAAC;IAG5B,KAAK,EAAG,OAAO,CAAC;IAGhB,SAAS,EAAE,IAAI,CAAc;IAG7B,SAAS,EAAE,IAAI,CAAc;CAC9B"}

package/dist/kernel/settings/setting-value.entity.js

@@ -0,0 +1,66 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Entity, Index, ManyToOne, OptionalProps, PrimaryKey, Property, Unique, } from '@mikro-orm/core';
+import { GlobalEntity } from '../../tenancy/org-scoped.decorator.js';
+import { randomUUID } from 'crypto';
+import { Setting } from './setting.entity.js';
+import { SalesChannel } from '../sales-channels/sales-channel.entity.js';
+/**
+ * SettingValue — feature 004 / data-model.md.
+ *
+ * Per-(setting, sales_channel) admin override. Resolution order from
+ * SettingsService: this row's value if present, otherwise the owning
+ * Setting's `defaultValue` (R-3).
+ *
+ * `updatedAt` backs the `If-Match` ETag pattern (R-6 / FR-012); admins must
+ * round-trip the timestamp from a prior GET to commit a write.
+ */
+let SettingValue = class SettingValue {
+    [OptionalProps];
+    id = randomUUID();
+    setting;
+    salesChannel;
+    value;
+    createdAt = new Date();
+    updatedAt = new Date();
+};
+__decorate([
+    PrimaryKey({ type: 'uuid' }),
+    __metadata("design:type", String)
+], SettingValue.prototype, "id", void 0);
+__decorate([
+    ManyToOne(() => Setting, { fieldName: 'setting_id' }),
+    Index(),
+    __metadata("design:type", Setting)
+], SettingValue.prototype, "setting", void 0);
+__decorate([
+    ManyToOne(() => SalesChannel, { fieldName: 'sales_channel_id' }),
+    Index(),
+    __metadata("design:type", SalesChannel)
+], SettingValue.prototype, "salesChannel", void 0);
+__decorate([
+    Property({ type: 'json' }),
+    __metadata("design:type", Object)
+], SettingValue.prototype, "value", void 0);
+__decorate([
+    Property({ type: 'datetime', onCreate: () => new Date(), fieldName: 'created_at' }),
+    __metadata("design:type", Date)
+], SettingValue.prototype, "createdAt", void 0);
+__decorate([
+    Property({ type: 'datetime', onUpdate: () => new Date(), fieldName: 'updated_at' }),
+    __metadata("design:type", Date)
+], SettingValue.prototype, "updatedAt", void 0);
+SettingValue = __decorate([
+    GlobalEntity(),
+    Entity({ tableName: 'setting_values' }),
+    Unique({ properties: ['setting', 'salesChannel'] })
+], SettingValue);
+export { SettingValue };
+//# sourceMappingURL=setting-value.entity.js.map

package/dist/kernel/settings/setting-value.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setting-value.entity.js","sourceRoot":"","sources":["../../../src/kernel/settings/setting-value.entity.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EACL,MAAM,EACN,KAAK,EACL,SAAS,EACT,aAAa,EACb,UAAU,EACV,QAAQ,EACR,MAAM,GACP,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAEzE;;;;;;;;;GASG;AAII,IAAM,YAAY,GAAlB,MAAM,YAAY;IACvB,CAAC,aAAa,CAAC,CAAoC;IAGnD,EAAE,GAAW,UAAU,EAAE,CAAC;IAI1B,OAAO,CAAW;IAIlB,YAAY,CAAgB;IAG5B,KAAK,CAAW;IAGhB,SAAS,GAAS,IAAI,IAAI,EAAE,CAAC;IAG7B,SAAS,GAAS,IAAI,IAAI,EAAE,CAAC;CAC9B,CAAA;AAlBC;IADC,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;;wCACH;AAI1B;IAFC,SAAS,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;IACrD,KAAK,EAAE;8BACE,OAAO;6CAAC;AAIlB;IAFC,SAAS,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChE,KAAK,EAAE;8BACO,YAAY;kDAAC;AAG5B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;;2CACX;AAGhB;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;8BACzE,IAAI;+CAAc;AAG7B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;8BACzE,IAAI;+CAAc;AArBlB,YAAY;IAHxB,YAAY,EAAE;IACd,MAAM,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,CAAC;GACvC,YAAY,CAsBxB"}

package/dist/kernel/settings/setting.entity.d.ts

@@ -0,0 +1,56 @@
+import { Collection, OptionalProps } from '@mikro-orm/core';
+import { SettingGroup } from './setting-group.entity.js';
+import { SalesChannel } from '../sales-channels/sales-channel.entity.js';
+export declare const SETTING_VALUE_TYPES: readonly ["string", "number", "boolean", "json", "string_list", "secret", "credential_ref"];
+export type SettingValueTypeDb = (typeof SETTING_VALUE_TYPES)[number];
+/**
+ * Setting — feature 004 / data-model.md.
+ *
+ * One tunable knob declared by a module. `defaultValue` is the manifest-
+ * supplied fallback used by the universal getter when no per-channel
+ * `SettingValue` exists for the requested sales channel.
+ */
+export declare class Setting {
+    [OptionalProps]?: 'id' | 'createdAt' | 'updatedAt' | 'description' | 'globalValue' | 'enumOptions' | 'configurationType' | 'hidden';
+    id: string;
+    code: string;
+    name: string;
+    group: SettingGroup;
+    valueType: SettingValueTypeDb;
+    defaultValue: unknown;
+    ownerModule: string;
+    description?: string | null;
+    /**
+     * Platform-wide "global override" the admin has set. NULL means no global
+     * override — the resolver falls back to `defaultValue`. Per-channel
+     * `SettingValue` rows take precedence over this for their channel.
+     */
+    globalValue?: unknown | null;
+    /**
+     * Closed list of allowed values for an enum-style `string` setting (manifest
+     * `enumOptions`). NULL ⇒ ordinary free-text setting. When set, the admin
+     * renders a dropdown and value writes are constrained to these options.
+     */
+    enumOptions?: string[] | null;
+    /**
+     * Feature 058 — for a `credential_ref` setting, the configuration type its
+     * reference is constrained to (e.g. `'llm'`). NULL for every other value
+     * type. Manifest-driven config, kept in sync by the reconciler.
+     */
+    configurationType?: string | null;
+    /**
+     * When true, the setting is excluded from the generic admin Settings screen
+     * and managed exclusively through its owning module's dedicated UI (e.g. the
+     * PWA settings page). It stays fully readable/writable by code. Manifest-
+     * driven config, kept in sync on every reconciliation.
+     */
+    hidden: boolean;
+    /**
+     * Sales-channel scope. Empty collection ⇒ "applies to all sales channels"
+     * (FR-004 / R-5). Backed by the `setting_sales_channels` join table.
+     */
+    salesChannels: Collection<SalesChannel, object>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+//# sourceMappingURL=setting.entity.d.ts.map

package/dist/kernel/settings/setting.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setting.entity.d.ts","sourceRoot":"","sources":["../../../src/kernel/settings/setting.entity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAMV,aAAa,EAId,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAEzE,eAAO,MAAM,mBAAmB,6FAStB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,qBAEa,OAAO;IAClB,CAAC,aAAa,CAAC,CAAC,EACZ,IAAI,GACJ,WAAW,GACX,WAAW,GACX,aAAa,GACb,aAAa,GACb,aAAa,GACb,mBAAmB,GACnB,QAAQ,CAAC;IAGb,EAAE,EAAE,MAAM,CAAgB;IAI1B,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAId,KAAK,EAAG,YAAY,CAAC;IAGrB,SAAS,EAAG,kBAAkB,CAAC;IAG/B,YAAY,EAAG,OAAO,CAAC;IAIvB,WAAW,EAAG,MAAM,CAAC;IAGrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;;;OAIG;IAEH,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAE7B;;;;OAIG;IAEH,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAE9B;;;;OAIG;IAEH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC;;;;;OAKG;IAEH,MAAM,EAAE,OAAO,CAAS;IAExB;;;OAGG;IAMH,aAAa,mCAAsC;IAGnD,SAAS,EAAE,IAAI,CAAc;IAG7B,SAAS,EAAE,IAAI,CAAc;CAC9B"}

package/dist/kernel/settings/setting.entity.js

@@ -0,0 +1,147 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Collection, Entity, Enum, Index, ManyToMany, ManyToOne, OptionalProps, PrimaryKey, Property, Unique, } from '@mikro-orm/core';
+import { GlobalEntity } from '../../tenancy/org-scoped.decorator.js';
+import { randomUUID } from 'crypto';
+import { SettingGroup } from './setting-group.entity.js';
+import { SalesChannel } from '../sales-channels/sales-channel.entity.js';
+export const SETTING_VALUE_TYPES = [
+    'string',
+    'number',
+    'boolean',
+    'json',
+    'string_list',
+    'secret',
+    // Feature 058 — reference to a saved credential configuration (by code).
+    'credential_ref',
+];
+/**
+ * Setting — feature 004 / data-model.md.
+ *
+ * One tunable knob declared by a module. `defaultValue` is the manifest-
+ * supplied fallback used by the universal getter when no per-channel
+ * `SettingValue` exists for the requested sales channel.
+ */
+let Setting = class Setting {
+    [OptionalProps];
+    id = randomUUID();
+    code;
+    name;
+    group;
+    valueType;
+    defaultValue;
+    ownerModule;
+    description;
+    /**
+     * Platform-wide "global override" the admin has set. NULL means no global
+     * override — the resolver falls back to `defaultValue`. Per-channel
+     * `SettingValue` rows take precedence over this for their channel.
+     */
+    globalValue;
+    /**
+     * Closed list of allowed values for an enum-style `string` setting (manifest
+     * `enumOptions`). NULL ⇒ ordinary free-text setting. When set, the admin
+     * renders a dropdown and value writes are constrained to these options.
+     */
+    enumOptions;
+    /**
+     * Feature 058 — for a `credential_ref` setting, the configuration type its
+     * reference is constrained to (e.g. `'llm'`). NULL for every other value
+     * type. Manifest-driven config, kept in sync by the reconciler.
+     */
+    configurationType;
+    /**
+     * When true, the setting is excluded from the generic admin Settings screen
+     * and managed exclusively through its owning module's dedicated UI (e.g. the
+     * PWA settings page). It stays fully readable/writable by code. Manifest-
+     * driven config, kept in sync on every reconciliation.
+     */
+    hidden = false;
+    /**
+     * Sales-channel scope. Empty collection ⇒ "applies to all sales channels"
+     * (FR-004 / R-5). Backed by the `setting_sales_channels` join table.
+     */
+    salesChannels = new Collection(this);
+    createdAt = new Date();
+    updatedAt = new Date();
+};
+__decorate([
+    PrimaryKey({ type: 'uuid' }),
+    __metadata("design:type", String)
+], Setting.prototype, "id", void 0);
+__decorate([
+    Property({ type: 'string', length: 160 }),
+    Unique(),
+    __metadata("design:type", String)
+], Setting.prototype, "code", void 0);
+__decorate([
+    Property({ type: 'string', length: 200 }),
+    __metadata("design:type", String)
+], Setting.prototype, "name", void 0);
+__decorate([
+    ManyToOne(() => SettingGroup, { fieldName: 'group_id' }),
+    Index(),
+    __metadata("design:type", SettingGroup)
+], Setting.prototype, "group", void 0);
+__decorate([
+    Enum({ items: () => SETTING_VALUE_TYPES, nativeEnumName: 'setting_value_type', fieldName: 'value_type' }),
+    __metadata("design:type", String)
+], Setting.prototype, "valueType", void 0);
+__decorate([
+    Property({ type: 'json', fieldName: 'default_value' }),
+    __metadata("design:type", Object)
+], Setting.prototype, "defaultValue", void 0);
+__decorate([
+    Property({ type: 'string', length: 120, fieldName: 'owner_module' }),
+    Index(),
+    __metadata("design:type", String)
+], Setting.prototype, "ownerModule", void 0);
+__decorate([
+    Property({ type: 'text', nullable: true }),
+    __metadata("design:type", Object)
+], Setting.prototype, "description", void 0);
+__decorate([
+    Property({ type: 'json', nullable: true, fieldName: 'global_value' }),
+    __metadata("design:type", Object)
+], Setting.prototype, "globalValue", void 0);
+__decorate([
+    Property({ type: 'json', nullable: true, fieldName: 'enum_options' }),
+    __metadata("design:type", Object)
+], Setting.prototype, "enumOptions", void 0);
+__decorate([
+    Property({ type: 'string', length: 64, nullable: true, fieldName: 'configuration_type' }),
+    __metadata("design:type", Object)
+], Setting.prototype, "configurationType", void 0);
+__decorate([
+    Property({ type: 'boolean', default: false }),
+    __metadata("design:type", Boolean)
+], Setting.prototype, "hidden", void 0);
+__decorate([
+    ManyToMany(() => SalesChannel, undefined, {
+        pivotTable: 'setting_sales_channels',
+        joinColumn: 'setting_id',
+        inverseJoinColumn: 'sales_channel_id',
+    }),
+    __metadata("design:type", Object)
+], Setting.prototype, "salesChannels", void 0);
+__decorate([
+    Property({ type: 'datetime', onCreate: () => new Date(), fieldName: 'created_at' }),
+    __metadata("design:type", Date)
+], Setting.prototype, "createdAt", void 0);
+__decorate([
+    Property({ type: 'datetime', onUpdate: () => new Date(), fieldName: 'updated_at' }),
+    __metadata("design:type", Date)
+], Setting.prototype, "updatedAt", void 0);
+Setting = __decorate([
+    GlobalEntity(),
+    Entity({ tableName: 'settings' })
+], Setting);
+export { Setting };
+//# sourceMappingURL=setting.entity.js.map

package/dist/kernel/settings/setting.entity.js.map

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

package/dist/kernel/settings/settings-cache.d.ts

@@ -0,0 +1,158 @@
+import type { Redis } from 'ioredis';
+/**
+ * Read-through cache for `SettingsService.get` — feature 004 / US3 (T050).
+ *
+ * Two layers, in this order on read:
+ *   1. Per-process LRU (cheap; absorbs intra-request bursts).
+ *   2. Redis (`settings:v1:<code>:<channelId>`, TTL 1h; survives restarts).
+ *
+ * Invalidation goes the other way: write → drop in Redis → drop in LRU. The
+ * write seam calls {@link SettingsCacheInvalidation} itself and awaits it
+ * (issue #45); until then the drop rode an EventBus notification, which made it
+ * a function of *which handler the bus reached first*.
+ *
+ * Dropping the shared layer first is deliberate: it is the layer that outlives
+ * this process and would otherwise be re-pulled into every other process's
+ * LRU. Dropping it is also the step that can fail (network, closed
+ * connection), and a half-done invalidation must degrade to "slower but
+ * correct", never to "fast and wrong". {@link SharedDropMarks} holds the two
+ * guards that enforce it.
+ *
+ * **The local layer expires.** The EventBus is in-process (`events/bus.ts`),
+ * so a second API instance learns about a write only through the shared layer:
+ * invalidation is, across processes, a broadcast that can be missed. Redis
+ * expires its entries after an hour; without {@link SETTINGS_LRU_TTL_MS} the
+ * LRU expired nothing and was bounded only by its capacity, so a process that
+ * missed a notification served the pre-write value indefinitely — the one case
+ * the operator's "clear cache" button cannot fix, because clearing rides the
+ * same in-process path that already failed. The window is on the value's age,
+ * never refreshed by a read: a setting read on every request is exactly the
+ * entry a sliding window would pin forever.
+ *
+ * Stored values are JSON-serialised so structured types (objects, arrays)
+ * survive the Redis hop. The `null` sentinel is never stored — absence of a
+ * key means "cache miss"; falsy values like `false`, `0`, `""` are valid.
+ */
+/** Shared with the operator-facing cache-clear surface, so the two cannot drift. */
+export declare const SETTINGS_CACHE_KEY_PREFIX = "settings:v1:";
+export declare const SETTINGS_CACHE_NAMESPACE = "settings";
+/**
+ * Maximum age of an entry in the per-process layer.
+ *
+ * 30 s is chosen from both ends. The layer exists to remove the Redis hop from
+ * a path read several times per request, and a request burst — a page load, a
+ * checkout step, a worker's batch — lives well inside 30 s, so the hit rate
+ * that justifies the layer is untouched; a 5 s window (what `custom_fields`
+ * uses for a far colder key space) would put a Redis round trip back on the
+ * hot path many times a second. At the other end, 30 s is a bound an operator
+ * experiences as "reload the page and it is right" rather than as a defect,
+ * and it is two orders of magnitude below the hour Redis keeps its own copy —
+ * which is what makes the self-healing real rather than theoretical.
+ */
+export declare const SETTINGS_LRU_TTL_MS = 30000;
+/**
+ * The invalidating half of the cache, as the **write seam** sees it (issue #45).
+ *
+ * `SettingsAdminService` — the one place a setting value or group changes —
+ * takes this and awaits it before it emits `settings.value_changed`. That is
+ * what makes the drop a property of the write instead of a property of the
+ * dispatch order: a caller that writes and reads back in the same tick, in the
+ * same `EventBus.run` scope, or with any number of module subscribers on the
+ * bus, cannot observe the pre-write value.
+ *
+ * Narrow on purpose. The reader (`SettingsService`) holds the whole
+ * {@link SettingsCache}; the writer needs only these two, and a module that can
+ * only invalidate cannot accidentally seed the cache from the write path.
+ */
+export interface SettingsCacheInvalidation {
+    /**
+     * Drop every cached entry for one setting code, across every channel, on
+     * behalf of a write that has **already committed**.
+     *
+     * Returns the number of shared keys deleted, or `null` when the shared layer
+     * could not be reached. The degrade lives here rather than in a `catch` at
+     * the call site, and it is in the return type on purpose: the row is written
+     * and audited, so a Redis blip must not fail the operator's request or make
+     * them retry a write that succeeded. Correctness does not rest on the number
+     * — {@link SharedDropMarks} has marked the prefix failed, so this process
+     * bypasses both layers for those keys and retries the drop on the next read.
+     */
+    invalidateAfterWrite(code: string): Promise<number | null>;
+    /**
+     * The same contract for a group change, which can move settings between
+     * groups or rescope channels and so can change resolution for any number of
+     * codes.
+     */
+    invalidateAllAfterWrite(): Promise<number | null>;
+}
+export declare class SettingsCache implements SettingsCacheInvalidation {
+    private readonly redis;
+    /** Injectable so a test can advance the TTL window without a real clock. */
+    private readonly now;
+    private readonly lru;
+    private readonly marks;
+    constructor(redis: Redis, 
+    /** Injectable so a test can advance the TTL window without a real clock. */
+    now?: () => number);
+    private static composeKey;
+    /**
+     * Returns:
+     *   - { hit: true; value: unknown } when the value (or "not registered" sentinel) is cached
+     *   - { hit: false } when the caller must fall through to Postgres
+     * The "not registered" sentinel is encoded as `{ __settings_not_registered__: true }`.
+     */
+    get(code: string, channelId: string | null): Promise<{
+        hit: false;
+    } | {
+        hit: true;
+        value: unknown;
+        notRegistered?: boolean;
+    }>;
+    set(code: string, channelId: string | null, value: unknown): Promise<void>;
+    /** Cache the "not registered" outcome so repeated typos don't hammer Postgres. */
+    setNotRegistered(code: string, channelId: string | null): Promise<void>;
+    /**
+     * Drop every cached entry for a given setting code (across every channel).
+     * Returns how many shared keys were deleted.
+     */
+    invalidate(code: string): Promise<number>;
+    /**
+     * Used after group-level changes that may affect many codes, and by the
+     * operator-facing cache clear. Returns how many shared keys were deleted.
+     */
+    invalidateAll(): Promise<number>;
+    /** {@inheritDoc SettingsCacheInvalidation.invalidateAfterWrite} */
+    invalidateAfterWrite(code: string): Promise<number | null>;
+    /** {@inheritDoc SettingsCacheInvalidation.invalidateAllAfterWrite} */
+    invalidateAllAfterWrite(): Promise<number | null>;
+    /**
+     * The one place the write seam's tolerance is written down.
+     *
+     * `drop` has already marked the prefix failed by the time it re-throws, so
+     * every read in this process bypasses both layers for those keys and retries
+     * the drop until Redis answers — the invariant is intact and the answer is
+     * "slower but correct". What is left of the throw is a report, and a report
+     * must not undo the write that produced it.
+     */
+    private afterWrite;
+    /**
+     * Drop both layers for a key prefix, shared layer first. The prefix is
+     * marked for the whole operation so concurrent reads and writes cannot
+     * observe or restore the pre-invalidation state; the mark is only released
+     * once the shared layer is known to be clean.
+     */
+    private drop;
+    /** SCAN + DEL, to avoid blocking on KEYS in production-sized databases. */
+    private dropShared;
+    private dropLocal;
+    /**
+     * True when neither layer may be trusted for this key: a drop is in flight,
+     * or an earlier drop failed and Redis was never cleaned. In the failed case
+     * the drop is retried here, so a transient outage costs the affected codes
+     * their caching until Redis answers again — not for the process lifetime.
+     */
+    private isBypassed;
+    private touchLru;
+    private isNotRegisteredSentinel;
+}
+//# sourceMappingURL=settings-cache.d.ts.map

package/dist/kernel/settings/settings-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-cache.d.ts","sourceRoot":"","sources":["../../../src/kernel/settings/settings-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,oFAAoF;AACpF,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAuB1C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;;OAWG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3D;;;;OAIG;IACH,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACnD;AAED,qBAAa,aAAc,YAAW,yBAAyB;IAK3D,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,GAAG;IANtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+B;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;gBAG5B,KAAK,EAAE,KAAK;IAC7B,4EAA4E;IAC3D,GAAG,GAAE,MAAM,MAAyB;IAGvD,OAAO,CAAC,MAAM,CAAC,UAAU;IAIzB;;;;;OAKG;IACG,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC;QAAE,GAAG,EAAE,KAAK,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IA8B7E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAShF,kFAAkF;IAC5E,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7E;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAItC,mEAAmE;IAC7D,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIhE,sEAAsE;IAChE,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIvD;;;;;;;;OAQG;YACW,UAAU;IAQxB;;;;;OAKG;YACW,IAAI;IAiBlB,2EAA2E;YAC7D,UAAU;IAmBxB,OAAO,CAAC,SAAS;IAMjB;;;;;OAKG;YACW,UAAU;IAaxB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,uBAAuB;CAQhC"}