@endora-commerce/platform 0.100.0

package/dist/kernel/sales-channels/sales-channels-cache.d.ts

@@ -0,0 +1,170 @@
+import type { Redis } from 'ioredis';
+import type { SalesChannel } from './sales-channel.entity.js';
+/**
+ * SalesChannelsCache — feature 005 / T012.
+ *
+ * Two-layer read-through cache used by the resolver service so that
+ * channel lookup costs <1 ms p95 even on hot paths (research R-11).
+ *
+ *   1. Per-process LRU (cap {@link LRU_MAX}, entries older than
+ *      {@link SALES_CHANNELS_LRU_TTL_MS} ignored) — absorbs intra-request
+ *      bursts and removes the Redis hop entirely on warm processes.
+ *   2. Redis (`sales-channels:v2:<code>`, TTL {@link TTL_SECONDS}) —
+ *      cross-process consistency in multi-instance deployments.
+ *
+ * Invalidation flows write → drop in Redis → drop in LRU → announce. It is the
+ * same two-layer shape as `SettingsCache` and carries the same **three**
+ * obligations, for the same reasons (see {@link SharedDropMarks} and the TTL
+ * note there; the third is {@link SalesChannelsCacheInvalidation}, which D-93
+ * finally gave it):
+ *
+ *   - the shared layer is dropped **first** and the prefix stays marked for
+ *     the whole operation, so a read that lands mid-invalidation cannot
+ *     re-pin the pre-drop value from Redis into the LRU, and a failed shared
+ *     drop leaves reads failing closed to PostgreSQL rather than to a value
+ *     the invalidation was supposed to remove;
+ *   - the local layer expires, because a drop is in-process: a second instance
+ *     that never ran it would otherwise serve the pre-change channel until
+ *     capacity evicted it;
+ *   - the drop is part of the **write**, not of the announcement.
+ *
+ * Cache values are JSON-serialised. The `null` sentinel is reserved
+ * for "no such channel"; absence of a key means "cache miss".
+ */
+/** Shared with the operator-facing cache-clear surface, so the two cannot drift. */
+export declare const SALES_CHANNELS_CACHE_KEY_PREFIX = "sales-channels:v2:";
+export declare const SALES_CHANNELS_CACHE_NAMESPACE = "sales_channels";
+/** Maximum age of an entry in the per-process layer; see `SETTINGS_LRU_TTL_MS`. */
+export declare const SALES_CHANNELS_LRU_TTL_MS = 30000;
+/** Plain serialisable view of a SalesChannel — what the resolver actually needs. */
+export interface CachedChannel {
+    id: string;
+    code: string;
+    name: Record<string, string>;
+    active: boolean;
+    /** Price-visibility flag (display concern, distinct from resolution). */
+    isPublic: boolean;
+    systemDefault: boolean;
+    defaultLanguage: string;
+    defaultCurrency: string;
+    themeCode: string | null;
+    logoAssetId: string | null;
+    languages: string[];
+    currencies: string[];
+    version: number;
+}
+export declare function toCachedChannel(channel: SalesChannel): CachedChannel;
+/**
+ * The invalidating half of the cache, as the **write seam** sees it (D-93,
+ * issue #160). The third obligation this cache's header already claimed from
+ * `SettingsCache` and had not been given.
+ *
+ * `SalesChannelsService` — the one place a channel's identity or lifecycle
+ * changes — takes this and awaits it before it emits, and `set-default` does
+ * the same after its Command commits. 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
+ * channel.
+ *
+ * Both hazards were live here. `dictionaries` subscribes to the same two event
+ * names and rebuilds its own cache on receipt, so a handler ahead of the drop
+ * is the ordinary case rather than a thought experiment; and `set-default` is a
+ * Command, so its event rides the `event:` slot and dispatches only when
+ * `CommandBus.run`'s scope ends — after every read-back inside it.
+ *
+ * Narrow on purpose. The reader (`SalesChannelResolverService`) holds the whole
+ * {@link SalesChannelsCache}; the writer needs only these two, and a module that
+ * can only invalidate cannot accidentally seed the cache from the write path.
+ */
+export interface SalesChannelsCacheInvalidation {
+    /**
+     * Drop one channel's cached entry, 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 change that can move more than one channel's cached
+     * state: a delete that rebinds orphans, or the `system_default` flag moving,
+     * where the demoted channel's entry is stale too because `systemDefault`
+     * lives inside the cached value.
+     */
+    invalidateAllAfterWrite(): Promise<number | null>;
+}
+export declare class SalesChannelsCache implements SalesChannelsCacheInvalidation {
+    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: CachedChannel } when the channel is cached
+     *   - { hit: true; value: null } when the cache positively knows it does not exist
+     *   - { hit: false } when the caller must fall through to Postgres
+     */
+    get(code: string): Promise<{
+        hit: false;
+    } | {
+        hit: true;
+        value: CachedChannel | null;
+    }>;
+    set(code: string, channel: CachedChannel): Promise<void>;
+    /** Cache the "no such channel" outcome so repeated typos do not hammer Postgres. */
+    setNotFound(code: string): Promise<void>;
+    /**
+     * Drop one channel's cached entry across both layers. Returns how many
+     * shared keys were deleted.
+     */
+    invalidate(code: string): Promise<number>;
+    /**
+     * Drop every cached channel. Used on broad lifecycle changes and by the
+     * operator-facing cache clear. Returns how many shared keys were deleted.
+     */
+    invalidateAll(): Promise<number>;
+    /** {@inheritDoc SalesChannelsCacheInvalidation.invalidateAfterWrite} */
+    invalidateAfterWrite(code: string): Promise<number | null>;
+    /** {@inheritDoc SalesChannelsCacheInvalidation.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, shared layer first, with the prefix marked for the whole
+     * operation. `exact` distinguishes the two shapes: one channel's key is
+     * deleted directly (a SCAN on `<key>*` would also take every channel whose
+     * code extends it), while the namespace drop scans.
+     */
+    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 channels
+     * their caching until Redis answers again — not for the process lifetime.
+     */
+    private isBypassed;
+    private touchLru;
+}
+//# sourceMappingURL=sales-channels-cache.d.ts.map

