@endora-commerce/mod-megamenu 0.100.0

package/dist/backend/services/cross-module-ports.js

@@ -0,0 +1,88 @@
+/**
+ * A category target's public storefront URL, or `null` for one a shopper may not
+ * reach — which drops the item, and its children with it.
+ *
+ * `/c/<slug>` is the storefront's category route
+ * (`storefront/app/(catalog)/c/[slug]`), and a module naming it is the tree's
+ * established shape: `seo`'s sitemap builds `/c/`, `/p/` and `/<slug>` in its own
+ * sources for the same three things. The composition roots disagreed about it —
+ * the harness built `/catalog/<slug>`, which no route serves — and no test in the
+ * tree read the value, so the harness's answer was wrong for as long as it
+ * existed.
+ *
+ * **Deactivated and soft-deleted are both refusals**, which is production's
+ * `is_active = true and deleted_at is null`. `liveOnly` is the port's word for
+ * the second; `isActive` rides on the record because it is the caller's
+ * judgement, and the admin-side existence check below deliberately makes the
+ * opposite one.
+ */
+export async function resolveCategoryUrl(categories, categoryId) {
+    const category = await categories.findById(categoryId, { liveOnly: true });
+    if (!category || !category.isActive || !category.slug)
+        return null;
+    return `/c/${category.slug}`;
+}
+/**
+ * A CMS page target's public storefront URL, or `null` when the page is gone.
+ *
+ * **No status or `active` narrowing**, which is what both roots did and is an
+ * asymmetry with the category case above rather than an oversight of this drain:
+ * a draft or deactivated page keeps its menu item and answers for itself when the
+ * shopper follows the link. Changing it is a product decision, and T118c moves a
+ * value rather than redesigning it.
+ */
+export async function resolveCmsPageUrl(pages, pageId) {
+    const page = await pages.findById(pageId);
+    if (!page?.slug)
+        return null;
+    return `/${page.slug}`;
+}
+/**
+ * An asset target or icon, resolved to the three fields a menu payload carries.
+ *
+ * `null` for an asset that is gone, and for one whose stored kind a menu cannot
+ * render: the library holds `pdf`, `certificate` and `other` as well, and
+ * `MegamenuAssetKind` is the narrower pair. The narrowing is the roots' own
+ * (`if (row.kind !== 'image' && row.kind !== 'video') return null`) and it is what
+ * keeps the wire shape's union honest.
+ *
+ * **No `catch` around `getAsset`, deliberately.** It throws 404 for a row that is
+ * gone, which the read above has already answered `null` for, so the only way to
+ * reach it is an asset deleted between the two reads — and swallowing it would
+ * also swallow `ModuleDisabledError`, which is the fail-open composition
+ * checklist item 7 refuses. Neither root caught here either.
+ */
+export async function resolveMenuAsset(ports, assetId) {
+    const record = await ports.assets.findById(assetId);
+    if (!record)
+        return null;
+    if (record.kind !== 'image' && record.kind !== 'video')
+        return null;
+    // D-223 — the URL arrives absolute; the module that built it is the only party
+    // that knows which adapter produced it and whether it is signed.
+    const detail = await ports.assetLibrary.getAsset(assetId);
+    return { url: detail.url, label: record.label, kind: record.kind };
+}
+/**
+ * The block a panel inlines, in the language the menu is being resolved for, or
+ * `null` when there is nothing to inline — which drops the item.
+ *
+ * `schemaVersion: 1` is **this module's wire contract**
+ * (`megamenuResolvedBlockSchema`) and not the CMS envelope's deprecated
+ * `schema_version`, which is normalized away on read. It is a constant here for
+ * the same reason it was a constant in the root closures: nothing produces a
+ * second version of this payload shape, and the field belongs to whoever owns the
+ * response.
+ */
+export async function resolveMenuBlock(blocks, blockId, language) {
+    const block = await blocks.findLocalizedById(blockId, language);
+    if (!block)
+        return null;
+    return {
+        id: block.id,
+        code: block.code,
+        language: block.language,
+        content: { schemaVersion: 1, data: block.data },
+    };
+}
+//# sourceMappingURL=cross-module-ports.js.map

