@tomflow/proflow-platform-cli 0.1.0

package/dist/src/install/environment.d.ts

@@ -0,0 +1,29 @@
+import { type NpmCommandRunner } from "../registry/index.ts";
+import { type SupportedWorkspacePackageManager } from "./package-manager.ts";
+export declare const PLATFORM_INSTALL_NODE_RANGE = ">=24.19.0";
+export type InstallerPreflightStatus = "READY" | "ACTION_REQUIRED" | "BLOCKED";
+export type InstallerFindingSeverity = "info" | "action" | "error";
+export interface InstallerFinding {
+    code: string;
+    severity: InstallerFindingSeverity;
+    message: string;
+}
+export interface InstallerEnvironmentPreflightResult {
+    contract: "deployment.installer-preflight.v1";
+    ok: boolean;
+    status: InstallerPreflightStatus;
+    workspaceRoot: string;
+    nodeVersion: string;
+    npmVersion?: string;
+    packageManager?: {
+        name: SupportedWorkspacePackageManager;
+        declared?: string;
+        version?: string;
+    };
+    registry?: string;
+    findings: InstallerFinding[];
+}
+export declare function preflightInstallerEnvironment(options: {
+    workspaceRoot: string;
+    runner?: NpmCommandRunner;
+}): Promise<InstallerEnvironmentPreflightResult>;

package/dist/src/install/environment.js

