@endora-commerce/platform 0.100.0

package/dist/demo/plan.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The half of the demo runner that has no database in it (feature 113 Phase 0,
+ * `specs/113-module-owned-demo-data/contracts/module-demo-data-layer.md` §3.5,
+ * §3.6 and §4).
+ *
+ * Which modules contribute, in what order, and which are reported as skips —
+ * all of it decided from the resolved manifest set and a presence oracle, so
+ * the three properties that are easiest to get quietly wrong are testable with
+ * no services at all.
+ *
+ * It is deliberately separate from `runner.ts`, which is the half that calls
+ * things: **presence is decided here, before a context exists**, which is what
+ * §3.5 asks for and what `backend/src/cli/module-commands.ts` already does for a
+ * module-declared command. A plan that had already built contexts would have
+ * done the work the gate is meant to prevent.
+ */
+import type { ModuleDemoManifest } from '@endora-commerce/contracts';
+/** Seed or withdraw — the two directions the whole layer is written in. */
+export type DemoMode = 'seed' | 'reset';
+/**
+ * The minimum of a resolved manifest entry the demo layer reads.
+ *
+ * Structural rather than `RegisteredManifestEntry`, for the reason
+ * `CommandDeclaringEntry` gives: the three origins the platform resolves —
+ * core, this deployment's overlay and an installed package — reach here as one
+ * array and none of them is more this file's business than the others.
+ */
+export interface DemoManifestEntry {
+    readonly id: string;
+    readonly dependencies: readonly string[];
+    /** `undefined` — nobody decided; `false` — nothing to demonstrate; an object — a body (§1.2). */
+    readonly demo?: ModuleDemoManifest<never> | false;
+}
+/** One module the run will invoke. */
+export interface DemoPlanStep {
+    readonly moduleId: string;
+    readonly demo: ModuleDemoManifest<never>;
+}
+/**
+ * One module the run will not invoke, and why.
+ *
+ * The population is deliberately narrow: a module that **declares a body** and
+ * is not effectively present. That is §3.7's *"an absent module is a reported
+ * skip, never an error and never a silence"*. A module that declares `false`
+ * and a module nobody has decided about are counted rather than listed — 57
+ * lines saying "this module has nothing to demonstrate" is a report nobody
+ * reads, and neither state is a skip: there was nothing to run.
+ */
+export interface DemoPlanSkip {
+    readonly moduleId: string;
+    readonly reason: 'not-present';
+}
+/** The two quiet states of §1.2, counted so the report can account for them. */
+export interface DemoPlanCounts {
+    /** Modules declaring `demo: false` — a decision that owes nothing. */
+    readonly declaredNone: number;
+    /** Modules declaring nothing at all — nobody has decided. */
+    readonly undecided: number;
+}
+export interface DemoPlan {
+    readonly mode: DemoMode;
+    readonly steps: readonly DemoPlanStep[];
+    readonly skipped: readonly DemoPlanSkip[];
+    readonly counts: DemoPlanCounts;
+    /** Reported, never fatal (§4.5). */
+    readonly diagnostics: readonly string[];
+}
+export interface PlanDemoRunInput {
+    readonly mode: DemoMode;
+    /** The set the composition was actually built from. */
+    readonly entries: readonly DemoManifestEntry[];
+    /**
+     * Effective presence — platform-available **and** operator-activated
+     * (Constitution XVII, §3.6). Injected rather than reached for, so the plan is
+     * decidable without a registry cache and so the host stays the one place that
+     * knows what "present" means here.
+     */
+    readonly isPresent: (moduleId: string) => boolean;
+}
+/**
+ * Which modules contribute, in what order.
+ *
+ * ## The order is the platform's, not this file's (§4.1)
+ *
+ * `orderModulesByDependencies` is the walk the migration order builds its own
+ * order from, so a demo run and a migration run cannot come to disagree about
+ * what "after" means. What this file adds is the **advisory** `after` edges
+ * (§4.3): they go into the same graph, are read by the same walk, and put no
+ * module in anyone's `dependencies`. The measured case is `megamenu`, whose demo
+ * menu mirrors `catalog`'s demo categories and which does not declare `catalog`
+ * — and must not begin to for the sake of a fixture (D-209).
+ *
+ * The graph is built over **every** entry, not only the declaring ones, so a
+ * module that ships no demo data still orders the two that do through it. Only
+ * the declaring, present ones become steps.
+ *
+ * An `after` entry naming a module that is not in the run orders nothing and is
+ * not a finding (§4.4) — that falls out of `orderModulesByDependencies` skipping
+ * an edge into a node the map does not hold, and it is the ordinary case in a
+ * partial install rather than an exception to be reported. §4.4's *"MAY be
+ * reported"* for an id the vocabulary does not hold is deliberately not taken:
+ * from inside a client's instance the two states are one, and the diagnostic
+ * would fire on every correct partial install.
+ *
+ * A cycle is a **reported diagnostic and never a throw** (§4.5), on
+ * `migration-order.ts`' reasoning: a manifest can arrive from an installed
+ * package, and one stranger's declaration must not stop a shop's own demo from
+ * seeding. Its members come out contiguous, in id order.
+ */
+export declare function planDemoRun(input: PlanDemoRunInput): DemoPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/demo/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/demo/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAMrE,2EAA2E;AAC3E,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,iGAAiG;IACjG,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;CACnD;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,oCAAoC;IACpC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,QAAQ,CA6C7D"}

