@endora-commerce/mod-sales-channels 0.100.0

package/dist/manifest.d.ts

@@ -0,0 +1,185 @@
+/** Module-lifecycle manifest (feature 018). */
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "text" | "textarea" | "select" | "radio" | "external" | "uuid" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+/** Legacy export retained for backward compatibility. */
+export declare const salesChannelsManifest: {
+    moduleCode: string;
+    groups: {
+        code: string;
+        name: string;
+        salesChannelCodes?: string[] | undefined;
+        isSystemProtected?: boolean | undefined;
+    }[];
+    settings: {
+        code: string;
+        name: string;
+        valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+        defaultValue: unknown;
+        description?: string | undefined;
+        groupCode?: string | undefined;
+        previousDefaultValues?: unknown[] | undefined;
+        salesChannelCodes?: string[] | undefined;
+        enumOptions?: string[] | undefined;
+        configurationType?: string | undefined;
+        hidden?: boolean | undefined;
+    }[];
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAgCA,+CAA+C;AAC/C,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8KnB,CAAC;AAEH,yDAAyD;AACzD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;CAAW,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,204 @@
+import { defineModuleManifest, defineModuleSettingsManifest, } from '@endora-commerce/contracts';
+/**
+ * Built-in settings manifest for the sales-channels module — feature 005.
+ *
+ * Reserves the `sales_channels` setting group so future channel-related
+ * knobs (default theme, host-map default, etc.) have a stable home.
+ */
+const settings = defineModuleSettingsManifest({
+    moduleCode: 'sales_channels',
+    groups: [
+        {
+            code: 'sales_channels',
+            name: 'Sales Channels',
+        },
+    ],
+    settings: [
+        {
+            code: 'sales_channels.storefront_url',
+            name: 'Storefront URL',
+            description: 'Public base URL of the storefront for this sales channel. Used by the SEO sitemap generator and any other module that stamps absolute URLs into outgoing payloads. Empty value falls back to STOREFRONT_BASE_URL env.',
+            groupCode: 'sales_channels',
+            valueType: 'string',
+            defaultValue: '',
+        },
+    ],
+});
+/** Module-lifecycle manifest (feature 018). */
+export const manifest = defineModuleManifest({
+    id: 'sales_channels',
+    name: 'Sales Channels',
+    description: 'Multi-channel storefront resolver and channel registry.',
+    version: '1.0.0',
+    // Rule 2 (bridge owner) — specs/065-manifest-aware-migrations/research.md §R9.
+    // This module owns nine `sales_channel_*` membership bridges plus
+    // `sales_channels.logo_asset_id`, so its tables foreign-key nine other
+    // modules. None of those edges is declared: the module that cannot function
+    // without channel scoping is the *domain* module, and every one of them
+    // already declares `sales_channels`. Four of the nine reverse edges close a
+    // cycle outright — sales_channels → catalog → sales_channels,
+    // sales_channels → cms → sales_channels,
+    // sales_channels → promotions → sales_channels, and
+    // sales_channels → customer_accounts → price_lists → catalog →
+    // sales_channels; together they are what made the naive union a 9-node SCC.
+    // The remaining five (assets_library, delivery_methods, organizations,
+    // payment_methods, taxes) close no cycle but are dropped by the same rule: a
+    // bridge owner declaring what it bridges inverts the ownership direction.
+    // Eight are recorded in test/unit/db/acknowledged-fk-edges.ts; the ninth,
+    // `sales_channels.logo_asset_id → assets`, is recorded there as
+    // `kernel → assets_library` because feature 072 T019 moved the SalesChannel
+    // entity — and with it the ownership of the `sales_channels` table — into the
+    // kernel. The nine bridge tables stay owned by this module.
+    //
+    // Forward-looking convention: a new bridge table for module X is owned by X's
+    // migration, so X → sales_channels covers it and no new exception is needed.
+    dependencies: ['dictionaries', 'settings'],
+    settings,
+    // Feature 074 (Constitution XVII), test C2 — functional base, and named by
+    // ruling 1. Channel scoping is structural: Principle XII is non-negotiable,
+    // every scoped read resolves the request's channel through the sanctioned
+    // accessors, and there is no unscoped read path to fall back to. The control
+    // this replaces was one of the nineteen that never accepted a deactivation
+    // — nineteen dependents refused it — so the lock takes away a dead button
+    // and adds a stated reason.
+    //
+    // `sales_channels.enabled` goes with it. Left declared it would fall through
+    // to an ordinary editable boolean that changes nothing; the existing rows are
+    // removed by a core data migration (feature 074, FR-010a), because the
+    // settings reconciler reports orphans and never deletes them.
+    activation: {
+        nonDeactivatable: true,
+        reason: 'Channel scoping is structural: every scoped read resolves the request\'s channel and ' +
+            'there is no unscoped path to fall back to.',
+    },
+    /**
+     * The twelve error codes this module owns — feature 090 Phase 3
+     * (`specs/090-module-owned-error-codes/contracts/error-code-declaration.md`
+     * §1.1). This is where the sentence for each is looked up from: `errors.<CODE>`
+     * in this module's own `i18n/{en,pl}.json`, which holds all twelve in both
+     * languages and holds no other `errors.*` key. None of them is a
+     * `check-error-translations.ts` `UNTRANSLATED_ERROR_CODES` entry.
+     *
+     * The list is answer-preserving, not a judgement (§6.2 and §6.5), and it was
+     * not written by hand: it is the verbatim output of the runbook's step-1
+     * derivation over the frozen capture at
+     * `backend/test/fixtures/error-code-routing/chain-answers.ts`, which records
+     * what the prefix chain in `@endora-commerce/mod-i18n` answered at
+     * `49f3c6817`. Re-routing a code to a better owner is
+     * `specs/082-error-code-ownership/rulings.md` §9's remaining work and is
+     * deliberately not done here.
+     *
+     * **`UNKNOWN_OPTION` is not here, and it is the one a reader will look for.**
+     * This module's rule in the chain is `UNKNOWN_` ∪ `SALES_CHANNEL_` ∪ a misc
+     * set, so reading the rule's *source* claims `UNKNOWN_OPTION` for
+     * `sales_channels`. The chain is an ordered `if` and `catalog`'s misc set
+     * names that code two branches earlier, so the chain's *answer* is `catalog`
+     * — which is what the capture records and what `catalog` declared in its own
+     * migration. Trap T1: read the answer, never the rule. The other three
+     * `UNKNOWN_` members of `ERROR_CODES` reach this rule and are here.
+     *
+     * **Four codes here look generic or look like another module's, and are
+     * this module's by a decision an earlier feature made** (trap T2).
+     * `CANNOT_MODIFY_SYSTEM_DEFAULT` and `ENTITY_WOULD_HAVE_ZERO_CHANNELS` name
+     * no channel at all and arrive through the chain's misc set;
+     * `UNKNOWN_CURRENCY_CODE` and `UNKNOWN_LANGUAGE_CODE` read like
+     * `dictionaries` codes and arrive through the `UNKNOWN_` prefix. The inverse
+     * holds as well: `CHANNEL_NO_WAREHOUSES`, `CHANNEL_WAREHOUSE_NOT_FOUND` and
+     * `WAREHOUSE_IS_DEFAULT_FOR_CHANNELS` route to `inventory`,
+     * `API_KEY_CHANNEL_MISMATCH` to `core`, `SETTING_OUT_OF_SCOPE_FOR_CHANNEL` to
+     * `settings`, `CMS_LANGUAGE_NOT_IN_CHANNEL_SCOPE` to `cms` and
+     * `MEGAMENU_LANGUAGE_NOT_IN_CHANNEL_SCOPE` to `megamenu`, so none of them is
+     * declared here.
+     *
+     * **Five of the twelve are raised outside this package**, which is D-95.2
+     * working as intended — routing follows the domain noun, never the thrower.
+     * `@endora-commerce/platform`'s channel resolver and membership service raise
+     * `MISSING_SALES_CHANNEL_CONTEXT`, `UNKNOWN_SALES_CHANNEL`,
+     * `INACTIVE_SALES_CHANNEL` and `ENTITY_WOULD_HAVE_ZERO_CHANNELS` (the
+     * `SalesChannel` entity moved to the kernel in feature 072 T019), and
+     * `search`'s public route raises `MISSING_SALES_CHANNEL_CONTEXT` too. The
+     * sentences stay here.
+     *
+     * **Three of the twelve are raised by nothing in the tree** —
+     * `UNKNOWN_LANGUAGE_CODE`, `UNKNOWN_CURRENCY_CODE` and
+     * `SALES_CHANNEL_ATTRIBUTION_IMMUTABLE`. The first two were superseded rather
+     * than never built: feature 017 moved language and currency validation onto
+     * the central dictionary, so an unknown code is refused as
+     * `DICTIONARY_ENTRY_NOT_FOUND` by `dictionaryReferenceHttpError` in this module's own
+     * service, and `test/contract/sales_channels/admin-crud-lifecycle.contract.test.ts`
+     * asserts that answer while calling these two "legacy" in its own comment. The
+     * third is a guard with nothing to guard: no admin route exposes
+     * `salesChannelId` mutation on an order or a quote, so FR-012's immutability
+     * is structural, and `specs/005-sales-channels/tasks.md` T044/T059 record the
+     * guard as vacuous and deferred to the first route that would need it. All
+     * three are declared anyway — ownership follows the capture and not the raise
+     * sites (trap T10); dropping one reds the progress test as `undeclared` and
+     * moves an answer this merge request is not allowed to move.
+     *
+     * No `tokens`: no code here carries a refusal discriminator. Derived from the
+     * raise sites per the runbook's §5 — the envelope's `refusalToken` reads
+     * `details.code` and nothing else, every `new HttpError` raising one of these
+     * twelve passes either no fourth argument or the Zod-style
+     * `Array<{path, issue}>`, which `refusalToken` ignores by construction; the
+     * §5 raise-site scan attributes the tree's token-carrying codes to `core`,
+     * `invoices` and `carts` and names none of these; and the bundles hold no
+     * `errors.<CODE>.<token>` key in the other direction.
+     */
+    errorCodes: [
+        { code: 'CANNOT_MODIFY_SYSTEM_DEFAULT' },
+        { code: 'DUPLICATE_SALES_CHANNEL_CODE' },
+        { code: 'ENTITY_WOULD_HAVE_ZERO_CHANNELS' },
+        { code: 'INACTIVE_SALES_CHANNEL' },
+        { code: 'MISSING_SALES_CHANNEL_CONTEXT' },
+        { code: 'SALES_CHANNEL_ATTRIBUTION_IMMUTABLE' },
+        { code: 'SALES_CHANNEL_CODE_IMMUTABLE' },
+        { code: 'SALES_CHANNEL_HAS_ATTRIBUTIONS' },
+        { code: 'STALE_SALES_CHANNEL_WRITE' },
+        { code: 'UNKNOWN_CURRENCY_CODE' },
+        { code: 'UNKNOWN_LANGUAGE_CODE' },
+        { code: 'UNKNOWN_SALES_CHANNEL' },
+    ],
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    permissions: [
+        { code: 'sales_channels:read', label: 'View sales channels' },
+        { code: 'sales_channels:write', label: 'Manage sales channels' },
+    ],
+    actions: [
+        /**
+         * The module's landing surface, declared by feature 091's Phase 4 batch 14.
+         *
+         * `AppShell.tsx` carried a hand-written *Navigate* row for
+         * `/sales-channels` until that batch, and this module declared only the
+         * *create* action beside it — so the roster was advertised by a copy the
+         * server was never asked about while the create form was advertised by a
+         * declaration it served. The destination, the code and the keywords are the
+         * row's; the label and description are the two strings it rendered
+         * (`appShell.nav.salesChannels`, `appShell.palette.sub.storefrontChannels`),
+         * moved into this module's own bundle.
+         */
+        {
+            id: 'open-sales-channels',
+            labelKey: 'actions.openSalesChannels.label',
+            descriptionKey: 'actions.openSalesChannels.description',
+            icon: 'Store',
+            targetRoute: '/sales-channels',
+            requiredPermission: 'sales_channels:read',
+            keywords: ['sales', 'channel', 'channels', 'kanał', 'sprzedaży'],
+            weight: 160,
+        },
+        {
+            id: 'new-sales-channel',
+            labelKey: 'actions.newSalesChannel.label',
+            descriptionKey: 'actions.newSalesChannel.description',
+            icon: 'Layers',
+            targetRoute: '/sales-channels/new',
+            requiredPermission: 'sales_channels:write',
+            keywords: ['channel', 'new', 'storefront', 'kanał', 'sprzedaży'],
+            weight: 150,
+        },
+    ],
+});
+/** Legacy export retained for backward compatibility. */
+export const salesChannelsManifest = settings;
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

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

package/docs/sales_channels/admin-usage.md

@@ -0,0 +1,77 @@
+---
+title: Admin usage
+sidebar_position: 2
+---
+
+# Admin usage — Sales Channels
+
+How a platform administrator drives the Sales Channels module from the Admin UI day to day. Every action below is also reachable through the module's admin HTTP API.
+
+## Locating the area
+
+Sidebar → **Operations → Sales channels**.
+
+The list page shows every channel registered on the platform. The system-default channel is marked with a `System default` badge and is always present (a freshly-installed platform automatically gets a `default` channel on first boot).
+
+## Creating a new channel
+
+1. Click **+ New channel**.
+2. Fill in:
+   - **Code** — lowercase machine-friendly identifier; immutable after creation.
+   - **Display name** — currently a single `en-US` string; multi-locale support is a follow-up.
+   - **Theme code** *(optional)* — opaque identifier the storefront uses to pick its theme.
+   - **Languages** — comma- or newline-separated. Codes must already exist in the i18n module's languages registry.
+   - **Default language** — must be one of the languages above.
+   - **Currencies** / **Default currency** — same shape; codes must exist in the currencies registry.
+   - **Active** *(default `true`)*.
+3. **Create channel.** The system refuses if the code is already in use, or if any language / currency code is unknown.
+
+## Editing an existing channel
+
+1. Click a channel's `code` in the list.
+2. The edit page loads its identity. Make changes; click **Save changes**.
+3. If another administrator changed the same channel between your load and save, the save returns a 412 conflict banner with the current version. Refresh the page to pull the latest state and re-apply your changes.
+
+## Deactivating a channel
+
+Use the **Deactivate** button on the channel detail page. Deactivation is idempotent and reversible:
+
+- The channel disappears from the resolver's accept list (storefront / POS requests pointing at it are refused with `INACTIVE_SALES_CHANNEL`).
+- It is hidden from the "Add to channel" picker on every entity edit page.
+- Existing memberships and historical Orders / Quotes still reference it.
+
+The system-default channel cannot be deactivated.
+
+## Hard-deleting a channel
+
+The **Delete** button is destructive. The platform refuses the operation when:
+
+- The channel is the system default.
+- Any Order or Quote references the channel — these attributions are immutable, so the only way to free the channel is to keep it (deactivation is the right answer here).
+- Removing the channel would leave one or more entities (Products, Customers, …) bound to **zero** channels — *unless* you confirm the rebind-to-Default prompt, in which case those entities are rebound to the system default in the same transaction before the channel row is dropped.
+
+The bridge tables' `ON DELETE CASCADE` removes every remaining membership row.
+
+## Managing membership from the entity side
+
+Every entity edit page that supports channel membership (Products to start; the other 8 types are a mechanical follow-up) shows a **Sales channels** card near the bottom:
+
+- The list shows the channels the entity is currently in, with a `System default` badge where appropriate.
+- The picker lists channels the entity is **not** yet in. Pick one and click **Add**.
+- **Remove** triggers the at-least-one-channel invariant — if the entity has only one channel left and you confirm the rebind-to-Default prompt, the system rebinds it to the system default before completing the remove.
+
+## Multi-storefront set-up
+
+To run two storefronts on the same backend (e.g. `serwisA.com` and `serwisB.com`), set the `SALES_CHANNEL_HOST_MAP` env var on the backend:
+
+```env
+SALES_CHANNEL_HOST_MAP=serwisA.com=channel-a,serwisB.com=channel-b
+```
+
+Each storefront request resolves to its host's channel automatically; no header is needed. Each storefront then sees only the products / customers / prices that belong to its channel.
+
+## What admins cannot do
+
+- Reassign an Order or Quote Request to a different channel after creation. The attribution is immutable; this is a deliberate audit guarantee, not an oversight.
+- Delete the system-default channel. The boot-time reconciler will recreate it on the next platform boot.
+- Force two channels to be system-default simultaneously. The partial unique index prevents it at the database layer.

package/docs/sales_channels/developer-guide.md

@@ -0,0 +1,107 @@
+---
+title: Developer guide
+sidebar_position: 3
+---
+
+# Developer guide — Sales Channels
+
+How a backend module integrates with the Sales Channels module: scoping queries by the resolved channel, managing memberships, and reading channel context from request handlers.
+
+## Reading the resolved channel inside a route
+
+The resolver middleware decorates every request under `/api/v1/*` with `req.salesChannel` (a serialised `CachedChannel` view of the resolved row). Use the typed helper to keep the access pattern consistent:
+
+```ts
+import { getResolvedChannel } from '../../kernel/sales-channels/sales-channel-resolver.middleware.js';
+
+app.get('/api/v1/storefront/products', async (request) => {
+  const channel = getResolvedChannel(request);
+  return productService.list({ salesChannelId: channel.id });
+});
+```
+
+Outside the request lifecycle (background jobs, CLI scripts), call `SalesChannelResolverService.getByCode(code)` or `getSystemDefault()` directly through the module's composition handle.
+
+## Adding a channel-scoped entity to your module
+
+Channel scoping has two layers:
+
+1. **Schema** — the entity gains a many-to-many relationship to `sales_channels` via a new bridge table `sales_channel_<entity>` (composite primary key on both ids, `ON DELETE CASCADE` on both sides). Add the table in your module's next migration.
+2. **Service** — every read path of the entity that should be filtered by channel takes a `salesChannelId` parameter and joins through the bridge table. Every create / update path that lands a new entity calls `SalesChannelMembershipService.bindToDefaultIfEmpty(entityType, entity.id)` after `persistAndFlush` so newly-created entities default to the system-default channel.
+
+Then add the member to the contract's `ChannelMemberEntityTypeSchema` enum, and **declare the bridge from your own module**: export the `{ entityType, table, entityIdColumn }` triple from `src/backend/index.ts` and register it from a boot hook —
+
+```ts
+ctx.onBoot(() => {
+  const { salesChannelBridgeRegistry } = ctx.cradle<YourCradle>();
+  for (const bridge of salesChannelBridges) salesChannelBridgeRegistry.register(bridge);
+});
+```
+
+The bidirectional admin routes then pick it up automatically — no per-module routes needed. The platform deliberately holds no map of the bridges: it used to, total over the enum, which meant a membership call for a member whose module an instance never installed ran SQL against a relation that is not there. A member no module registered now refuses with `503 MODULE_DISABLED` before the database is reached, and the enum stays the published *vocabulary* while the registry decides which members are live.
+
+## Mutating memberships
+
+`SalesChannelMembershipService` is the single mutator for every bridge table. Direct INSERT / DELETE on `sales_channel_*` from anywhere else is forbidden — the lint rule `no-unscoped-channel-query` is the safety net (it ships disabled and gets turned on once every existing call site has been threaded).
+
+```ts
+const result = await membershipService.addToChannel(channelId, 'product', productId);
+// result.changed is false on idempotent re-add.
+
+const removed = await membershipService.removeFromChannel(channelId, 'product', productId, {
+  fallbackToDefault: true,
+});
+// throws ENTITY_WOULD_HAVE_ZERO_CHANNELS if it would orphan the entity AND fallbackToDefault is false.
+```
+
+## The Default channel guarantee
+
+The `DefaultChannelReconciler` runs at every backend boot from `composition.ts` (and from `test-server.ts` for integration tests). Three branches:
+
+1. **Empty `sales_channels` table** — inserts a new `default` row sourced from `DEFAULT_SALES_CHANNEL_CODE` (env, default `default`).
+2. **Rows exist but none has `system_default = true`** — promotes the lexically-first row, with a tie-break preferring the row whose `code = 'default'`.
+3. **Exactly one row already has `system_default = true`** — no-op.
+
+The reconciler never demotes, never deletes, and never edits identity. Code outside this module assumes the default exists; if you're writing infra-level code that runs before the reconciler, call `DefaultChannelReconciler.run()` first.
+
+## Optimistic concurrency for identity edits
+
+The `version` integer column on `sales_channels` increments by exactly 1 on every successful identity update. The PATCH endpoint requires the client's `expectedVersion` to match the row's current `version`, mismatch → HTTP 412 `STALE_SALES_CHANNEL_WRITE` with the current `version` in the error envelope so the client can refresh and retry.
+
+Membership add / remove operations are idempotent by construction and do not bump the channel's `version`.
+
+## Audit hooks
+
+Every identity change, lifecycle change, and membership change writes one `audit_log_entries` row synchronously inside the same transaction. Action codes live in `@endora-commerce/contracts`:
+
+```ts
+import { SALES_CHANNEL_AUDIT_ACTIONS } from '@endora-commerce/contracts';
+
+await auditLogService.record({
+  action: SALES_CHANNEL_AUDIT_ACTIONS.IDENTITY_CHANGED,
+  // ...
+});
+```
+
+Use the constants — never hardcode the strings — so a future enum / type rename ripples cleanly.
+
+## Cache invalidation
+
+`SalesChannelsCache` (process-local LRU + Redis) holds a `CachedChannel` per `code`. The cache is invalidated on every identity / lifecycle change via the existing `EventBus`:
+
+- `sales_channels.identity_changed` → drops one entry by code.
+- `sales_channels.lifecycle_changed` → drops one entry, or all entries when `invalidateAll: true` is set (used on hard delete).
+
+Both drop the shared Redis entry first and the local one second, with the key marked for the whole operation so a concurrent read cannot re-pin the pre-change channel — and so a failed Redis drop leaves reads falling through to PostgreSQL rather than being served the value the invalidation was meant to remove. The `EventBus` is in-process, so a second instance converges through the local layer's 30 s window instead.
+
+Membership lookups go through MikroORM directly (no cache layer); if you need them faster, add a Redis layer keyed by `(entityType, entityId)` with a short TTL — the hooks are already in place.
+
+## Testing your channel-aware code
+
+Use the existing `setupBackendServer()` test harness — it boots the full stack with a fresh `default` channel reconciled against the test seed (`en-US` / `PLN`). For raw-DB-level tests, use `setupTestDb()` and call `DefaultChannelReconciler.run()` yourself, optionally overriding the bootstrap defaults if your test seeds different language/currency codes.
+
+The repo's existing precedent for channel-aware integration tests (transactional rollback, parameterised entity types, raw-SQL fixtures decoupled from owning-module entity classes) is in:
+
+- `backend/test/integration/sales_channels/bidirectional-membership-every-bridge.test.ts` — table-driven over all 9 bridges.
+- `backend/test/integration/sales_channels/at-least-one-channel-invariant.test.ts` — enforcement of the at-least-one-channel invariant.
+- `backend/test/contract/sales_channels/admin-membership.contract.test.ts` — HTTP-side cover.