@endora-commerce/platform 0.100.0

package/dist/kernel/lifecycle/required-modules.js

@@ -0,0 +1,80 @@
+/**
+ * The refusal. A distinct type from every other absence refusal, per D-101's
+ * closing rule.
+ */
+export class RequiredModuleAbsentError extends Error {
+    findings;
+    constructor(findings) {
+        super(refusalMessage(findings));
+        this.name = 'RequiredModuleAbsentError';
+        this.findings = findings;
+    }
+}
+function refusalMessage(findings) {
+    const lines = [
+        'This deployment will not start: it is missing a module the platform requires.',
+        '',
+    ];
+    for (const finding of findings) {
+        if (finding.kind === 'not-composed') {
+            lines.push(`  ${finding.moduleId} — declared by this deployment's manifests, but no module registered it,`, `      and the platform cannot run without it: ${finding.reason}`, '      remedy: the composed module list and the manifest index disagree — run', '              `pnpm --filter backend run composer:generate` and rebuild.');
+        }
+        else {
+            lines.push(`  ${finding.moduleId} — composed, but module presence says \`${finding.platformState}\`,`, `      and the platform cannot run without it: ${finding.reason}`, `      remedy: pnpm --filter backend run module:enable ${finding.moduleId}`);
+        }
+        lines.push('');
+    }
+    lines.push('A module whose manifest declares `activation.nonDeactivatable` is required to be present,', 'not merely un-switch-off-able: the orchestrator refuses to disable or uninstall it, and this', 'refuses a composition that would reach its boot phase without it. Starting anyway means', 'every boot hook, route and worker that needs it fails one at a time, each naming whichever', 'module happened to ask first rather than the one that is missing.');
+    return lines.join('\n');
+}
+/**
+ * The required set, straight from the shipped manifests.
+ *
+ * Pure and exported so its proof drives the classification from a fixture that
+ * enters at the top of the analysis, rather than from a value a composition
+ * already computed.
+ */
+export function requiredModulesFrom(manifests) {
+    const required = [];
+    for (const manifest of manifests) {
+        const activation = manifest.activation;
+        if (activation === undefined || !('nonDeactivatable' in activation))
+            continue;
+        required.push({ moduleId: manifest.id, reason: activation.reason });
+    }
+    return required;
+}
+/**
+ * Every required module this composition cannot serve, in manifest order.
+ *
+ * Pure, and that is load-bearing rather than stylistic — the same reason
+ * `assertLockedModulesPresent` is: its whole input is the three things a
+ * composition has by the end of its registration pass.
+ */
+export function absentRequiredModules(required, composed, presence) {
+    const findings = [];
+    for (const entry of required) {
+        if (!composed.has(entry.moduleId)) {
+            findings.push({ kind: 'not-composed', moduleId: entry.moduleId, reason: entry.reason });
+            continue;
+        }
+        if (presence.isPresent(entry.moduleId))
+            continue;
+        findings.push({
+            kind: 'absent',
+            moduleId: entry.moduleId,
+            reason: entry.reason,
+            // Undefined means the id is unknown to both axes, which for a module the
+            // manifests declare can only mean presence was seeded without it.
+            platformState: presence.presence(entry.moduleId)?.platformState ?? 'not-installed',
+        });
+    }
+    return findings;
+}
+/** {@link absentRequiredModules}, as the refusal the composer makes. */
+export function assertRequiredModulesPresent(required, composed, presence) {
+    const findings = absentRequiredModules(required, composed, presence);
+    if (findings.length > 0)
+        throw new RequiredModuleAbsentError(findings);
+}
+//# sourceMappingURL=required-modules.js.map

package/dist/kernel/lifecycle/required-modules.js.map

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