package/dist/backend/services/cross-module-ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-module-ports.js","sourceRoot":"","sources":["../../../src/backend/services/cross-module-ports.ts"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAAkD,EAClD,UAAkB;IAElB,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3E,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACnE,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAwC,EACxC,MAAc;IAEd,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,EAAE,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAgE,EAChE,OAAe;IAEf,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAEpE,+EAA+E;IAC/E,iEAAiE;IACjE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1D,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;AACrE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAA0C,EAC1C,OAAe,EACf,QAAgB;IAEhB,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;KAChD,CAAC;AACJ,CAAC"}

package/dist/backend/services/megamenu-cache.d.ts

@@ -0,0 +1,36 @@
+import type { Redis } from 'ioredis';
+import type { ResolvedMegamenu } from '@endora-commerce/contracts';
+/**
+ * Storefront read-through cache for the Megamenu module — feature 015 / T017.
+ *
+ * Mirrors feature 014's `CmsCache` shape exactly: same key-prefix scheme,
+ * same TTL, same SCAN-based coarse invalidation. Keys live under
+ * `megamenu:v1:<channelCode>:<language>`.
+ */
+export declare const MEGAMENU_CACHE_KEY_PREFIX = "megamenu:v1:";
+export declare const MEGAMENU_CACHE_DEFAULT_TTL_SECONDS: number;
+export interface MegamenuCacheOptions {
+    ttlSeconds?: number;
+    /** When false, get/set are short-circuit no-ops (useful for tests). */
+    enabled?: boolean;
+}
+export declare class MegamenuCache {
+    private readonly redis;
+    private readonly ttlSeconds;
+    private readonly enabled;
+    constructor(redis: Redis, options?: MegamenuCacheOptions);
+    static composeKey(channelCode: string, language: string): string;
+    get(channelCode: string, language: string): Promise<ResolvedMegamenu | null>;
+    set(channelCode: string, language: string, payload: ResolvedMegamenu): Promise<void>;
+    invalidateScope(channelCode: string, language: string): Promise<void>;
+    /**
+     * Coarse drop of every cache entry for one channel — used when a binding
+     * for that channel changes scope (the language is not always known to the
+     * caller without an extra DB read).
+     */
+    invalidateChannel(channelCode: string): Promise<void>;
+    /** Used when a menu-level write happens (one menu may serve N bindings). */
+    invalidateAll(): Promise<void>;
+    private scanDelete;
+}
+//# sourceMappingURL=megamenu-cache.d.ts.map

package/dist/backend/services/megamenu-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu-cache.d.ts","sourceRoot":"","sources":["../../../src/backend/services/megamenu-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;GAMG;AAEH,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AACxD,eAAO,MAAM,kCAAkC,QAAS,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,aAAa;IAIZ,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEL,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,oBAAyB;IAK7E,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAI1D,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAY5E,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUpF,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3E;;;;OAIG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,4EAA4E;IACtE,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;YAItB,UAAU;CASzB"}

package/dist/backend/services/megamenu-cache.js

