@tomflow/proflow-platform-cli 0.1.0

package/dist/src/planner/check.js

@@ -0,0 +1,96 @@
+import { CheckStrategy } from "./steps.js";
+function satisfied(reason) {
+    return { status: "SATISFIED", reason };
+}
+function notSatisfied(reason) {
+    return { status: "NOT_SATISFIED", reason };
+}
+function unknown(reason) {
+    return { status: "UNKNOWN", reason };
+}
+function moduleOf(plan, step) {
+    return plan.resolvedModules.find((module) => module.moduleRef === step.moduleRef);
+}
+export function evaluateStepCheck(step, plan, reality) {
+    switch (step.checkStrategy) {
+        case CheckStrategy.packageInstalled:
+            return checkPackage(step, plan, reality);
+        case CheckStrategy.packageAbsent:
+            return reality.installedVersion === undefined
+                ? satisfied(`${step.moduleRef} package is absent`)
+                : notSatisfied(`${step.moduleRef} package is still installed at ${reality.installedVersion}`);
+        case CheckStrategy.configMaterialized:
+            return checkConfig(step, plan, reality);
+        case CheckStrategy.lifecycleRunning:
+            return reality.processRunning === true
+                ? satisfied(`${step.moduleRef} is running`)
+                : notSatisfied(`${step.moduleRef} is not observed running`);
+        case CheckStrategy.lifecycleStopped:
+            return reality.processRunning === false
+                ? satisfied(`${step.moduleRef} is stopped`)
+                : notSatisfied(`${step.moduleRef} is not observed stopped`);
+        case CheckStrategy.externalResourceConfigured:
+            return reality.resourceConfigured === true
+                ? satisfied(`external resource ${step.moduleRef} configured`)
+                : notSatisfied(`external resource ${step.moduleRef} not observed configured`);
+        case CheckStrategy.humanVerified:
+            return reality.humanActionVerified === true
+                ? satisfied(`human action for ${step.moduleRef} verified`)
+                : notSatisfied(`human action for ${step.moduleRef} not observed verified`);
+        case CheckStrategy.migrateComplete:
+            return reality.migrated === true
+                ? satisfied(`${step.moduleRef} migrated`)
+                : notSatisfied(`${step.moduleRef} not observed migrated`);
+        case CheckStrategy.verifyChecksPass:
+            return checkVerify(step, plan, reality);
+        default:
+            return unknown(`unknown check strategy ${step.checkStrategy}`);
+    }
+}
+function checkPackage(step, plan, reality) {
+    const module = moduleOf(plan, step);
+    if (module === undefined) {
+        return unknown(`module ${step.moduleRef} is not in the plan`);
+    }
+    if (reality.installedVersion === undefined) {
+        return notSatisfied(`installed version for ${step.moduleRef} is not observed`);
+    }
+    if (reality.installedVersion !== module.moduleVersion) {
+        return notSatisfied(`installed ${reality.installedVersion} != expected ${module.moduleVersion}`);
+    }
+    return satisfied(`installed ${module.moduleVersion} matches target`);
+}
+function checkConfig(step, plan, reality) {
+    const module = moduleOf(plan, step);
+    if (module === undefined) {
+        return unknown(`module ${step.moduleRef} is not in the plan`);
+    }
+    if (reality.configValues === undefined) {
+        return notSatisfied(`config for ${step.moduleRef} is not materialized`);
+    }
+    for (const slot of module.configSlots) {
+        if (!slot.required)
+            continue;
+        const value = reality.configValues[slot.key];
+        if (value === undefined || value === "") {
+            return notSatisfied(`required config ${slot.key} is missing`);
+        }
+    }
+    return satisfied(`required config materialized for ${step.moduleRef}`);
+}
+function checkVerify(step, plan, reality) {
+    const module = moduleOf(plan, step);
+    if (module === undefined) {
+        return unknown(`module ${step.moduleRef} is not in the plan`);
+    }
+    if (reality.verificationChecks === undefined) {
+        return notSatisfied(`verification for ${step.moduleRef} is not run`);
+    }
+    const byId = new Map(reality.verificationChecks.map((check) => [check.id, check.status]));
+    for (const check of module.verification.checks) {
+        if (byId.get(check.id) !== "PASS") {
+            return notSatisfied(`verification check ${check.id} is not passing`);
+        }
+    }
+    return satisfied(`verification checks pass for ${step.moduleRef}`);
+}

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