package/dist/kernel/lifecycle/unique-module-ids.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Module id uniqueness at the composition seam (T030c, D-155.7 placement 2).
+ *
+ * ## The gap this closes
+ *
+ * `composeModules` had no id-uniqueness assertion. It composed every entry it
+ * was given, and the only thing that could surface a second claimant was
+ * `DuplicateRegistrationError` — which fires on the first *registration name*
+ * two modules share, names that key and the module id twice, and identifies
+ * neither claimant. Two modules claiming one id while registering disjoint
+ * names collided on nothing and both composed, so the container ran two
+ * strangers under one identity while the manifest set carried one of them.
+ *
+ * That mattered because the id is the identity everything downstream keys on.
+ * `specs/081-per-module-migration-order/contracts/migration-identity.md` §2
+ * argues that a migration class name scoped by its module is sufficient,
+ * *"because module ids are unique platform-wide — the lifecycle refuses a
+ * second module claiming an id"*. Until this landed, that refusal existed only
+ * in `buildStaticRegistry`, reachable from the `module:*` CLI scripts, each of
+ * which fed bare-core `REGISTERED_MANIFESTS`: the right refusal, wired where a
+ * package could not reach it. (T036 pointed those five at the resolved set,
+ * which reaches the *discovery* refusal below rather than that one — a `Map`
+ * keyed by id leaves no duplicate for `buildStaticRegistry` to see.)
+ *
+ * ## Why here as well as at discovery
+ *
+ * `src/packages/module-id-claims.ts` refuses the same thing where the
+ * `package.json` paths still exist, which is the only place a message can name
+ * both vendors. This one is the structural half: it holds for **any** entry
+ * source — core, overlay, package, or whatever composes next — instead of being
+ * a property of one loader. By the time a list reaches the composer an entry is
+ * an id, a version and a function, so this can only say *how many* claimed the
+ * id, and it says where to look for who.
+ *
+ * ## Why it is not `assertRequiredModulesPresent`, `assertDeactivatable` or
+ * `assertLockedModulesPresent`
+ *
+ * D-101's rule: refusals that share a subject and nothing else stay separate,
+ * so a reader can tell which question they are looking at without reading the
+ * others. Those three are about *absence*; this is about *two of something*.
+ * It runs in the same slot as the first of them, which is the only thing they
+ * share.
+ */
+/** An id claimed more than once, and by how many entries. */
+export interface DuplicateModuleIdFinding {
+    readonly id: string;
+    readonly count: number;
+}
+/** Every repeated id, in first-seen order. */
+export declare function duplicateModuleIds(ids: readonly string[]): DuplicateModuleIdFinding[];
+/** The refusal. A distinct type, per D-101's closing rule. */
+export declare class DuplicateModuleIdError extends Error {
+    readonly findings: readonly DuplicateModuleIdFinding[];
+    constructor(findings: readonly DuplicateModuleIdFinding[]);
+}
+/** {@link duplicateModuleIds}, as the refusal the composer makes. */
+export declare function assertUniqueModuleIds(ids: readonly string[]): void;
+//# sourceMappingURL=unique-module-ids.d.ts.map

package/dist/kernel/lifecycle/unique-module-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unique-module-ids.d.ts","sourceRoot":"","sources":["../../../src/kernel/lifecycle/unique-module-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,wBAAwB,EAAE,CAQrF;AAED,8DAA8D;AAC9D,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;gBAE3C,QAAQ,EAAE,SAAS,wBAAwB,EAAE;CAK1D;AA0BD,qEAAqE;AACrE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAGlE"}

package/dist/kernel/lifecycle/unique-module-ids.js

