@endora-commerce/platform 0.100.0

package/dist/lifecycle/manifest-registry.js

@@ -0,0 +1,223 @@
+/**
+ * The manifest registry's **derivation** — the core entries, the origin field,
+ * the path refusal, the collision assembly and the three-way merge
+ * (`specs/115-lifecycle-container-move/`, D115-2;
+ * `contracts/operator-half.md` §3).
+ *
+ * ## Why it is here and its input is not
+ *
+ * All of this lived in `backend/src/lifecycle/registered-manifests.ts`, because
+ * its **input** does: the generated manifest index is a fact about one
+ * repository's tree, is bare core under every value of `DEPLOYMENT` (D-104), and
+ * an instance's is a different file (D-160.3). But *"which modules exist, which
+ * of them claim the same id, and where did each entry come from"* is platform
+ * logic, and it sat in the application only because the artefact that answers
+ * the first clause is the application's.
+ *
+ * So the index is a **parameter**, never a reach: {@link coreManifestEntries}
+ * takes the discovered array and {@link resolveManifestEntries} takes
+ * {@link ManifestSources}. That is `specs/110-instance-repository/` FR-014
+ * stated as a mechanism, and the precedent is one directory over —
+ * `services/gating-graph.ts`'s `provideDefaultGatingManifests` is the host
+ * installing a supplier the platform refuses to default, with a comment saying
+ * exactly why the platform cannot read the registry itself. What that comment
+ * did not do is apply the reasoning to the derivation, which is what this file
+ * is.
+ *
+ * A parameter rather than a supplier slot, and the distinction is R3.2's: a slot
+ * is right for a *fallback* most processes never need and that must refuse
+ * rather than default. "Which modules exist" is answered at import,
+ * deterministically, by whoever built the binding; a slot would make *"did
+ * anyone supply it, and when?"* a runtime question in the one file whose job is
+ * to have the answer.
+ *
+ * ## What is left in the application, and why it is twenty lines
+ *
+ * `backend/src/lifecycle/registered-manifests.ts` keeps its path and every name
+ * it exports, and binds three suppliers — the generated index, this deployment's
+ * overlay scan and this instance's installed packages. 121 files import that
+ * path; moving the *file* would be a 121-file rewrite whose entire content is a
+ * path, and moving the *derivation* is a one-file edit. An instance writes the
+ * same twenty lines against its own three answers, which it owns regardless.
+ */
+import { assertNoModuleIdCollisions, } from './services/module-id-claims.js';
+import { platformResidentManifestEntries } from './resident.js';
+function optionalExports(found) {
+    return {
+        ...(found.installHook ? { installHook: found.installHook } : {}),
+        ...(found.uninstallHook ? { uninstallHook: found.uninstallHook } : {}),
+        ...(found.lifecycleParticipant
+            ? { lifecycleParticipant: found.lifecycleParticipant }
+            : {}),
+        ...(found.cliCommands ? { cliCommands: found.cliCommands } : {}),
+        ...(found.recentActivity ? { recentActivity: found.recentActivity } : {}),
+    };
+}
+function entryFor(discovered, filePath) {
+    return {
+        manifest: discovered.manifest,
+        filePath,
+        // The generated index is bare core under every value of `DEPLOYMENT`
+        // (D-104), so every entry it carries is one this build ships — including a
+        // module that has become a workspace package, which the composer bakes in
+        // with a bare specifier (D-149).
+        origin: 'core',
+        ...optionalExports(discovered),
+    };
+}
+/** Raised when an index entry carries no location for the manifest it imported. */
+export class ManifestPathMissingError extends Error {
+    name = 'ManifestPathMissingError';
+}
+/**
+ * The core registry: every discovered module, with the location the generator
+ * recorded for it.
+ *
+ * The index has no deployment entry to filter out any more (D-104). It is a
+ * walk of the shared core tree and nothing else, whatever `DEPLOYMENT` is set
+ * to when it is generated — which is what makes the committed artefact mean the
+ * same thing in every environment, and what makes a stale one detectable
+ * (FR-004, issue #120).
+ *
+ * **The path is read, not computed** (feature 080, T041a). It used to be
+ * `join(MODULES_ROOT, entry.id, 'manifest.ts')` — a convention, holding for as
+ * long as every module sits at `backend/src/modules/<id>/`, and giving a
+ * confident wrong answer the moment one does not. There is no reader of
+ * `filePath` that does not take `dirname` of it and join a directory: the
+ * `_i18n` boot reconciler joins `bundlesDir`, the orchestrator hands the same
+ * directory to the install-time bundle load, and both **skip** a directory that
+ * is absent. So a packaged module would have loaded no bundle, rendered every
+ * command-palette label as its raw key, and reported nothing anywhere.
+ *
+ * An entry with no path is therefore refused rather than defaulted. There is no
+ * honest fallback: the only candidate is the convention that just stopped
+ * holding, and a registry that answers with a directory nobody verified is the
+ * failure this replaces. The type makes the field required, which is what stops
+ * a *new* emitter from omitting it; this refusal is for the older artefact — a
+ * committed index generated before the field existed, or a hand-edited one —
+ * which the type cannot reach because it was compiled against a different shape.
+ */
+export function coreManifestEntries(discovered) {
+    return discovered.map((entry) => {
+        const manifestPath = entry.manifestPath;
+        if (typeof manifestPath !== 'string' || manifestPath.length === 0) {
+            throw new ManifestPathMissingError(`[registered-manifests] the generated index entry for '${entry.id}' carries no ` +
+                `manifestPath. Every consumer takes dirname() of it to reach the module's own ` +
+                `directory — its i18n bundles above all — and there is no convention left to ` +
+                `guess one from, because a module may now live in a workspace package. ` +
+                `Regenerate the index: pnpm --filter backend run composer:generate`);
+        }
+        return entryFor(entry, manifestPath);
+    });
+}
+/**
+ * The **instance-resolved** manifest set = the core registry, PLUS every
+ * overlay module the active deployment ships (feature 057, D-104), PLUS every
+ * Endora module package installed in this instance's `node_modules` (feature
+ * 080, D-119/D-155).
+ *
+ * All three arrive through {@link ManifestSources}, each from the one
+ * implementation that discovers it. There used to be two overlay
+ * implementations: this function merged the generated index's overlay entries,
+ * `composition.ts` merged the runtime scan's, and the one under test was not
+ * the one that ran.
+ *
+ * Runtime discovery is not an optimisation, it is the only correct answer, and
+ * D-104's predicate gives it for both: an artefact is committed when its
+ * content is a fact about *the tree*, and resolved at runtime when it is a fact
+ * about *the process*. Which deployment this process runs as is one; which
+ * packages an operator installed into this instance is the other. For a
+ * bare-core build with nothing installed — every developer checkout and every
+ * test run — both discoveries come back empty and this returns the core
+ * registry unchanged (FR-008).
+ *
+ * ## Collisions: one rule, whoever the claimants are
+ *
+ * A module id claimed twice is **refused**, naming every claimant's file
+ * (T030c, D-155.7; widened to the overlay by feature 103, FR-004).
+ *
+ * The overlay half used to be answered differently — dropped with a `continue`,
+ * on the reading that a deployment shadowing a module it authored is what the
+ * overlay mechanism is for. File shadowing is retired (D-201), so that reading
+ * has nothing left to refer to, and it was never the whole answer anyway: this
+ * function dropped the manifest while `overlayModuleEntriesUnder` composed the
+ * module, so the deployment ran a module the resolved registry did not know
+ * about — no `module_registrations` row, no permission-catalogue entry, and its
+ * routes gated on the effective state of somebody else's module of the same id.
+ * Principle XVII defeated in silence.
+ *
+ * The refusal an overlay claim reaches is raised **before** this function sees
+ * it, inside the overlay scan, so that the composition path reaches the same
+ * rule without depending on a composition root calling this function first.
+ * What is left here is the claim set no single scan can assemble: core, the
+ * overlay and every installed package at once, so an operator with two bad
+ * packages has to run this only once.
+ */
+export async function resolveManifestEntries(sources) {
+    const overlay = await sources.overlay();
+    const packages = await sources.packages();
+    const byId = new Map(sources.core.map((entry) => [entry.manifest.id, entry]));
+    // The platform's own resident modules (`specs/110-instance-repository/` T141).
+    // `_lifecycle`'s sources are this package's, so the only tree that could name
+    // it is one carrying a generated index — and an instance carries none, which
+    // is what left every instance refusing its own boot with
+    // `not-shipped: _lifecycle`, needed by five modules of the set the scaffolder
+    // itself writes.
+    //
+    // **Only where the host did not name it**, and appended rather than seeded, so
+    // a host that does — this repository's generated index, through the
+    // host-internal subpath — keeps its own entry *and* its own order. A `set`
+    // over an existing key would keep the position and replace the value, which is
+    // a difference nothing here needs to make. It is deliberately absent from the
+    // claim set below for the same reason: two names for one module is not a
+    // collision and must not be reported as one.
+    for (const resident of platformResidentManifestEntries()) {
+        if (!byId.has(resident.manifest.id))
+            byId.set(resident.manifest.id, resident);
+    }
+    for (const found of overlay) {
+        byId.set(found.id, {
+            manifest: found.manifest,
+            filePath: found.filePath,
+            origin: 'overlay',
+            ...optionalExports(found),
+        });
+    }
+    // Every claim at once, so the refusal reports all of them rather than the
+    // first — an operator with two bad packages should have to run this once.
+    //
+    // Assembled from the three discoveries and **not** from `byId`, which is keyed
+    // by id: reading the claim set off it would be asking a map that has already
+    // resolved the collision whether there was one.
+    const claims = [
+        ...sources.core.map((entry) => ({
+            id: entry.manifest.id,
+            origin: entry.origin,
+            claimedBy: entry.filePath,
+        })),
+        ...overlay.map((found) => ({
+            id: found.id,
+            origin: 'overlay',
+            claimedBy: found.filePath,
+        })),
+    ];
+    for (const found of packages) {
+        claims.push({
+            id: found.id,
+            origin: 'package',
+            claimedBy: found.filePath,
+            name: found.packageName,
+        });
+    }
+    assertNoModuleIdCollisions(claims);
+    for (const found of packages) {
+        byId.set(found.id, {
+            manifest: found.manifest,
+            filePath: found.filePath,
+            origin: 'package',
+            ...optionalExports(found),
+        });
+    }
+    return [...byId.values()];
+}
+//# sourceMappingURL=manifest-registry.js.map