package/dist/demo/plan.js

@@ -0,0 +1,74 @@
+import { moduleDependencyCycles, orderModulesByDependencies, } from '../lifecycle/services/dep-graph.js';
+/**
+ * Which modules contribute, in what order.
+ *
+ * ## The order is the platform's, not this file's (§4.1)
+ *
+ * `orderModulesByDependencies` is the walk the migration order builds its own
+ * order from, so a demo run and a migration run cannot come to disagree about
+ * what "after" means. What this file adds is the **advisory** `after` edges
+ * (§4.3): they go into the same graph, are read by the same walk, and put no
+ * module in anyone's `dependencies`. The measured case is `megamenu`, whose demo
+ * menu mirrors `catalog`'s demo categories and which does not declare `catalog`
+ * — and must not begin to for the sake of a fixture (D-209).
+ *
+ * The graph is built over **every** entry, not only the declaring ones, so a
+ * module that ships no demo data still orders the two that do through it. Only
+ * the declaring, present ones become steps.
+ *
+ * An `after` entry naming a module that is not in the run orders nothing and is
+ * not a finding (§4.4) — that falls out of `orderModulesByDependencies` skipping
+ * an edge into a node the map does not hold, and it is the ordinary case in a
+ * partial install rather than an exception to be reported. §4.4's *"MAY be
+ * reported"* for an id the vocabulary does not hold is deliberately not taken:
+ * from inside a client's instance the two states are one, and the diagnostic
+ * would fire on every correct partial install.
+ *
+ * A cycle is a **reported diagnostic and never a throw** (§4.5), on
+ * `migration-order.ts`' reasoning: a manifest can arrive from an installed
+ * package, and one stranger's declaration must not stop a shop's own demo from
+ * seeding. Its members come out contiguous, in id order.
+ */
+export function planDemoRun(input) {
+    const declaring = new Map();
+    let declaredNone = 0;
+    let undecided = 0;
+    for (const entry of input.entries) {
+        if (entry.demo === undefined)
+            undecided += 1;
+        else if (entry.demo === false)
+            declaredNone += 1;
+        else
+            declaring.set(entry.id, entry.demo);
+    }
+    // Presence, once per declaring module, before anything is built. It is asked
+    // about the **declaring** module and never about a dependency: that answer is
+    // the owner's own gate's, and asking it twice is how the two come to disagree
+    // (D-157.5).
+    const skipped = [];
+    const running = new Map();
+    for (const [moduleId, demo] of declaring) {
+        if (input.isPresent(moduleId))
+            running.set(moduleId, demo);
+        else
+            skipped.push({ moduleId, reason: 'not-present' });
+    }
+    const graph = new Map();
+    for (const entry of input.entries) {
+        const after = running.get(entry.id)?.after ?? [];
+        graph.set(entry.id, [...entry.dependencies, ...after]);
+    }
+    const diagnostics = moduleDependencyCycles(graph).map((members) => `[demo] modules [${members.join(', ')}] order each other in a loop, counting ` +
+        `\`demo.after\`. Their demo data runs as one block in module-id order, because ` +
+        `the declarations contain no order.`);
+    const ordered = orderModulesByDependencies(graph).filter((id) => running.has(id));
+    const sequence = input.mode === 'reset' ? [...ordered].reverse() : ordered;
+    return {
+        mode: input.mode,
+        steps: sequence.map((moduleId) => ({ moduleId, demo: running.get(moduleId) })),
+        skipped: skipped.sort((left, right) => left.moduleId.localeCompare(right.moduleId)),
+        counts: { declaredNone, undecided },
+        diagnostics,
+    };
+}
+//# sourceMappingURL=plan.js.map