@@ -0,0 +1,82 @@
+/**
+ * Module id uniqueness at the composition seam (T030c, D-155.7 placement 2).
+ *
+ * ## The gap this closes
+ *
+ * `composeModules` had no id-uniqueness assertion. It composed every entry it
+ * was given, and the only thing that could surface a second claimant was
+ * `DuplicateRegistrationError` — which fires on the first *registration name*
+ * two modules share, names that key and the module id twice, and identifies
+ * neither claimant. Two modules claiming one id while registering disjoint
+ * names collided on nothing and both composed, so the container ran two
+ * strangers under one identity while the manifest set carried one of them.
+ *
+ * That mattered because the id is the identity everything downstream keys on.
+ * `specs/081-per-module-migration-order/contracts/migration-identity.md` §2
+ * argues that a migration class name scoped by its module is sufficient,
+ * *"because module ids are unique platform-wide — the lifecycle refuses a
+ * second module claiming an id"*. Until this landed, that refusal existed only
+ * in `buildStaticRegistry`, reachable from the `module:*` CLI scripts, each of
+ * which fed bare-core `REGISTERED_MANIFESTS`: the right refusal, wired where a
+ * package could not reach it. (T036 pointed those five at the resolved set,
+ * which reaches the *discovery* refusal below rather than that one — a `Map`
+ * keyed by id leaves no duplicate for `buildStaticRegistry` to see.)
+ *
+ * ## Why here as well as at discovery
+ *
+ * `src/packages/module-id-claims.ts` refuses the same thing where the
+ * `package.json` paths still exist, which is the only place a message can name
+ * both vendors. This one is the structural half: it holds for **any** entry
+ * source — core, overlay, package, or whatever composes next — instead of being
+ * a property of one loader. By the time a list reaches the composer an entry is
+ * an id, a version and a function, so this can only say *how many* claimed the
+ * id, and it says where to look for who.
+ *
+ * ## Why it is not `assertRequiredModulesPresent`, `assertDeactivatable` or
+ * `assertLockedModulesPresent`
+ *
+ * D-101's rule: refusals that share a subject and nothing else stay separate,
+ * so a reader can tell which question they are looking at without reading the
+ * others. Those three are about *absence*; this is about *two of something*.
+ * It runs in the same slot as the first of them, which is the only thing they
+ * share.
+ */
+/** Every repeated id, in first-seen order. */
+export function duplicateModuleIds(ids) {
+    const counts = new Map();
+    for (const id of ids)
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+    const findings = [];
+    for (const [id, count] of counts) {
+        if (count > 1)
+            findings.push({ id, count });
+    }
+    return findings;
+}
+/** The refusal. A distinct type, per D-101's closing rule. */
+export class DuplicateModuleIdError extends Error {
+    findings;
+    constructor(findings) {
+        super(refusalMessage(findings));
+        this.name = 'DuplicateModuleIdError';
+        this.findings = findings;
+    }
+}
+function refusalMessage(findings) {
+    const lines = [
+        'This composition will not run: more than one module entry claims the same module id.',
+        '',
+    ];
+    for (const finding of findings) {
+        lines.push(`  ${finding.id} — claimed by ${finding.count} entries in one composition`);
+    }
+    lines.push('', 'The module id is what migrations are ordered and reverted by, what settings and permissions', 'are namespaced by, and what the lifecycle registry is keyed on. Two claimants cannot be told', 'apart afterwards, so composing both would mean one hard uninstall reverting two strangers’', 'migrations.', '', 'A composer entry carries an id, a version and a function, so this cannot say which files', 'claimed the id. Where the entries came from can: the core list is', '`src/composition.generated.ts`, a deployment’s overlay modules are under', '`src/apps/<deployment>/modules/`, and an installed package is refused earlier, by', '`ModuleIdCollisionError`, with both `package.json` paths in the message.');
+    return lines.join('\n');
+}
+/** {@link duplicateModuleIds}, as the refusal the composer makes. */
+export function assertUniqueModuleIds(ids) {
+    const findings = duplicateModuleIds(ids);
+    if (findings.length > 0)
+        throw new DuplicateModuleIdError(findings);
+}
+//# sourceMappingURL=unique-module-ids.js.map

package/dist/kernel/lifecycle/unique-module-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unique-module-ids.js","sourceRoot":"","sources":["../../../src/kernel/lifecycle/unique-module-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAQH,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,EAAE,IAAI,GAAG;QAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,MAAM,QAAQ,GAA+B,EAAE,CAAC;IAChD,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACjC,IAAI,KAAK,GAAG,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,8DAA8D;AAC9D,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,QAAQ,CAAsC;IAEvD,YAAY,QAA6C;QACvD,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,SAAS,cAAc,CAAC,QAA6C;IACnE,MAAM,KAAK,GAAa;QACtB,sFAAsF;QACtF,EAAE;KACH,CAAC;IACF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,EAAE,iBAAiB,OAAO,CAAC,KAAK,6BAA6B,CAAC,CAAC;IACzF,CAAC;IACD,KAAK,CAAC,IAAI,CACR,EAAE,EACF,6FAA6F,EAC7F,8FAA8F,EAC9F,4FAA4F,EAC5F,aAAa,EACb,EAAE,EACF,0FAA0F,EAC1F,mEAAmE,EACnE,0EAA0E,EAC1E,mFAAmF,EACnF,0EAA0E,CAC3E,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,qBAAqB,CAAC,GAAsB;IAC1D,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,sBAAsB,CAAC,QAAQ,CAAC,CAAC;AACtE,CAAC"}