@@ -0,0 +1,70 @@
+/**
+ * Storefront read-through cache for the Megamenu module — feature 015 / T017.
+ *
+ * Mirrors feature 014's `CmsCache` shape exactly: same key-prefix scheme,
+ * same TTL, same SCAN-based coarse invalidation. Keys live under
+ * `megamenu:v1:<channelCode>:<language>`.
+ */
+export const MEGAMENU_CACHE_KEY_PREFIX = 'megamenu:v1:';
+export const MEGAMENU_CACHE_DEFAULT_TTL_SECONDS = 5 * 60;
+export class MegamenuCache {
+    redis;
+    ttlSeconds;
+    enabled;
+    constructor(redis, options = {}) {
+        this.redis = redis;
+        this.ttlSeconds = options.ttlSeconds ?? MEGAMENU_CACHE_DEFAULT_TTL_SECONDS;
+        this.enabled = (options.enabled ?? true) && this.ttlSeconds > 0;
+    }
+    static composeKey(channelCode, language) {
+        return `${MEGAMENU_CACHE_KEY_PREFIX}${channelCode}:${language}`;
+    }
+    async get(channelCode, language) {
+        if (!this.enabled)
+            return null;
+        const raw = await this.redis.get(MegamenuCache.composeKey(channelCode, language));
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            await this.redis.del(MegamenuCache.composeKey(channelCode, language));
+            return null;
+        }
+    }
+    async set(channelCode, language, payload) {
+        if (!this.enabled)
+            return;
+        await this.redis.set(MegamenuCache.composeKey(channelCode, language), JSON.stringify(payload), 'EX', this.ttlSeconds);
+    }
+    async invalidateScope(channelCode, language) {
+        if (!this.enabled)
+            return;
+        await this.redis.del(MegamenuCache.composeKey(channelCode, language));
+    }
+    /**
+     * Coarse drop of every cache entry for one channel — used when a binding
+     * for that channel changes scope (the language is not always known to the
+     * caller without an extra DB read).
+     */
+    async invalidateChannel(channelCode) {
+        await this.scanDelete(`${MEGAMENU_CACHE_KEY_PREFIX}${channelCode}:*`);
+    }
+    /** Used when a menu-level write happens (one menu may serve N bindings). */
+    async invalidateAll() {
+        await this.scanDelete(`${MEGAMENU_CACHE_KEY_PREFIX}*`);
+    }
+    async scanDelete(pattern) {
+        if (!this.enabled)
+            return;
+        let cursor = '0';
+        do {
+            const [next, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 200);
+            cursor = next;
+            if (keys.length > 0)
+                await this.redis.del(...keys);
+        } while (cursor !== '0');
+    }
+}
+//# sourceMappingURL=megamenu-cache.js.map

package/dist/backend/services/megamenu-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu-cache.js","sourceRoot":"","sources":["../../../src/backend/services/megamenu-cache.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG,cAAc,CAAC;AACxD,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,GAAG,EAAE,CAAC;AAQzD,MAAM,OAAO,aAAa;IAIK;IAHZ,UAAU,CAAS;IACnB,OAAO,CAAU;IAElC,YAA6B,KAAY,EAAE,UAAgC,EAAE;QAAhD,UAAK,GAAL,KAAK,CAAO;QACvC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kCAAkC,CAAC;QAC3E,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,WAAmB,EAAE,QAAgB;QACrD,OAAO,GAAG,yBAAyB,GAAG,WAAW,IAAI,QAAQ,EAAE,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,WAAmB,EAAE,QAAgB;QAC7C,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC/B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;QAClF,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;YACtE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,WAAmB,EAAE,QAAgB,EAAE,OAAyB;QACxE,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAClB,aAAa,CAAC,UAAU,CAAC,WAAW,EAAE,QAAQ,CAAC,EAC/C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EACvB,IAAI,EACJ,IAAI,CAAC,UAAU,CAChB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,WAAmB,EAAE,QAAgB;QACzD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IACxE,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,iBAAiB,CAAC,WAAmB;QACzC,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,yBAAyB,GAAG,WAAW,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,aAAa;QACjB,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,yBAAyB,GAAG,CAAC,CAAC;IACzD,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,OAAe;QACtC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,MAAM,GAAG,GAAG,CAAC;QACjB,GAAG,CAAC;YACF,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;YACnF,MAAM,GAAG,IAAI,CAAC;YACd,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACrD,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;IAC3B,CAAC;CACF"}

package/dist/backend/services/megamenu-item-service.d.ts

@@ -0,0 +1,39 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type MegamenuDetail, type PutItemsRequest } from '@endora-commerce/contracts';
+import type { MegamenuCache } from './megamenu-cache.js';
+import type { MegamenuService } from './megamenu-service.js';
+import type { MegamenuCrossModulePorts } from './cross-module-ports.js';
+export interface SetTreeWarning {
+    code: 'MEGAMENU_DEPTH_EXCEEDED';
+    message: string;
+}
+export interface SetTreeResult {
+    detail: MegamenuDetail;
+    warnings: SetTreeWarning[];
+}
+/**
+ * Tree mutations for a Megamenu — feature 015 / T026. Full-overwrite per
+ * save (per `research.md` § R4): the request supplies the desired tree
+ * and the service rewrites `megamenu_items` for the menu in one
+ * transaction. Per-kind targets are validated through the cross-module
+ * ports so the unit test can stub them.
+ */
+export declare class MegamenuItemService {
+    private readonly emFactory;
+    private readonly menuService;
+    private readonly ports;
+    private readonly cache?;
+    constructor(emFactory: () => EntityManager, menuService: MegamenuService, ports: MegamenuCrossModulePorts, cache?: MegamenuCache | undefined);
+    setTree(menuId: string, body: PutItemsRequest): Promise<SetTreeResult>;
+    /**
+     * Normalises the request tree:
+     *  - assigns server ids to items missing one;
+     *  - validates every parentId either references an item also present in
+     *    the payload or is null (top-level);
+     *  - sorts siblings by their input position and rewrites position 0..N-1;
+     *  - computes depth per node so the soft-warning check stays cheap.
+     */
+    private normalise;
+    private fetchChannelIdsForMenu;
+}
+//# sourceMappingURL=megamenu-item-service.d.ts.map