@@ -0,0 +1,226 @@
+import { constants } from "node:fs";
+import { access, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { PlatformError } from "../errors.js";
+import { versionSatisfies } from "../modules.js";
+import { resolveScopeRegistry, systemNpmRunner, } from "../registry/index.js";
+import { findExecutable, readWorkspacePackageManagerSelection, systemPackageCommandRunner, } from "./package-manager.js";
+export const PLATFORM_INSTALL_NODE_RANGE = ">=24.19.0";
+export async function preflightInstallerEnvironment(options) {
+    const runner = options.runner ?? systemNpmRunner();
+    const findings = [];
+    const nodeVersion = process.versions.node;
+    if (!versionSatisfies(nodeVersion, PLATFORM_INSTALL_NODE_RANGE)) {
+        findings.push({
+            code: "NODE_VERSION_UNSUPPORTED",
+            severity: "error",
+            message: `node ${nodeVersion} does not satisfy ${PLATFORM_INSTALL_NODE_RANGE}`,
+        });
+    }
+    else {
+        findings.push({
+            code: "NODE_VERSION_READY",
+            severity: "info",
+            message: `node ${nodeVersion} satisfies ${PLATFORM_INSTALL_NODE_RANGE}`,
+        });
+    }
+    const workspace = await inspectWorkspace(options.workspaceRoot);
+    findings.push(...workspace.findings);
+    let npmVersion;
+    if (!findExecutable("npm")) {
+        findings.push({
+            code: "NPM_UNAVAILABLE",
+            severity: "error",
+            message: "npm executable is not available on PATH",
+        });
+    }
+    else {
+        try {
+            const npm = await runner.run(["--version"], options.workspaceRoot);
+            npmVersion = npm.stdout.trim();
+            findings.push({
+                code: "NPM_READY",
+                severity: "info",
+                message: `npm ${npmVersion || "<unknown>"} is available`,
+            });
+        }
+        catch (error) {
+            findings.push(platformErrorFinding(error, "NPM_UNAVAILABLE"));
+        }
+    }
+    const packageManager = await readWorkspacePackageManagerSelection(options.workspaceRoot);
+    let packageManagerVersion;
+    if (packageManager === undefined) {
+        findings.push({
+            code: "PACKAGE_MANAGER_UNSUPPORTED",
+            severity: "action",
+            message: `unsupported packageManager declaration: ${workspace.packageManager ?? "<unknown>"}`,
+        });
+    }
+    else if (packageManager.name === "pnpm") {
+        if (!findExecutable("pnpm")) {
+            findings.push({
+                code: "PNPM_REQUIRED",
+                severity: "action",
+                message: `workspace declares ${packageManager.declared}; install/enable pnpm before applying package changes`,
+            });
+        }
+        else {
+            try {
+                const result = (await systemPackageCommandRunner().run("pnpm", ["--version"], options.workspaceRoot)).trim();
+                packageManagerVersion = result;
+                findings.push({
+                    code: "PNPM_READY",
+                    severity: "info",
+                    message: `pnpm ${result} is available for this workspace`,
+                });
+            }
+            catch (error) {
+                findings.push({
+                    code: "PNPM_REQUIRED",
+                    severity: "action",
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    else if (npmVersion !== undefined) {
+        packageManagerVersion = npmVersion;
+        findings.push({
+            code: "PACKAGE_MANAGER_READY",
+            severity: "info",
+            message: packageManager.declared === undefined
+                ? "workspace does not declare packageManager; npm will be used for bootstrap package operations"
+                : `workspace declares ${packageManager.declared}`,
+        });
+    }
+    let registry;
+    if (npmVersion !== undefined) {
+        try {
+            registry = await resolveScopeRegistry(options.workspaceRoot, runner);
+            await runner.run(["ping", "--json", "--prefer-online", `--registry=${registry}`], options.workspaceRoot);
+            findings.push({
+                code: "REGISTRY_READY",
+                severity: "info",
+                message: `npm registry is reachable: ${registry}`,
+            });
+        }
+        catch (error) {
+            findings.push(platformErrorFinding(error, "REGISTRY_UNAVAILABLE"));
+        }
+    }
+    const status = aggregateInstallerStatus(findings);
+    return {
+        contract: "deployment.installer-preflight.v1",
+        ok: status === "READY",
+        status,
+        workspaceRoot: options.workspaceRoot,
+        nodeVersion,
+        ...(npmVersion === undefined ? {} : { npmVersion }),
+        ...(packageManager === undefined
+            ? {}
+            : {
+                packageManager: {
+                    ...packageManager,
+                    ...(packageManagerVersion === undefined
+                        ? {}
+                        : { version: packageManagerVersion }),
+                },
+            }),
+        ...(registry === undefined ? {} : { registry }),
+        findings,
+    };
+}
+async function inspectWorkspace(workspaceRoot) {
+    const findings = [];
+    try {
+        const info = await stat(workspaceRoot);
+        if (!info.isDirectory()) {
+            return {
+                findings: [
+                    {
+                        code: "WORKSPACE_INVALID",
+                        severity: "error",
+                        message: `${workspaceRoot} is not a directory`,
+                    },
+                ],
+            };
+        }
+        await access(workspaceRoot, constants.R_OK | constants.W_OK);
+        findings.push({
+            code: "WORKSPACE_WRITABLE",
+            severity: "info",
+            message: `workspace is readable and writable: ${workspaceRoot}`,
+        });
+    }
+    catch {
+        return {
+            findings: [
+                {
+                    code: "WORKSPACE_NOT_WRITABLE",
+                    severity: "error",
+                    message: `workspace is missing or not writable: ${workspaceRoot}`,
+                },
+            ],
+        };
+    }
+    const manifestPath = join(workspaceRoot, "package.json");
+    try {
+        const raw = await readFile(manifestPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed))
+            throw new Error("package.json root is not an object");
+        const manifest = parsed;
+        findings.push({
+            code: "PACKAGE_JSON_READY",
+            severity: "info",
+            message: "workspace package.json is readable",
+        });
+        return {
+            ...(typeof manifest.packageManager === "string"
+                ? { packageManager: manifest.packageManager }
+                : {}),
+            findings,
+        };
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            findings.push({
+                code: "PACKAGE_JSON_CREATABLE",
+                severity: "info",
+                message: "workspace has no package.json; installer may create one before the first package mutation",
+            });
+            return { findings };
+        }
+        findings.push({
+            code: "PACKAGE_JSON_INVALID",
+            severity: "error",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return { findings };
+    }
+}
+function aggregateInstallerStatus(findings) {
+    if (findings.some((finding) => finding.severity === "error"))
+        return "BLOCKED";
+    if (findings.some((finding) => finding.severity === "action")) {
+        return "ACTION_REQUIRED";
+    }
+    return "READY";
+}
+function platformErrorFinding(error, fallbackCode) {
+    if (error instanceof PlatformError) {
+        return { code: error.code, severity: "error", message: error.message };
+    }
+    return {
+        code: fallbackCode,
+        severity: "error",
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMissingFile(error) {
+    return isRecord(error) && error.code === "ENOENT";
+}

package/dist/src/install/index.d.ts

@@ -0,0 +1,6 @@
+export { registryCandidateToBootstrapModule, selectBootstrapModules, } from "./bootstrap.ts";
+export type { InstallerEnvironmentPreflightResult, InstallerFinding, InstallerFindingSeverity, InstallerPreflightStatus, } from "./environment.ts";
+export { PLATFORM_INSTALL_NODE_RANGE, preflightInstallerEnvironment, } from "./environment.ts";
+export type { GenerateInstallDocInput, InstallDocInput, } from "./install.ts";
+export { generateInstallDoc, renderInstallDoc } from "./install.ts";
+export type { SupportedWorkspacePackageManager, WorkspacePackageManagerSelection, } from "./package-manager.ts";

package/dist/src/install/index.js

@@ -0,0 +1,3 @@
+export { registryCandidateToBootstrapModule, selectBootstrapModules, } from "./bootstrap.js";
+export { PLATFORM_INSTALL_NODE_RANGE, preflightInstallerEnvironment, } from "./environment.js";
+export { generateInstallDoc, renderInstallDoc } from "./install.js";

package/dist/src/install/install.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedModule } from "../contracts.ts";
+import type { WorkspacePaths } from "../paths.ts";
+export interface InstallDocInput {
+    modules: readonly ResolvedModule[];
+    config?: Record<string, Record<string, string>>;
+    now?: Date;
+}
+export interface GenerateInstallDocInput extends InstallDocInput {
+    paths: WorkspacePaths;
+}
+/**
+ * Renders the generated INSTALL document from the real selected module set:
+ * module refs/versions, machine/runtime requirements, secret-redacted config
+ * slots, external resources, effects, human actions, and the verification plan.
+ * No raw secret value may survive — config values are redacted by key, and the
+ * whole document is deep-redacted against every known raw secret value.
+ */
+export declare function renderInstallDoc(input: InstallDocInput): string;
+export declare function generateInstallDoc(input: GenerateInstallDocInput): Promise<string>;

package/dist/src/install/install.js

@@ -0,0 +1,131 @@
+import { writeInstallDoc } from "../persistence/index.js";
+import { resolveModuleConfig } from "../preflight/index.js";
+import { redactDeep, redactSecretValues } from "../security/index.js";
+function compareRef(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function requirementLine(moduleRef, requirement) {
+    switch (requirement.kind) {
+        case "runtime":
+            return `- \`${moduleRef}\`: runtime \`${requirement.runtime}\` ${requirement.versionRange}`;
+        case "executable":
+            return `- \`${moduleRef}\`: executable \`${requirement.command}\`${requirement.versionRange !== undefined
+                ? ` ${requirement.versionRange}`
+                : ""}`;
+        case "filesystem":
+            return `- \`${moduleRef}\`: filesystem \`${requirement.path}\` (${requirement.access})`;
+        case "port":
+            return `- \`${moduleRef}\`: port ${requirement.port}/${requirement.protocol}`;
+        case "network":
+            return `- \`${moduleRef}\`: network \`${requirement.url}\``;
+        case "module-contract":
+            return `- \`${moduleRef}\`: module-contract \`${requirement.contractRef}\` ${requirement.versionRange}`;
+        case "human":
+            return `- \`${moduleRef}\`: human — ${requirement.action}`;
+    }
+}
+function collectRawSecrets(modules, config) {
+    const secrets = [];
+    for (const module of modules) {
+        const resolved = resolveModuleConfig(module, config?.[module.moduleRef]);
+        const sensitiveKeys = new Set(module.configSlots
+            .filter((slot) => slot.sensitive === true && slot.type !== "secretRef")
+            .map((slot) => slot.key));
+        for (const [key, value] of Object.entries(resolved.values)) {
+            if (sensitiveKeys.has(key) && value.length > 0)
+                secrets.push(value);
+        }
+    }
+    return secrets;
+}
+/**
+ * Renders the generated INSTALL document from the real selected module set:
+ * module refs/versions, machine/runtime requirements, secret-redacted config
+ * slots, external resources, effects, human actions, and the verification plan.
+ * No raw secret value may survive — config values are redacted by key, and the
+ * whole document is deep-redacted against every known raw secret value.
+ */
+export function renderInstallDoc(input) {
+    const generatedAt = (input.now ?? new Date()).toISOString();
+    const modules = [...input.modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
+    const lines = [];
+    lines.push("# ProFlow Deployment — Generated INSTALL");
+    lines.push("");
+    lines.push(`> Generated at ${generatedAt}. Regenerated by \`platform manifest\`.`);
+    lines.push("");
+    lines.push("## Selected Module Set");
+    lines.push("");
+    for (const module of modules) {
+        lines.push(`- \`${module.moduleRef}\` (\`${module.packageName}@${module.moduleVersion}\`, kind: \`${module.kind}\`)`);
+    }
+    lines.push("");
+    lines.push("## Requirements");
+    lines.push("");
+    for (const module of modules) {
+        for (const requirement of module.requirements) {
+            lines.push(requirementLine(module.moduleRef, requirement));
+        }
+    }
+    lines.push("");
+    lines.push("## Config Slots");
+    lines.push("");
+    for (const module of modules) {
+        const resolved = resolveModuleConfig(module, input.config?.[module.moduleRef]);
+        const values = redactSecretValues(resolved.values, resolved.secretRefs);
+        for (const slot of module.configSlots) {
+            const value = values[slot.key];
+            const suffix = value !== undefined ? ` = \`${value}\`` : "";
+            const required = slot.required ? " (required)" : "";
+            lines.push(`- \`${module.moduleRef}\`.\`${slot.key}\` [${slot.type}]${required}${suffix}`);
+        }
+    }
+    lines.push("");
+    const external = modules.filter((module) => module.kind === "external-resource");
+    if (external.length > 0) {
+        lines.push("## External Resources");
+        lines.push("");
+        for (const module of external) {
+            lines.push(`- \`${module.moduleRef}\` (\`${module.packageName}@${module.moduleVersion}\`)`);
+        }
+        lines.push("");
+    }
+    lines.push("## Effects");
+    lines.push("");
+    for (const module of modules) {
+        for (const effect of module.effects) {
+            lines.push(`- \`${module.moduleRef}\`: [${effect.kind}] ${effect.description}`);
+        }
+    }
+    lines.push("");
+    const humanActions = modules.flatMap((module) => module.requirements
+        .filter((requirement) => requirement.kind === "human")
+        .map((requirement) => ({
+        moduleRef: module.moduleRef,
+        action: requirement.action,
+    })));
+    if (humanActions.length > 0) {
+        lines.push("## Human Actions");
+        lines.push("");
+        for (const action of humanActions) {
+            lines.push(`- \`${action.moduleRef}\`: ${action.action}`);
+        }
+        lines.push("");
+    }
+    lines.push("## Verification Plan");
+    lines.push("");
+    for (const module of modules) {
+        for (const verificationCheck of module.verification.checks) {
+            lines.push(`- \`${module.moduleRef}\`: \`${verificationCheck.id}\` (${verificationCheck.lifecycle}) — ${verificationCheck.description}`);
+        }
+    }
+    const content = `${lines.join("\n")}\n`;
+    // defense-in-depth: deep-redact every raw secret value wherever it appears
+    const rawSecrets = collectRawSecrets(modules, input.config);
+    const redacted = redactDeep(content, rawSecrets);
+    return typeof redacted === "string" ? redacted : content;
+}
+export async function generateInstallDoc(input) {
+    const content = renderInstallDoc(input);
+    await writeInstallDoc(input.paths, content);
+    return content;
+}

package/dist/src/install/package-manager.d.ts

@@ -0,0 +1,11 @@
+export type SupportedWorkspacePackageManager = "npm" | "pnpm";
+export interface WorkspacePackageManagerSelection {
+    name: SupportedWorkspacePackageManager;
+    declared?: string;
+}
+export interface PackageCommandRunner {
+    run(command: string, args: readonly string[], cwd: string): Promise<string>;
+}
+export declare function systemPackageCommandRunner(): PackageCommandRunner;
+export declare function readWorkspacePackageManagerSelection(workspaceRoot: string): Promise<WorkspacePackageManagerSelection | undefined>;
+export declare function findExecutable(command: string): boolean;

package/dist/src/install/package-manager.js

@@ -0,0 +1,58 @@
+import { execFile } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export function systemPackageCommandRunner() {
+    return {
+        async run(command, args, cwd) {
+            const result = await execFileAsync(command, [...args], {
+                cwd,
+                encoding: "utf8",
+                maxBuffer: 4 * 1024 * 1024,
+            });
+            return result.stdout;
+        },
+    };
+}
+export async function readWorkspacePackageManagerSelection(workspaceRoot) {
+    let declared;
+    try {
+        const raw = await readFile(join(workspaceRoot, "package.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        if (isRecord(parsed) && typeof parsed.packageManager === "string") {
+            declared = parsed.packageManager;
+        }
+    }
+    catch {
+        // A Fresh Workspace without package.json uses npm for bootstrap. Invalid
+        // package.json is rejected earlier by installer preflight.
+    }
+    if (declared === undefined)
+        return { name: "npm" };
+    const separator = declared.lastIndexOf("@");
+    const name = separator > 0 ? declared.slice(0, separator) : declared;
+    if (name !== "npm" && name !== "pnpm")
+        return undefined;
+    return { name, declared };
+}
+export function findExecutable(command) {
+    const path = process.env.PATH ?? "";
+    const suffixes = process.platform === "win32" ? [".cmd", ".exe", ""] : [""];
+    for (const directory of path.split(delimiter).filter(Boolean)) {
+        for (const suffix of suffixes) {
+            try {
+                accessSync(join(directory, `${command}${suffix}`), constants.X_OK);
+                return true;
+            }
+            catch {
+                // keep scanning PATH
+            }
+        }
+    }
+    return false;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/lifecycle/dispatch.d.ts

@@ -0,0 +1,47 @@
+import { type LifecyclePrimitive, type ModuleOperationResult } from "@tomflow/proflow-module-contract";
+import type { ResolvedModule } from "../contracts.ts";
+import type { ModuleCatalog } from "../modules.ts";
+export interface LifecycleDispatchResult {
+    moduleRef: string;
+    primitive: LifecyclePrimitive;
+    result: ModuleOperationResult;
+    observedEffects: string[];
+}
+export type LifecycleRunStatus = "EXECUTED" | "SKIP_UNSUPPORTED";
+export interface LifecycleRunResult {
+    moduleRef: string;
+    primitive: LifecyclePrimitive;
+    status: LifecycleRunStatus;
+    result: ModuleOperationResult | undefined;
+    observedEffects: string[];
+}
+/**
+ * Dispatches a single lifecycle primitive against one module through its
+ * public deployment adapter. The descriptor is the source of truth for what is
+ * supported: a primitive not declared in `lifecycle` is rejected with
+ * `LIFECYCLE_UNSUPPORTED` rather than faked. The adapter result is always
+ * runtime-validated against the Module Operation Result schema.
+ */
+export declare function dispatchLifecycle(catalog: ModuleCatalog, module: ResolvedModule, primitive: LifecyclePrimitive): Promise<LifecycleDispatchResult>;
+/**
+ * Starts a module set in forward dependency topological order, dispatching the
+ * `start` primitive only to modules that declare it.
+ */
+export declare function startModules(catalog: ModuleCatalog, modules: readonly ResolvedModule[]): Promise<LifecycleRunResult[]>;
+/**
+ * Stops a module set in reverse dependency topological order, dispatching the
+ * `stop` primitive only to modules that declare it.
+ */
+export declare function stopModules(catalog: ModuleCatalog, modules: readonly ResolvedModule[]): Promise<LifecycleRunResult[]>;
+/**
+ * Restarts a module set in forward dependency topological order, dispatching
+ * `restart` only to modules that explicitly declare it. Dependencies are
+ * settled before the modules that consume them.
+ */
+export declare function restartModules(catalog: ModuleCatalog, modules: readonly ResolvedModule[]): Promise<LifecycleRunResult[]>;
+/**
+ * Queries current reality by dispatching the `status` primitive to every
+ * module that declares it. Status is always read live from the adapter; no
+ * persisted or cached value is substituted for current reality.
+ */
+export declare function statusModules(catalog: ModuleCatalog, modules: readonly ResolvedModule[]): Promise<LifecycleRunResult[]>;

package/dist/src/lifecycle/dispatch.js

@@ -0,0 +1,142 @@
+import { moduleOperationResultSchema, } from "@tomflow/proflow-module-contract";
+import { PlatformError } from "../errors.js";
+import { buildDependencyGraph } from "../graph/graph.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isPrimitiveFn(value) {
+    return typeof value === "function";
+}
+function isWrappedResult(value) {
+    return isRecord(value) && "result" in value;
+}
+function moduleSource(module) {
+    if (module.source.type === "registry") {
+        throw new PlatformError("DESCRIPTOR_INVALID", `registry bootstrap target ${module.packageName} has no local lifecycle adapter`);
+    }
+    const source = {
+        type: module.source.type,
+        packageName: module.packageName,
+    };
+    if (module.source.path !== undefined)
+        source.path = module.source.path;
+    return source;
+}
+function resolveBehaviorAdapter(namespace) {
+    if (!isRecord(namespace)) {
+        throw new PlatformError("COMMAND_FAILED", "lifecycle adapter namespace is not an object");
+    }
+    const behaviorAdapter = namespace.behaviorAdapter;
+    if (!isRecord(behaviorAdapter)) {
+        throw new PlatformError("COMMAND_FAILED", "lifecycle adapter exposes no behaviorAdapter object");
+    }
+    return behaviorAdapter;
+}
+function observedEffectsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+function normalizeInvocation(raw) {
+    if (isWrappedResult(raw)) {
+        return {
+            result: raw.result,
+            observedEffects: observedEffectsOf(raw.observedEffects),
+        };
+    }
+    return { result: raw, observedEffects: [] };
+}
+/**
+ * Dispatches a single lifecycle primitive against one module through its
+ * public deployment adapter. The descriptor is the source of truth for what is
+ * supported: a primitive not declared in `lifecycle` is rejected with
+ * `LIFECYCLE_UNSUPPORTED` rather than faked. The adapter result is always
+ * runtime-validated against the Module Operation Result schema.
+ */
+export async function dispatchLifecycle(catalog, module, primitive) {
+    if (!module.lifecycle.includes(primitive)) {
+        throw new PlatformError("LIFECYCLE_UNSUPPORTED", `module ${module.moduleRef} does not declare lifecycle primitive "${primitive}"`);
+    }
+    const namespace = await catalog.loadAdapter(moduleSource(module));
+    const adapter = resolveBehaviorAdapter(namespace);
+    const invoke = adapter[primitive];
+    if (!isPrimitiveFn(invoke)) {
+        throw new PlatformError("COMMAND_FAILED", `module ${module.moduleRef} declares "${primitive}" but its adapter does not implement it`);
+    }
+    const { result, observedEffects } = normalizeInvocation(await invoke());
+    const parsed = moduleOperationResultSchema.safeParse(result);
+    if (!parsed.success) {
+        throw new PlatformError("COMMAND_FAILED", `module ${module.moduleRef} "${primitive}" returned an invalid result: ${parsed.error.message}`);
+    }
+    return {
+        moduleRef: module.moduleRef,
+        primitive,
+        result: parsed.data,
+        observedEffects,
+    };
+}
+async function runOne(catalog, module, primitive) {
+    if (!module.lifecycle.includes(primitive)) {
+        return {
+            moduleRef: module.moduleRef,
+            primitive,
+            status: "SKIP_UNSUPPORTED",
+            result: undefined,
+            observedEffects: [],
+        };
+    }
+    const dispatched = await dispatchLifecycle(catalog, module, primitive);
+    return {
+        moduleRef: dispatched.moduleRef,
+        primitive,
+        status: "EXECUTED",
+        result: dispatched.result,
+        observedEffects: dispatched.observedEffects,
+    };
+}
+async function runInOrder(catalog, modules, order, primitive) {
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const results = [];
+    for (const moduleRef of order) {
+        const module = byRef.get(moduleRef);
+        if (module === undefined)
+            continue;
+        results.push(await runOne(catalog, module, primitive));
+    }
+    return results;
+}
+/**
+ * Starts a module set in forward dependency topological order, dispatching the
+ * `start` primitive only to modules that declare it.
+ */
+export async function startModules(catalog, modules) {
+    return runInOrder(catalog, modules, buildDependencyGraph(modules).order, "start");
+}
+/**
+ * Stops a module set in reverse dependency topological order, dispatching the
+ * `stop` primitive only to modules that declare it.
+ */
+export async function stopModules(catalog, modules) {
+    const order = [...buildDependencyGraph(modules).order].reverse();
+    return runInOrder(catalog, modules, order, "stop");
+}
+/**
+ * Restarts a module set in forward dependency topological order, dispatching
+ * `restart` only to modules that explicitly declare it. Dependencies are
+ * settled before the modules that consume them.
+ */
+export async function restartModules(catalog, modules) {
+    return runInOrder(catalog, modules, buildDependencyGraph(modules).order, "restart");
+}
+/**
+ * Queries current reality by dispatching the `status` primitive to every
+ * module that declares it. Status is always read live from the adapter; no
+ * persisted or cached value is substituted for current reality.
+ */
+export async function statusModules(catalog, modules) {
+    const results = [];
+    for (const module of modules) {
+        results.push(await runOne(catalog, module, "status"));
+    }
+    return results;
+}