package/dist/demo/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/demo/plan.ts"],"names":[],"mappings":"AAiBA,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,oCAAoC,CAAC;AAuE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAqC,CAAC;IAC/D,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS,IAAI,CAAC,CAAC;aACxC,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK;YAAE,YAAY,IAAI,CAAC,CAAC;;YAC5C,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED,6EAA6E;IAC7E,8EAA8E;IAC9E,8EAA8E;IAC9E,aAAa;IACb,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAqC,CAAC;IAC7D,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;QACzC,IAAI,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;;YACtD,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;IACnD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;QACjD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,YAAY,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,WAAW,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC,GAAG,CACnD,CAAC,OAAO,EAAE,EAAE,CACV,mBAAmB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,yCAAyC;QAC9E,gFAAgF;QAChF,oCAAoC,CACvC,CAAC;IAEF,MAAM,OAAO,GAAG,0BAA0B,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IAE3E,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAE,EAAE,CAAC,CAAC;QAC/E,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACnF,MAAM,EAAE,EAAE,YAAY,EAAE,SAAS,EAAE;QACnC,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/demo/report.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What the operator reads at the end of a demo run (feature 113 Phase 0,
+ * `contracts/module-demo-data-layer.md` §3.7).
+ *
+ * *"The command MUST report per module what was contributed and per composition
+ * step what was skipped and why. An absent module is a reported skip, never an
+ * error and never a silence."*
+ *
+ * Formatting lives apart from the running so that the report is assertable
+ * without invoking anything, and so that a module's body never formats: it
+ * returns counts and the runner lays them out once. A client's scaffolded
+ * composition therefore does not have to know how the platform prints
+ * credentials.
+ */
+import type { DemoRunResult } from './runner.js';
+export declare function formatDemoReport(result: DemoRunResult): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/demo/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/demo/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyBjD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAoE9D"}

package/dist/demo/report.js