package/dist/lifecycle/manifest-registry.js.map

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

package/dist/lifecycle/manifest.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Bootstrap manifest for the lifecycle subsystem itself. Carries no
+ * dependencies and no settings — every other module's manifest is
+ * discovered relative to this sentinel entry.
+ */
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "uuid" | "text" | "textarea" | "select" | "radio" | "external" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/lifecycle/manifest.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsHnB,CAAC"}

package/dist/lifecycle/manifest.js

@@ -0,0 +1,121 @@
+import { defineModuleManifest } from '@endora-commerce/contracts';
+/**
+ * Bootstrap manifest for the lifecycle subsystem itself. Carries no
+ * dependencies and no settings — every other module's manifest is
+ * discovered relative to this sentinel entry.
+ */
+export const manifest = defineModuleManifest({
+    id: '_lifecycle',
+    name: 'Module Lifecycle',
+    description: 'Platform-internal subsystem that orchestrates install / uninstall / ' +
+        'enable / disable / status across every domain module.',
+    version: '1.0.0',
+    dependencies: [],
+    /**
+     * The one edge this subsystem resolves and cannot declare (issue #90).
+     *
+     * Its two admin surfaces — the API-interceptor screen and the module presence
+     * projection — are guarded by `auth`'s `requireAdmin` port, exactly as every
+     * other admin surface is. `dependencies` is the wrong home for it: that array
+     * drives the **install order**, and this is the sentinel manifest every other
+     * module's installation is recorded against, so ordering it after `auth` (and
+     * transitively `admin_roles`) would have those modules install before the
+     * registry that records an installation exists. With `auth` absent the gate
+     * refuses and these surfaces answer 503 exactly as every other admin route
+     * does — which is what the edge costs, said as a behaviour rather than as a
+     * claim about a lock the build re-derives on every run (D-100). It stayed
+     * invisible until `check-port-dependencies` learned to follow a module-local
+     * cradle alias.
+     */
+    acknowledgedDependencies: [
+        {
+            moduleId: 'auth',
+            port: 'requireAdmin',
+            reason: 'The lifecycle admin surfaces are guarded by requireAdmin like every other admin ' +
+                'surface, but this is the sentinel manifest the install order starts from: declaring ' +
+                'auth would install it, and admin_roles, before the registry that records an ' +
+                'installation. With auth absent the gate refuses and these surfaces answer 503, ' +
+                'exactly as every other admin route does.',
+        },
+    ],
+    /**
+     * The live datum on the deactivation-confirmation screen (owner ruling on
+     * D-96.5): how many people hold a second factor, read from `mfa` before an
+     * operator switches it off.
+     *
+     * Non-binding, and it has to be: this is the sentinel manifest the install
+     * order starts from, and a module that reports on every module's presence may
+     * not be made to depend on one of them. `mfa` is the most switchable module
+     * in the tree — a client security policy — and the whole point of this read
+     * is to inform the flip, not to refuse it.
+     */
+    nonBindingDependencies: [
+        {
+            moduleId: 'mfa',
+            name: 'mfaEnrolmentCountPort',
+            kind: 'degrades-without',
+            whenAbsent: 'The deactivation dialog renders every consequence except the number of users who ' +
+                'currently hold a second factor, which is shown as unavailable.',
+            reason: 'GET /api/v1/admin/modules/:id/deactivation-impact answers the one question the ' +
+                'consequence rows cannot: how many people this flip affects. The count is a read of ' +
+                '`mfa_enrolments`, which `mfa` owns, so it arrives through a port and never as a ' +
+                'query this module writes. The route decides `mfa`\'s presence before it resolves ' +
+                'anything — an already-off module has no dialog to render — and a read that fails ' +
+                'answers `null` rather than blocking the operator, because a number that could not ' +
+                'be fetched is not a reason to refuse a deactivation.',
+        },
+    ],
+    // Feature 074 (Constitution XVII), test C1 — reachability. The ground is the
+    // presence machinery itself: this module resolves every other module's two
+    // axes, owns the orchestrator that flips them and the Command the activation
+    // endpoint runs, so switched off there is no way back on for anything,
+    // including itself. That is a statement about what this module *is*, not
+    // about the screen it once hosted — D-36 moved the activation surface to
+    // `/platform/modules`, which belongs to no module, and the old circular
+    // argument went with it. The `_`-prefix rule is the structural second
+    // ground: `assertActivationRules` (`packages/contracts/src/modules.ts`)
+    // refuses any other activation form for a platform-internal id. The route
+    // exemption (`ctx.ungatedRoutes`, T125) is a separate mechanism and is not
+    // what this declaration rests on.
+    activation: {
+        nonDeactivatable: true,
+        reason: 'Owns the presence machinery and the activation switches themselves; switched off, ' +
+            'there is no way back on.',
+    },
+    i18n: { bundlesDir: 'i18n' },
+    /**
+     * Principle XVI. The screen that says what this deployment offers and what
+     * the business has switched on is reachable from ⌘K, not only from a nav
+     * entry buried under System — it is the surface an operator goes looking for
+     * precisely when something is missing and they cannot find the sidebar item
+     * for it, because the module owning it is off.
+     *
+     * One action, deliberately: the write is a per-module flip with no route of
+     * its own, so a palette entry per module would be a route dump.
+     */
+    actions: [
+        {
+            id: 'open-platform-modules',
+            labelKey: 'actions.openPlatformModules.label',
+            descriptionKey: 'actions.openPlatformModules.description',
+            icon: 'Boxes',
+            targetRoute: '/platform/modules',
+            requiredPermission: 'platform.modules.read',
+            keywords: ['modules', 'moduły', 'włącz', 'wyłącz', 'enable', 'disable', 'platform'],
+            weight: 300,
+        },
+    ],
+    permissions: [
+        {
+            code: 'platform.modules.read',
+            module: 'module_lifecycle',
+            label: 'View module lifecycle status',
+        },
+        {
+            code: 'platform.modules.activate',
+            module: 'module_lifecycle',
+            label: 'Switch modules on and off',
+        },
+    ],
+});
+//# sourceMappingURL=manifest.js.map