package/dist/backend/services/megamenu-item-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu-item-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/megamenu-item-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAaxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAHN,SAAS,EAAE,MAAM,aAAa,EAC9B,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,wBAAwB,EAC/B,KAAK,CAAC,EAAE,aAAa,YAAA;IAGlC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAmE5E;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;YAwEH,sBAAsB;CAQrC"}

package/dist/backend/services/megamenu-item-service.js

@@ -0,0 +1,151 @@
+import { randomUUID } from 'crypto';
+import { ERROR_CODES, } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { validateTarget } from './target-validator.js';
+const SOFT_DEPTH_WARN_AT = 4;
+/**
+ * Tree mutations for a Megamenu — feature 015 / T026. Full-overwrite per
+ * save (per `research.md` § R4): the request supplies the desired tree
+ * and the service rewrites `megamenu_items` for the menu in one
+ * transaction. Per-kind targets are validated through the cross-module
+ * ports so the unit test can stub them.
+ */
+export class MegamenuItemService {
+    emFactory;
+    menuService;
+    ports;
+    cache;
+    constructor(emFactory, menuService, ports, cache) {
+        this.emFactory = emFactory;
+        this.menuService = menuService;
+        this.ports = ports;
+        this.cache = cache;
+    }
+    async setTree(menuId, body) {
+        const em = this.emFactory();
+        const menuRow = await this.menuService.findRow(menuId);
+        if (!menuRow)
+            throw new HttpError(404, ERROR_CODES.MEGAMENU_NOT_FOUND, 'Megamenu not found.');
+        if (body.version !== menuRow.version) {
+            throw new HttpError(409, ERROR_CODES.VERSION_CONFLICT, 'Megamenu was updated concurrently.');
+        }
+        const normalised = this.normalise(body.items);
+        const warnings = [];
+        if (normalised.some((item) => item.depth > SOFT_DEPTH_WARN_AT)) {
+            warnings.push({
+                code: 'MEGAMENU_DEPTH_EXCEEDED',
+                message: `Tree contains items deeper than level ${SOFT_DEPTH_WARN_AT}.`,
+            });
+        }
+        // Cross-module target validation — Channel scope is the union of
+        // every binding's channel. v1 enforces existence only; full
+        // out-of-scope refusal lands in US3.
+        const channelIds = await this.fetchChannelIdsForMenu(menuId);
+        for (const item of normalised) {
+            await validateTarget(item, channelIds, this.ports);
+        }
+        await em.transactional(async (tx) => {
+            // `tx.execute`, not `tx.getConnection().execute`: a connection carries no
+            // transaction context, so this delete used to commit on its own connection
+            // the moment it ran. A re-insert the database then refused — a child item
+            // listed before its parent is enough — rolled a transaction back that had
+            // never held the delete, and the operator's whole menu was gone (issue
+            // #200). `test/integration/megamenu/write-atomicity.test.ts` is that case.
+            await tx.execute(`delete from megamenu_items where megamenu_id = ?`, [menuId]);
+            for (const item of normalised) {
+                const now = new Date();
+                await tx.execute(`insert into megamenu_items
+             (id, megamenu_id, parent_id, position, kind, labels, descriptions, target, created_at, updated_at)
+           values (?, ?, ?, ?, ?, ?::jsonb, ?::jsonb, ?::jsonb, ?, ?)`, [
+                    item.id,
+                    menuId,
+                    item.parentId,
+                    item.position,
+                    item.kind,
+                    JSON.stringify(item.labels),
+                    JSON.stringify(item.descriptions ?? null),
+                    JSON.stringify(item.target),
+                    now,
+                    now,
+                ]);
+            }
+            await tx.execute(`update megamenus set version = version + 1, updated_at = now() where id = ?`, [menuId]);
+        });
+        if (this.cache)
+            await this.cache.invalidateAll();
+        const detail = await this.menuService.get(menuId);
+        return { detail, warnings };
+    }
+    /**
+     * Normalises the request tree:
+     *  - assigns server ids to items missing one;
+     *  - validates every parentId either references an item also present in
+     *    the payload or is null (top-level);
+     *  - sorts siblings by their input position and rewrites position 0..N-1;
+     *  - computes depth per node so the soft-warning check stays cheap.
+     */
+    normalise(items) {
+        const seenIds = new Set();
+        const expanded = items.map((item) => {
+            const id = item.id ?? randomUUID();
+            if (seenIds.has(id)) {
+                throw new HttpError(400, ERROR_CODES.VALIDATION_FAILED, `Duplicate item id "${id}".`);
+            }
+            seenIds.add(id);
+            return {
+                ...item,
+                id,
+                parentId: item.parentId ?? null,
+                position: item.position,
+                depth: 0,
+            };
+        });
+        // Validate parentId references.
+        for (const item of expanded) {
+            if (item.parentId !== null && !seenIds.has(item.parentId)) {
+                throw new HttpError(400, ERROR_CODES.VALIDATION_FAILED, `Item ${item.id} references parentId ${item.parentId} which is not in the payload.`);
+            }
+        }
+        // Sort by parent + supplied position, then rewrite to 0..N-1.
+        const byParent = new Map();
+        for (const item of expanded) {
+            const list = byParent.get(item.parentId) ?? [];
+            list.push(item);
+            byParent.set(item.parentId, list);
+        }
+        for (const list of byParent.values()) {
+            list.sort((a, b) => a.position - b.position);
+            list.forEach((item, idx) => {
+                item.position = idx;
+            });
+        }
+        // Compute depth via BFS from roots.
+        const childrenIndex = byParent;
+        const queue = [];
+        for (const root of childrenIndex.get(null) ?? []) {
+            root.depth = 1;
+            queue.push({ id: root.id, depth: 1 });
+        }
+        while (queue.length > 0) {
+            const head = queue.shift();
+            const children = childrenIndex.get(head.id) ?? [];
+            for (const child of children) {
+                child.depth = head.depth + 1;
+                queue.push({ id: child.id, depth: child.depth });
+            }
+        }
+        // Detect cycles / orphans — every item should have its depth set.
+        for (const item of expanded) {
+            if (item.depth === 0) {
+                throw new HttpError(400, ERROR_CODES.VALIDATION_FAILED, `Item ${item.id} forms an orphan or cycle (no path to root).`);
+            }
+        }
+        return expanded;
+    }
+    async fetchChannelIdsForMenu(menuId) {
+        const rows = (await this.emFactory().execute(`select distinct sales_channel_id::text as channel_id
+         from megamenu_bindings where megamenu_id = ?`, [menuId]));
+        return rows.map((r) => r.channel_id);
+    }
+}
+//# sourceMappingURL=megamenu-item-service.js.map