@@ -0,0 +1,12 @@
+import type { DeploymentPlan } from "../contracts.ts";
+export interface FingerprintSource {
+    intent: string;
+    targets: string;
+    modules: string;
+    steps: string;
+    effects: string;
+    humanActions: string;
+    verification: string;
+}
+export declare function buildFingerprintSource(plan: DeploymentPlan): FingerprintSource;
+export declare function computeFingerprint(plan: DeploymentPlan): string;

package/dist/src/planner/fingerprint.js

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+function compareRef(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function stableStringify(value) {
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .join(",")}}`;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+// Maps each moduleRef to the config keys that hold RAW secret values and must
+// be redacted from the fingerprint. secretRef slots are explicitly excluded:
+// their values are opaque reference identities (e.g. `secret://…`), which are
+// fingerprinted verbatim so a reference change (A→B) changes the fingerprint.
+function rawSecretKeyMap(modules) {
+    const map = new Map();
+    for (const module of modules) {
+        const set = new Set();
+        for (const slot of module.configSlots) {
+            if (slot.type !== "secretRef" && slot.sensitive === true) {
+                set.add(slot.key);
+            }
+        }
+        map.set(module.moduleRef, set);
+    }
+    return map;
+}
+function canonicalModules(modules) {
+    return [...modules]
+        .sort((a, b) => compareRef(a.moduleRef, b.moduleRef))
+        .map((module) => ({
+        moduleRef: module.moduleRef,
+        packageName: module.packageName,
+        moduleVersion: module.moduleVersion,
+        kind: module.kind,
+        installClass: module.installClass,
+        identity: module.identity,
+        documentation: [...module.documentation]
+            .sort((a, b) => compareRef(a.id, b.id))
+            .map((entry) => ({
+            id: entry.id,
+            path: entry.path,
+            description: entry.description ?? null,
+        })),
+        provides: [...module.provides]
+            .sort((a, b) => compareRef(a.contractRef, b.contractRef))
+            .map((provide) => ({
+            contractRef: provide.contractRef,
+            version: provide.version,
+        })),
+        requires: [...module.requires]
+            .sort((a, b) => compareRef(a.contractRef, b.contractRef))
+            .map((require) => ({
+            contractRef: require.contractRef,
+            versionRange: require.versionRange,
+            optional: require.optional ?? false,
+        })),
+        requirements: [...module.requirements]
+            .sort((a, b) => compareRef(stableStringify(a), stableStringify(b)))
+            .map((requirement) => requirement),
+        configSlots: [...module.configSlots]
+            .sort((a, b) => compareRef(a.key, b.key))
+            .map((slot) => ({
+            key: slot.key,
+            type: slot.type,
+            required: slot.required,
+            sensitive: slot.sensitive ?? false,
+            default: slot.default === undefined ? null : stableStringify(slot.default),
+        })),
+        lifecycle: [...module.lifecycle].sort(compareRef),
+        verification: [...module.verification.checks]
+            .sort((a, b) => compareRef(a.id, b.id))
+            .map((check) => ({
+            id: check.id,
+            lifecycle: check.lifecycle,
+            description: check.description,
+        })),
+        effects: [...module.effects]
+            .sort((a, b) => compareRef(`${a.kind}:${a.description}`, `${b.kind}:${b.description}`))
+            .map((effect) => ({
+            kind: effect.kind,
+            description: effect.description,
+            path: effect.path ?? null,
+            retention: effect.retention,
+        })),
+    }));
+}
+function redactConfig(config, rawSecretKeys) {
+    const result = {};
+    for (const key of Object.keys(config).sort()) {
+        result[key] = rawSecretKeys.has(key) ? "<redacted>" : (config[key] ?? "");
+    }
+    return result;
+}
+function redactedTargets(targets, rawSecretByRef) {
+    return [...targets]
+        .sort((a, b) => compareRef(a.moduleRef, b.moduleRef))
+        .map((target) => {
+        const rawSecretKeys = rawSecretByRef.get(target.moduleRef) ?? new Set();
+        const config = target.config === undefined
+            ? null
+            : redactConfig(target.config, rawSecretKeys);
+        return {
+            moduleRef: target.moduleRef,
+            targetVersion: target.targetVersion ?? null,
+            config,
+        };
+    });
+}
+function canonicalSteps(steps) {
+    return steps.map((step) => ({
+        stepRef: step.stepRef,
+        moduleRef: step.moduleRef,
+        kind: step.kind,
+        preconditions: [...step.preconditions].sort(compareRef),
+        expectedEffect: step.expectedEffect,
+        checkStrategy: step.checkStrategy,
+        executeStrategy: step.executeStrategy ?? null,
+        postcondition: step.postcondition,
+    }));
+}
+export function buildFingerprintSource(plan) {
+    const rawSecretByRef = rawSecretKeyMap(plan.resolvedModules);
+    return {
+        intent: plan.intent,
+        targets: stableStringify(redactedTargets(plan.moduleTargets, rawSecretByRef)),
+        modules: stableStringify(canonicalModules(plan.resolvedModules)),
+        steps: stableStringify(canonicalSteps(plan.steps)),
+        effects: stableStringify([...plan.effects]
+            .sort((a, b) => compareRef(`${a.kind}:${a.description}`, `${b.kind}:${b.description}`))
+            .map((effect) => ({
+            kind: effect.kind,
+            description: effect.description,
+            path: effect.path ?? null,
+            retention: effect.retention,
+        }))),
+        humanActions: stableStringify([...plan.humanActions]
+            .sort((a, b) => compareRef(a.action, b.action))
+            .map((action) => ({
+            action: action.action,
+            description: action.description,
+        }))),
+        verification: stableStringify([...plan.verification]
+            .sort((a, b) => compareRef(a.moduleRef, b.moduleRef))
+            .map((verification) => ({
+            moduleRef: verification.moduleRef,
+            checks: [...verification.checks].sort(compareRef),
+        }))),
+    };
+}
+export function computeFingerprint(plan) {
+    return sha256(stableStringify(buildFingerprintSource(plan)));
+}

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

