@tomflow/proflow-platform-cli 0.1.0

package/dist/src/observer/deployment-summary.js

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+import { atomicWrite } from "../paths.js";
+function stateOf(statuses) {
+    if (statuses.includes("FAILED") || statuses.includes("BLOCKED"))
+        return "NOT_READY";
+    if (statuses.includes("ACTION_REQUIRED"))
+        return "ACTION_REQUIRED";
+    return statuses.length === 0 ? "NOT_READY" : "READY";
+}
+export const DEPLOYMENT_OBSERVER_SUMMARY_TTL_MS = 60_000;
+export async function writeDeploymentObserverSummary(input) {
+    const modules = [...input.modules].sort((a, b) => a.moduleRef.localeCompare(b.moduleRef));
+    const observedAt = new Date();
+    const isCompletePlatformObservation = input.selectedModuleCount === input.totalModuleCount &&
+        modules.length === input.totalModuleCount;
+    const summary = {
+        contract: "proflow.deployment-observer-summary.v1",
+        scope: "PLATFORM",
+        source: input.source,
+        state: isCompletePlatformObservation
+            ? stateOf(modules.map((item) => item.status))
+            : "NOT_READY",
+        selectedModuleCount: input.selectedModuleCount,
+        totalModuleCount: input.totalModuleCount,
+        observedModuleCount: modules.length,
+        blockingModuleCount: modules.filter((item) => item.status !== "SUCCEEDED")
+            .length,
+        modules,
+        observedAt: observedAt.toISOString(),
+        freshUntil: new Date(observedAt.getTime() + DEPLOYMENT_OBSERVER_SUMMARY_TTL_MS).toISOString(),
+    };
+    await atomicWrite(join(input.paths.deployment, "observer-summary.json"), `${JSON.stringify(summary, null, 2)}\n`);
+    return summary;
+}

package/dist/src/paths.d.ts

@@ -0,0 +1,21 @@
+export interface WorkspacePaths {
+    root: string;
+    proflow: string;
+    config: string;
+    data: string;
+    logs: string;
+    logsDeployment: string;
+    runtime: string;
+    cache: string;
+    tmp: string;
+    deployment: string;
+    stateJson: string;
+    plans: string;
+    verification: string;
+    generated: string;
+    installMd: string;
+}
+export declare function workspacePaths(root: string): WorkspacePaths;
+export declare function ensureLayout(paths: WorkspacePaths): Promise<void>;
+export declare function atomicWrite(file: string, content: string): Promise<void>;
+export declare function readJson<T>(file: string): Promise<T | undefined>;

package/dist/src/paths.js

@@ -0,0 +1,56 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export function workspacePaths(root) {
+    const proflow = join(root, ".proflow");
+    const deployment = join(proflow, "deployment");
+    return {
+        root,
+        proflow,
+        config: join(proflow, "config"),
+        data: join(proflow, "data"),
+        logs: join(proflow, "logs"),
+        logsDeployment: join(proflow, "logs", "deployment"),
+        runtime: join(proflow, "runtime"),
+        cache: join(proflow, "cache"),
+        tmp: join(proflow, "tmp"),
+        deployment,
+        stateJson: join(deployment, "state.json"),
+        plans: join(deployment, "plans"),
+        verification: join(deployment, "verification"),
+        generated: join(deployment, "generated"),
+        installMd: join(deployment, "generated", "INSTALL.md"),
+    };
+}
+export async function ensureLayout(paths) {
+    for (const dir of [
+        paths.config,
+        paths.data,
+        paths.logsDeployment,
+        paths.runtime,
+        paths.cache,
+        paths.tmp,
+        paths.plans,
+        paths.verification,
+        paths.generated,
+    ]) {
+        await mkdir(dir, { recursive: true });
+    }
+}
+// Atomic write: bounded write to a temp sibling then rename into place.
+export async function atomicWrite(file, content) {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${randomBytes(6).toString("hex")}`;
+    await writeFile(tmp, content, "utf8");
+    await rename(tmp, file);
+}
+export async function readJson(file) {
+    try {
+        const { readFile } = await import("node:fs/promises");
+        const raw = await readFile(file, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/persistence/atomic.d.ts

@@ -0,0 +1,2 @@
+export declare function writeFileAtomic(file: string, content: string, mode?: number): Promise<void>;
+export declare function writeJsonAtomic(file: string, value: unknown, mode?: number): Promise<void>;

package/dist/src/persistence/atomic.js

@@ -0,0 +1,16 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+// Mode-aware atomic write: bounded write to a temp sibling, then rename into
+// place. This is an enhancement of paths.atomicWrite that pins an explicit file
+// mode (e.g. 0o600 for secret-bearing materialization) independent of umask.
+export async function writeFileAtomic(file, content, mode = 0o644) {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${randomBytes(6).toString("hex")}`;
+    await writeFile(tmp, content, { encoding: "utf8", mode });
+    await chmod(tmp, mode);
+    await rename(tmp, file);
+}
+export async function writeJsonAtomic(file, value, mode = 0o644) {
+    await writeFileAtomic(file, `${JSON.stringify(value, null, 2)}\n`, mode);
+}

