@endora-commerce/platform 0.100.0

package/dist/kernel/public-api-base-url.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The public origin of this backend — one reader, and one production refusal
+ * (issue #218).
+ *
+ * Every payment-gateway callback URL (Tpay `notification`, PayU `notifyUrl`,
+ * Autopay ITN/ISTN), every public product-feed URL and every newsletter
+ * confirmation link is `<this origin>` plus an `/api/v1/...` path. Eight sites
+ * used to read `PUBLIC_API_BASE_URL` directly and each invented
+ * `http://localhost:3001` when it was unset, so a production deployment that
+ * had never heard of the variable handed the gateway a callback nothing on the
+ * internet can reach: no payment was ever confirmed, and nothing logged or
+ * refused. A value whose absence produces a wrong-but-plausible URL is worse
+ * than one that refuses — the argument `SESSION_COOKIE_SECRET` already wins in
+ * `src/index.ts`.
+ *
+ * **Three spellings, one meaning.** `BACKEND_PUBLIC_URL` is what
+ * `deploy/compose.prod.yml` has always derived from `API_DOMAIN`;
+ * `API_PUBLIC_URL` is the second choice `tpay` / `payu` / `autopay` carry; and
+ * `PUBLIC_API_BASE_URL` is the one the eight sites read. They named the same
+ * thing and the templates set the wrong one, which is the whole defect. Reading
+ * all three here is also what keeps the refusal from taking down a deployment
+ * that is configured today: the shipped compose file supplies
+ * `BACKEND_PUBLIC_URL`, so what this refuses is a production boot with *no*
+ * public origin at all.
+ *
+ * Kept in the kernel rather than in a module because the refusal happens at the
+ * top of `composeApp()`, before a module exists to own it, and because five
+ * modules read the value.
+ */
+/** Refusal to boot a production backend that has no public origin. */
+export declare class PublicApiBaseUrlNotConfiguredError extends Error {
+    constructor();
+}
+/**
+ * The explicitly configured public origin, or `null`.
+ *
+ * Never invents one — the callers that use this rather than
+ * {@link resolvePublicApiBaseUrl} are the ones that answer "is an origin
+ * configured?" (the Autopay admin screen renders a relative ITN path and a
+ * `publicApiBaseConfigured: false` flag) or that would rather emit nothing than
+ * something unreachable (a product-feed image URL).
+ *
+ * Trailing slashes are stripped because every call site concatenates a path.
+ */
+export declare function configuredPublicApiBaseUrl(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Refuse a production process that has no public origin.
+ *
+ * Called at the top of `composeApp()`, before the ORM, Redis or any module
+ * exists, so both deployment entry points (`src/index.ts` and `src/worker.ts`)
+ * inherit it from the one root they share and the operator sees the message
+ * instead of a stack trace from whichever call site would have built the first
+ * wrong URL.
+ */
+export declare function assertPublicApiBaseUrlConfigured(env?: NodeJS.ProcessEnv): void;
+/**
+ * The public origin a URL should be built on.
+ *
+ * Outside production it falls back to this process's own local origin, which is
+ * what a developer running `pnpm run dev` means. In production it throws rather
+ * than returning that fallback.
+ */
+export declare function resolvePublicApiBaseUrl(env?: NodeJS.ProcessEnv): string;
+/**
+ * Make an asset / API path absolute for a consumer that is not a browser on
+ * this host — an e-mail client, a push payload, a partner's feed reader.
+ * Relative `/assets/file/...` URLs only work in a browser on the API host.
+ *
+ * It arrived here from `modules/email/` (feature 080, T040b), where it was
+ * filed under the module that first needed it and had **no consumer inside
+ * that module at all**: the composition root was its only caller, for the PWA
+ * asset bridge and the transactional-email asset URL. A deployment-origin
+ * helper the host calls is the host's, and while it lived in a module the root
+ * had a value import that stops having a spelling the day the module becomes a
+ * package (D-160.6.1).
+ *
+ * Deliberately **not** on the `./kernel` barrel: no module reaches it, and a
+ * published symbol with one host-internal consumer is public API nobody asked
+ * for.
+ *
+ * **The default base is the two spellings this function has always read, in the
+ * order it has always read them** — not {@link configuredPublicApiBaseUrl}.
+ * The two disagree on precedence when both variables are set to different
+ * origins, and that disagreement is one of the five answers **D-223** ended.
+ *
+ * **It has no consumer today, and that is the state the ruling left it in.**
+ * `assets_library` resolves the public API origin itself and every URL it
+ * produces is absolute, so the two composition-root call sites this function
+ * existed for — the PWA asset bridge and the transactional-email asset URL —
+ * are gone, and it came off the `./composition` barrel with them, which is what
+ * holding that barrel to its consumers in both directions means. The
+ * declaration stays: it is a correct, tested helper, and it returns to the
+ * barrel the day an application needs one again. What it must not become is a
+ * *sixth* answer to the question the ruling settled — a consumer rebasing a URL
+ * a module already made absolute is a consumer that can disagree with it.
+ */
+export declare function absolutizePublicUrl(url: string | null | undefined, publicBase?: string): string;
+//# sourceMappingURL=public-api-base-url.d.ts.map

package/dist/kernel/public-api-base-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api-base-url.d.ts","sourceRoot":"","sources":["../../src/kernel/public-api-base-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAoBH,sEAAsE;AACtE,qBAAa,kCAAmC,SAAQ,KAAK;;CAK5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAM9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAI3F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAKpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,UAAU,SAAgF,GACzF,MAAM,CAOR"}

package/dist/kernel/public-api-base-url.js

@@ -0,0 +1,144 @@
+/**
+ * The public origin of this backend — one reader, and one production refusal
+ * (issue #218).
+ *
+ * Every payment-gateway callback URL (Tpay `notification`, PayU `notifyUrl`,
+ * Autopay ITN/ISTN), every public product-feed URL and every newsletter
+ * confirmation link is `<this origin>` plus an `/api/v1/...` path. Eight sites
+ * used to read `PUBLIC_API_BASE_URL` directly and each invented
+ * `http://localhost:3001` when it was unset, so a production deployment that
+ * had never heard of the variable handed the gateway a callback nothing on the
+ * internet can reach: no payment was ever confirmed, and nothing logged or
+ * refused. A value whose absence produces a wrong-but-plausible URL is worse
+ * than one that refuses — the argument `SESSION_COOKIE_SECRET` already wins in
+ * `src/index.ts`.
+ *
+ * **Three spellings, one meaning.** `BACKEND_PUBLIC_URL` is what
+ * `deploy/compose.prod.yml` has always derived from `API_DOMAIN`;
+ * `API_PUBLIC_URL` is the second choice `tpay` / `payu` / `autopay` carry; and
+ * `PUBLIC_API_BASE_URL` is the one the eight sites read. They named the same
+ * thing and the templates set the wrong one, which is the whole defect. Reading
+ * all three here is also what keeps the refusal from taking down a deployment
+ * that is configured today: the shipped compose file supplies
+ * `BACKEND_PUBLIC_URL`, so what this refuses is a production boot with *no*
+ * public origin at all.
+ *
+ * Kept in the kernel rather than in a module because the refusal happens at the
+ * top of `composeApp()`, before a module exists to own it, and because five
+ * modules read the value.
+ */
+/**
+ * The spellings of the public API origin, in precedence order.
+ *
+ * `PUBLIC_API_BASE_URL` leads because it is the name every call site, every
+ * module README and the deployment checklist already document; the other two
+ * are accepted so an already-configured deployment is not asked to rename a
+ * variable to keep booting.
+ */
+const ORIGIN_VARIABLES = ['PUBLIC_API_BASE_URL', 'BACKEND_PUBLIC_URL', 'API_PUBLIC_URL'];
+const REFUSAL_MESSAGE = 'PUBLIC_API_BASE_URL is not set and NODE_ENV=production. It is the origin every ' +
+    'payment-gateway callback URL, public product-feed URL and newsletter confirmation link is ' +
+    'built on, so defaulting it to http://localhost:3001 would hand the gateway a callback it ' +
+    'cannot reach and no payment would ever be confirmed. Set PUBLIC_API_BASE_URL (or ' +
+    'BACKEND_PUBLIC_URL) to the public https origin of this API — deploy/compose.prod.yml ' +
+    'derives both from API_DOMAIN.';
+/** Refusal to boot a production backend that has no public origin. */
+export class PublicApiBaseUrlNotConfiguredError extends Error {
+    constructor() {
+        super(REFUSAL_MESSAGE);
+        this.name = 'PublicApiBaseUrlNotConfiguredError';
+    }
+}
+/**
+ * The explicitly configured public origin, or `null`.
+ *
+ * Never invents one — the callers that use this rather than
+ * {@link resolvePublicApiBaseUrl} are the ones that answer "is an origin
+ * configured?" (the Autopay admin screen renders a relative ITN path and a
+ * `publicApiBaseConfigured: false` flag) or that would rather emit nothing than
+ * something unreachable (a product-feed image URL).
+ *
+ * Trailing slashes are stripped because every call site concatenates a path.
+ */
+export function configuredPublicApiBaseUrl(env = process.env) {
+    for (const name of ORIGIN_VARIABLES) {
+        const raw = env[name]?.trim();
+        if (raw !== undefined && raw !== '')
+            return raw.replace(/\/+$/, '');
+    }
+    return null;
+}
+/**
+ * Refuse a production process that has no public origin.
+ *
+ * Called at the top of `composeApp()`, before the ORM, Redis or any module
+ * exists, so both deployment entry points (`src/index.ts` and `src/worker.ts`)
+ * inherit it from the one root they share and the operator sees the message
+ * instead of a stack trace from whichever call site would have built the first
+ * wrong URL.
+ */
+export function assertPublicApiBaseUrlConfigured(env = process.env) {
+    if (env['NODE_ENV'] === 'production' && configuredPublicApiBaseUrl(env) === null) {
+        throw new PublicApiBaseUrlNotConfiguredError();
+    }
+}
+/**
+ * The public origin a URL should be built on.
+ *
+ * Outside production it falls back to this process's own local origin, which is
+ * what a developer running `pnpm run dev` means. In production it throws rather
+ * than returning that fallback.
+ */
+export function resolvePublicApiBaseUrl(env = process.env) {
+    const configured = configuredPublicApiBaseUrl(env);
+    if (configured !== null)
+        return configured;
+    assertPublicApiBaseUrlConfigured(env);
+    return `http://localhost:${env['PORT'] ?? '3001'}`;
+}
+/**
+ * Make an asset / API path absolute for a consumer that is not a browser on
+ * this host — an e-mail client, a push payload, a partner's feed reader.
+ * Relative `/assets/file/...` URLs only work in a browser on the API host.
+ *
+ * It arrived here from `modules/email/` (feature 080, T040b), where it was
+ * filed under the module that first needed it and had **no consumer inside
+ * that module at all**: the composition root was its only caller, for the PWA
+ * asset bridge and the transactional-email asset URL. A deployment-origin
+ * helper the host calls is the host's, and while it lived in a module the root
+ * had a value import that stops having a spelling the day the module becomes a
+ * package (D-160.6.1).
+ *
+ * Deliberately **not** on the `./kernel` barrel: no module reaches it, and a
+ * published symbol with one host-internal consumer is public API nobody asked
+ * for.
+ *
+ * **The default base is the two spellings this function has always read, in the
+ * order it has always read them** — not {@link configuredPublicApiBaseUrl}.
+ * The two disagree on precedence when both variables are set to different
+ * origins, and that disagreement is one of the five answers **D-223** ended.
+ *
+ * **It has no consumer today, and that is the state the ruling left it in.**
+ * `assets_library` resolves the public API origin itself and every URL it
+ * produces is absolute, so the two composition-root call sites this function
+ * existed for — the PWA asset bridge and the transactional-email asset URL —
+ * are gone, and it came off the `./composition` barrel with them, which is what
+ * holding that barrel to its consumers in both directions means. The
+ * declaration stays: it is a correct, tested helper, and it returns to the
+ * barrel the day an application needs one again. What it must not become is a
+ * *sixth* answer to the question the ruling settled — a consumer rebasing a URL
+ * a module already made absolute is a consumer that can disagree with it.
+ */
+export function absolutizePublicUrl(url, publicBase = process.env['BACKEND_PUBLIC_URL'] ?? process.env['PUBLIC_API_BASE_URL'] ?? '') {
+    if (!url)
+        return '';
+    if (/^(https?:|data:|mailto:)/i.test(url))
+        return url;
+    const base = publicBase.replace(/\/+$/, '');
+    if (!base)
+        return url;
+    if (url.startsWith('/'))
+        return `${base}${url}`;
+    return `${base}/${url}`;
+}
+//# sourceMappingURL=public-api-base-url.js.map

package/dist/kernel/public-api-base-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api-base-url.js","sourceRoot":"","sources":["../../src/kernel/public-api-base-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,CAAC,qBAAqB,EAAE,oBAAoB,EAAE,gBAAgB,CAAU,CAAC;AAElG,MAAM,eAAe,GACnB,iFAAiF;IACjF,4FAA4F;IAC5F,2FAA2F;IAC3F,mFAAmF;IACnF,uFAAuF;IACvF,+BAA+B,CAAC;AAElC,sEAAsE;AACtE,MAAM,OAAO,kCAAmC,SAAQ,KAAK;IAC3D;QACE,KAAK,CAAC,eAAe,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,oCAAoC,CAAC;IACnD,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7E,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;QAC9B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gCAAgC,CAAC,MAAyB,OAAO,CAAC,GAAG;IACnF,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,IAAI,0BAA0B,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QACjF,MAAM,IAAI,kCAAkC,EAAE,CAAC;IACjD,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC1E,MAAM,UAAU,GAAG,0BAA0B,CAAC,GAAG,CAAC,CAAC;IACnD,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAC3C,gCAAgC,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,oBAAoB,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAA8B,EAC9B,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,EAAE;IAE1F,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,IAAI,2BAA2B,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACtD,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI;QAAE,OAAO,GAAG,CAAC;IACtB,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,IAAI,GAAG,GAAG,EAAE,CAAC;IAChD,OAAO,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC;AAC1B,CAAC"}

package/dist/kernel/request-scope-hook.d.ts

@@ -0,0 +1,63 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import { type TenantContext } from '../tenancy/tenant-context.js';
+/**
+ * The HTTP entry into `enterPlatformScope` (feature 072, FR-015…FR-021).
+ *
+ * Registered by both the production composition root and the test harness, from
+ * this one file on purpose: the two hand-written copies of the tenant hook it
+ * replaces had already drifted apart in their comments, and a drift in *this*
+ * hook is a silent cross-tenant leak rather than a failing test.
+ *
+ * ## Shape
+ *
+ * `done()` is called **synchronously inside** the store, which is what makes the
+ * store propagate into every later hook and into the handler's awaited
+ * continuations — `enterWith` from an async hook does not, and fails silently
+ * (`tenancy/tenant-context.ts`). The work the scope wraps is therefore "the rest
+ * of this request", expressed as a promise that settles when `reply.raw` emits
+ * `close`. That one event covers success, error and client abort, so the scope
+ * is disposed in all three cases with a single mechanism and no `try/finally`
+ * spread across the response path.
+ *
+ * ## Ordering
+ *
+ * This hook must be registered **after** the auth hook (it derives tenancy from
+ * `request.actor`) and **before** the sales-channel resolver (which fills the
+ * scope's channel slot and whose refusal path writes an audit row, so it needs
+ * tenancy). See the ordering note in `scope.ts` — that order is a constraint,
+ * not an accident of registration.
+ *
+ * ## Disclosure
+ *
+ * It also carries the *outbound* half (feature 087, owner decision of
+ * 2026-08-29): `preSerialization` puts `meta.scopeNotice` on a successful body
+ * when the tenant filter refused a whole table for want of an organization
+ * column. It lives here, and not on each route, because that is the only place
+ * both facts are in hand at once — the context this hook opened, and the body
+ * about to go out — and because a per-route flag is a flag somebody forgets.
+ * Both composition roots register this hook, so neither can disclose less than
+ * the other.
+ */
+export interface RequestScopeHookOptions {
+    /**
+     * Derive the request's tenant context from the already-authenticated actor —
+     * never from request inputs (Constitution XI). Rejecting here fails the
+     * request through `done(err)`, exactly as the pre-kernel hook did.
+     */
+    buildTenantContext: (request: FastifyRequest) => Promise<TenantContext>;
+}
+export declare function registerRequestScopeHook(app: FastifyInstance, options: RequestScopeHookOptions): Promise<void>;
+/**
+ * Put `meta.scopeNotice` on `payload` when this execution's tenant filter
+ * refused a whole table, and return `payload` untouched otherwise.
+ *
+ * Three things it deliberately does not do. It does not touch an **error**
+ * body: a 4xx/5xx envelope is `{ error: … }` and already says why, and a notice
+ * about emptiness on a refusal is noise. It does not touch a **non-object**
+ * body — the newsletter CSV export is a string, and a Buffer or a stream is
+ * nobody's envelope. And it does not overwrite an existing `meta`, it merges
+ * into it, because `meta` is where two of the three surfaces already keep their
+ * pagination.
+ */
+export declare function withScopeNotice(payload: unknown, statusCode: number): unknown;
+//# sourceMappingURL=request-scope-hook.d.ts.map

package/dist/kernel/request-scope-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-scope-hook.d.ts","sourceRoot":"","sources":["../../src/kernel/request-scope-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG/D,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CACzE;AAWD,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAc7E"}

package/dist/kernel/request-scope-hook.js

@@ -0,0 +1,67 @@
+import fastifyPlugin from 'fastify-plugin';
+import { SCOPE_NOTICE_CODES } from '@endora-commerce/contracts';
+import { getTenantContext } from '../tenancy/tenant-context.js';
+import { enterPlatformScope } from './scope.js';
+function requestMetaOf(request) {
+    const userAgent = request.headers['user-agent'];
+    return {
+        requestId: request.id ? String(request.id) : null,
+        ipAddress: request.ip ?? null,
+        userAgent: Array.isArray(userAgent) ? (userAgent[0] ?? null) : (userAgent ?? null),
+    };
+}
+export async function registerRequestScopeHook(app, options) {
+    await app.register(fastifyPlugin(async (inner) => {
+        inner.addHook('onRequest', (request, reply, done) => {
+            options.buildTenantContext(request).then((tenant) => {
+                void enterPlatformScope(tenant, () => new Promise((resolve) => {
+                    reply.raw.once('close', resolve);
+                    done();
+                }), { entryPoint: 'http', requestMeta: requestMetaOf(request) }).catch((err) => {
+                    // Reaching here means the scope failed to close down, not that the
+                    // request failed — the response has already been written by then.
+                    request.log.error({ err }, 'platform scope disposal failed');
+                });
+            }, (err) => done(err));
+        });
+        // The disclosure (feature 087). `preSerialization` runs inside the store
+        // this hook opened — the `onRequest` callback calls `done()`
+        // synchronously inside it, so the whole lifecycle continues in that async
+        // context — which is what lets the sink written by the filter during the
+        // handler be read here.
+        inner.addHook('preSerialization', (_request, reply, payload, done) => {
+            done(null, withScopeNotice(payload, reply.statusCode));
+        });
+    }));
+}
+/**
+ * Put `meta.scopeNotice` on `payload` when this execution's tenant filter
+ * refused a whole table, and return `payload` untouched otherwise.
+ *
+ * Three things it deliberately does not do. It does not touch an **error**
+ * body: a 4xx/5xx envelope is `{ error: … }` and already says why, and a notice
+ * about emptiness on a refusal is noise. It does not touch a **non-object**
+ * body — the newsletter CSV export is a string, and a Buffer or a stream is
+ * nobody's envelope. And it does not overwrite an existing `meta`, it merges
+ * into it, because `meta` is where two of the three surfaces already keep their
+ * pagination.
+ */
+export function withScopeNotice(payload, statusCode) {
+    if (statusCode >= 400)
+        return payload;
+    if (!getTenantContext()?.notices?.organizationAttributionRefused)
+        return payload;
+    if (typeof payload !== 'object' || payload === null)
+        return payload;
+    if (Array.isArray(payload) || Buffer.isBuffer(payload))
+        return payload;
+    const body = payload;
+    const existingMeta = typeof body.meta === 'object' && body.meta !== null && !Array.isArray(body.meta)
+        ? body.meta
+        : {};
+    return {
+        ...body,
+        meta: { ...existingMeta, scopeNotice: SCOPE_NOTICE_CODES.ORGANIZATION_ATTRIBUTION_PENDING },
+    };
+}
+//# sourceMappingURL=request-scope-hook.js.map

package/dist/kernel/request-scope-hook.js.map

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

package/dist/kernel/sales-channels/channel-bridge-registry.d.ts

@@ -0,0 +1,109 @@
+import { type ChannelMemberEntityType } from '@endora-commerce/contracts';
+/**
+ * Which table holds a channel-scoped entity type's memberships, said by the
+ * module that owns that entity type (feature 120, FR-015; D-226).
+ *
+ * ## What this replaces, and why it was a defect rather than a tidiness question
+ *
+ * `SalesChannelMembershipService` held a literal map **total** over
+ * `ChannelMemberEntityTypeSchema` — nine `{ table, entityIdColumn }` triples,
+ * naming `catalog`'s, `cms`', `promotions`' and six other modules' tables from
+ * inside the platform. `tsc` kept it honest precisely *because* it was total,
+ * and that totality is the defect: the platform named nine module concepts, so
+ * D-52/D-53's prohibition was expressed in a contract instead of in an import
+ * and no check in the estate could see it. On an instance that never installed
+ * `cms`, a membership call for `cms-page` executed SQL against a relation that
+ * is not there.
+ *
+ * A second copy of the same nine triples lived in `sales_channels`' own admin
+ * service, on the channel-**delete** path, justified by a circular import that
+ * had not existed since feature 072's T019 moved the membership service into the
+ * kernel. Both are gone; this registry is what they became.
+ *
+ * ## The two axes, and which one this answers
+ *
+ * A registration is a statement about **schema**: *this entity type's
+ * memberships live in this table, keyed by this column*. It is contributed once
+ * per composition by the module whose migrations create the table, which makes
+ * it an answer on the **platform-availability** axis — a module that is not
+ * composed contributes nothing, and {@link ChannelBridgeRegistry.require}
+ * refuses rather than reaching a relation that may not exist (FR-017).
+ *
+ * It is deliberately **not** an answer on the operator-activation axis. The
+ * rows survive an operator switching the owning module off, so the bridge must
+ * still be readable — which is the same reasoning the asset-reference and
+ * language-reference registries state for their own contributions: a
+ * contribution is inert, and probing presence in the hook that makes one would
+ * make runtime activation require a restart (D-62/D-68). The activation axis is
+ * answered where it belongs, at the owning module's own routes and ports.
+ *
+ * ## Why it is not published on the kernel barrel
+ *
+ * Nothing here needs an address a module compiles against: a module contributes
+ * by resolving `salesChannelBridgeRegistry` from the container, which is a
+ * runtime name and not an import. Publishing the registry would enlarge the
+ * platform's published surface — which `check:platform-surface` judges and
+ * `PUBLISHED_SUBPATHS` pins — for a seam whose whole purpose is to *remove* a
+ * platform-held map.
+ */
+export interface ChannelBridgeRegistration {
+    /** The published vocabulary member this bridge serves. */
+    readonly entityType: ChannelMemberEntityType;
+    /** The M:N bridge table, created by the contributing module's own migration. */
+    readonly table: string;
+    /** The column in it holding the entity's id; `sales_channel_id` holds the other side. */
+    readonly entityIdColumn: string;
+}
+export declare class ChannelBridgeRegistry {
+    private readonly bridges;
+    /**
+     * Declare the bridge this module owns.
+     *
+     * **A conflicting second registration is refused, never silently
+     * overwritten**: two modules claiming one member of the vocabulary is an
+     * ownership collision, and the last composer winning would decide which
+     * table a membership write lands in by module order.
+     *
+     * Re-declaring the **same** triple is a no-op rather than a refusal, and the
+     * distinction is the design rather than a leniency. A registration is a
+     * statement of fact about the schema, not a capability instance: nothing is
+     * overwritten by repeating it, and a process legitimately composes more than
+     * once — the test harness builds a platform per file, and several unit files
+     * compose the whole module list twice to compare two compositions. Refusing
+     * an identical repeat would make this seam fail for a reason that has nothing
+     * to do with what it guards.
+     */
+    register(bridge: ChannelBridgeRegistration): void;
+    /**
+     * The bridge for `entityType`, or a refusal (FR-017).
+     *
+     * The refusal is the whole point of the registry: on an instance that did not
+     * install the module owning this entity type there is no table to read, and
+     * the honest answer is *"this platform cannot serve that capability"* rather
+     * than a Postgres `relation … does not exist` from inside a transaction that
+     * has already written something else.
+     *
+     * `MODULE_DISABLED` is the code because it is the one the platform already
+     * publishes and translates for *"a capability this platform is not currently
+     * serving"*, and a consumer branching on it needs no new vocabulary. The
+     * module is **not** named in the details, because the honest answer is that
+     * no module registered it: naming one would be a guess about which package an
+     * operator was expected to install.
+     */
+    require(entityType: ChannelMemberEntityType): ChannelBridgeRegistration;
+    /** The registered bridges, in registration order. Empty in a process that composed nothing. */
+    list(): readonly ChannelBridgeRegistration[];
+}
+/**
+ * The registry a composition uses unless it is handed another.
+ *
+ * Process-level, on `inProcessCaches`' precedent, and for the same reason: the
+ * contributors are modules and the reader is the kernel, so threading one
+ * handle through every composition root — and through every test that
+ * constructs the membership service against a bare database — is a lot of
+ * wiring for a table that is a property of the build rather than of a
+ * composition. {@link ChannelBridgeRegistry.register}'s idempotence is what
+ * makes one-per-process safe.
+ */
+export declare const channelBridges: ChannelBridgeRegistry;
+//# sourceMappingURL=channel-bridge-registry.d.ts.map

package/dist/kernel/sales-channels/channel-bridge-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-bridge-registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/sales-channels/channel-bridge-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAGvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,yBAAyB;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiE;IAEzF;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI;IAcjD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,UAAU,EAAE,uBAAuB,GAAG,yBAAyB;IAcvE,+FAA+F;IAC/F,IAAI,IAAI,SAAS,yBAAyB,EAAE;CAG7C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,uBAA8B,CAAC"}

package/dist/kernel/sales-channels/channel-bridge-registry.js

@@ -0,0 +1,75 @@
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '../../http/error-envelope.js';
+export class ChannelBridgeRegistry {
+    bridges = new Map();
+    /**
+     * Declare the bridge this module owns.
+     *
+     * **A conflicting second registration is refused, never silently
+     * overwritten**: two modules claiming one member of the vocabulary is an
+     * ownership collision, and the last composer winning would decide which
+     * table a membership write lands in by module order.
+     *
+     * Re-declaring the **same** triple is a no-op rather than a refusal, and the
+     * distinction is the design rather than a leniency. A registration is a
+     * statement of fact about the schema, not a capability instance: nothing is
+     * overwritten by repeating it, and a process legitimately composes more than
+     * once — the test harness builds a platform per file, and several unit files
+     * compose the whole module list twice to compare two compositions. Refusing
+     * an identical repeat would make this seam fail for a reason that has nothing
+     * to do with what it guards.
+     */
+    register(bridge) {
+        const held = this.bridges.get(bridge.entityType);
+        if (held !== undefined) {
+            if (held.table === bridge.table && held.entityIdColumn === bridge.entityIdColumn)
+                return;
+            throw new Error(`sales-channel bridge '${bridge.entityType}' is already registered as ` +
+                `"${held.table}"."${held.entityIdColumn}" and cannot be re-registered as ` +
+                `"${bridge.table}"."${bridge.entityIdColumn}" — two modules claim one member of the ` +
+                'channel-membership vocabulary');
+        }
+        this.bridges.set(bridge.entityType, bridge);
+    }
+    /**
+     * The bridge for `entityType`, or a refusal (FR-017).
+     *
+     * The refusal is the whole point of the registry: on an instance that did not
+     * install the module owning this entity type there is no table to read, and
+     * the honest answer is *"this platform cannot serve that capability"* rather
+     * than a Postgres `relation … does not exist` from inside a transaction that
+     * has already written something else.
+     *
+     * `MODULE_DISABLED` is the code because it is the one the platform already
+     * publishes and translates for *"a capability this platform is not currently
+     * serving"*, and a consumer branching on it needs no new vocabulary. The
+     * module is **not** named in the details, because the honest answer is that
+     * no module registered it: naming one would be a guess about which package an
+     * operator was expected to install.
+     */
+    require(entityType) {
+        const bridge = this.bridges.get(entityType);
+        if (bridge === undefined) {
+            throw new HttpError(503, ERROR_CODES.MODULE_DISABLED, `Sales-channel membership for '${entityType}' is not available on this platform: no ` +
+                'installed module contributes that bridge.', [{ path: 'entityType', issue: entityType }]);
+        }
+        return bridge;
+    }
+    /** The registered bridges, in registration order. Empty in a process that composed nothing. */
+    list() {
+        return [...this.bridges.values()];
+    }
+}
+/**
+ * The registry a composition uses unless it is handed another.
+ *
+ * Process-level, on `inProcessCaches`' precedent, and for the same reason: the
+ * contributors are modules and the reader is the kernel, so threading one
+ * handle through every composition root — and through every test that
+ * constructs the membership service against a bare database — is a lot of
+ * wiring for a table that is a property of the build rather than of a
+ * composition. {@link ChannelBridgeRegistry.register}'s idempotence is what
+ * makes one-per-process safe.
+ */
+export const channelBridges = new ChannelBridgeRegistry();
+//# sourceMappingURL=channel-bridge-registry.js.map

package/dist/kernel/sales-channels/channel-bridge-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-bridge-registry.js","sourceRoot":"","sources":["../../../src/kernel/sales-channels/channel-bridge-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAgC,MAAM,4BAA4B,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AA0DzD,MAAM,OAAO,qBAAqB;IACf,OAAO,GAAG,IAAI,GAAG,EAAsD,CAAC;IAEzF;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAiC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACjD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,cAAc,KAAK,MAAM,CAAC,cAAc;gBAAE,OAAO;YACzF,MAAM,IAAI,KAAK,CACb,yBAAyB,MAAM,CAAC,UAAU,6BAA6B;gBACrE,IAAI,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,cAAc,mCAAmC;gBAC1E,IAAI,MAAM,CAAC,KAAK,MAAM,MAAM,CAAC,cAAc,0CAA0C;gBACrF,+BAA+B,CAClC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,UAAmC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC5C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,SAAS,CACjB,GAAG,EACH,WAAW,CAAC,eAAe,EAC3B,iCAAiC,UAAU,0CAA0C;gBACnF,2CAA2C,EAC7C,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAC5C,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+FAA+F;IAC/F,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,qBAAqB,EAAE,CAAC"}