package/dist/kernel/logging.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Where a module's log lines go (issue #269).
+ *
+ * ## What was wrong
+ *
+ * `ModuleContext.log` was whatever the composition root could name at the
+ * moment it composed, and composition runs before `buildServer`. So
+ * `composition.ts` passed the global `console` and the test harness passed a
+ * no-op — the two roots disagreed on the destination, and neither of them was
+ * the log the platform actually collects. A module writing `ctx.log.warn(...)`
+ * produced an unstructured line on stdout, uncorrelated with the request that
+ * caused it and outside the pino stream a deployment ships.
+ *
+ * Four modules feed `ctx.log` into a service that keeps it (`invoices`,
+ * `payments`, `pwa`, `shipments`), and `invoices` writes `{ module: 'invoices' }`
+ * into every object by hand, which is the attribution this file makes automatic.
+ *
+ * ## The shape
+ *
+ * Two concerns, deliberately split, because they have different owners:
+ *
+ *  - **The destination** ({@link platformLogger}) is late-bound. A composition
+ *    root passes it before there is an app; `buildServer` attaches the app's
+ *    own pino instance the moment one exists, so every line emitted after that
+ *    lands in the collected log without either root remembering to do anything.
+ *  - **Attribution and correlation** ({@link moduleLogger}) are applied per
+ *    line, over whatever destination the root chose. `createModuleContext` wraps
+ *    the root's logger in one of these, so `ctx.log` stamps the module id and
+ *    the current request's id without the author naming either.
+ *
+ * ## Why the request id, and not `request.log`
+ *
+ * Fastify's `request.log` is `app.log.child({ reqId })` and nothing else, so a
+ * line carrying `reqId` joins up with Fastify's own `req`/`res` lines exactly
+ * as one written through `request.log` would. Reading the id out of the
+ * platform scope instead of holding the request buys two things: it works from
+ * any depth without threading `request`, and it retains nothing — `scope.ts`
+ * documents at length that a value captured into the scope is pinned for as
+ * long as any async resource created inside it lives, and a Fastify request is
+ * the single most expensive thing that could be pinned there.
+ *
+ * ## Outside a request, and before the app exists
+ *
+ * There is no request id to stamp, so the line carries the module id alone and
+ * is emitted all the same. Which destination it reaches depends on where the
+ * process is:
+ *
+ *  - **A boot hook** runs before `buildServer` in both composition roots, so it
+ *    reaches {@link consoleFallback}. That is what a boot line has always had,
+ *    and it is on stdout, where a boot failure is read.
+ *  - **A worker, a timer, an EventBus subscriber** all run after the app was
+ *    built — `worker.ts` builds a server it never listens on, precisely so the
+ *    module plugins register — so they reach the app's pino instance.
+ *  - **A process that composes modules and builds no server** (the boot-shape
+ *    integration tests) reaches the fallback.
+ *
+ * The fallback is a real write, never a no-op: turning an unstructured line
+ * into a dropped one would be a worse platform than the one this replaces.
+ *
+ * ## One shape, one name
+ *
+ * This interface is **the** structured-logger surface of the platform, and it
+ * is the type of `ModuleContext.log`, of `DefineModuleWorkerOptions.logger`,
+ * and of every `log` a module is handed. It used to have three names —
+ * `WorkerLogger` in `lifecycle/plugin-helpers.ts` (identical body, published on
+ * the `./kernel` barrel), `ModuleLifecycleLogger` in `module-context.ts` (an
+ * alias of that), and this one — for one shape. Structural typing made the
+ * duplication invisible: `moduleLogger` returns a `PlatformLogger` and the
+ * field it lands in was declared as the other two.
+ *
+ * The name that did the damage was `ModuleLifecycleLogger`, because
+ * `@endora-commerce/contracts` **also** exports one — the install/uninstall
+ * hook logger, whose `info(msg)` takes a message and no bound object. A module
+ * author who read the published package and wrote `ctx.log.info('…')` was
+ * wrong, and both names resolved. Do not reintroduce an alias of this
+ * interface: a second name for one shape is what that defect was made of.
+ */
+export interface PlatformLogger {
+    info(obj: object, msg: string): void;
+    warn(obj: object, msg: string): void;
+    error(obj: object, msg: string): void;
+}
+/**
+ * Point every {@link platformLogger} at `logger`, and return a detach.
+ *
+ * Called once per built server, from `buildServer` — the one place in the tree
+ * where the platform's collected logger comes into existence, and therefore the
+ * only place where neither composition root can forget it and the two cannot
+ * drift apart on it.
+ *
+ * The detach clears the slot **only if this logger is still the current one**,
+ * so a suite that builds a second server before closing the first does not have
+ * the first one's teardown silence the second.
+ */
+export declare function attachPlatformLogger(logger: PlatformLogger): () => void;
+/** The attached destination, or `undefined` when nothing is attached. Diagnostics and tests. */
+export declare function currentPlatformLogger(): PlatformLogger | undefined;
+/**
+ * The late-bound destination a composition root passes as `log`.
+ *
+ * It reads the slot **per line** rather than capturing it, which is the whole
+ * point: composition happens before the app exists, so anything captured at
+ * composition time is the fallback forever.
+ */
+export declare function platformLogger(): PlatformLogger;
+/**
+ * Wrap `destination` so every line it carries names `moduleId`, and names the
+ * request it was emitted during when there is one.
+ *
+ * The module id is written **after** the caller's own fields, so attribution is
+ * the wrapper's answer and not something a caller can shadow by accident. The
+ * request id is written the same way; a caller that genuinely means a different
+ * correlation names its own field.
+ */
+export declare function moduleLogger(moduleId: string, to: PlatformLogger): PlatformLogger;
+//# sourceMappingURL=logging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/kernel/logging.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,IAAI,CAKvE;AAED,gGAAgG;AAChG,wBAAgB,qBAAqB,IAAI,cAAc,GAAG,SAAS,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAO/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,cAAc,CAQjF"}

