@endora-commerce/platform 0.100.0

package/dist/commands/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Command Bus core layer (feature 054 — Uniform Write Auditing & Undo,
+ * Constitution Principle XIII). Peer of `events/`, `tenancy/`, `http/`,
+ * `kernel/`; becomes the `./commands` subpath of `@endora-commerce/platform`
+ * (feature 080, D-160.1/D-160.7), and that subpath is the boundary a future
+ * `@endora-commerce/commands` would take (D-160.6).
+ *
+ * **This barrel is a package boundary in waiting, so it carries this
+ * directory's symbols and nothing else.** Three of the shapes a consumer needs
+ * to use it come from elsewhere and stay there: `AuditPort`
+ * (`@endora-commerce/platform/kernel`) is `recordAuditFromContext`'s first
+ * argument, `TenantContext` (`…/tenancy`) is `actorFromContext`'s, and
+ * `EventBase` (`…/events`) is what a {@link CommandEvent} carries. Re-exporting
+ * one of them here to save a consumer an import line spends the split option
+ * for a convenience.
+ *
+ * **What is on it is decided by `contracts/host-package.md` §1.3, not by what
+ * happens to be here** (T042f, applying T042c's rule to this directory for the
+ * first time). §1.3 rows 5, 12 and 33 are all **P**, and the 177 module reaches
+ * into this directory name **ten** distinct symbols between them; the barrel
+ * carried 27.
+ *
+ * So the rule is the kernel barrel's: a symbol is here when §1.3 records a
+ * module taking it from a **P** file, or when it is the argument, return or
+ * thrown shape of one of those. Two groups are deliberately absent and a future
+ * author will look for them:
+ *
+ *  - **the bus's construction** — `CommandBusOptions` and
+ *    `CommandRequestMeta`. A composition root builds the one {@link CommandBus}
+ *    and supplies its request-metadata resolver; a module resolves
+ *    `commandBus` from the container and calls `run`. The class travels because
+ *    75 module files name it in a constructor signature or a cradle field.
+ *  - **the command registry**, which this barrel exported until T042f pruned it
+ *    and !897 deleted outright. D-163 settled it: the registry was read by
+ *    **nothing** in `src/`, and both consumers its own header named had been
+ *    wrong since it was created — `check:command-coverage` decides coverage
+ *    syntactically and never imported it, and the undo affordance reads
+ *    `op.reversible`, a column. The question it appeared to raise for a
+ *    packaged module — *a central list of every module's actions* — is real and
+ *    lives four tables away, in `audit_logs/action-catalog.ts`, whose
+ *    `RECENT_ACTIVITY_ACTIONS` silently drops a package's row from the
+ *    dashboard. Publishing a list with no reader would have answered nothing.
+ */
+export { type Command, 
+/** {@link Command.run}'s parameter; its `actor` is a {@link CommandActor}. */
+type CommandContext, 
+/** {@link Command.run}'s return shape. */
+type CommandOutcome, 
+/** {@link Command.event}'s return shape, and the audit snapshot type. */
+type CommandEvent, type AuditState, 
+/** What {@link resolveCommandActor} returns and what a Command's `ctx.actor` is. */
+type CommandActor, } from './command.js';
+/** Row 5's "+5" — both derive the actor server-side, never from a request body. */
+export { resolveCommandActor, actorFromContext } from './actor.js';
+/** Row 5's second-largest symbol — 51 reaches — plus its own input shape. */
+export { recordAuditFromContext, type AuditFromContextInput } from './audit-from-context.js';
+/** Rows 5 and 33 — the class 75 module files name. */
+export { CommandBus } from './command-bus.js';
+/**
+ * The stored-revert undo (US2). `applyUndo`'s argument and return shapes travel
+ * with it; `UndoStatus`, `RevertConflict` and `RevertConflictReason` are members
+ * of {@link UndoResult} that its one consumer reads structurally.
+ */
+export { applyUndo, type RevertRecord, type RevertHandlers, type UndoResult, } from './reversible.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,EACL,KAAK,OAAO;AACZ,8EAA8E;AAC9E,KAAK,cAAc;AACnB,0CAA0C;AAC1C,KAAK,cAAc;AACnB,yEAAyE;AACzE,KAAK,YAAY,EACjB,KAAK,UAAU;AACf,oFAAoF;AACpF,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,mFAAmF;AACnF,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnE,6EAA6E;AAC7E,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,sDAAsD;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C;;;;GAIG;AACH,OAAO,EACL,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,UAAU,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/commands/index.js