@@ -0,0 +1,13 @@
+export type { StepCheckResult, StepCheckStatus, StepReality, VerificationCheckResult, } from "./check.ts";
+export { evaluateStepCheck } from "./check.ts";
+export type { FingerprintSource } from "./fingerprint.ts";
+export { computeFingerprint } from "./fingerprint.ts";
+export type { PlanInput } from "./plan.ts";
+export { planDeployment } from "./plan.ts";
+export type { RepairFact, RepairFactCode, RepairPlanInput } from "./repair.ts";
+export { planRepair, repairFactCodes } from "./repair.ts";
+export type { StalenessResult } from "./stale.ts";
+export { checkPlanStale } from "./stale.ts";
+export { CheckStrategy, ExecuteStrategy } from "./steps.ts";
+export type { UpgradeAssessment } from "./upgrade.ts";
+export { assessUpgrade, planUpgrade } from "./upgrade.ts";

package/dist/src/planner/index.js

@@ -0,0 +1,7 @@
+export { evaluateStepCheck } from "./check.js";
+export { computeFingerprint } from "./fingerprint.js";
+export { planDeployment } from "./plan.js";
+export { planRepair, repairFactCodes } from "./repair.js";
+export { checkPlanStale } from "./stale.js";
+export { CheckStrategy, ExecuteStrategy } from "./steps.js";
+export { assessUpgrade, planUpgrade } from "./upgrade.js";

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

@@ -0,0 +1,14 @@
+import type { ModuleDescriptor } from "@tomflow/proflow-module-contract";
+import type { DeploymentIntent, DeploymentPlan, ModuleTarget, ResolvedModule } from "../contracts.ts";
+import type { RepairFact } from "./repair.ts";
+export interface PlanInput {
+    intent: DeploymentIntent;
+    modules?: readonly ResolvedModule[];
+    targets?: readonly ModuleTarget[];
+    config?: Record<string, Record<string, string>>;
+    currentDescriptors?: readonly ModuleDescriptor[];
+    targetDescriptors?: readonly ModuleDescriptor[];
+    facts?: readonly RepairFact[];
+    now?: Date;
+}
+export declare function planDeployment(input: PlanInput): DeploymentPlan;