package/dist/backend/services/megamenu-item-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu-item-service.js","sourceRoot":"","sources":["../../../src/backend/services/megamenu-item-service.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/megamenu-language-reference.d.ts

@@ -0,0 +1,12 @@
+import type { DictionaryReferenceRegistryPort } from '@endora-commerce/contracts';
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * Who in `megamenu` still points at a language (feature 077, D-87).
+ *
+ * `languages` used to count `megamenu_bindings` itself, naming this module's
+ * table in a string no import-level boundary check can see. A binding is
+ * per-channel and per-language, so a language the platform has dropped
+ * leaves the binding unreachable rather than merely untranslated.
+ */
+export declare function registerMegamenuLanguageReferences(registry: DictionaryReferenceRegistryPort, emFactory: () => EntityManager): void;
+//# sourceMappingURL=megamenu-language-reference.d.ts.map

package/dist/backend/services/megamenu-language-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu-language-reference.d.ts","sourceRoot":"","sources":["../../../src/backend/services/megamenu-language-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,+BAA+B,EACzC,SAAS,EAAE,MAAM,aAAa,GAC7B,IAAI,CAoBN"}

package/dist/backend/services/megamenu-language-reference.js

@@ -0,0 +1,24 @@
+/**
+ * Who in `megamenu` still points at a language (feature 077, D-87).
+ *
+ * `languages` used to count `megamenu_bindings` itself, naming this module's
+ * table in a string no import-level boundary check can see. A binding is
+ * per-channel and per-language, so a language the platform has dropped
+ * leaves the binding unreachable rather than merely untranslated.
+ */
+export function registerMegamenuLanguageReferences(registry, emFactory) {
+    registry.register({
+        ownerModuleId: 'megamenu',
+        consumer: 'megamenu',
+        tableName: 'megamenu_bindings',
+        columnName: 'language',
+        blocking: true,
+        countReferences: async (code) => {
+            const rows = (await emFactory().execute(`select count(*)::int as n from "megamenu_bindings" where "language" = ?`, [code]));
+            return rows[0]?.n ?? 0;
+        },
+        usedCodes: async () => (await emFactory().execute(`select "language" as code, count(*)::int as count
+           from "megamenu_bindings" where "language" is not null group by "language"`)),
+    });
+}
+//# sourceMappingURL=megamenu-language-reference.js.map