package/dist/src/persistence/config.d.ts

@@ -0,0 +1,12 @@
+import { type WorkspacePaths } from "../paths.ts";
+export interface MaterializedConfig {
+    publicValues: Record<string, string>;
+    secretValues: Record<string, string>;
+}
+export interface ModuleConfig {
+    moduleRef: string;
+    values: Record<string, string>;
+    secretRefs: readonly string[];
+}
+export declare function materializeConfig(paths: WorkspacePaths, config: ModuleConfig): Promise<void>;
+export declare function loadConfig(paths: WorkspacePaths, moduleRef: string): Promise<MaterializedConfig | undefined>;

package/dist/src/persistence/config.js

@@ -0,0 +1,43 @@
+import { join } from "node:path";
+import { readJson } from "../paths.js";
+import { writeJsonAtomic } from "./atomic.js";
+import { assertSafeFileName } from "./guards.js";
+function configFilePath(paths, moduleRef) {
+    assertSafeFileName(moduleRef, "moduleRef");
+    return join(paths.config, `${moduleRef}.json`);
+}
+function secretsFilePath(paths, moduleRef) {
+    assertSafeFileName(moduleRef, "moduleRef");
+    return join(paths.config, `${moduleRef}.secrets.json`);
+}
+function isStringMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    return Object.values(value).every((item) => typeof item === "string");
+}
+// secretRef config values are opaque reference identities (e.g.
+// `secret://model-provider/default`), not raw secrets, so they materialize to
+// the public config file verbatim. A raw secret would go to the separate 0o600
+// secrets file — but v1 planning produces no raw secrets, so it stays empty and
+// must never hold a secretRef reference.
+export async function materializeConfig(paths, config) {
+    const publicValues = {};
+    for (const [key, value] of Object.entries(config.values)) {
+        publicValues[key] = value;
+    }
+    await writeJsonAtomic(configFilePath(paths, config.moduleRef), publicValues, 0o644);
+    await writeJsonAtomic(secretsFilePath(paths, config.moduleRef), {}, 0o600);
+}
+export async function loadConfig(paths, moduleRef) {
+    const publicRaw = await readJson(configFilePath(paths, moduleRef));
+    const secretRaw = await readJson(secretsFilePath(paths, moduleRef));
+    const publicValues = isStringMap(publicRaw) ? publicRaw : undefined;
+    const secretValues = isStringMap(secretRaw) ? secretRaw : undefined;
+    if (publicValues === undefined && secretValues === undefined)
+        return undefined;
+    return {
+        publicValues: publicValues ?? {},
+        secretValues: secretValues ?? {},
+    };
+}

package/dist/src/persistence/generated.d.ts

@@ -0,0 +1,2 @@
+import type { WorkspacePaths } from "../paths.ts";
+export declare function writeInstallDoc(paths: WorkspacePaths, content: string): Promise<void>;

package/dist/src/persistence/generated.js

@@ -0,0 +1,4 @@
+import { writeFileAtomic } from "./atomic.js";
+export async function writeInstallDoc(paths, content) {
+    await writeFileAtomic(paths.installMd, content, 0o644);
+}

package/dist/src/persistence/guards.d.ts