package/dist/src/planner/plan.js

@@ -0,0 +1,156 @@
+import { PlatformError } from "../errors.js";
+import { buildDependencyGraph } from "../graph/graph.js";
+import { assemblePlan } from "./assemble.js";
+import { planRepair } from "./repair.js";
+import { configStep, createSequencer, externalResourceStep, humanActionsFromModules, humanStep, lifecycleStep, packageStep, upstreamDependencies, } from "./steps.js";
+import { planUpgrade } from "./upgrade.js";
+export function planDeployment(input) {
+    switch (input.intent) {
+        case "upgrade":
+            return input.modules?.every((module) => module.source.type === "registry")
+                ? planRegistryPackageUpgrade(input)
+                : planUpgrade(input);
+        case "repair":
+            return planRepair(input);
+        case "uninstall":
+            return planUninstall(input);
+        case "install":
+        case "configure":
+            return planInstallOrConfigure(input);
+    }
+}
+function planRegistryPackageUpgrade(input) {
+    const modules = input.modules;
+    if (modules === undefined) {
+        throw new PlatformError("INVALID_REQUEST", "registry-backed upgrade requires modules");
+    }
+    const graph = buildDependencyGraph(modules);
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const seq = createSequencer();
+    const steps = [];
+    for (const ref of graph.order) {
+        const module = byRef.get(ref);
+        if (module === undefined)
+            continue;
+        steps.push(packageStep(seq, module, "upgrade", []));
+    }
+    return assemblePlan({
+        intent: "upgrade",
+        modules,
+        targets: input.targets ?? [],
+        config: undefined,
+        steps,
+        humanActions: [],
+        now: input.now ?? new Date(),
+    });
+}
+function planInstallOrConfigure(input) {
+    const modules = input.modules;
+    if (modules === undefined) {
+        throw new PlatformError("INVALID_REQUEST", `${input.intent} requires modules`);
+    }
+    const graph = buildDependencyGraph(modules);
+    const steps = input.intent === "install"
+        ? installSteps(modules, graph)
+        : configureSteps(modules, graph);
+    return assemblePlan({
+        intent: input.intent,
+        modules,
+        targets: input.targets ?? [],
+        config: input.config,
+        steps,
+        humanActions: humanActionsFromModules(modules),
+        now: input.now ?? new Date(),
+    });
+}
+function installSteps(modules, graph) {
+    const seq = createSequencer();
+    const deps = upstreamDependencies(graph);
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const steps = [];
+    for (const ref of graph.order) {
+        const module = byRef.get(ref);
+        if (module === undefined)
+            continue;
+        const dependencies = deps.get(ref) ?? [];
+        steps.push(packageStep(seq, module, "install", dependencies));
+        if (module.configSlots.length > 0) {
+            steps.push(configStep(seq, module));
+        }
+        if (module.kind === "external-resource") {
+            const step = externalResourceStep(seq, module);
+            if (step !== undefined)
+                steps.push(step);
+        }
+        for (const requirement of module.requirements) {
+            if (requirement.kind === "human") {
+                steps.push(humanStep(seq, module, requirement.action));
+            }
+        }
+    }
+    return steps;
+}
+function configureSteps(modules, graph) {
+    const seq = createSequencer();
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const steps = [];
+    for (const ref of graph.order) {
+        const module = byRef.get(ref);
+        if (module === undefined)
+            continue;
+        if (module.configSlots.length > 0) {
+            steps.push(configStep(seq, module));
+        }
+        if (module.kind === "external-resource") {
+            const step = externalResourceStep(seq, module);
+            if (step !== undefined)
+                steps.push(step);
+        }
+        if (module.kind === "service") {
+            if (module.lifecycle.includes("restart")) {
+                steps.push(lifecycleStep(seq, module, "restart"));
+            }
+            else if (module.lifecycle.includes("start")) {
+                steps.push(lifecycleStep(seq, module, "start"));
+            }
+        }
+        for (const requirement of module.requirements) {
+            if (requirement.kind === "human") {
+                steps.push(humanStep(seq, module, requirement.action));
+            }
+        }
+    }
+    return steps;
+}
+function planUninstall(input) {
+    const modules = input.modules;
+    if (modules === undefined || modules.length === 0) {
+        throw new PlatformError("INVALID_REQUEST", "uninstall requires modules");
+    }
+    const core = modules.find((module) => module.installClass === "core");
+    if (core !== undefined) {
+        throw new PlatformError("CORE_PACKAGE_REQUIRED", `core module ${core.moduleRef} cannot be individually uninstalled`);
+    }
+    const graph = buildDependencyGraph(modules);
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const seq = createSequencer();
+    const steps = [];
+    for (const ref of [...graph.order].reverse()) {
+        const module = byRef.get(ref);
+        if (module === undefined)
+            continue;
+        if (module.lifecycle.includes("uninstall")) {
+            steps.push(lifecycleStep(seq, module, "uninstall"));
+        }
+        steps.push(packageStep(seq, module, "remove", []));
+    }
+    return assemblePlan({
+        intent: "uninstall",
+        modules,
+        targets: input.targets ?? [],
+        config: undefined,
+        steps,
+        humanActions: [],
+        now: input.now ?? new Date(),
+    });
+}

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