@@ -0,0 +1,57 @@
+/**
+ * Command Bus core layer (feature 054 — Uniform Write Auditing & Undo,
+ * Constitution Principle XIII). Peer of `events/`, `tenancy/`, `http/`,
+ * `kernel/`; becomes the `./commands` subpath of `@endora-commerce/platform`
+ * (feature 080, D-160.1/D-160.7), and that subpath is the boundary a future
+ * `@endora-commerce/commands` would take (D-160.6).
+ *
+ * **This barrel is a package boundary in waiting, so it carries this
+ * directory's symbols and nothing else.** Three of the shapes a consumer needs
+ * to use it come from elsewhere and stay there: `AuditPort`
+ * (`@endora-commerce/platform/kernel`) is `recordAuditFromContext`'s first
+ * argument, `TenantContext` (`…/tenancy`) is `actorFromContext`'s, and
+ * `EventBase` (`…/events`) is what a {@link CommandEvent} carries. Re-exporting
+ * one of them here to save a consumer an import line spends the split option
+ * for a convenience.
+ *
+ * **What is on it is decided by `contracts/host-package.md` §1.3, not by what
+ * happens to be here** (T042f, applying T042c's rule to this directory for the
+ * first time). §1.3 rows 5, 12 and 33 are all **P**, and the 177 module reaches
+ * into this directory name **ten** distinct symbols between them; the barrel
+ * carried 27.
+ *
+ * So the rule is the kernel barrel's: a symbol is here when §1.3 records a
+ * module taking it from a **P** file, or when it is the argument, return or
+ * thrown shape of one of those. Two groups are deliberately absent and a future
+ * author will look for them:
+ *
+ *  - **the bus's construction** — `CommandBusOptions` and
+ *    `CommandRequestMeta`. A composition root builds the one {@link CommandBus}
+ *    and supplies its request-metadata resolver; a module resolves
+ *    `commandBus` from the container and calls `run`. The class travels because
+ *    75 module files name it in a constructor signature or a cradle field.
+ *  - **the command registry**, which this barrel exported until T042f pruned it
+ *    and !897 deleted outright. D-163 settled it: the registry was read by
+ *    **nothing** in `src/`, and both consumers its own header named had been
+ *    wrong since it was created — `check:command-coverage` decides coverage
+ *    syntactically and never imported it, and the undo affordance reads
+ *    `op.reversible`, a column. The question it appeared to raise for a
+ *    packaged module — *a central list of every module's actions* — is real and
+ *    lives four tables away, in `audit_logs/action-catalog.ts`, whose
+ *    `RECENT_ACTIVITY_ACTIONS` silently drops a package's row from the
+ *    dashboard. Publishing a list with no reader would have answered nothing.
+ */
+export {} from './command.js';
+/** Row 5's "+5" — both derive the actor server-side, never from a request body. */
+export { resolveCommandActor, actorFromContext } from './actor.js';
+/** Row 5's second-largest symbol — 51 reaches — plus its own input shape. */
+export { recordAuditFromContext } from './audit-from-context.js';
+/** Rows 5 and 33 — the class 75 module files name. */
+export { CommandBus } from './command-bus.js';
+/**
+ * The stored-revert undo (US2). `applyUndo`'s argument and return shapes travel
+ * with it; `UndoStatus`, `RevertConflict` and `RevertConflictReason` are members
+ * of {@link UndoResult} that its one consumer reads structurally.
+ */
+export { applyUndo, } from './reversible.js';
+//# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,EAWN,MAAM,cAAc,CAAC;AACtB,mFAAmF;AACnF,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnE,6EAA6E;AAC7E,OAAO,EAAE,sBAAsB,EAA8B,MAAM,yBAAyB,CAAC;AAC7F,sDAAsD;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C;;;;GAIG;AACH,OAAO,EACL,SAAS,GAIV,MAAM,iBAAiB,CAAC"}

package/dist/commands/reversible.d.ts