package/dist/lifecycle/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/lifecycle/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IAC3C,EAAE,EAAE,YAAY;IAChB,IAAI,EAAE,kBAAkB;IACxB,WAAW,EACT,sEAAsE;QACtE,uDAAuD;IACzD,OAAO,EAAE,OAAO;IAChB,YAAY,EAAE,EAAE;IAChB;;;;;;;;;;;;;;;OAeG;IACH,wBAAwB,EAAE;QACxB;YACE,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,cAAc;YACpB,MAAM,EACJ,kFAAkF;gBAClF,sFAAsF;gBACtF,8EAA8E;gBAC9E,iFAAiF;gBACjF,0CAA0C;SAC7C;KACF;IACD;;;;;;;;;;OAUG;IACH,sBAAsB,EAAE;QACtB;YACE,QAAQ,EAAE,KAAK;YACf,IAAI,EAAE,uBAAuB;YAC7B,IAAI,EAAE,kBAAkB;YACxB,UAAU,EACR,mFAAmF;gBACnF,gEAAgE;YAClE,MAAM,EACJ,iFAAiF;gBACjF,qFAAqF;gBACrF,kFAAkF;gBAClF,mFAAmF;gBACnF,mFAAmF;gBACnF,oFAAoF;gBACpF,sDAAsD;SACzD;KACF;IACD,6EAA6E;IAC7E,2EAA2E;IAC3E,6EAA6E;IAC7E,uEAAuE;IACvE,yEAAyE;IACzE,yEAAyE;IACzE,wEAAwE;IACxE,sEAAsE;IACtE,wEAAwE;IACxE,0EAA0E;IAC1E,2EAA2E;IAC3E,kCAAkC;IAClC,UAAU,EAAE;QACV,gBAAgB,EAAE,IAAI;QACtB,MAAM,EACJ,oFAAoF;YACpF,0BAA0B;KAC7B;IACD,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE;IAC5B;;;;;;;;;OASG;IACH,OAAO,EAAE;QACP;YACE,EAAE,EAAE,uBAAuB;YAC3B,QAAQ,EAAE,mCAAmC;YAC7C,cAAc,EAAE,yCAAyC;YACzD,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,mBAAmB;YAChC,kBAAkB,EAAE,uBAAuB;YAC3C,QAAQ,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC;YACnF,MAAM,EAAE,GAAG;SACZ;KACF;IACD,WAAW,EAAE;QACX;YACE,IAAI,EAAE,uBAAuB;YAC7B,MAAM,EAAE,kBAAkB;YAC1B,KAAK,EAAE,8BAA8B;SACtC;QACD;YACE,IAAI,EAAE,2BAA2B;YACjC,MAAM,EAAE,kBAAkB;YAC1B,KAAK,EAAE,2BAA2B;SACnC;KACF;CACF,CAAC,CAAC"}