package/dist/backend/services/megamenu-language-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu-language-reference.js","sourceRoot":"","sources":["../../../src/backend/services/megamenu-language-reference.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,UAAU,kCAAkC,CAChD,QAAyC,EACzC,SAA8B;IAE9B,QAAQ,CAAC,QAAQ,CAAC;QAChB,aAAa,EAAE,UAAU;QACzB,QAAQ,EAAE,UAAU;QACpB,SAAS,EAAE,mBAAmB;QAC9B,UAAU,EAAE,UAAU;QACtB,QAAQ,EAAE,IAAI;QACd,eAAe,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAC9B,MAAM,IAAI,GAAG,CAAC,MAAM,SAAS,EAAE,CAAC,OAAO,CACrC,yEAAyE,EACzE,CAAC,IAAI,CAAC,CACP,CAAyB,CAAC;YAC3B,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QACD,SAAS,EAAE,KAAK,IAAI,EAAE,CACpB,CAAC,MAAM,SAAS,EAAE,CAAC,OAAO,CACxB;qFAC6E,CAC9E,CAA2C;KAC/C,CAAC,CAAC;AACL,CAAC"}

package/dist/backend/services/megamenu-reference-registry.d.ts

@@ -0,0 +1,24 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+export interface MegamenuItemReference {
+    menuId: string;
+    itemId: string;
+    menuName: string;
+    /** Distinguishes assetId vs iconAssetId hits in the asset scan. */
+    via?: 'assetId' | 'iconAssetId';
+}
+export declare class MegamenuReferenceRegistry {
+    private readonly emFactory;
+    constructor(emFactory: () => EntityManager);
+    findCategoryReferences(categoryId: string): Promise<MegamenuItemReference[]>;
+    findCmsPageReferences(pageId: string): Promise<MegamenuItemReference[]>;
+    findCmsBlockReferences(blockId: string): Promise<MegamenuItemReference[]>;
+    /**
+     * Asset references — both `target.assetId` (asset items) and
+     * `target.iconAssetId` (link items with an icon) count. Returns one
+     * row per item; a single item that matches both scanners is rare in
+     * practice but the SQL deduplicates regardless.
+     */
+    findAssetReferences(assetIds: string[]): Promise<MegamenuItemReference[]>;
+    private findByKindAndPath;
+}
+//# sourceMappingURL=megamenu-reference-registry.d.ts.map

package/dist/backend/services/megamenu-reference-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu-reference-registry.d.ts","sourceRoot":"","sources":["../../../src/backend/services/megamenu-reference-registry.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,GAAG,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;CACjC;AAED,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,MAAM,aAAa;IAErD,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAI5E,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAIvE,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAI/E;;;;;OAKG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;YA0BjE,iBAAiB;CAqBhC"}

package/dist/backend/services/megamenu-reference-registry.js