package/dist/kernel/sales-channels/sales-channels-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sales-channels-cache.d.ts","sourceRoot":"","sources":["../../../src/kernel/sales-channels/sales-channels-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,oFAAoF;AACpF,eAAO,MAAM,+BAA+B,uBAAuB,CAAC;AACpE,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAE/D,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAOhD,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAgBpE;AAQD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;;;;;;;;;OAWG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3D;;;;;OAKG;IACH,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACnD;AAED,qBAAa,kBAAmB,YAAW,8BAA8B;IAKrE,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,GACX,OAAO,CAAC;QAAE,GAAG,EAAE,KAAK,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;KAAE,CAAC;IA6BjE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9D,oFAAoF;IAC9E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAItC,wEAAwE;IAClE,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIhE,2EAA2E;IACrE,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIvD;;;;;;;;OAQG;YACW,UAAU;IAQxB;;;;;OAKG;YACW,IAAI;IAmBlB,2EAA2E;YAC7D,UAAU;IAmBxB,OAAO,CAAC,SAAS;IAMjB;;;;;OAKG;YACW,UAAU;IAaxB,OAAO,CAAC,QAAQ;CASjB"}

package/dist/kernel/sales-channels/sales-channels-cache.js

@@ -0,0 +1,243 @@
+import { SharedDropMarks } from '../cache/shared-drop-marks.js';
+/**
+ * SalesChannelsCache — feature 005 / T012.
+ *
+ * Two-layer read-through cache used by the resolver service so that
+ * channel lookup costs <1 ms p95 even on hot paths (research R-11).
+ *
+ *   1. Per-process LRU (cap {@link LRU_MAX}, entries older than
+ *      {@link SALES_CHANNELS_LRU_TTL_MS} ignored) — absorbs intra-request
+ *      bursts and removes the Redis hop entirely on warm processes.
+ *   2. Redis (`sales-channels:v2:<code>`, TTL {@link TTL_SECONDS}) —
+ *      cross-process consistency in multi-instance deployments.
+ *
+ * Invalidation flows write → drop in Redis → drop in LRU → announce. It is the
+ * same two-layer shape as `SettingsCache` and carries the same **three**
+ * obligations, for the same reasons (see {@link SharedDropMarks} and the TTL
+ * note there; the third is {@link SalesChannelsCacheInvalidation}, which D-93
+ * finally gave it):
+ *
+ *   - the shared layer is dropped **first** and the prefix stays marked for
+ *     the whole operation, so a read that lands mid-invalidation cannot
+ *     re-pin the pre-drop value from Redis into the LRU, and a failed shared
+ *     drop leaves reads failing closed to PostgreSQL rather than to a value
+ *     the invalidation was supposed to remove;
+ *   - the local layer expires, because a drop is in-process: a second instance
+ *     that never ran it would otherwise serve the pre-change channel until
+ *     capacity evicted it;
+ *   - the drop is part of the **write**, not of the announcement.
+ *
+ * Cache values are JSON-serialised. The `null` sentinel is reserved
+ * for "no such channel"; absence of a key means "cache miss".
+ */
+// v2 (feature 053): `isPublic` added to the cached shape so storefront
+// consumers read price-visibility off the resolved channel instead of
+// re-querying. Bumped from v1 so entries cached without the field are ignored.
+/** Shared with the operator-facing cache-clear surface, so the two cannot drift. */
+export const SALES_CHANNELS_CACHE_KEY_PREFIX = 'sales-channels:v2:';
+export const SALES_CHANNELS_CACHE_NAMESPACE = 'sales_channels';
+/** Maximum age of an entry in the per-process layer; see `SETTINGS_LRU_TTL_MS`. */
+export const SALES_CHANNELS_LRU_TTL_MS = 30_000;
+const KEY_PREFIX = SALES_CHANNELS_CACHE_KEY_PREFIX;
+const TTL_SECONDS = 5 * 60;
+const LRU_MAX = 256;
+const NOT_FOUND_SENTINEL = '__sales_channel_not_found__';
+export function toCachedChannel(channel) {
+    return {
+        id: channel.id,
+        code: channel.code,
+        name: channel.name,
+        active: channel.active,
+        isPublic: channel.isPublic,
+        systemDefault: channel.systemDefault,
+        defaultLanguage: channel.defaultLanguage,
+        defaultCurrency: channel.defaultCurrency,
+        themeCode: channel.themeCode ?? null,
+        logoAssetId: channel.logoAssetId ?? null,
+        languages: [...channel.languages],
+        currencies: [...channel.currencies],
+        version: channel.version,
+    };
+}
+export class SalesChannelsCache {
+    redis;
+    now;
+    lru = new Map();
+    marks = new SharedDropMarks();
+    constructor(redis, 
+    /** Injectable so a test can advance the TTL window without a real clock. */
+    now = () => Date.now()) {
+        this.redis = redis;
+        this.now = now;
+    }
+    static composeKey(code) {
+        return `${KEY_PREFIX}${code}`;
+    }
+    /**
+     * Returns:
+     *   - { hit: true; value: CachedChannel } when the channel is cached
+     *   - { hit: true; value: null } when the cache positively knows it does not exist
+     *   - { hit: false } when the caller must fall through to Postgres
+     */
+    async get(code) {
+        const key = SalesChannelsCache.composeKey(code);
+        if (await this.isBypassed(key))
+            return { hit: false };
+        const entry = this.lru.get(key);
+        if (entry !== undefined) {
+            if (this.now() - entry.storedAt < SALES_CHANNELS_LRU_TTL_MS) {
+                // Touch for eviction order only — the window is on the value's age, so
+                // a channel resolved on every request still ages out.
+                this.lru.delete(key);
+                this.lru.set(key, entry);
+                return { hit: true, value: entry.value };
+            }
+            this.lru.delete(key);
+        }
+        const raw = await this.redis.get(key);
+        if (raw === null)
+            return { hit: false };
+        if (raw === NOT_FOUND_SENTINEL) {
+            this.touchLru(key, null);
+            return { hit: true, value: null };
+        }
+        const decoded = JSON.parse(raw);
+        this.touchLru(key, decoded);
+        return { hit: true, value: decoded };
+    }
+    async set(code, channel) {
+        const key = SalesChannelsCache.composeKey(code);
+        // A read that started before the change resolved the pre-change row from
+        // Postgres. Caching it now would undo the invalidation in flight.
+        if (await this.isBypassed(key))
+            return;
+        this.touchLru(key, channel);
+        await this.redis.set(key, JSON.stringify(channel), 'EX', TTL_SECONDS);
+    }
+    /** Cache the "no such channel" outcome so repeated typos do not hammer Postgres. */
+    async setNotFound(code) {
+        const key = SalesChannelsCache.composeKey(code);
+        if (await this.isBypassed(key))
+            return;
+        this.touchLru(key, null);
+        await this.redis.set(key, NOT_FOUND_SENTINEL, 'EX', TTL_SECONDS);
+    }
+    /**
+     * Drop one channel's cached entry across both layers. Returns how many
+     * shared keys were deleted.
+     */
+    async invalidate(code) {
+        return this.drop(SalesChannelsCache.composeKey(code), true);
+    }
+    /**
+     * Drop every cached channel. Used on broad lifecycle changes and by the
+     * operator-facing cache clear. Returns how many shared keys were deleted.
+     */
+    async invalidateAll() {
+        return this.drop(KEY_PREFIX, false);
+    }
+    /** {@inheritDoc SalesChannelsCacheInvalidation.invalidateAfterWrite} */
+    async invalidateAfterWrite(code) {
+        return this.afterWrite(() => this.invalidate(code));
+    }
+    /** {@inheritDoc SalesChannelsCacheInvalidation.invalidateAllAfterWrite} */
+    async invalidateAllAfterWrite() {
+        return this.afterWrite(() => this.invalidateAll());
+    }
+    /**
+     * 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.
+     */
+    async afterWrite(drop) {
+        try {
+            return await drop();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Drop both layers, shared layer first, with the prefix marked for the whole
+     * operation. `exact` distinguishes the two shapes: one channel's key is
+     * deleted directly (a SCAN on `<key>*` would also take every channel whose
+     * code extends it), while the namespace drop scans.
+     */
+    async drop(prefix, exact) {
+        this.marks.begin(prefix);
+        try {
+            const deleted = exact
+                ? await this.redis.del(prefix)
+                : await this.dropShared(prefix);
+            this.marks.retireFailedUnder(prefix);
+            return deleted;
+        }
+        catch (err) {
+            // Fail closed: Redis may still serve the pre-invalidation value to this
+            // process, so keep reads off the cache until a later drop succeeds.
+            this.marks.markFailed(prefix);
+            throw err;
+        }
+        finally {
+            this.dropLocal(prefix);
+            this.marks.finish(prefix);
+        }
+    }
+    /** SCAN + DEL, to avoid blocking on KEYS in production-sized databases. */
+    async dropShared(prefix) {
+        let cursor = '0';
+        let deleted = 0;
+        do {
+            const [next, keys] = await this.redis.scan(cursor, 'MATCH', `${prefix}*`, 'COUNT', 500);
+            cursor = next;
+            if (keys.length > 0) {
+                deleted += await this.redis.del(...keys);
+            }
+        } while (cursor !== '0');
+        return deleted;
+    }
+    dropLocal(prefix) {
+        for (const k of this.lru.keys()) {
+            if (k.startsWith(prefix))
+                this.lru.delete(k);
+        }
+    }
+    /**
+     * 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 channels
+     * their caching until Redis answers again — not for the process lifetime.
+     */
+    async isBypassed(key) {
+        if (this.marks.isClean)
+            return false;
+        if (this.marks.isDraining(key))
+            return true;
+        const failed = this.marks.failedPrefixFor(key);
+        if (failed === undefined)
+            return false;
+        try {
+            await this.drop(failed, failed !== KEY_PREFIX);
+        }
+        catch {
+            // Still unreachable — stay off the cache and read through to Postgres.
+        }
+        return true;
+    }
+    touchLru(key, value) {
+        if (this.lru.has(key))
+            this.lru.delete(key);
+        this.lru.set(key, { value, storedAt: this.now() });
+        while (this.lru.size > LRU_MAX) {
+            const oldest = this.lru.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.lru.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=sales-channels-cache.js.map

package/dist/kernel/sales-channels/sales-channels-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sales-channels-cache.js","sourceRoot":"","sources":["../../../src/kernel/sales-channels/sales-channels-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,uEAAuE;AACvE,sEAAsE;AACtE,+EAA+E;AAC/E,oFAAoF;AACpF,MAAM,CAAC,MAAM,+BAA+B,GAAG,oBAAoB,CAAC;AACpE,MAAM,CAAC,MAAM,8BAA8B,GAAG,gBAAgB,CAAC;AAE/D,mFAAmF;AACnF,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEhD,MAAM,UAAU,GAAG,+BAA+B,CAAC;AACnD,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,CAAC;AAC3B,MAAM,OAAO,GAAG,GAAG,CAAC;AACpB,MAAM,kBAAkB,GAAG,6BAA6B,CAAC;AAoBzD,MAAM,UAAU,eAAe,CAAC,OAAqB;IACnD,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;QACpC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,SAAS,EAAE,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;QACjC,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;QACnC,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC;AAsDD,MAAM,OAAO,kBAAkB;IAKV;IAEA;IANF,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IAClC,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IAE/C,YACmB,KAAY;IAC7B,4EAA4E;IAC3D,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QAFpC,UAAK,GAAL,KAAK,CAAO;QAEZ,QAAG,GAAH,GAAG,CAAiC;IACpD,CAAC;IAEI,MAAM,CAAC,UAAU,CAAC,IAAY;QACpC,OAAO,GAAG,UAAU,GAAG,IAAI,EAAE,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CACP,IAAY;QAEZ,MAAM,GAAG,GAAG,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAEtD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,QAAQ,GAAG,yBAAyB,EAAE,CAAC;gBAC5D,uEAAuE;gBACvE,sDAAsD;gBACtD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACrB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBACzB,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YAC3C,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAExC,IAAI,GAAG,KAAK,kBAAkB,EAAE,CAAC;YAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACzB,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACpC,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAkB,CAAC;QACjD,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC5B,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,OAAsB;QAC5C,MAAM,GAAG,GAAG,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAChD,yEAAyE;QACzE,kEAAkE;QAClE,IAAI,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO;QACvC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC5B,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IACxE,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,WAAW,CAAC,IAAY;QAC5B,MAAM,GAAG,GAAG,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO;QACvC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACzB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IACnE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,IAAY;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,oBAAoB,CAAC,IAAY;QACrC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,uBAAuB;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,UAAU,CAAC,IAA2B;QAClD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,KAAc;QAC/C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,KAAK;gBACnB,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;gBAC9B,CAAC,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;YACrC,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wEAAwE;YACxE,oEAAoE;YACpE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC9B,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACvB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,2EAA2E;IACnE,KAAK,CAAC,UAAU,CAAC,MAAc;QACrC,IAAI,MAAM,GAAG,GAAG,CAAC;QACjB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,GAAG,CAAC;YACF,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CACxC,MAAM,EACN,OAAO,EACP,GAAG,MAAM,GAAG,EACZ,OAAO,EACP,GAAG,CACJ,CAAC;YACF,MAAM,GAAG,IAAI,CAAC;YACd,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,OAAO,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,SAAS,CAAC,MAAc;QAC9B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;YAChC,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,UAAU,CAAC,GAAW;QAClC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QACrC,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAC/C,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;QACzE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,QAAQ,CAAC,GAAW,EAAE,KAA2B;QACvD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC5C,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM;YAChC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;CACF"}

package/dist/kernel/scope.d.ts

@@ -0,0 +1,153 @@
+import type { RequestMeta, ScopeEntryPointKind } from '@endora-commerce/contracts';
+import { type TenantContext } from '../tenancy/tenant-context.js';
+import type { ResolvedChannel } from './ports/sales-channel.js';
+import { type KernelContainer, type KernelCradle } from './container.js';
+/**
+ * `enterPlatformScope` — the one entry into a scoped execution (feature 072,
+ * FR-015…FR-021). Six callers: the HTTP `onRequest` hook, BullMQ processors,
+ * the 15 CLI scripts, the four boot reconcilers, the four `setInterval` sweeps
+ * and — since issue #235 — the registry cache's Redis pub/sub handler.
+ *
+ * ## Three rules, none of them negotiable
+ *
+ * **1. AsyncLocalStorage stays the tenancy carrier.** `@OrgScoped` attaches a
+ * MikroORM filter with `args: false` whose `cond` is a zero-argument thunk that
+ * reads `getTenantContext()` **when the query is built**
+ * (`tenancy/org-scoped.decorator.ts` → `tenancy/filters.ts`). The EntityManager
+ * is therefore stateless with respect to tenancy, and that is exactly what makes
+ * `forkScopedEm(orm) = orm.em.fork()` correct. Registering tenancy in the
+ * container instead would require `setFilterParams` on a scoped EM and would
+ * break every `em.transactional` sub-fork and every service that forks its own
+ * manager. `test/integration/tenancy/fault-injection.test.ts` is this design's
+ * unit test: it calls one EM factory inside five different ambient stores and
+ * asserts five different result sets. Any design in which a scoped EM captures
+ * tenancy at construction inverts every assertion in that file.
+ *
+ * **2. The ALS `run()` is the outermost wrapper of the work.** It is the
+ * callback form (`storage.run`), never `storage.enterWith`: `enterWith` called
+ * inside an *async* Fastify hook does not propagate into the handler, and it
+ * fails **silently** (`tenancy/tenant-context.ts`). The consequence is
+ * structural — the awilix scope cannot be created in a separate, earlier hook,
+ * because its disposal and the store's lifetime would then not coincide.
+ *
+ * **3. The channel goes into the scope; tenancy does not.** The channel is
+ * already per-request and has no non-HTTP counterpart. Tenancy must stay
+ * establishable by CLI scripts, workers, boot reconcilers and interval timers
+ * that will never have a request scope.
+ *
+ * ## `onRequest` hook ordering is load-bearing
+ *
+ * The three global `onRequest` hooks run in array order (`http/server.ts`):
+ *
+ *     auth  →  tenant  →  sales channel
+ *
+ * **This ordering is a constraint, not an accident of registration.** The
+ * channel resolver performs database reads through `emFactory`, and would throw
+ * `MissingTenantContextError` if it ran before the tenant hook and `SalesChannel`
+ * were tenant-scoped. `SalesChannel` is `@GlobalEntity` today, so either order
+ * survives — which is precisely why the kernel must not reorder them on the
+ * assumption that it is free. Classify `SalesChannel` any other way and the
+ * reversed order breaks every request.
+ *
+ * Three call sites already run inside a request but *before* tenancy exists and
+ * use `withSystemScope` for it: auth resolving the customer organisation, mfa,
+ * and `customer-rollup-scope.ts` called from inside the context builder itself.
+ * They are the precedent this ordering has to preserve.
+ *
+ * ## Using it from the HTTP hook
+ *
+ * The hook must call the next stage **synchronously inside** the store and keep
+ * the scope alive for the whole request, so the shape is a promise that settles
+ * when the response does:
+ *
+ * ```ts
+ * app.addHook('onRequest', (request, reply, done) => {
+ *   buildTenantContext(request).then(
+ *     (tenant) => {
+ *       void enterPlatformScope(
+ *         tenant,
+ *         () =>
+ *           new Promise<void>((resolve) => {
+ *             reply.raw.once('close', resolve);
+ *             done();
+ *           }),
+ *         { requestMeta: requestMetaOf(request) },
+ *       );
+ *     },
+ *     (err: unknown) => done(err as Error),
+ *   );
+ * });
+ * ```
+ *
+ * `done()` runs inside `storage.run`, so the store propagates across the
+ * handler's awaited continuations; `close` fires on success, on error and on
+ * client abort, so the scope is disposed in all three cases.
+ */
+/** A scoped execution: an awilix child container plus the ambient tenant store. */
+export interface PlatformScope {
+    /** Resolution surface for this execution. */
+    readonly cradle: KernelCradle;
+    /**
+     * The ambient tenant context. Present here for inspection only — it is **not**
+     * a container registration, and reading it back from a scope is never a
+     * substitute for `getTenantContext()`, which is what the ORM filter uses.
+     */
+    readonly tenant: TenantContext;
+    /** Which class of entry point opened this scope. */
+    readonly entryPoint: ScopeEntryPointKind;
+    /** The resolved sales channel; `null` until resolved, and outside HTTP forever. */
+    readonly channel: ResolvedChannel | null;
+    /** Correlation id and client info; absent outside HTTP. */
+    readonly requestMeta: RequestMeta | null;
+    /**
+     * Fill the channel slot. HTTP only, and called exactly once, by the
+     * sales-channel resolver hook.
+     *
+     * **Why the slot is mutable at all** — a correction to `contracts/request-scope.md`,
+     * which reads as though the channel is known when the scope opens. It is not:
+     * the hook order is auth → tenant → channel (see above), so the scope is
+     * already open when the resolver runs, and the resolver *must* run after
+     * tenancy because its refusal path writes an audit row. The alternatives are
+     * reordering the hooks (forbidden — the ordering is load-bearing) or opening a
+     * second scope for the channel (its disposal would no longer coincide with the
+     * store's lifetime, which rule 2 forbids).
+     */
+    setChannel(channel: ResolvedChannel): void;
+    dispose(): Promise<void>;
+}
+export interface EnterPlatformScopeOptions {
+    readonly channel?: ResolvedChannel | undefined;
+    readonly requestMeta?: RequestMeta | undefined;
+    /** Which class of entry point this is. Defaults to `'http'`. */
+    readonly entryPoint?: ScopeEntryPointKind | undefined;
+    /** Root to branch from. Defaults to the process-wide root container. */
+    readonly container?: KernelContainer | undefined;
+}
+/** The scope of the current execution, or `undefined` outside one. */
+export declare function getCurrentPlatformScope(): PlatformScope | undefined;
+/**
+ * How many scopes are currently open. Diagnostics only — the leak test asserts
+ * it returns to its pre-request value after success, error and client abort
+ * (FR-015).
+ */
+export declare function openPlatformScopeCount(): number;
+/**
+ * Run `run` inside a fresh resolution scope with `tenant` as the ambient tenant
+ * context. The scope is disposed when `run` settles — on success, on error and
+ * on abort.
+ */
+export declare function enterPlatformScope<T>(tenant: TenantContext, run: (scope: PlatformScope) => T | Promise<T>, opts?: EnterPlatformScopeOptions): Promise<T>;
+/**
+ * Open a scope that crosses every organisation, for an execution that has no
+ * caller to derive tenancy from: a worker job, a CLI script, a boot reconciler
+ * or an interval sweep.
+ *
+ * The difference from `withSystemScope` is which question it answers.
+ * `withSystemScope` **widens an execution that already has a context** (a
+ * request handler that must read across organisations); this **starts** one, and
+ * is therefore also where the resolution scope is created. Both emit the same
+ * escape-hatch audit record, so `reason` stays mandatory and the cross-org
+ * access stays observable.
+ */
+export declare function enterSystemScope<T>(reason: string, run: (scope: PlatformScope) => T | Promise<T>, opts?: Omit<EnterPlatformScopeOptions, 'channel'>): Promise<T>;
+//# sourceMappingURL=scope.d.ts.map

package/dist/kernel/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/kernel/scope.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAoB,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AAEH,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IACzC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACtD,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CAClD;AAcD,sEAAsE;AACtE,wBAAgB,uBAAuB,IAAI,aAAa,GAAG,SAAS,CAEnE;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AA8GD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7C,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,CAAC,CAAC,CAeZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7C,IAAI,GAAE,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAM,GACpD,OAAO,CAAC,CAAC,CAAC,CAMZ"}