@@ -0,0 +1,7 @@
+import type { DeploymentPlan, DeploymentState, LockRecord, VerificationRecord } from "../contracts.ts";
+export declare const DEPLOYMENT_STATE_CONTRACT = "proflow.deployment-state.v1";
+export declare function assertSafeFileName(name: string, kind: string): void;
+export declare function isDeploymentState(value: unknown): value is DeploymentState;
+export declare function isVerificationRecord(value: unknown): value is VerificationRecord;
+export declare function isDeploymentPlan(value: unknown): value is DeploymentPlan;
+export declare function isLockRecord(value: unknown): value is LockRecord;

package/dist/src/persistence/guards.js

@@ -0,0 +1,120 @@
+import { PlatformError } from "../errors.js";
+export const DEPLOYMENT_STATE_CONTRACT = "proflow.deployment-state.v1";
+const SAFE_FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function assertSafeFileName(name, kind) {
+    if (!SAFE_FILE_NAME.test(name)) {
+        throw new PlatformError("INVALID_REQUEST", `invalid ${kind} name: ${name}`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(isString);
+}
+function isDeploymentIntent(value) {
+    return (value === "install" ||
+        value === "configure" ||
+        value === "upgrade" ||
+        value === "repair");
+}
+function isSelectedModuleFact(value) {
+    return (isRecord(value) &&
+        isString(value.moduleRef) &&
+        isString(value.moduleVersion));
+}
+function isLastAppliedPlan(value) {
+    return (isRecord(value) &&
+        isString(value.planRef) &&
+        isDeploymentIntent(value.intent) &&
+        isString(value.appliedAt));
+}
+function isVerificationIndexEntry(value) {
+    return (isRecord(value) && isString(value.moduleRef) && isString(value.latestRef));
+}
+function isPendingAction(value) {
+    return (isRecord(value) &&
+        isString(value.planRef) &&
+        isString(value.stepRef) &&
+        isString(value.moduleRef) &&
+        isString(value.action) &&
+        (value.description === undefined || isString(value.description)) &&
+        isString(value.createdAt));
+}
+export function isDeploymentState(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.contract !== DEPLOYMENT_STATE_CONTRACT)
+        return false;
+    if (!Array.isArray(value.selectedModules))
+        return false;
+    if (!value.selectedModules.every(isSelectedModuleFact))
+        return false;
+    if (!Array.isArray(value.lastAppliedPlans))
+        return false;
+    if (!value.lastAppliedPlans.every(isLastAppliedPlan))
+        return false;
+    if (!Array.isArray(value.verificationIndex))
+        return false;
+    if (!value.verificationIndex.every(isVerificationIndexEntry))
+        return false;
+    if (!Array.isArray(value.pendingActions))
+        return false;
+    if (!value.pendingActions.every(isPendingAction))
+        return false;
+    return isString(value.updatedAt);
+}
+export function isVerificationRecord(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isString(value.verificationRef))
+        return false;
+    if (!isString(value.moduleRef))
+        return false;
+    if (!isString(value.moduleVersion))
+        return false;
+    if (value.resourceIdentity !== undefined && !isString(value.resourceIdentity))
+        return false;
+    if (value.resourceVersion !== undefined && !isString(value.resourceVersion))
+        return false;
+    if (value.result !== "PASS" && value.result !== "FAIL")
+        return false;
+    if (!isString(value.summary))
+        return false;
+    if (!isStringArray(value.evidenceRefs))
+        return false;
+    return isString(value.verifiedAt);
+}
+export function isDeploymentPlan(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isString(value.planRef))
+        return false;
+    if (!isDeploymentIntent(value.intent))
+        return false;
+    if (!Array.isArray(value.moduleTargets))
+        return false;
+    if (!Array.isArray(value.resolvedModules))
+        return false;
+    if (!Array.isArray(value.steps))
+        return false;
+    if (!Array.isArray(value.effects))
+        return false;
+    if (!Array.isArray(value.humanActions))
+        return false;
+    if (!Array.isArray(value.verification))
+        return false;
+    if (!isString(value.fingerprint))
+        return false;
+    return isString(value.createdAt);
+}
+export function isLockRecord(value) {
+    return (isRecord(value) &&
+        typeof value.pid === "number" &&
+        isString(value.createdAt) &&
+        isString(value.planRef) &&
+        isString(value.workspaceFingerprint));
+}

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