@@ -0,0 +1,69 @@
+// In-process registry of references between Megamenu items and the
+// upstream entities they target. Consulted by:
+//
+//   * the catalog category-delete endpoint (Category → MegamenuItem)
+//   * the cms page + block delete endpoints (CmsPage / CmsBlock → MegamenuItem)
+//   * the AssetReferenceRegistry (Asset → MegamenuItem)
+//
+// All scans are GIN-index-served by `idx_megamenu_items_target_refs`
+// (jsonb_path_ops) so scale is sub-millisecond at the platform's low-
+// hundreds item count.
+export class MegamenuReferenceRegistry {
+    emFactory;
+    constructor(emFactory) {
+        this.emFactory = emFactory;
+    }
+    async findCategoryReferences(categoryId) {
+        return this.findByKindAndPath('category-link', 'categoryId', categoryId);
+    }
+    async findCmsPageReferences(pageId) {
+        return this.findByKindAndPath('cms-page-link', 'pageId', pageId);
+    }
+    async findCmsBlockReferences(blockId) {
+        return this.findByKindAndPath('cms-block-embed', 'blockId', blockId);
+    }
+    /**
+     * Asset references — both `target.assetId` (asset items) and
+     * `target.iconAssetId` (link items with an icon) count. Returns one
+     * row per item; a single item that matches both scanners is rare in
+     * practice but the SQL deduplicates regardless.
+     */
+    async findAssetReferences(assetIds) {
+        if (assetIds.length === 0)
+            return [];
+        const placeholders = assetIds.map(() => '?').join(', ');
+        const rows = (await this.emFactory().execute(`select mi.id::text     as item_id,
+              m.id::text      as menu_id,
+              m.name          as menu_name,
+              case
+                when mi.target->>'assetId'     in (${placeholders}) then 'assetId'
+                when mi.target->>'iconAssetId' in (${placeholders}) then 'iconAssetId'
+                else null
+              end             as via
+         from megamenu_items mi
+         join megamenus m on m.id = mi.megamenu_id
+        where mi.target->>'assetId'     in (${placeholders})
+           or mi.target->>'iconAssetId' in (${placeholders})`, [...assetIds, ...assetIds, ...assetIds, ...assetIds]));
+        return rows.map((row) => ({
+            itemId: row.item_id,
+            menuId: row.menu_id,
+            menuName: row.menu_name,
+            via: row.via,
+        }));
+    }
+    async findByKindAndPath(kind, targetField, value) {
+        const rows = (await this.emFactory().execute(`select mi.id::text as item_id,
+              m.id::text  as menu_id,
+              m.name      as menu_name
+         from megamenu_items mi
+         join megamenus m on m.id = mi.megamenu_id
+        where mi.kind = ?
+          and mi.target->>'${targetField}' = ?`, [kind, value]));
+        return rows.map((row) => ({
+            itemId: row.item_id,
+            menuId: row.menu_id,
+            menuName: row.menu_name,
+        }));
+    }
+}
+//# sourceMappingURL=megamenu-reference-registry.js.map

package/dist/backend/services/megamenu-reference-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu-reference-registry.js","sourceRoot":"","sources":["../../../src/backend/services/megamenu-reference-registry.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,qEAAqE;AACrE,gFAAgF;AAChF,wDAAwD;AACxD,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,uBAAuB;AAYvB,MAAM,OAAO,yBAAyB;IACP;IAA7B,YAA6B,SAA8B;QAA9B,cAAS,GAAT,SAAS,CAAqB;IAAG,CAAC;IAE/D,KAAK,CAAC,sBAAsB,CAAC,UAAkB;QAC7C,OAAO,IAAI,CAAC,iBAAiB,CAAC,eAAe,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;IAC3E,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAC,MAAc;QACxC,OAAO,IAAI,CAAC,iBAAiB,CAAC,eAAe,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,sBAAsB,CAAC,OAAe;QAC1C,OAAO,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACvE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,mBAAmB,CAAC,QAAkB;QAC1C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACrC,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAC1C;;;;qDAI+C,YAAY;qDACZ,YAAY;;;;;8CAKnB,YAAY;8CACZ,YAAY,GAAG,EACvD,CAAC,GAAG,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC,CACrD,CAAmG,CAAC;QACrG,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACxB,MAAM,EAAE,GAAG,CAAC,OAAO;YACnB,MAAM,EAAE,GAAG,CAAC,OAAO;YACnB,QAAQ,EAAE,GAAG,CAAC,SAAS;YACvB,GAAG,EAAE,GAAG,CAAC,GAAG;SACb,CAAC,CAAC,CAAC;IACN,CAAC;IAEO,KAAK,CAAC,iBAAiB,CAC7B,IAAY,EACZ,WAAmB,EACnB,KAAa;QAEb,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAC1C;;;;;;6BAMuB,WAAW,OAAO,EACzC,CAAC,IAAI,EAAE,KAAK,CAAC,CACd,CAAmE,CAAC;QACrE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACxB,MAAM,EAAE,GAAG,CAAC,OAAO;YACnB,MAAM,EAAE,GAAG,CAAC,OAAO;YACnB,QAAQ,EAAE,GAAG,CAAC,SAAS;SACxB,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/dist/backend/services/megamenu-service.d.ts