@@ -0,0 +1,85 @@
+function countLine(entity) {
+    return `${entity.entity} ${entity.count}`;
+}
+/**
+ * The two quiet states of §1.2, as one sentence.
+ *
+ * Counted rather than listed: 57 lines saying "this module has nothing to
+ * demonstrate" is a report nobody reads, and neither state is a skip — there
+ * was nothing to run. They are printed at all because *"nobody has decided"* is
+ * a real state an operator may want to see the size of.
+ */
+function quietStates(result) {
+    const parts = [];
+    if (result.counts.declaredNone > 0) {
+        parts.push(`${result.counts.declaredNone} declares none`);
+    }
+    if (result.counts.undecided > 0) {
+        parts.push(`${result.counts.undecided} has not decided`);
+    }
+    return parts.length === 0 ? undefined : `Modules with no demo data: ${parts.join(', ')}.`;
+}
+export function formatDemoReport(result) {
+    const verb = result.mode === 'seed' ? 'seeded' : 'withdrawn';
+    const lines = [];
+    if (result.modules.length === 0) {
+        lines.push(`No module contributed demo data — nothing was ${verb}.`);
+    }
+    else {
+        lines.push(`Demo ${verb}, module by module:`);
+        for (const module of result.modules) {
+            const counts = module.entities.map(countLine).join(', ');
+            lines.push(`  ${module.moduleId} — ${module.summary}${counts ? ` (${counts})` : ''}`);
+            for (const note of module.notes)
+                lines.push(`      note: ${note}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        lines.push('');
+        lines.push('Skipped, and why:');
+        for (const skip of result.skipped) {
+            // Two reasons, printed apart, because they ask the operator for two
+            // different things: switch the module on, or install a package. Reading
+            // an uninstalled demo package as "not present" would send them to the
+            // module screen, where the module is on and nothing is wrong (§6.3).
+            lines.push(skip.reason === 'demo-package-not-installed'
+                ? `  ${skip.moduleId} — its demo data lives in '${skip.package}', which is not ` +
+                    `installed in this instance. The module itself is present; install that ` +
+                    `package to seed its demo data.`
+                : `  ${skip.moduleId} — not present in this instance (either not installed, or ` +
+                    `switched off by an operator).`);
+        }
+    }
+    if (result.composition) {
+        lines.push('');
+        if (result.composition.applied.length > 0) {
+            lines.push(`Composition ${result.mode === 'seed' ? 'applied' : 'withdrawn'}:`);
+            for (const step of result.composition.applied)
+                lines.push(`  ${step}`);
+        }
+        if (result.composition.skipped.length > 0) {
+            lines.push('Composition steps skipped, and why:');
+            for (const skip of result.composition.skipped) {
+                lines.push(`  ${skip.step} — ${skip.reason}`);
+            }
+        }
+    }
+    const quiet = quietStates(result);
+    if (quiet) {
+        lines.push('');
+        lines.push(quiet);
+    }
+    if (result.credentials.length > 0) {
+        lines.push('');
+        lines.push('Sign in with:');
+        for (const credential of result.credentials) {
+            lines.push(`  ${credential.label}: ${credential.value}`);
+        }
+    }
+    for (const diagnostic of result.diagnostics) {
+        lines.push('');
+        lines.push(diagnostic);
+    }
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=report.js.map

package/dist/demo/report.js.map

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

package/dist/demo/runner.d.ts

@@ -0,0 +1,207 @@
+/**
+ * The demo runner (feature 113 Phase 0,
+ * `specs/113-module-owned-demo-data/contracts/module-demo-data-layer.md` §3 and
+ * §5.5).
+ *
+ * Given a plan, invoke each module's body with that module's own context, run
+ * the instance's composition at the one point in the sequence where it belongs,
+ * and return a report. Everything decidable without a database is `plan.ts`'s;
+ * this file is the part that calls things.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not open a scope and it does not call the production guard. Both are
+ * the **entry point's** (§3.3, §3.4): the guard runs first, before anything is
+ * composed, outside every `try`, and the scope is opened once for the whole run
+ * over the composition's own container. A runner that opened its own would be a
+ * second entry point, which is exactly the property §3.4 buys by taking the
+ * responsibility off every module's body.
+ *
+ * It also holds no module list of its own and imports from no module. It is
+ * handed the resolved manifest set, a presence oracle and a context factory —
+ * which is what lets it live in the platform at all (D-52/D-53).
+ */
+import type { DemoCredential, DemoEntityCount } from '@endora-commerce/contracts';
+import { type DemoManifestEntry, type DemoMode, type DemoPlanCounts, type DemoPlanSkip } from './plan.js';
+import { type DemoPackageResolver } from './packages.js';
+/**
+ * The cross-module wiring, supplied by whoever owns the instance (§5, D-209).
+ *
+ * It is a **parameter** and never an import: a composition names `megamenu` and
+ * `catalog`, and a platform root that named a module would be D-52/D-53's one
+ * rule with an exception. In this repository the host passes its own; in a
+ * client's instance the scaffold writes one into their tree and their entry
+ * point passes that.
+ */
+export interface DemoComposition {
+    /** Runs after every module's `seed` and before the summary (§5.5). */
+    apply(): Promise<DemoCompositionResult>;
+    /** Runs before any module's `reset` (§5.5). */
+    withdraw(): Promise<DemoCompositionResult>;
+    /**
+     * The **foundation**: rows every module's demo body already assumes, created
+     * before the first `seed` (§5.5a, feature 113 T226).
+     *
+     * ## Why a second phase exists, measured rather than argued
+     *
+     * §5.5's single after-the-modules position is right for *wiring* — a step
+     * that joins two modules' rows can only run once both exist. It is wrong for
+     * a row a module's body **reads**, and this repository holds exactly one:
+     * the demo's two sales channels. `sales_channels` is the kernel's table, so
+     * no module may declare it as demo data (§2.1) and the kernel carries no
+     * `demo` field; and `inventory`'s body does `em.find(SalesChannel, {})` and
+     * assigns the demo warehouse to every channel it finds. Created in `apply`,
+     * the second channel arrives after that read has happened and
+     * `pl_b2b_vip` silently loses its `warehouse_channel_assignments` row.
+     *
+     * Measured before this phase existed: `inventory` reports
+     * `WarehouseChannelAssignment 2` on a seed where the channels precede it and
+     * would report 1 where they do not, with nothing failing.
+     *
+     * It is **optional**, and an instance that declares none is an ordinary
+     * instance rather than a degraded one — §5.6's rule for a composition that is
+     * absent entirely, one level down. A composition written against the
+     * Phase-0 interface keeps working unchanged, which is §6.5's property applied
+     * to this interface rather than to the hatch.
+     */
+    applyFoundation?(): Promise<DemoCompositionResult>;
+    /**
+     * The mirror of {@link DemoComposition.applyFoundation}: runs **after** the
+     * last module's `reset` (§5.5a).
+     *
+     * The position is forced rather than chosen. A withdrawal is the reverse of
+     * the sequence that built it, so the foundation goes last — and here that is
+     * the difference between a filtered delete and a cascade: withdrawing the
+     * demo's sales channels *before* `inventory`'s `reset` would take that
+     * module's assignment rows with them through the database rather than
+     * through the module that owns them, which is an unfiltered destruction by
+     * another name.
+     */
+    withdrawFoundation?(): Promise<DemoCompositionResult>;
+}
+/**
+ * What a composition reports.
+ *
+ * `skipped` is not an afterthought — it is FR-011 and US2's first acceptance
+ * scenario. Every step is guarded by an effective-presence question about every
+ * module it touches, and a step whose modules are not all present is a reported
+ * skip carrying the reason (§5.4): never a throw, never a silence.
+ */
+export interface DemoCompositionResult {
+    readonly applied: readonly string[];
+    readonly skipped: readonly {
+        readonly step: string;
+        readonly reason: string;
+    }[];
+    /**
+     * Sign-in details this composition created, merged into the run's own list
+     * and formatted once by {@link formatDemoReport} (feature 113, T226).
+     *
+     * A composition creates accounts a module cannot: `customer_accounts.
+     * organization_id` is `NOT NULL` under Principle XI, so the demo buyer is
+     * created by a composition step and by nothing else, and until this field
+     * existed the only thing that could print its password was the legacy seed
+     * script — which this task deletes. Without it the composed path would have
+     * printed three of the four pairs and said nothing about the fourth, which
+     * is the silent half-report §3.7 is written against.
+     */
+    readonly credentials?: readonly DemoCredential[];
+}
+/** What one module contributed. */
+export interface DemoModuleOutcome {
+    readonly moduleId: string;
+    readonly summary: string;
+    readonly entities: readonly DemoEntityCount[];
+    readonly notes: readonly string[];
+}
+/**
+ * A module the escape hatch's package is not installed for (§6.3's **second**
+ * answer, feature 113 T235).
+ *
+ * A skip and never a failure: the module contributes nothing, the run
+ * continues, and the report names the package so an operator can install it.
+ * It is a kind of its own rather than a second `reason` on
+ * {@link DemoPlanSkip} because that type is `plan.ts`', decidable with no
+ * module system, and this one is not — collapsing them would put a resolution
+ * this file performs into a type that promises never to perform one.
+ */
+export interface DemoPackageSkip {
+    readonly moduleId: string;
+    readonly reason: 'demo-package-not-installed';
+    readonly package: string;
+}
+/** Everything the run did not do, and why. */
+export type DemoRunSkip = DemoPlanSkip | DemoPackageSkip;
+export interface DemoRunResult {
+    readonly mode: DemoMode;
+    readonly modules: readonly DemoModuleOutcome[];
+    readonly skipped: readonly DemoRunSkip[];
+    readonly counts: DemoPlanCounts;
+    readonly credentials: readonly DemoCredential[];
+    readonly diagnostics: readonly string[];
+    /**
+     * Absent when the caller supplied no composition.
+     *
+     * Both phases (§5.5a) are here, concatenated in the order they ran: the
+     * foundation's steps and the wiring's are one list because an operator reads
+     * a sequence, and the step name — the composition's own sentence — is what
+     * says which is which.
+     */
+    readonly composition?: DemoCompositionResult;
+}
+/**
+ * A module's demo body failed, and the run failed with it (§3.8).
+ *
+ * *"A demo seed that half-succeeded silently is worse than one that failed: the
+ * operator cannot tell a partial demo from a complete one."* So the throw is
+ * unconditional and nothing is swallowed — the original error is the `cause`,
+ * unmodified, which is what keeps the entry point's `ModuleDisabledError`
+ * discrimination working through one `unwrapDemoFailure` call rather than
+ * through a `catch` that decides anything.
+ */
+export declare class DemoRunFailedError extends Error {
+    readonly moduleId: string;
+    readonly mode: DemoMode;
+    readonly cause: unknown;
+    constructor(moduleId: string, mode: DemoMode, cause: unknown);
+}
+/**
+ * The error a demo run really failed with.
+ *
+ * Not a `catch` and not a decision: it unwraps one known wrapper so that an
+ * entry point's existing discrimination — `err instanceof ModuleDisabledError`
+ * — sees what it saw before this layer existed. Everything else passes through.
+ */
+export declare function unwrapDemoFailure(error: unknown): unknown;
+export interface RunDemoInput {
+    readonly mode: DemoMode;
+    readonly entries: readonly DemoManifestEntry[];
+    readonly isPresent: (moduleId: string) => boolean;
+    /** The composition's own context factory — `ComposeAppHandle.contextFor`. */
+    readonly contextFor: (moduleId: string) => unknown;
+    readonly composition?: DemoComposition;
+    /**
+     * How a `demo.package` name is resolved (§6, T235).
+     *
+     * Defaults to {@link createDemoPackageResolver} over the working directory,
+     * which for `endora demo seed` is the instance root. A host that runs from
+     * somewhere else, and a test asserting §6.3's three answers, passes its own.
+     */
+    readonly demoPackages?: DemoPackageResolver;
+}
+/**
+ * Run one demo pass and report it.
+ *
+ * The sequence is §3's and §5.5a's, in full: plan (which decides presence),
+ * then the foundation, then each module in order, then the wiring —
+ *
+ * ```
+ * seed   applyFoundation? -> module seed  (dependency order) -> apply
+ * reset  withdraw         -> module reset (reverse order)    -> withdrawFoundation?
+ * ```
+ *
+ * — so `reset` is the exact reverse of `seed` at every position, which is the
+ * property that lets a withdrawal be a filtered delete rather than a cascade.
+ */
+export declare function runDemo(input: RunDemoInput): Promise<DemoRunResult>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/demo/runner.d.ts.map

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