package/dist/kernel/logging.js

@@ -0,0 +1,71 @@
+import { getCurrentPlatformScope } from './scope.js';
+/**
+ * The destination before one is attached, and after the app that was attached
+ * has closed.
+ *
+ * `console.info` is the one call the repository's `no-console` rule does not
+ * already allow; it is right here, because this object exists to be the last
+ * resort of a platform whose structured logger does not exist yet, and
+ * downgrading an info line to `console.warn` would misreport its level to
+ * whatever is reading stdout.
+ */
+const consoleFallback = {
+    // eslint-disable-next-line no-console -- the pre-`buildServer` destination; see above.
+    info: (obj, msg) => console.info(obj, msg),
+    warn: (obj, msg) => console.warn(obj, msg),
+    error: (obj, msg) => console.error(obj, msg),
+};
+let destination;
+/**
+ * Point every {@link platformLogger} at `logger`, and return a detach.
+ *
+ * Called once per built server, from `buildServer` — the one place in the tree
+ * where the platform's collected logger comes into existence, and therefore the
+ * only place where neither composition root can forget it and the two cannot
+ * drift apart on it.
+ *
+ * The detach clears the slot **only if this logger is still the current one**,
+ * so a suite that builds a second server before closing the first does not have
+ * the first one's teardown silence the second.
+ */
+export function attachPlatformLogger(logger) {
+    destination = logger;
+    return () => {
+        if (destination === logger)
+            destination = undefined;
+    };
+}
+/** The attached destination, or `undefined` when nothing is attached. Diagnostics and tests. */
+export function currentPlatformLogger() {
+    return destination;
+}
+/**
+ * The late-bound destination a composition root passes as `log`.
+ *
+ * It reads the slot **per line** rather than capturing it, which is the whole
+ * point: composition happens before the app exists, so anything captured at
+ * composition time is the fallback forever.
+ */
+export function platformLogger() {
+    const emit = (level) => (obj, msg) => {
+        (destination ?? consoleFallback)[level](obj, msg);
+    };
+    return { info: emit('info'), warn: emit('warn'), error: emit('error') };
+}
+/**
+ * Wrap `destination` so every line it carries names `moduleId`, and names the
+ * request it was emitted during when there is one.
+ *
+ * The module id is written **after** the caller's own fields, so attribution is
+ * the wrapper's answer and not something a caller can shadow by accident. The
+ * request id is written the same way; a caller that genuinely means a different
+ * correlation names its own field.
+ */
+export function moduleLogger(moduleId, to) {
+    const emit = (level) => (obj, msg) => {
+        const requestId = getCurrentPlatformScope()?.requestMeta?.requestId;
+        to[level]({ ...obj, module: moduleId, ...(requestId ? { reqId: requestId } : {}) }, msg);
+    };
+    return { info: emit('info'), warn: emit('warn'), error: emit('error') };
+}
+//# sourceMappingURL=logging.js.map

package/dist/kernel/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/kernel/logging.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAuFrD;;;;;;;;;GASG;AACH,MAAM,eAAe,GAAmB;IACtC,uFAAuF;IACvF,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC;IAC1C,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC;IAC1C,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC;CAC7C,CAAC;AAEF,IAAI,WAAuC,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAsB;IACzD,WAAW,GAAG,MAAM,CAAC;IACrB,OAAO,GAAS,EAAE;QAChB,IAAI,WAAW,KAAK,MAAM;YAAE,WAAW,GAAG,SAAS,CAAC;IACtD,CAAC,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,qBAAqB;IACnC,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,IAAI,GACR,CAAC,KAAe,EAAE,EAAE,CACpB,CAAC,GAAW,EAAE,GAAW,EAAQ,EAAE;QACjC,CAAC,WAAW,IAAI,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC,CAAC;IACJ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,EAAkB;IAC/D,MAAM,IAAI,GACR,CAAC,KAAe,EAAE,EAAE,CACpB,CAAC,GAAW,EAAE,GAAW,EAAQ,EAAE;QACjC,MAAM,SAAS,GAAG,uBAAuB,EAAE,EAAE,WAAW,EAAE,SAAS,CAAC;QACpE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAC3F,CAAC,CAAC;IACJ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;AAC1E,CAAC"}