@@ -0,0 +1,28 @@
+import type { DeploymentPlan, ModuleTarget, ResolvedModule } from "../contracts.ts";
+import type { DoctorReport } from "../doctor/doctor.ts";
+export declare const repairFactCodes: readonly ["CONFIG_MISSING", "LIFECYCLE_NOT_RUNNING", "VERIFY_FAILED", "EXTERNAL_RESOURCE_UNAVAILABLE", "ACTION_REQUIRED", "DEPENDENCY_UNRESOLVED"];
+export type RepairFactCode = (typeof repairFactCodes)[number];
+export interface RepairFact {
+    moduleRef: string;
+    code: RepairFactCode;
+    message: string;
+}
+export interface RepairPlanInput {
+    modules?: readonly ResolvedModule[];
+    targets?: readonly ModuleTarget[];
+    config?: Record<string, Record<string, string>>;
+    facts?: readonly RepairFact[];
+    now?: Date;
+}
+export interface RepairBlockedReason {
+    moduleRef: string;
+    code: string;
+    message: string;
+}
+export interface RepairDiagnosis {
+    facts: RepairFact[];
+    blocked: RepairBlockedReason[];
+}
+export declare function repairFactsFromDoctor(report: DoctorReport): RepairDiagnosis;
+export declare function diagnoseRepair(reports: readonly DoctorReport[]): RepairDiagnosis;
+export declare function planRepair(input: RepairPlanInput): DeploymentPlan;

package/dist/src/planner/repair.js