package/dist/lifecycle/plugin.d.ts

@@ -0,0 +1,56 @@
+import type { EntityManager, MikroORM } from '@mikro-orm/postgresql';
+import type { Redis } from 'ioredis';
+import type { ModulePlugin } from '../http/server.js';
+import type { AuditPort } from '../kernel/ports/audit.js';
+import { ModuleLifecycleOrchestrator, type OrchestratorDeps } from './services/orchestrator.js';
+import type { ModuleRegistryCache } from '../kernel/lifecycle/registry-cache.js';
+import { buildStaticRegistry } from './services/static-registry.js';
+import type { LoadedManifestRegistry } from './services/manifest-loader.js';
+export interface LifecycleModuleDeps {
+    orm: MikroORM;
+    redis: Redis;
+    /** Subscriber-mode Redis client; ioredis requires a separate connection for pub/sub. */
+    redisSubscriber: Redis;
+    emFactory: () => EntityManager;
+    auditLog: AuditPort;
+    /**
+     * Either a pre-built registry (production composition root supplies the
+     * static one), or a manifest list the module composes itself.
+     *
+     * Since feature 080's T036a it also carries the lifecycle participants the
+     * orchestrator runs on every install and hard uninstall — see
+     * `OrchestratorDeps.registry`. The two reconcilers this interface used to
+     * forward are gone with it: they were services only a composition root could
+     * resolve, which is why the five `module:*` commands passed neither.
+     */
+    registry: LoadedManifestRegistry;
+    /**
+     * Who owns which migration, for `uninstall --hard` (feature 080, T033).
+     *
+     * Forwarded rather than computed: the merged answer depends on which
+     * extension packages this instance installed, which only a composition root
+     * knows. Omitted, the orchestrator answers from the committed core registry
+     * and refuses a hard uninstall it cannot enumerate — see `OrchestratorDeps`.
+     */
+    migrationOwnership?: OrchestratorDeps['migrationOwnership'];
+}
+export interface LifecycleModuleHandle {
+    orchestrator: ModuleLifecycleOrchestrator;
+    registryCache: ModuleRegistryCache;
+    registry: LoadedManifestRegistry;
+}
+export interface LifecycleModule {
+    /** Composition handle exposed to other modules and the test harness. */
+    handle: LifecycleModuleHandle;
+    /** Fastify plugin — registers the read-only admin endpoint (US4). */
+    plugin: ModulePlugin;
+}
+export declare function lifecycleModule(deps: LifecycleModuleDeps): LifecycleModule;
+/**
+ * Convenience factory for the production composition root: build the
+ * lifecycle module from a static list of manifest entries plus the
+ * cross-cutting deps. Other call sites (CLI scripts, tests) typically
+ * pass a `LoadedManifestRegistry` they already discovered.
+ */
+export declare function lifecycleModuleFromStaticEntries(deps: Omit<LifecycleModuleDeps, 'registry'>, entries: Parameters<typeof buildStaticRegistry>[0]): LifecycleModule;
+//# sourceMappingURL=plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/lifecycle/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,2BAA2B,EAC3B,KAAK,gBAAgB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,mBAAmB,EAAC,MAAM,uCAAuC,CAAC;AAIpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;IACb,wFAAwF;IACxF,eAAe,EAAE,KAAK,CAAC;IACvB,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;;;;;OASG;IACH,QAAQ,EAAE,sBAAsB,CAAC;IACjC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,gBAAgB,CAAC,oBAAoB,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,2BAA2B,CAAC;IAC1C,aAAa,EAAE,mBAAmB,CAAC;IACnC,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,MAAM,EAAE,qBAAqB,CAAC;IAC9B,qEAAqE;IACrE,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CA6C1E;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,EAC3C,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,GACjD,eAAe,CAKjB"}