@@ -0,0 +1,70 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type ActivateBindingResponse, type CreateMegamenuRequest, type DictionaryValidator, type MegamenuBinding as MegamenuBindingDto, type MegamenuDetail, type MegamenuSummary, type PatchMegamenuRequest, type ResolvedMenuItem } from '@endora-commerce/contracts';
+import type { MegamenuCache } from './megamenu-cache.js';
+type MegamenuRow = {
+    id: string;
+    name: string;
+    description: string | null;
+    version: number;
+    created_at: Date | string;
+    updated_at: Date | string;
+};
+/**
+ * Megamenu CRUD + binding lifecycle. The activation transaction enforces
+ * "exactly one active megamenu per (channel, language)" via the partial
+ * unique index on `megamenu_bindings(sales_channel_id, language) WHERE
+ * active = true` (R3 / FR-008).
+ */
+export declare class MegamenuService {
+    private readonly emFactory;
+    private readonly cache?;
+    private readonly dictionaryValidator?;
+    constructor(emFactory: () => EntityManager, cache?: MegamenuCache | undefined, dictionaryValidator?: DictionaryValidator | undefined);
+    list(): Promise<{
+        data: MegamenuSummary[];
+        nextCursor: null;
+    }>;
+    create(input: CreateMegamenuRequest): Promise<MegamenuDetail>;
+    get(id: string): Promise<MegamenuDetail>;
+    patch(id: string, input: PatchMegamenuRequest): Promise<MegamenuDetail>;
+    delete(id: string): Promise<void>;
+    listBindings(menuId: string): Promise<MegamenuBindingDto[]>;
+    addBinding(menuId: string, salesChannelId: string, language: string): Promise<MegamenuBindingDto>;
+    private validateLanguage;
+    removeBinding(menuId: string, salesChannelId: string, language: string): Promise<void>;
+    /**
+     * Atomic activation swap (FR-008 / R3): deactivate the prior holder
+     * for the scope (if any) inside the same transaction, then upsert the
+     * new active row. The partial unique index refuses dual-active state
+     * even if this method's body regresses.
+     */
+    activate(menuId: string, salesChannelId: string, language: string): Promise<ActivateBindingResponse>;
+    deactivate(menuId: string, salesChannelId: string, language: string): Promise<void>;
+    findRow(id: string, em?: EntityManager): Promise<MegamenuRow | null>;
+    private assertMenuExists;
+    private assertVersion;
+    /**
+     * The kernel's own entity, not `select … from sales_channels` (feature 075,
+     * D-87). `sales_channels` is the kernel's table since feature 072 moved the
+     * resolution machinery there, and a module relating into the kernel by ORM is
+     * the sanctioned access.
+     *
+     * Read through the caller's `em`, not through
+     * `salesChannelResolutionPort.getById`: every caller here is inside
+     * `em.transactional`, and that accessor forks its own EntityManager, so the
+     * binding checks below would validate against rows outside the transaction
+     * they are about to write into.
+     */
+    private fetchChannel;
+    private fetchItems;
+    private fetchBindings;
+    private toSummary;
+    private toDetail;
+    private toBindingDto;
+    private toItemDto;
+    private iso;
+}
+/** Small helper for tests / smoke flows that need to assemble a tree. */
+export declare function emptyResolvedItems(): ResolvedMenuItem[];
+export {};
+//# sourceMappingURL=megamenu-service.d.ts.map