@@ -0,0 +1,131 @@
+import { PlatformError } from "../errors.js";
+import { assemblePlan } from "./assemble.js";
+import { configStep, createSequencer, externalResourceStep, humanStep, lifecycleStep, } from "./steps.js";
+export const repairFactCodes = [
+    "CONFIG_MISSING",
+    "LIFECYCLE_NOT_RUNNING",
+    "VERIFY_FAILED",
+    "EXTERNAL_RESOURCE_UNAVAILABLE",
+    "ACTION_REQUIRED",
+    "DEPENDENCY_UNRESOLVED",
+];
+// Frozen error codes that carry an automatic repair mapping. Everything else
+// is left BLOCKED for human review rather than inventing a mutation.
+const ERROR_CODE_TO_FACT = {
+    CONFIG_REQUIRED: "CONFIG_MISSING",
+    DEPENDENCY_UNRESOLVED: "DEPENDENCY_UNRESOLVED",
+    EXTERNAL_RESOURCE_UNAVAILABLE: "EXTERNAL_RESOURCE_UNAVAILABLE",
+    VERIFY_FAILED: "VERIFY_FAILED",
+};
+export function repairFactsFromDoctor(report) {
+    const facts = [];
+    const blocked = [];
+    if (report.nextAction.kind === "human-action") {
+        facts.push({
+            moduleRef: report.moduleRef,
+            code: "ACTION_REQUIRED",
+            message: report.nextAction.action,
+        });
+        return { facts, blocked };
+    }
+    if (report.status === "SUCCEEDED") {
+        return { facts, blocked };
+    }
+    if (report.errors.length === 0) {
+        blocked.push({
+            moduleRef: report.moduleRef,
+            code: report.status,
+            message: `module ${report.moduleRef} is ${report.status.toLowerCase()} with no typed error`,
+        });
+        return { facts, blocked };
+    }
+    for (const error of report.errors) {
+        const factCode = ERROR_CODE_TO_FACT[error.code];
+        if (factCode === undefined) {
+            blocked.push({
+                moduleRef: report.moduleRef,
+                code: error.code,
+                message: error.message,
+            });
+            continue;
+        }
+        facts.push({
+            moduleRef: report.moduleRef,
+            code: factCode,
+            message: error.message,
+        });
+    }
+    return { facts, blocked };
+}
+export function diagnoseRepair(reports) {
+    const facts = [];
+    const blocked = [];
+    for (const report of reports) {
+        const diagnosis = repairFactsFromDoctor(report);
+        facts.push(...diagnosis.facts);
+        blocked.push(...diagnosis.blocked);
+    }
+    return { facts, blocked };
+}
+export function planRepair(input) {
+    const modules = input.modules;
+    if (modules === undefined) {
+        throw new PlatformError("INVALID_REQUEST", "repair requires modules");
+    }
+    const facts = input.facts ?? [];
+    const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
+    const seq = createSequencer();
+    const steps = [];
+    const humanActions = [];
+    const seen = new Set();
+    for (const fact of facts) {
+        const module = byRef.get(fact.moduleRef);
+        if (module === undefined)
+            continue;
+        const dedupeKey = `${fact.moduleRef}|${fact.code}`;
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        switch (fact.code) {
+            case "CONFIG_MISSING":
+                if (module.configSlots.length > 0) {
+                    steps.push(configStep(seq, module));
+                }
+                break;
+            case "LIFECYCLE_NOT_RUNNING":
+                if (module.lifecycle.includes("start")) {
+                    steps.push(lifecycleStep(seq, module, "start"));
+                }
+                break;
+            case "EXTERNAL_RESOURCE_UNAVAILABLE":
+                if (module.kind === "external-resource") {
+                    const step = externalResourceStep(seq, module);
+                    if (step !== undefined)
+                        steps.push(step);
+                }
+                break;
+            case "ACTION_REQUIRED":
+                steps.push(humanStep(seq, module, fact.message));
+                humanActions.push({
+                    action: fact.message,
+                    description: `action required for ${module.moduleRef}`,
+                });
+                break;
+            case "VERIFY_FAILED":
+                // Verification re-runs after repair; no mutation is invented here.
+                break;
+            case "DEPENDENCY_UNRESOLVED":
+                // Resolution requires a plan/human decision; no mutation is invented.
+                break;
+        }
+    }
+    return assemblePlan({
+        intent: "repair",
+        modules,
+        targets: input.targets ?? [],
+        config: input.config,
+        steps,
+        humanActions,
+        now: input.now ?? new Date(),
+    });
+}

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

@@ -0,0 +1,7 @@
+import type { DeploymentPlan } from "../contracts.ts";
+import { type PlanInput } from "./plan.ts";
+export interface StalenessResult {
+    stale: boolean;
+    reasons: string[];
+}
+export declare function checkPlanStale(plan: DeploymentPlan, current: PlanInput): StalenessResult;

package/dist/src/planner/stale.js

@@ -0,0 +1,23 @@
+import { buildFingerprintSource } from "./fingerprint.js";
+import { planDeployment } from "./plan.js";
+const COMPARED_FIELDS = [
+    "intent",
+    "targets",
+    "modules",
+    "steps",
+    "effects",
+    "humanActions",
+    "verification",
+];
+export function checkPlanStale(plan, current) {
+    const fresh = planDeployment(current);
+    const before = buildFingerprintSource(plan);
+    const after = buildFingerprintSource(fresh);
+    const reasons = [];
+    for (const field of COMPARED_FIELDS) {
+        if (before[field] !== after[field]) {
+            reasons.push(`${field} changed`);
+        }
+    }
+    return { stale: reasons.length > 0, reasons };
+}