@@ -0,0 +1,6 @@
+export type { MaterializedConfig, ModuleConfig } from "./config.ts";
+export { loadConfig, materializeConfig } from "./config.ts";
+export { writeInstallDoc } from "./generated.ts";
+export { listPlans, loadPlan, savePlan } from "./plans.ts";
+export { emptyDeploymentState, loadDeploymentState, saveDeploymentState, } from "./state.ts";
+export { appendVerification, loadLatestVerification, loadVerificationHistory, } from "./verification.ts";

package/dist/src/persistence/index.js

@@ -0,0 +1,5 @@
+export { loadConfig, materializeConfig } from "./config.js";
+export { writeInstallDoc } from "./generated.js";
+export { listPlans, loadPlan, savePlan } from "./plans.js";
+export { emptyDeploymentState, loadDeploymentState, saveDeploymentState, } from "./state.js";
+export { appendVerification, loadLatestVerification, loadVerificationHistory, } from "./verification.js";

package/dist/src/persistence/plans.d.ts

@@ -0,0 +1,5 @@
+import type { DeploymentPlan } from "../contracts.ts";
+import { type WorkspacePaths } from "../paths.ts";
+export declare function savePlan(paths: WorkspacePaths, plan: DeploymentPlan): Promise<void>;
+export declare function loadPlan(paths: WorkspacePaths, planRef: string): Promise<DeploymentPlan | undefined>;
+export declare function listPlans(paths: WorkspacePaths): Promise<string[]>;

package/dist/src/persistence/plans.js

@@ -0,0 +1,34 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { readJson } from "../paths.js";
+import { writeJsonAtomic } from "./atomic.js";
+import { assertSafeFileName, isDeploymentPlan } from "./guards.js";
+function planFilePath(paths, planRef) {
+    assertSafeFileName(planRef, "planRef");
+    return join(paths.plans, `${planRef}.json`);
+}
+// Plans are public DTOs: secretRef config values are opaque reference
+// identities (e.g. `secret://model-provider/default`), safe to persist verbatim.
+// No raw secret ever enters a plan, so no redaction is applied on save.
+export async function savePlan(paths, plan) {
+    await writeJsonAtomic(planFilePath(paths, plan.planRef), plan);
+}
+export async function loadPlan(paths, planRef) {
+    const value = await readJson(planFilePath(paths, planRef));
+    if (value === undefined)
+        return undefined;
+    return isDeploymentPlan(value) ? value : undefined;
+}
+export async function listPlans(paths) {
+    let entries;
+    try {
+        entries = await readdir(paths.plans);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => entry.slice(0, -".json".length))
+        .sort();
+}

package/dist/src/persistence/state.d.ts

@@ -0,0 +1,7 @@
+import type { DeploymentState, PendingActionRecord } from "../contracts.ts";
+import { type WorkspacePaths } from "../paths.ts";
+export declare function emptyDeploymentState(): DeploymentState;
+export declare function clearPendingActions(state: DeploymentState, isResolved: (action: PendingActionRecord) => boolean): DeploymentState;
+export declare function clearCompletedPendingActions(state: DeploymentState): DeploymentState;
+export declare function loadDeploymentState(paths: WorkspacePaths): Promise<DeploymentState | undefined>;
+export declare function saveDeploymentState(paths: WorkspacePaths, state: DeploymentState): Promise<void>;

package/dist/src/persistence/state.js