@@ -0,0 +1,66 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * Reversible-operation contract (feature 054, US2 — bulk-edit undo).
+ *
+ * A reversible command captures, per affected record, the minimal changed-field
+ * before-values plus the after-values it wrote (research §R3/§R5). Undo restores
+ * `before` for every record whose current state still matches `after` (unchanged
+ * since the operation), and refuses records that changed — all-or-nothing per
+ * record, with a conflict report (FR-006). The stored `RevertRecord[]` is the
+ * `revert_state` persisted on the operation row.
+ */
+/** One affected record's captured pre/post state, sufficient to detect conflicts and restore. */
+export interface RevertRecord {
+    /** Id of the affected record. */
+    readonly recordId: string;
+    /** Minimal changed-field values before the operation (what undo restores). */
+    readonly before: Record<string, unknown>;
+    /** The values the operation wrote (compared against current state to detect conflicts). */
+    readonly after: Record<string, unknown>;
+}
+/** Terminal-ish undo state of a reversible operation (FR-014 idempotent re-invoke). */
+export type UndoStatus = 'none' | 'reverted' | 'partially_reverted';
+/** Why a record could not be reverted. */
+export type RevertConflictReason = 'changed_since_operation' | 'missing';
+/** A record the undo refused to touch, with the reason. */
+export interface RevertConflict {
+    readonly recordId: string;
+    readonly reason: RevertConflictReason;
+}
+/** Outcome of running an undo over a set of {@link RevertRecord}s. */
+export interface UndoResult {
+    /** Ids restored to their `before` state. */
+    readonly reverted: string[];
+    /** Records refused (changed since / missing), never overwritten. */
+    readonly conflicts: RevertConflict[];
+    /** The resulting operation undo status. */
+    readonly undoStatus: UndoStatus;
+}
+/**
+ * The per-record hooks a module supplies to make its records revertible. The
+ * generic {@link applyUndo} helper drives them: it reads current state, compares
+ * to `after`, and either restores `before` or records a conflict.
+ */
+export interface RevertHandlers {
+    /**
+     * Current changed-field values for a record, keyed like `RevertRecord.after`.
+     * Return `null` if the record no longer exists.
+     */
+    readCurrent(em: EntityManager, rec: RevertRecord): Promise<Record<string, unknown> | null>;
+    /** Restore a single record's `before` values on the transactional em. */
+    restore(em: EntityManager, rec: RevertRecord): Promise<void>;
+    /** Whether the record already carries its `before` state (already reverted → skip, no conflict). */
+    matchesBefore?(current: Record<string, unknown>, rec: RevertRecord): boolean;
+    /** Field-equality predicate; defaults to shallow JSON equality. */
+    equals?(a: Record<string, unknown>, b: Record<string, unknown>): boolean;
+}
+/** Shallow, order-insensitive JSON equality over the keys present in `expected`. */
+export declare function shallowFieldEquals(current: Record<string, unknown>, expected: Record<string, unknown>): boolean;
+/**
+ * Restore every record whose current state still matches its captured `after`;
+ * refuse the rest. All-or-nothing per record (FR-006). Idempotent-safe: a record
+ * already at its `before` state (matchesBefore) is counted as reverted without a
+ * second write. The caller persists the returned `undoStatus` on the operation row.
+ */
+export declare function applyUndo(em: EntityManager, records: readonly RevertRecord[], handlers: RevertHandlers): Promise<UndoResult>;
+//# sourceMappingURL=reversible.d.ts.map

package/dist/commands/reversible.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reversible.d.ts","sourceRoot":"","sources":["../../src/commands/reversible.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;GASG;AAEH,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,uFAAuF;AACvF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,oBAAoB,CAAC;AAEpE,0CAA0C;AAC1C,MAAM,MAAM,oBAAoB,GAAG,yBAAyB,GAAG,SAAS,CAAC;AAEzE,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE,CAAC;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3F,yEAAyE;IACzE,OAAO,CAAC,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,oGAAoG;IACpG,aAAa,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC;IAC7E,mEAAmE;IACnE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC1E;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAKT;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,aAAa,EACjB,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,CAAC,CA4BrB"}

package/dist/commands/reversible.js