package/dist/lifecycle/plugin.js

@@ -0,0 +1,59 @@
+import { ModuleLifecycleOrchestrator, } from './services/orchestrator.js';
+import { registryCache } from '../kernel/lifecycle/registry-cache.js';
+import { buildStaticRegistry } from './services/static-registry.js';
+export function lifecycleModule(deps) {
+    const orchestrator = new ModuleLifecycleOrchestrator({
+        orm: deps.orm,
+        redis: deps.redis,
+        em: deps.emFactory,
+        auditLog: deps.auditLog,
+        registry: deps.registry,
+        ...(deps.migrationOwnership ? { migrationOwnership: deps.migrationOwnership } : {}),
+    });
+    // Feature 072 (D-38) — what is left of the boot half: arming the pub/sub
+    // subscriber that keeps the loaded presence fresh.
+    //
+    // The load itself is gone from here, and that is the point. Loading at plugin
+    // attach means loading inside `buildServer`, i.e. after `composeApp()` has
+    // registered every module and run every boot hook — while eleven of those
+    // hooks resolve a gated port. `loadModulePresence()` now runs as a
+    // composition step before the first module registers; see
+    // `services/presence-load.ts`.
+    //
+    // Three things went with it:
+    //   - the first-boot reconciler, which is the load's first half;
+    //   - `registryCache.start`, split into `load()` (fatal, PostgreSQL) and
+    //     `watch()` (non-fatal, Redis);
+    //   - the resume-everything worker loop. It existed to undo the pauses a cold
+    //     cache caused at registration, and it iterated `enabledIds()` — the
+    //     platform axis alone — so it resumed the workers of a module the
+    //     operator had deactivated (a live Constitution XVII hole). With presence
+    //     loaded before composition, `defineModuleWorker` sees the true effective
+    //     state at registration and there is nothing to undo.
+    const plugin = async () => {
+        await registryCache.watch({
+            redisSubscriber: deps.redisSubscriber,
+            em: deps.emFactory,
+        });
+        // Feature 072 (T125) — the four route registrations moved to
+        // `backend.ts`, where they are declared through `ctx.ungatedRoutes` with
+        // the reason attached.
+    };
+    return {
+        handle: { orchestrator, registryCache, registry: deps.registry },
+        plugin,
+    };
+}
+/**
+ * Convenience factory for the production composition root: build the
+ * lifecycle module from a static list of manifest entries plus the
+ * cross-cutting deps. Other call sites (CLI scripts, tests) typically
+ * pass a `LoadedManifestRegistry` they already discovered.
+ */
+export function lifecycleModuleFromStaticEntries(deps, entries) {
+    return lifecycleModule({
+        ...deps,
+        registry: buildStaticRegistry(entries),
+    });
+}
+//# sourceMappingURL=plugin.js.map