@@ -0,0 +1,34 @@
+import { readJson } from "../paths.js";
+import { writeJsonAtomic } from "./atomic.js";
+import { DEPLOYMENT_STATE_CONTRACT, isDeploymentState } from "./guards.js";
+export function emptyDeploymentState() {
+    return {
+        contract: DEPLOYMENT_STATE_CONTRACT,
+        selectedModules: [],
+        lastAppliedPlans: [],
+        verificationIndex: [],
+        pendingActions: [],
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function clearPendingActions(state, isResolved) {
+    return {
+        ...state,
+        pendingActions: state.pendingActions.filter((action) => !isResolved(action)),
+    };
+}
+export function clearCompletedPendingActions(state) {
+    const completed = new Set(state.lastAppliedPlans.map((entry) => entry.planRef));
+    return clearPendingActions(state, (action) => completed.has(action.planRef));
+}
+// Loaded state is validated at the boundary; a missing or corrupt file resolves
+// to undefined so stale persisted facts can never impersonate current reality.
+export async function loadDeploymentState(paths) {
+    const value = await readJson(paths.stateJson);
+    if (value === undefined)
+        return undefined;
+    return isDeploymentState(value) ? value : undefined;
+}
+export async function saveDeploymentState(paths, state) {
+    await writeJsonAtomic(paths.stateJson, state);
+}

package/dist/src/persistence/verification.d.ts

@@ -0,0 +1,5 @@
+import type { VerificationRecord } from "../contracts.ts";
+import type { WorkspacePaths } from "../paths.ts";
+export declare function appendVerification(paths: WorkspacePaths, record: VerificationRecord): Promise<void>;
+export declare function loadVerificationHistory(paths: WorkspacePaths, moduleRef: string): Promise<VerificationRecord[]>;
+export declare function loadLatestVerification(paths: WorkspacePaths, moduleRef: string): Promise<VerificationRecord | undefined>;

package/dist/src/persistence/verification.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { assertSafeFileName, isVerificationRecord } from "./guards.js";
+function verificationFilePath(paths, moduleRef) {
+    assertSafeFileName(moduleRef, "moduleRef");
+    return join(paths.verification, `${moduleRef}.jsonl`);
+}
+async function readJsonlLines(file) {
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const lines = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            lines.push(JSON.parse(trimmed));
+        }
+        catch {
+            // skip a corrupt line rather than discarding otherwise valid history
+        }
+    }
+    return lines;
+}
+// Verification history is append-only: existing records are preserved and the
+// new record is appended, then the whole file is atomically replaced.
+export async function appendVerification(paths, record) {
+    const file = verificationFilePath(paths, record.moduleRef);
+    const records = (await readJsonlLines(file)).filter(isVerificationRecord);
+    records.push(record);
+    const content = `${records.map((item) => JSON.stringify(item)).join("\n")}\n`;
+    await writeFileAtomic(file, content);
+}
+export async function loadVerificationHistory(paths, moduleRef) {
+    const lines = await readJsonlLines(verificationFilePath(paths, moduleRef));
+    return lines.filter(isVerificationRecord);
+}
+export async function loadLatestVerification(paths, moduleRef) {
+    const history = await loadVerificationHistory(paths, moduleRef);
+    return history[history.length - 1];
+}

package/dist/src/planner/assemble.d.ts

@@ -0,0 +1,16 @@
+import type { HumanAction, ModuleDescriptor } from "@tomflow/proflow-module-contract";
+import type { DeploymentIntent, DeploymentPlan, DeploymentStep, ModuleTarget, ResolvedModule } from "../contracts.ts";
+export declare function toResolvedModule(descriptor: ModuleDescriptor): ResolvedModule;
+export declare function generatePlanRef(intent: DeploymentIntent, moduleTargets: readonly ModuleTarget[], now: Date): string;
+export declare function deepFreeze<T>(value: T): T;
+export interface AssembleArgs {
+    intent: DeploymentIntent;
+    modules: readonly ResolvedModule[];
+    targets: readonly ModuleTarget[];
+    config: Record<string, Record<string, string>> | undefined;
+    steps: DeploymentStep[];
+    humanActions: HumanAction[];
+    now: Date;
+    targetDescriptors?: readonly ModuleDescriptor[];
+}
+export declare function assemblePlan(args: AssembleArgs): DeploymentPlan;