@@ -0,0 +1,41 @@
+/** Shallow, order-insensitive JSON equality over the keys present in `expected`. */
+export function shallowFieldEquals(current, expected) {
+    for (const key of Object.keys(expected)) {
+        if (JSON.stringify(current[key]) !== JSON.stringify(expected[key]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Restore every record whose current state still matches its captured `after`;
+ * refuse the rest. All-or-nothing per record (FR-006). Idempotent-safe: a record
+ * already at its `before` state (matchesBefore) is counted as reverted without a
+ * second write. The caller persists the returned `undoStatus` on the operation row.
+ */
+export async function applyUndo(em, records, handlers) {
+    const equals = handlers.equals ?? shallowFieldEquals;
+    const reverted = [];
+    const conflicts = [];
+    for (const rec of records) {
+        const current = await handlers.readCurrent(em, rec);
+        if (current === null) {
+            conflicts.push({ recordId: rec.recordId, reason: 'missing' });
+            continue;
+        }
+        // Already restored (e.g. a prior partial undo) — count as reverted, no rewrite.
+        if (handlers.matchesBefore?.(current, rec) ?? equals(current, rec.before)) {
+            reverted.push(rec.recordId);
+            continue;
+        }
+        // Changed since the operation → refuse, never clobber.
+        if (!equals(current, rec.after)) {
+            conflicts.push({ recordId: rec.recordId, reason: 'changed_since_operation' });
+            continue;
+        }
+        await handlers.restore(em, rec);
+        reverted.push(rec.recordId);
+    }
+    const undoStatus = conflicts.length === 0 ? 'reverted' : reverted.length === 0 ? 'none' : 'partially_reverted';
+    return { reverted, conflicts, undoStatus };
+}
+//# sourceMappingURL=reversible.js.map

package/dist/commands/reversible.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reversible.js","sourceRoot":"","sources":["../../src/commands/reversible.ts"],"names":[],"mappings":"AAgEA,oFAAoF;AACpF,MAAM,UAAU,kBAAkB,CAChC,OAAgC,EAChC,QAAiC;IAEjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACnF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAiB,EACjB,OAAgC,EAChC,QAAwB;IAExB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,kBAAkB,CAAC;IACrD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAqB,EAAE,CAAC;IAEvC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACpD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,SAAS,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;YAC9D,SAAS;QACX,CAAC;QACD,gFAAgF;QAChF,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,uDAAuD;QACvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,SAAS,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;YAC9E,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAChC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM,UAAU,GACd,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC;IAC9F,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AAC7C,CAAC"}

package/dist/composition/compose-app.d.ts

@@ -0,0 +1,305 @@
+/**
+ * `composeApp` — the production half of what `composeTestServer` already is
+ * (`specs/110-instance-repository/` T118; `contracts/instance-repository.md`
+ * R1.4 and R2.4).
+ *
+ * ## What "the platform's" means here, precisely
+ *
+ * Everything in a deployment's composition that is true of **any** Endora
+ * platform and mentions no module: refuse a boot with no public origin, open the
+ * ORM, build the container, register the ORM-derived names and the host values,
+ * construct the audit writer, the event bus, the command bus and the two Redis
+ * clients, load presence from the database, compose the settings and
+ * sales-channel kernels, run `composeModules` once, open the contribution window
+ * once, install the request-scope hook, reconcile the settings manifests, run
+ * the boot phase once, assemble the error envelope, and give back a handle that
+ * can take all of it down again.
+ *
+ * Everything else — which modules, which ORM configuration, which manifests,
+ * which contributions, which actor a request carries — is the caller's, and
+ * reaches this function either as {@link AppComposition} or as one of the hooks
+ * below.
+ *
+ * ## The contribution wiring is the point, and it is a callback
+ *
+ * R1.4 puts *the contribution wiring* in this package; it does **not** put the
+ * 61 values `backend/src/composition.ts` contributes here. 41 of them carry a
+ * module's type or a value built out of a module's services, which D-52/D-53
+ * refuses from inside this package — so what moves is the *slot*, and the values
+ * arrive through {@link ComposeAppOptions.contribute}. Twenty do move, and every
+ * one of them is a kernel sub-kernel's object, a host value or an environment
+ * read; they are contributed **before** the caller's callback, so a deployment
+ * can still overwrite one.
+ *
+ * That is what makes R2.4 true the day this lands rather than after a sweep: an
+ * instance supplies no callback, so no file in a client's tree contributes over
+ * a name a module defaults, while this repository's `composition.ts` keeps its
+ * own as the **reference deployment's** — which is what it is, and not an
+ * instance.
+ *
+ * ## The one ordering rule, and why it is a shape rather than a comment
+ *
+ * `composeModules` runs once and `runBootHooks` runs once, immediately before
+ * this function returns, so a boot hook may resolve anything. A contribution
+ * over a name a module defaults goes in the single slot between them — earlier
+ * and the module's own registration overwrites it, later and a boot hook has
+ * already read the default (D-45). That slot is
+ * {@link ComposeAppOptions.contribute}, and both edges are enforced by the
+ * platform rather than remembered: the early one because `ComposedModules` does
+ * not exist until every module has registered, the late one because `contribute`
+ * throws `ContributionWindowClosedError` once `runBootHooks` has started
+ * (issue #52).
+ *
+ * ## Why no module may name this file
+ *
+ * It is on `./composition`, the host-internal subpath D-160.14 rules: declared
+ * by the `exports` map, carried by no published barrel, and answered for a
+ * module's reach with `host-internal-subpath`.
+ */
+import type { EntityManager, MikroORM } from '@mikro-orm/postgresql';
+import type { FastifyRequest } from 'fastify';
+import { Redis } from 'ioredis';
+import { CommandBus } from '../commands/index.js';
+import { EventBus } from '../events/bus.js';
+import { type ErrorEnvelopeOptions } from '../http/error-envelope.js';
+import { ApiInterceptorRegistry } from '../http/interceptors/index.js';
+import type { ModulePlugin } from '../http/server.js';
+import { AuditLogService } from '../kernel/audit/audit-log-service.js';
+import { composeModules } from '../kernel/compose.js';
+import { type KernelContainer } from '../kernel/container.js';
+import { type SalesChannelsKernel } from '../kernel/sales-channels/compose.js';
+import { type SettingsKernel } from '../kernel/settings/compose.js';
+import { type RegisteredManifestEntry } from '../lifecycle/index.js';
+import type { TenantContext } from '../tenancy/tenant-context.js';
+/** One composed module, named through `composeModules`' own signature. */
+type ModuleEntry = Parameters<typeof composeModules>[0][number];
+/** `composeModules`' return, named through its signature, for the same reason. */
+type ComposedModules = ReturnType<typeof composeModules>;
+/**
+ * How a composition opens and closes its ORM.
+ *
+ * A pair rather than an instance, for the reason the application's own
+ * `initOrm`/`closeOrm` are a pair: the ORM configuration captures
+ * `DATABASE_URL` at import, so *when* it is opened is part of what the caller
+ * decides.
+ */
+export interface AppOrmLifecycle {
+    open(): Promise<MikroORM>;
+    close(): Promise<void>;
+}
+/**
+ * What only this build knows about itself.
+ *
+ * Every member is optional, and the default is the same call with the
+ * **compiled-in half empty** — which is exactly an instance: it ships no
+ * generated manifest index, no committed entity registry and no committed
+ * migration registry, so its modules, its entities and its migrations are the
+ * packages it installed and nothing else (R1.2, D-119/D-155).
+ *
+ * A member is therefore never a second derivation of an answer the platform
+ * already has. `resolveManifestEntries`, `configuredEntitiesFrom` and
+ * `discoverConfiguredMigrations` are the same functions the application's own
+ * bindings call; what an application supplies is their `core*` argument.
+ */
+export interface AppComposition {
+    /**
+     * The module entries to compose — this repository's `MODULES` plus its
+     * overlay modules plus its discovered packages, or an instance's own set.
+     *
+     * A composition lacking a module that declares `activation.nonDeactivatable`
+     * is refused by `composeModules` before the first module registers (issue
+     * #258), and nothing here adds a second check or swallows the refusal.
+     */
+    readonly modules?: readonly ModuleEntry[];
+    /** An opener and a closer, per {@link AppOrmLifecycle}. */
+    readonly orm?: AppOrmLifecycle;
+    /**
+     * The instance-resolved manifest set: core, this deployment's overlay
+     * modules, and every installed module package.
+     *
+     * It is what the required-module set, the presence load, the error-code
+     * routing and the settings reconcile are all derived from — four derivations
+     * from one input, on every composition, so a caller that withdraws a module
+     * changes all four in the same run and there is no list anywhere (D-100).
+     */
+    readonly manifests?: readonly RegisteredManifestEntry[];
+}
+/** What every hook is handed once the modules have registered. */
+export interface ComposedAppContext {
+    readonly orm: MikroORM;
+    /** A fresh tenant-filtered fork per call — the seam production forks through. */
+    readonly em: () => EntityManager;
+    readonly container: KernelContainer;
+    readonly eventBus: EventBus;
+    readonly commandBus: CommandBus;
+    readonly auditLogService: AuditLogService;
+    readonly apiInterceptors: ApiInterceptorRegistry;
+    readonly redis: Redis;
+    readonly redisSubscriber: Redis;
+    readonly settings: SettingsKernel;
+    readonly salesChannels: SalesChannelsKernel;
+    /** The manifest set this composition was built from, resolved once. */
+    readonly resolvedModules: readonly RegisteredManifestEntry[];
+    /** The contribution window itself — `composed.contribute({ … })`. */
+    readonly composed: ComposedModules;
+}
+export interface ComposeAppOptions {
+    /**
+     * The absolute path of the directory that holds `apps/`.
+     *
+     * **A composition input, not a container contribution** (T114a,
+     * `contracts/application-root-supplier.md` R1.1). The proof is an ordering
+     * rather than a preference: the overlay entries it locates are spread into
+     * the module list `composeModules` receives, so a value deciding which
+     * modules exist cannot arrive through D-45's window, which opens on that
+     * call's return value.
+     *
+     * **It is required, and that is the point.** In this repository the answer is
+     * `overlay-roots.ts`' one expression and it would be easy to default to; in an
+     * instance the platform came out of `node_modules` and any default it could
+     * compute names a directory holding no `apps/` at all — silently, because an
+     * absent declaration and an empty one are deliberately the same answer.
+     */
+    readonly deploymentRoot: string;
+    /** What only this build knows — see {@link AppComposition}. */
+    readonly composition?: AppComposition;
+    /**
+     * Host values **no module defaults** — a deployment flag, a resolver only a
+     * composition can write. Registered before the modules do, where a value
+     * comes into existence, because there is nothing to overwrite and therefore
+     * no contribution window (AGENTS.md § Composition item 8).
+     *
+     * The platform registers its own here too: `redis`, `redisSubscriber`,
+     * `eventBus`, `commandBus`, `auditLogService`, `apiInterceptors`,
+     * `resolvedModuleRegistry` and the deployment dials derived from
+     * `BACKEND_ROLE`. A caller's entry of the same name wins.
+     */
+    readonly values?: Readonly<Record<string, unknown>>;
+    /**
+     * The contribution window (D-45, issue #52) — the one slot where a value a
+     * module defaults may be overwritten.
+     *
+     * It runs **after** the platform's own twenty contributions, so a deployment
+     * that wants a different answer for one of them says so here.
+     */
+    readonly contribute?: (ctx: ComposedAppContext) => void | Promise<void>;
+    /**
+     * Route plugins mounted after every module's own, after the modules' root
+     * plugins, and **before** the request-scope hook.
+     */
+    readonly plugins?: readonly ModulePlugin[];
+    /**
+     * Route plugins mounted **after** the request-scope hook.
+     *
+     * The scope sits in the middle of the chain rather than at its end, so there
+     * are two sides to it and a caller needs both. The platform's own
+     * sales-channel resolver is the first entry on this side, because it writes
+     * the resolved channel into the open request scope.
+     *
+     * Both arrays are read after the contribution window closes, so a caller may
+     * push into either from inside {@link contribute}, where the value a plugin
+     * needs finally exists.
+     */
+    readonly scopedPlugins?: readonly ModulePlugin[];
+    /**
+     * Establish the ambient `TenantContext` for a request (Principle XI).
+     *
+     * Omitting it is not "no tenancy": the platform installs
+     * `registerRequestScopeHook` either way and the default context is a system
+     * one. There is no path through this function that leaves the hook off.
+     *
+     * The actor → context mapping is the caller's until
+     * `specs/110-instance-repository/` T118b relocates the `request.actor`
+     * augmentation: reading `request.actor` needs a `declare module 'fastify'`
+     * block `auth` owns, and a platform file that named it would be the
+     * D-52/D-53 reach this function exists to end.
+     */
+    readonly buildTenantContext?: (request: FastifyRequest) => Promise<TenantContext>;
+    /**
+     * The wrapping order this deployment declares for a name more than one of its
+     * overlay modules decorates (feature 107, FR-040/FR-041).
+     *
+     * The deployment's own fact, read from its `divergence.ts` and handed over.
+     * Forwarded to `composeModules` unchanged and **checked, never applied**.
+     */
+    readonly decorationOrder?: Readonly<Record<string, readonly string[]>> | undefined;
+    /**
+     * The modules this deployment declares it omits (D-101), from the same
+     * declaration `decorationOrder` comes from.
+     *
+     * Supplied rather than read here: which deployment this process runs as is a
+     * fact about the process, and the file that locates the declaration is the
+     * application's (D115-3).
+     */
+    readonly declaredOmissions?: readonly string[];
+}
+export interface ComposeAppHandle {
+    orm: MikroORM;
+    redis: Redis;
+    modules: ModulePlugin[];
+    errorEnvelope: ErrorEnvelopeOptions;
+    /** Feature 054 — the Command Bus, exposed so migrated module wiring can consume it. */
+    commandBus: CommandBus;
+    /**
+     * Feature 060 — the API interceptor registry. An entry point passes it to
+     * `buildServer({ apiInterceptors })`; modules receive it at registration.
+     */
+    apiInterceptors: ApiInterceptorRegistry;
+    /**
+     * Feature 080 (T042b, D-157.12 item 1) — the composed kernel container.
+     *
+     * Passing it is mandatory rather than convenient for anything that opens a
+     * scope over this composition: `composeApp` deliberately does **not** call
+     * `setRootContainer` (see the reason at the container's construction below),
+     * so an `enterSystemScope` with no `container` branches off a process-wide
+     * root that has nothing registered.
+     */
+    container: KernelContainer;
+    /**
+     * Feature 080 (T042b, D-157.12 item 2) — a post-registration `ModuleContext`
+     * for one composed module, forwarded from `ComposedModules.contextFor`.
+     */
+    contextFor: ComposedModules['contextFor'];
+    /**
+     * The instance-resolved manifest set this composition was actually built
+     * from: core, this deployment's overlay modules and every installed package.
+     */
+    resolvedModules: readonly RegisteredManifestEntry[];
+    /** Closes the ORM + redis connections; call from a SIGTERM handler. */
+    dispose: () => Promise<void>;
+}
+/**
+ * The default {@link AppComposition} — the compiled-in half empty.
+ *
+ * An instance ships no generated manifest index and no committed registry, so
+ * its modules are its overlay modules plus the packages it installed, its
+ * entities are those packages' entities, and its migrations are those packages'
+ * migrations. Each is the same platform function the application's own binding
+ * calls, with `core` empty, so there is no second derivation of any of them.
+ *
+ * **Exported for its own test and named by no barrel.** Every other seam that
+ * could reach it needs a PostgreSQL, a Redis and an installed module set —
+ * `composeApp` opens all three before it composes anything — while the property
+ * this function has to hold is decided entirely by what it reads off disk: the
+ * modules it composes and the manifests it resolves must be one set.
+ * `default-composition-overlay.test.ts` is that assertion and it runs against a
+ * fixture deployment root with no service behind it. `./composition` does not
+ * carry the name, so nothing outside this package can call it.
+ */
+export declare function defaultComposition(deploymentRoot: string, env: NodeJS.ProcessEnv): Promise<Required<AppComposition>>;
+/**
+ * Every environment value below is read as `process.env['NAME']` at its own
+ * site, and never through a local alias.
+ *
+ * That is a rule about `check:env-inputs`, not about style: its walk reconciles
+ * `ENVIRONMENT_INPUTS` against the `process.env` reads it can **see**, and an
+ * alias hides every read behind it. Measured on the first draft of this file,
+ * which bound `const env = process.env` once: the check's site count fell from
+ * 67 to 58 and `REDIS_URL` and `REVALIDATE_SECRET` were reported as
+ * `unread-input` — an operator asked for two values that appeared to change
+ * nothing, on the merge request that made them load-bearing for every
+ * deployment at once.
+ */
+export declare function composeApp(options: ComposeAppOptions): Promise<ComposeAppHandle>;
+export {};
+//# sourceMappingURL=compose-app.d.ts.map

package/dist/composition/compose-app.d.ts.map

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