package/dist/lifecycle/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/lifecycle/plugin.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,2BAA2B,GAE5B,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,aAAa,EACd,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AA6CpE,MAAM,UAAU,eAAe,CAAC,IAAyB;IACvD,MAAM,YAAY,GAAG,IAAI,2BAA2B,CAAC;QACnD,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,EAAE,EAAE,IAAI,CAAC,SAAS;QAClB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzD,CAAC,CAAC;IAE9B,yEAAyE;IACzE,mDAAmD;IACnD,EAAE;IACF,8EAA8E;IAC9E,2EAA2E;IAC3E,0EAA0E;IAC1E,mEAAmE;IACnE,0DAA0D;IAC1D,+BAA+B;IAC/B,EAAE;IACF,6BAA6B;IAC7B,iEAAiE;IACjE,yEAAyE;IACzE,oCAAoC;IACpC,8EAA8E;IAC9E,yEAAyE;IACzE,sEAAsE;IACtE,8EAA8E;IAC9E,8EAA8E;IAC9E,0DAA0D;IAC1D,MAAM,MAAM,GAAiB,KAAK,IAAI,EAAE;QACtC,MAAM,aAAa,CAAC,KAAK,CAAC;YACxB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,EAAE,EAAE,IAAI,CAAC,SAAS;SACnB,CAAC,CAAC;QAEH,6DAA6D;QAC7D,yEAAyE;QACzE,uBAAuB;IACzB,CAAC,CAAC;IAEF,OAAO;QACL,MAAM,EAAE,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE;QAChE,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAC9C,IAA2C,EAC3C,OAAkD;IAElD,OAAO,eAAe,CAAC;QACrB,GAAG,IAAI;QACP,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC;KACvC,CAAC,CAAC;AACL,CAAC"}