package/dist/src/planner/assemble.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { buildDependencyGraph } from "../graph/graph.js";
+import { computeFingerprint } from "./fingerprint.js";
+function compareRef(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function toResolvedModule(descriptor) {
+    return {
+        moduleRef: descriptor.moduleRef,
+        packageName: descriptor.packageName,
+        moduleVersion: descriptor.moduleVersion,
+        kind: descriptor.kind,
+        installClass: descriptor.installClass,
+        identity: descriptor.identity,
+        documentation: descriptor.documentation,
+        provides: descriptor.provides,
+        requires: descriptor.requires,
+        requirements: descriptor.requirements,
+        configSlots: descriptor.configSlots,
+        lifecycle: descriptor.lifecycle.supported,
+        verification: descriptor.verification,
+        effects: descriptor.effects,
+        source: { type: "installed" },
+    };
+}
+export function generatePlanRef(intent, moduleTargets, now) {
+    const key = JSON.stringify({
+        intent,
+        targets: [...moduleTargets]
+            .sort((a, b) => compareRef(a.moduleRef, b.moduleRef))
+            .map((target) => ({
+            moduleRef: target.moduleRef,
+            targetVersion: target.targetVersion ?? null,
+        })),
+    });
+    const hash = createHash("sha256").update(key).digest("hex").slice(0, 8);
+    return `plan-${intent}-${now.getTime()}-${hash}`;
+}
+export function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const key of Object.keys(value)) {
+            deepFreeze(value[key]);
+        }
+    }
+    return value;
+}
+export function assemblePlan(args) {
+    const graph = buildDependencyGraph(args.modules);
+    const byRef = new Map(args.modules.map((module) => [module.moduleRef, module]));
+    const targetByRef = new Map(args.targets.map((target) => [target.moduleRef, target]));
+    const moduleTargets = [];
+    for (const ref of graph.order) {
+        const explicit = targetByRef.get(ref);
+        const merged = {
+            ...(explicit?.config ?? {}),
+            ...(args.config?.[ref] ?? {}),
+        };
+        const target = { moduleRef: ref };
+        if (explicit?.targetVersion !== undefined) {
+            target.targetVersion = explicit.targetVersion;
+        }
+        if (Object.keys(merged).length > 0) {
+            target.config = merged;
+        }
+        moduleTargets.push(target);
+    }
+    const verification = graph.order.map((ref) => ({
+        moduleRef: ref,
+        checks: (byRef.get(ref)?.verification.checks ?? []).map((check) => check.id),
+    }));
+    const effectMap = new Map();
+    for (const module of args.modules) {
+        for (const effect of module.effects) {
+            const key = `${effect.kind}:${effect.description}`;
+            if (!effectMap.has(key))
+                effectMap.set(key, effect);
+        }
+    }
+    const effects = [...effectMap.values()].sort((a, b) => compareRef(`${a.kind}:${a.description}`, `${b.kind}:${b.description}`));
+    const humanByAction = new Map();
+    for (const action of args.humanActions) {
+        if (!humanByAction.has(action.action)) {
+            humanByAction.set(action.action, action);
+        }
+    }
+    const humanActions = [...humanByAction.values()].sort((a, b) => compareRef(a.action, b.action));
+    const resolvedModules = [...args.modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
+    const plan = {
+        planRef: "",
+        intent: args.intent,
+        moduleTargets,
+        resolvedModules,
+        ...(args.targetDescriptors !== undefined
+            ? { targetDescriptors: [...args.targetDescriptors] }
+            : {}),
+        steps: args.steps,
+        effects,
+        humanActions,
+        verification,
+        fingerprint: "",
+        createdAt: args.now.toISOString(),
+    };
+    plan.planRef = generatePlanRef(args.intent, moduleTargets, args.now);
+    plan.fingerprint = computeFingerprint(plan);
+    return deepFreeze(plan);
+}

package/dist/src/planner/check.d.ts

@@ -0,0 +1,20 @@
+import type { DeploymentPlan, DeploymentStep } from "../contracts.ts";
+export interface VerificationCheckResult {
+    id: string;
+    status: "PASS" | "FAIL";
+}
+export interface StepReality {
+    installedVersion?: string;
+    configValues?: Record<string, string>;
+    processRunning?: boolean;
+    resourceConfigured?: boolean;
+    humanActionVerified?: boolean;
+    verificationChecks?: readonly VerificationCheckResult[];
+    migrated?: boolean;
+}
+export type StepCheckStatus = "SATISFIED" | "NOT_SATISFIED" | "UNKNOWN";
+export interface StepCheckResult {
+    status: StepCheckStatus;
+    reason: string;
+}
+export declare function evaluateStepCheck(step: DeploymentStep, plan: DeploymentPlan, reality: StepReality): StepCheckResult;