@endora-commerce/platform 0.100.0

package/dist/lifecycle/commands/uninstall.js

@@ -0,0 +1,223 @@
+import { z } from 'zod';
+import { LifecycleError } from '../services/orchestrator.js';
+import { buildStaticRegistry } from '../services/static-registry.js';
+import { orchestratorFor } from './operator-runtime.js';
+/**
+ * `module:uninstall <module-id> [--hard] [--force] [--json]` — the body
+ * (`specs/115-lifecycle-container-move/`, D115-1).
+ *
+ * Soft uninstall (default): unregisters the module's settings, marks the
+ * registry row as `uninstalled`, leaves DB tables / data intact.
+ * Hard uninstall (`--hard`): also reverts the module's migrations and
+ * deletes the registry row. `--hard` additionally requires `--force` — on every
+ * run, terminal or not (owner ruling **D-217**), because no caller supplies
+ * {@link OperatorRuntime.confirm} and absent means this run cannot ask
+ * (D115-7, R2.7).
+ *
+ * Exit codes (per `specs/018-module-lifecycle/contracts/cli-commands.md` §C-2),
+ * preserved byte-for-byte by the move (R2.3):
+ *   - 0   success (or already uninstalled — no-op)
+ *   - 64  misuse: bad argv, --hard without --force (D-217: every run)
+ *   - 66  conflict: dependents still installed
+ *   - 70  internal error during uninstall
+ *   - 75  lock unavailable
+ *   - 77  refused: the module declares itself non-deactivatable (D-69)
+ */
+const UninstallArgsSchema = z.object({
+    id: z.string().regex(/^_?[a-z][a-z0-9_]*$/),
+    hard: z.boolean().default(false),
+    force: z.boolean().default(false),
+    json: z.boolean().default(false),
+});
+function parseArgv(argv) {
+    const positional = [];
+    let hard = false;
+    let force = false;
+    let json = false;
+    // Backward-compat aliases for the legacy modules:uninstall flags.
+    for (const arg of argv) {
+        if (arg === '--hard')
+            hard = true;
+        else if (arg === '--force')
+            force = true;
+        else if (arg === '--json')
+            json = true;
+        else if (arg === '--remove-settings') {
+            hard = true;
+            force = true;
+        }
+        else if (arg === '--preserve-settings') {
+            // soft default — no-op flag, kept for back-compat
+        }
+        else if (arg.startsWith('--'))
+            return { error: `unknown flag: ${arg}` };
+        else
+            positional.push(arg);
+    }
+    if (positional.length === 0)
+        return { error: 'missing module id' };
+    if (positional.length > 1) {
+        return { error: `extra positional args: ${positional.slice(1).join(' ')}` };
+    }
+    const result = UninstallArgsSchema.safeParse({
+        id: positional[0],
+        hard,
+        force,
+        json,
+    });
+    if (!result.success) {
+        return {
+            error: `invalid argument: ${result.error.issues.map((i) => i.message).join('; ')}`,
+        };
+    }
+    return result.data;
+}
+export async function runUninstallCommand(argv, rt) {
+    const parsed = parseArgv(argv);
+    if ('error' in parsed) {
+        rt.err(`usage: module:uninstall <module-id> [--hard] [--force] [--json]\n` +
+            `error: ${parsed.error}\n`);
+        return 64;
+    }
+    const args = parsed;
+    // Hard uninstall without --force requires a confirmation this run can
+    // obtain, and whether it can is the *caller's* answer rather than this file's
+    // (D115-7, R2.7). It used to be `!process.stdout.isTTY` here. That read is a
+    // decision taken from a process global, which defeats R2.4's two reasons —
+    // *testable without a process*, and *an instance may frame the output* —
+    // exactly as writing to one would: a body test has to mutate a global to
+    // reach this branch, and a deploy script, a systemd unit or an admin action
+    // has its destructive-write policy decided by whether *its own* stdout
+    // happens to be a terminal, which is a fact about the wrapper and not about
+    // the operator. It was also wrong on its own terms — it tested stdout alone,
+    // so `docker run -t`, a `script -qec` wrapper or any CI configuration that
+    // allocates a terminal for coloured output read as interactive and took the
+    // branch that **proceeds**, which is the mirror of the predicate
+    // `specs/117-instance-bring-up/contracts/input-resolution.md` R3.5 refuses.
+    //
+    // The exit code and the sentence stay here, on this side of the partition
+    // with the rest of the table (§1.1, R2.3); only the fact travels.
+    //
+    // **Absent means this run cannot ask**, and nothing supplies `confirm`, so the
+    // refusal is what every invocation meets — which is the whole of §C-2 step 6
+    // since owner ruling **D-217** (2026-09-07). That ruling struck the step's
+    // second half, *"or a tty prompt confirming "yes" verbatim"*, which had been
+    // contract since feature 018 and was never implemented in either tree: a
+    // promise that went unimplemented that long, in a destructive path, with
+    // nobody noticing, is evidence nobody needed it. `--hard` requires `--force`
+    // whether or not the run has a terminal, and nothing in the platform ever
+    // needs stdin.
+    //
+    // **The field stays** and this predicate keeps reading it, both by the
+    // ruling's own words. Supplying `confirm` from an entry point *without* also
+    // building the prompt is therefore the one way back to the data loss above —
+    // and it is the shape D115-7 anticipated, since it recorded the intent that
+    // the entry points would supply it on the R2.7 conjunction. It is pinned by
+    // `uninstall-hard-needs-force.integration.test.ts`, whose second case runs
+    // this entry point with every interactivity signal reading true; the first
+    // case spawns through a pipe and, measured, stays green under exactly that
+    // change.
+    if (args.hard && !args.force && !rt.confirm) {
+        rt.err(`[uninstall] --hard requires --force unless this run can ask for confirmation ` +
+            `(refusing to delete data without explicit confirmation).\n`);
+        return 64;
+    }
+    let registry;
+    try {
+        // The entries are the **instance-resolved** set (D-157.6a) — core, this
+        // deployment's overlay modules and every installed Endora module package —
+        // resolved by the entry point, which is where the collision refusal reaches
+        // an operator (R2.2). The runtime carries no container, so a command cannot
+        // compose the platform it operates on (D-157.2).
+        registry = buildStaticRegistry(rt.entries);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        rt.err(`[manifest] ${msg}\n`);
+        return 65;
+    }
+    // A platform command composes nothing (D-157.2), so the merged ownership a
+    // composition root builds is not available to it: it answers for the committed
+    // core registry and for nothing else, and a hard uninstall of a package module
+    // is refused from the terminal rather than reverting core's rows and leaving the
+    // package's behind. The map is read from the host's generated registry, which
+    // is why it arrives on the runtime rather than being reached for here.
+    const migrationOwnership = rt.migrationOwnership
+        ? await rt.migrationOwnership()
+        : undefined;
+    const orchestrator = await orchestratorFor(rt, registry, migrationOwnership ? { migrationOwnership } : {});
+    try {
+        const result = await orchestrator.uninstall(args.id, { hard: args.hard });
+        if (args.json) {
+            rt.out(JSON.stringify(result) + '\n');
+        }
+        else if (result.state === 'already-uninstalled') {
+            rt.out(`[uninstall] ${args.id} — already uninstalled (no-op)\n`);
+        }
+        else if (args.hard) {
+            rt.out(`[uninstall] ${args.id} --hard (DATA DELETED)\n` +
+                `  ✓ uninstall hook completed\n` +
+                `  ✓ settings removed: ${result.removedGroups} groups, ${result.removedSettings} settings\n` +
+                `  ✓ migrations reverted: ${result.revertedMigrations.length === 0 ? '(none matched filename pattern)' : result.revertedMigrations.join(', ')}\n` +
+                `  ✓ registry row deleted\n`);
+        }
+        else {
+            rt.out(`[uninstall] ${args.id} (soft, data preserved)\n` +
+                `  ✓ uninstall hook completed\n` +
+                `  ✓ settings unregistered: ${result.removedGroups} groups, ${result.removedSettings} settings (rows removed; tables intact)\n` +
+                `  ✓ registry updated: state=uninstalled\n` +
+                `re-installing re-uses the applied migrations, but not the configuration:\n` +
+                `the settings above are gone; a re-install recreates them from the manifest defaults.\n` +
+                `Use module:disable to pause a module without losing its configuration.\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        return mapError(err, args.json, rt);
+    }
+}
+function mapError(err, asJson, rt) {
+    if (err instanceof LifecycleError) {
+        if (asJson) {
+            rt.err(JSON.stringify({
+                error: err.kind,
+                message: err.message,
+                ...err.details,
+            }) + '\n');
+        }
+        else {
+            rt.err(`[uninstall] ${err.message}\n`);
+            if (err.kind === 'non-deactivatable') {
+                // Same hint the disable path prints, for the same reason: there is no
+                // `--force` to suggest. The consequence of removing one of these is a
+                // deployment that cannot authenticate the operator who would put it
+                // back — and after `--hard` the tables that recovery needs are gone.
+                rt.err(`hint: this module declares itself non-deactivatable in its manifest, which refuses ` +
+                    `uninstall as well as disable. If that declaration is wrong, change the manifest — ` +
+                    `there is no override flag.\n`);
+            }
+        }
+        switch (err.kind) {
+            case 'unknown-module':
+            case 'wrong-state':
+                return 64;
+            case 'manifest-cycle':
+                return 65;
+            case 'missing-deps':
+            case 'dependents-block':
+                return 66;
+            case 'install-failed':
+            case 'uninstall-failed':
+                return 70;
+            case 'lock-busy':
+                return 75;
+            case 'non-deactivatable':
+                // EX_NOPERM — the request was well-formed and is not permitted.
+                return 77;
+        }
+    }
+    const msg = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+    rt.err(`[internal] ${msg}\n`);
+    return 70;
+}
+//# sourceMappingURL=uninstall.js.map

package/dist/lifecycle/commands/uninstall.js.map

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

package/dist/lifecycle/divergence-declaration.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A deployment's divergence declaration — the **shape half**
+ * (`specs/115-lifecycle-container-move/`, D115-3;
+ * `contracts/operator-half.md` §4).
+ *
+ * What a deployment declares about how it means to differ from core. Its first
+ * content is the declared escape from D-101's boot refusal: a deployment may
+ * ship fewer modules than its manifests declare — that is the reduced
+ * deployment feature 071's packaging split exists to make possible — and what it
+ * may not do is arrive at that state silently. The owner's E1 ruling is that
+ * *"someone deliberately assembling a reduced deployment must declare that they
+ * know"*.
+ *
+ * The declaration is a **committed, reviewed, per-deployment file**, not a flag.
+ * D-69 refused a `--force` on the orchestrator's withdrawal guard on the ground
+ * that a flag is weighed once, at 2 a.m., by one person; the same reasoning
+ * points the same way here. A committed entry appears in the merge request that
+ * assembles the deployment, where somebody who is not mid-incident reads it.
+ *
+ * No file, or a declaration with nothing in it, means "this deployment differs
+ * from core in no way it has to declare" — the two states are deliberately the
+ * same answer, which is what makes the split below load-bearing rather than
+ * tidy.
+ *
+ * ## Why only two functions are here
+ *
+ * `divergence.ts` was one file with three things in it: this parser, a path
+ * derivation and a loader. The rule that splits them is `contracts/operator-half.md`
+ * §1's — *a file belongs to `@endora-commerce/platform` unless it names a path in
+ * the tree that installs the platform* — and these two name none. They are pure
+ * over {@link DeploymentDivergenceDeclarationSchema}: no disk, no environment,
+ * no deployment. `path` is a caller-supplied string that appears in a refusal
+ * and is never composed, resolved or read.
+ *
+ * **The other half may not follow them here, and that is measured rather than
+ * preferred.** The loader derives its root from its own `import.meta.url`, and
+ * that chain is correct for its location and for no other: it was one `dirname`
+ * too high once, so it composed `backend/apps/<d>/divergence.ts`, `existsSync`
+ * said no, and **every deployment read as declaring nothing** — D-101's declared
+ * escape had never worked, in production or under `tsx`, and nothing could see
+ * it because an absent file and an empty declaration are the same answer. Three
+ * `dirname`s from a file in this directory's neighbourhood give
+ * `packages/platform/src` or `packages/platform`, so a wholesale move reproduces
+ * that state exactly. The locator stays in the tree that owns `apps/`, and the
+ * platform receives the *value* — which is the seam it already had:
+ * `kernel/compose.ts` takes the declaration as a field of `ComposeModulesOptions`
+ * and has never called the loader.
+ *
+ * @see `backend/src/overlay/divergence-loader.ts` — the half that reads the disk.
+ */
+import { type DeploymentDivergenceDeclaration } from '@endora-commerce/contracts';
+/** A declaration that declares nothing — an absent file's answer, as data. */
+export declare function emptyDivergenceDeclaration(): DeploymentDivergenceDeclaration;
+/**
+ * A declaration is only a declaration if each entry carries its reason.
+ *
+ * Exported and pure so the shape rules have a proof that does not need a
+ * deployment on disk: a fixture enters here as the raw exported value, which is
+ * the top of this analysis rather than something the loader already computed.
+ *
+ * A field left out means *none of these*, which is the reading an absent file
+ * already gets; a field that is present and malformed is refused, naming the
+ * deployment's own file. An **array** is refused with the shape it should have
+ * had, because that is what every declaration in the tree looked like before
+ * D-205 and a client copying an older one deserves the sentence rather than
+ * `expected object, received array`.
+ *
+ * @param path the declaration's own location, as the caller wishes to name it
+ *   to its reader. It is prose in a refusal and nothing else — this function
+ *   neither composes it nor reads it, which is what lets the platform hold the
+ *   shape rule while the tree that owns `apps/` holds the layout.
+ */
+export declare function parseDivergenceDeclaration(value: unknown, path: string): DeploymentDivergenceDeclaration;
+//# sourceMappingURL=divergence-declaration.d.ts.map

package/dist/lifecycle/divergence-declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"divergence-declaration.d.ts","sourceRoot":"","sources":["../../src/lifecycle/divergence-declaration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,4BAA4B,CAAC;AAEpC,8EAA8E;AAC9E,wBAAgB,0BAA0B,IAAI,+BAA+B,CAE5E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,GACX,+BAA+B,CAoBjC"}

package/dist/lifecycle/divergence-declaration.js

@@ -0,0 +1,92 @@
+/**
+ * A deployment's divergence declaration — the **shape half**
+ * (`specs/115-lifecycle-container-move/`, D115-3;
+ * `contracts/operator-half.md` §4).
+ *
+ * What a deployment declares about how it means to differ from core. Its first
+ * content is the declared escape from D-101's boot refusal: a deployment may
+ * ship fewer modules than its manifests declare — that is the reduced
+ * deployment feature 071's packaging split exists to make possible — and what it
+ * may not do is arrive at that state silently. The owner's E1 ruling is that
+ * *"someone deliberately assembling a reduced deployment must declare that they
+ * know"*.
+ *
+ * The declaration is a **committed, reviewed, per-deployment file**, not a flag.
+ * D-69 refused a `--force` on the orchestrator's withdrawal guard on the ground
+ * that a flag is weighed once, at 2 a.m., by one person; the same reasoning
+ * points the same way here. A committed entry appears in the merge request that
+ * assembles the deployment, where somebody who is not mid-incident reads it.
+ *
+ * No file, or a declaration with nothing in it, means "this deployment differs
+ * from core in no way it has to declare" — the two states are deliberately the
+ * same answer, which is what makes the split below load-bearing rather than
+ * tidy.
+ *
+ * ## Why only two functions are here
+ *
+ * `divergence.ts` was one file with three things in it: this parser, a path
+ * derivation and a loader. The rule that splits them is `contracts/operator-half.md`
+ * §1's — *a file belongs to `@endora-commerce/platform` unless it names a path in
+ * the tree that installs the platform* — and these two name none. They are pure
+ * over {@link DeploymentDivergenceDeclarationSchema}: no disk, no environment,
+ * no deployment. `path` is a caller-supplied string that appears in a refusal
+ * and is never composed, resolved or read.
+ *
+ * **The other half may not follow them here, and that is measured rather than
+ * preferred.** The loader derives its root from its own `import.meta.url`, and
+ * that chain is correct for its location and for no other: it was one `dirname`
+ * too high once, so it composed `backend/apps/<d>/divergence.ts`, `existsSync`
+ * said no, and **every deployment read as declaring nothing** — D-101's declared
+ * escape had never worked, in production or under `tsx`, and nothing could see
+ * it because an absent file and an empty declaration are the same answer. Three
+ * `dirname`s from a file in this directory's neighbourhood give
+ * `packages/platform/src` or `packages/platform`, so a wholesale move reproduces
+ * that state exactly. The locator stays in the tree that owns `apps/`, and the
+ * platform receives the *value* — which is the seam it already had:
+ * `kernel/compose.ts` takes the declaration as a field of `ComposeModulesOptions`
+ * and has never called the loader.
+ *
+ * @see `backend/src/overlay/divergence-loader.ts` — the half that reads the disk.
+ */
+import { DeploymentDivergenceDeclarationSchema, } from '@endora-commerce/contracts';
+/** A declaration that declares nothing — an absent file's answer, as data. */
+export function emptyDivergenceDeclaration() {
+    return { omittedModules: [], decorationOrder: {}, reasons: {} };
+}
+/**
+ * A declaration is only a declaration if each entry carries its reason.
+ *
+ * Exported and pure so the shape rules have a proof that does not need a
+ * deployment on disk: a fixture enters here as the raw exported value, which is
+ * the top of this analysis rather than something the loader already computed.
+ *
+ * A field left out means *none of these*, which is the reading an absent file
+ * already gets; a field that is present and malformed is refused, naming the
+ * deployment's own file. An **array** is refused with the shape it should have
+ * had, because that is what every declaration in the tree looked like before
+ * D-205 and a client copying an older one deserves the sentence rather than
+ * `expected object, received array`.
+ *
+ * @param path the declaration's own location, as the caller wishes to name it
+ *   to its reader. It is prose in a refusal and nothing else — this function
+ *   neither composes it nor reads it, which is what lets the platform hold the
+ *   shape rule while the tree that owns `apps/` holds the layout.
+ */
+export function parseDivergenceDeclaration(value, path) {
+    if (Array.isArray(value)) {
+        throw new Error(`${path} must export \`divergence\` as an object — ` +
+            '{ omittedModules, decorationOrder, reasons }. It was an array, which is the shape ' +
+            'the declaration had while it carried omissions and nothing else (D-205); the ' +
+            'omissions move into `omittedModules` unchanged.');
+    }
+    const parsed = DeploymentDivergenceDeclarationSchema.safeParse(value);
+    if (!parsed.success) {
+        const detail = parsed.error.issues
+            .map((issue) => `${issue.path.join('.') || '(declaration)'}: ${issue.message}`)
+            .join('; ');
+        throw new Error(`${path} is not a declaration — ${detail}. An omission says which module this ` +
+            'deployment does not ship and what it does instead; the sentence is the review.');
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=divergence-declaration.js.map

package/dist/lifecycle/divergence-declaration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"divergence-declaration.js","sourceRoot":"","sources":["../../src/lifecycle/divergence-declaration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EACL,qCAAqC,GAEtC,MAAM,4BAA4B,CAAC;AAEpC,8EAA8E;AAC9E,MAAM,UAAU,0BAA0B;IACxC,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAc,EACd,IAAY;IAEZ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,6CAA6C;YAClD,oFAAoF;YACpF,+EAA+E;YAC/E,iDAAiD,CACpD,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,qCAAqC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACtE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,eAAe,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;aAC9E,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,2BAA2B,MAAM,uCAAuC;YAC7E,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/lifecycle/i18n/en.json

@@ -0,0 +1,4 @@
+{
+  "actions.openPlatformModules.label": "Modules",
+  "actions.openPlatformModules.description": "What this deployment offers, and what your business has switched on"
+}

package/dist/lifecycle/i18n/pl.json

@@ -0,0 +1,4 @@
+{
+  "actions.openPlatformModules.label": "Moduły",
+  "actions.openPlatformModules.description": "Co udostępnia ta instalacja i co Twoja firma ma włączone"
+}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `./lifecycle` — the platform's operator surface, and the third subpath that is
+ * **declared and not published** (`specs/115-lifecycle-container-move/`, D115-4;
+ * `contracts/operator-half.md` §5).
+ *
+ * ## Why it exists at all
+ *
+ * `_lifecycle` is one module whose sources sit in two artefacts. The manifest,
+ * the routes, the Commands, the orchestrator and eight services are in
+ * `packages/platform/src/lifecycle/`; the manifest registry, the divergence
+ * loader and the five `module:*` commands are still in the application. The
+ * application reaches the first half through twelve re-export shims, and each of
+ * those shims forwards to `../../../../packages/platform/dist/lifecycle/…` — a
+ * relative path into a sibling package's build output, which resolves in this
+ * checkout and in **no client instance**. `manifest-index.generated.ts` carries
+ * the same reach for `_lifecycle`'s manifest, which is the sharpest form of it:
+ * the artefact whose whole job is to register the modules a build ships cannot
+ * register `_lifecycle` anywhere but here.
+ *
+ * This barrel is the address those reaches are drained onto. It is one subpath
+ * for one surface, deliberately — a second, `./lifecycle/commands`, would be a
+ * second address for one thing, and a consumer that wants one symbol imports one
+ * symbol.
+ *
+ * ## The rule it carries: no module may name it, ever
+ *
+ * D-160.11 refused to make `_lifecycle` its own package on the ground that it
+ * would be *"a public API with one consumer forever"*. That is an argument
+ * against **publishing** a surface and not against giving it an address, which
+ * is the distinction this subpath is built on: it is declared by the `exports`
+ * map, so `node` and `tsc` resolve it for the host, its five entry points and
+ * the test kit, and it is carried by no *published* barrel, so
+ * `check:platform-surface` reports a module naming it as `host-internal-subpath`
+ * — with no change to that check, because `declaredSubpaths` is read off the
+ * manifest rather than written down.
+ *
+ * `PUBLISHED_SUBPATHS` therefore stays at five, and that is not an omission to
+ * be tidied later. `PlatformSurface.published` is keyed by target file with no
+ * subpath dimension, so a sixth entry there would publish
+ * `ModuleLifecycleOrchestrator` and `installGatingGraph` for a module's
+ * *relative* reach at those files too, and — the check reporting `violations=0`
+ * — would change nothing it prints. A blindness that arrives green.
+ *
+ * The rule the class encodes is one sentence: this surface **drives** the
+ * platform's own presence axis, so a module that could name it could install,
+ * uninstall, enable or disable its siblings. That is `./composition`'s reason
+ * with one noun changed.
+ *
+ * ## What is on it, and why exactly this
+ *
+ * Exactly the names a first-party source outside the platform imports through
+ * `@endora-commerce/platform/lifecycle`, and nothing else. It is a
+ * **consequence** rather than a ruling — unlike `./composition`, whose 27
+ * symbols D-160.14 names one by one — so writing the set down anywhere would be
+ * a derived fact copied into a second place (D-100).
+ * `test/unit/kernel/published-surface.test.ts` derives it from the consumers on
+ * every run and holds the two to each other in both directions: a name here
+ * that nobody imports is surface parked against a future need, and a name
+ * imported that is not here is a consumer that cannot compile.
+ *
+ * A symbol **graduates** to a public barrel in the merge request that first
+ * gives it a module-package production consumer, and leaves this one in the same
+ * merge request (§5, R5.5). Two homes would be two answers to "is this public
+ * API?". There is no such consumer today and none is anticipated.
+ *
+ * ## The population it was derived from until Phase 7, and why that ended
+ *
+ * The consumer rule could not be the rule while the application reached this
+ * surface through fifteen re-export shims: nothing outside the platform named
+ * the specifier, so the ratchet would have been green over nothing — issue
+ * #113's shape. What stood in its place was a *ledger*-derived rule. Each shim
+ * spells `export * from '<target>'`, so the application holds that file's whole
+ * namespace, and a reach could retire onto this barrel only if every name it
+ * yielded were here; the expected set was therefore a function of
+ * `RELATIVE_HOST_REACHES` and the fourteen files it named.
+ *
+ * Phase 3 gave the subpath its first consumers, Phase 5 and Phase 6 added the
+ * five command bodies and the two generated artefacts, and Phase 7 re-pointed
+ * the 112 reaches in `backend/test/**` and deleted the last nine shims. So the
+ * ledger derivation has no population left — no ledgered reach names a platform
+ * lifecycle file, and none will again, because the address exists — and 28
+ * names left with it: symbols that were here only because some shim's
+ * `export *` yielded them and that nobody had ever asked for by name.
+ * `routes.storefront.ts` and `commands/activation.commands.ts` were absent for
+ * that same reason all along.
+ */
+export { type OperatorResources, type OperatorRuntime, } from './commands/operator-runtime.js';
+export { runInstallCommand } from './commands/install.js';
+export { runUninstallCommand } from './commands/uninstall.js';
+export { runEnableCommand } from './commands/enable.js';
+export { runDisableCommand } from './commands/disable.js';
+export { runStatusCommand } from './commands/status.js';
+export { runInstanceOperatorCommand } from './commands/operator-entry.js';
+export { registerModule } from './backend.js';
+export { manifest } from './manifest.js';
+export { lifecycleModuleFromStaticEntries } from './plugin.js';
+export { registerLifecycleAdminRoutes, } from './routes.admin.js';
+export { LifecycleError, ModuleLifecycleOrchestrator, } from './services/orchestrator.js';
+export { LOCK_KEY } from './services/lock.js';
+export { ModuleDepGraph } from './services/dep-graph.js';
+export { acknowledgedPortEdgesFrom, gatingGraph, installGatingGraph, ModuleGatingGraph, nonBindingPortEdgesFrom, provideDefaultGatingManifests, type NonBindingPortEdge, } from './services/gating-graph.js';
+export { buildDeactivationLedger, deactivationConsequencesFor, type CrossModuleRead, type DeactivationLedger, type LedgerEntry, type UnassignedEdge, } from './services/deactivation-ledger.js';
+export { discoverManifests, folderNameFromPath, ManifestLoadError, type LoadedLifecycleParticipant, type LoadedManifestRegistry, } from './services/manifest-loader.js';
+export { deploymentShippedEntries, type ModuleIdClaimOrigin, } from './services/module-origin.js';
+export { assertNoModuleIdCollisions, moduleIdCollisions, ModuleIdCollisionError, type ModuleIdClaim, type ModuleIdCollision, } from './services/module-id-claims.js';
+export { coreManifestEntries, ManifestPathMissingError, resolveManifestEntries, type ManifestSources, type RegisteredManifestEntry, } from './manifest-registry.js';
+export { buildStaticRegistry } from './services/static-registry.js';
+export { emptyDivergenceDeclaration, parseDivergenceDeclaration, } from './divergence-declaration.js';
+export { assertLockedModulesPresent, bootConvergenceWarnings, firstBootInsertPopulation, loadModulePresence, ReducedDeploymentError, type ShippedModuleEntry, } from './services/presence-load.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAQH,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAkBxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAmB1E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,cAAc,EACd,2BAA2B,GAC5B,MAAM,4BAA4B,CAAC;AAOpC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAS9C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EACL,yBAAyB,EACzB,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,6BAA6B,EAC7B,KAAK,kBAAkB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,uBAAuB,EACvB,2BAA2B,EAC3B,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,wBAAwB,EACxB,KAAK,mBAAmB,GACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,gCAAgC,CAAC;AAMxC,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,uBAAuB,GAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAYpE,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,0BAA0B,EAK1B,uBAAuB,EACvB,yBAAyB,EACzB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,6BAA6B,CAAC"}