agentera 3.0.0-dev.8 → 3.0.0-dev.81

package/dist/upgrade/migrateArtifactsV2ToV3.js

@@ -1,36 +1,151 @@
 import fs from "node:fs";
 import path from "node:path";
+import YAML from "yaml";
 import { isFile, pathExists, resolvePath } from "../core/paths.js";
+import { loadYamlMapping } from "../core/yaml.js";
+import { loadArtifactRecord, resolveArtifactPath } from "../registries/artifactRegistry.js";
 import { BUNDLE_MARKER } from "../state/installRoot.js";
+import { hasBundleRootEvidence } from "./bundleEvidence.js";
+import { applyAppContentRefreshItems, planAppContentRefreshItems, } from "./appContentRefresh.js";
 import { doctorRoots } from "./appModel.js";
 import { AGENTERA_USER_STATE_NAMES, } from "./doctor.js";
-import { applyV1ArtifactsPhase, planV1ArtifactsPhase, } from "./migrateArtifactsV1ToV2.js";
 import { appHomeHasUnrecognizedEntriesWithPreflight, handoffCatalogMessage, resolveMigrationUserStatePreflight, } from "../migrate/v2HandoffManifest.js";
-import { applyAppContentRefreshItems, planAppContentRefreshItems, } from "./appContentRefresh.js";
 import { applyLegacyAgentCleanupItems, planLegacyAgentCleanupItems, planLegacyCapabilityAgentCleanupItems, } from "./legacyAgentCleanup.js";
-import { applyRuntimeMigrationItems, planRuntimeMigrationItems, resolveNpxHookCommands, rewireRuntimeText, } from "./runtimeMigration.js";
+import { applyRuntimeMigrationItems, planRuntimeMigrationItems, } from "./runtimeMigration.js";
+import { writeFileAtomic } from "./atomicWriter.js";
+import { bindMigrationTree, cloneMigrationItem, removeBoundMigrationTree } from "./migrationPublication.js";
+import { applyInstalledHooksRetirementItems, planInstalledHooksRetirementItems, } from "./installedHooksRetirement.js";
 /**
  * v2→v3 migration phases: artifacts (noop for YAML), runtime rewire, cleanup.
- * v1 Markdown→YAML migration uses detectV1ArtifactPairs (shared with prime).
  */
-export const MIGRATION_STATUSES = ["pending", "applied", "noop", "blocked", "failed", "skipped"];
-export const V1_ARTIFACT_PAIRS = [
-    [".agentera/PROGRESS.md", ".agentera/progress.yaml"],
-    [".agentera/PLAN.md", ".agentera/plan.yaml"],
-    [".agentera/DECISIONS.md", ".agentera/decisions.yaml"],
-    [".agentera/HEALTH.md", ".agentera/health.yaml"],
-    [".agentera/DOCS.md", ".agentera/docs.yaml"],
-    ["VISION.md", ".agentera/vision.yaml"],
-];
-/** Default development-channel npm entrypoint for tests and legacy imports. */
-export const NPX_CLI_ENTRYPOINT = "npx -y agentera@next";
-export const NPX_HOOK_VALIDATE = `${NPX_CLI_ENTRYPOINT} hook validate-artifact`;
-export const NPX_HOOK_CURSOR_SESSION_START = `${NPX_CLI_ENTRYPOINT} hook cursor-session-start`;
-export const NPX_HOOK_CURSOR_SESSION_STOP = `${NPX_CLI_ENTRYPOINT} hook session-stop`;
-export const NPX_HOOK_CURSOR_PRE_TOOL = `${NPX_CLI_ENTRYPOINT} hook cursor-pre-tool-use`;
-export { rewireRuntimeText, resolveNpxHookCommands };
+export const MIGRATION_STATUSES = ["pending", "applied", "noop", "blocked", "failed"];
+const PLAN_ARCHIVE_FILE = /^PLAN-.+\.ya?ml$/i;
+const PLAN_LIFECYCLE_ACTION = "normalize-plan-lifecycle";
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function relativeToProject(project, artifactPath) {
+    return path.relative(project, artifactPath);
+}
+function planTaskList(data) {
+    if (Array.isArray(data.tasks))
+        return data.tasks;
+    if (Array.isArray(data.entries))
+        return data.entries;
+    return null;
+}
+function completedTasksOnly(tasks) {
+    return tasks.every((task) => isMapping(task) && (task.status === "complete" || task.status === "completed"));
+}
+function rewritePlanStatus(text, status) {
+    const document = YAML.parseDocument(text);
+    if (document.errors.length > 0) {
+        throw new Error(document.errors.map((error) => error.message).join("; "));
+    }
+    document.setIn(["header", "status"], status);
+    return document.toString();
+}
+function lifecycleMigrationItem(project, artifactPath) {
+    const source = relativeToProject(project, artifactPath);
+    try {
+        const text = fs.readFileSync(artifactPath, "utf8");
+        const data = loadYamlMapping(text);
+        const header = isMapping(data.header) ? data.header : null;
+        const tasks = planTaskList(data);
+        if (!header || tasks === null) {
+            return {
+                status: "blocked",
+                action: PLAN_LIFECYCLE_ACTION,
+                source,
+                target: source,
+                message: "plan requires a header mapping and a tasks or entries array before lifecycle migration",
+            };
+        }
+        const status = typeof header.status === "string" ? header.status : "";
+        if (status === "open" || status === "complete") {
+            return {
+                status: "noop",
+                action: PLAN_LIFECYCLE_ACTION,
+                source,
+                target: source,
+                preserved: ["all plan fields"],
+                message: "plan lifecycle is already canonical",
+            };
+        }
+        if (status !== "active" && status !== "completed") {
+            return {
+                status: "blocked",
+                action: PLAN_LIFECYCLE_ACTION,
+                source,
+                target: source,
+                message: `plan header.status must be active, completed, open, or complete; received ${status || "missing"}`,
+            };
+        }
+        const collisions = [];
+        const targetStatus = status === "active" || !completedTasksOnly(tasks)
+            ? "open"
+            : "complete";
+        if (status === "completed" && targetStatus === "open") {
+            collisions.push("header.status=completed conflicts with unfinished task evidence; preserving task evidence and migrating status to open");
+        }
+        return {
+            status: "pending",
+            action: PLAN_LIFECYCLE_ACTION,
+            source,
+            target: source,
+            preserved: ["all plan fields except header.status"],
+            ...(collisions.length > 0 ? { collisions } : {}),
+            newText: rewritePlanStatus(text, targetStatus),
+            message: `will migrate plan lifecycle ${status} to ${targetStatus}`,
+        };
+    }
+    catch (error) {
+        return {
+            status: "blocked",
+            action: PLAN_LIFECYCLE_ACTION,
+            source,
+            target: source,
+            message: `cannot migrate plan lifecycle: ${error.message}`,
+        };
+    }
+}
+function lifecyclePlanArtifacts(project) {
+    const root = resolvePath(project);
+    let activePath;
+    try {
+        const record = loadArtifactRecord("plan");
+        if (!record)
+            throw new Error("plan artifact is not registered");
+        activePath = resolveArtifactPath(record, root, { strictWrite: true });
+    }
+    catch (error) {
+        return [{
+                status: "blocked",
+                action: PLAN_LIFECYCLE_ACTION,
+                message: `cannot resolve docs-mapped plan path: ${error.message}`,
+            }];
+    }
+    const artifacts = isFile(activePath) ? [activePath] : [];
+    const archiveDirectory = path.join(path.dirname(activePath), "archive");
+    try {
+        for (const name of fs.readdirSync(archiveDirectory).sort()) {
+            if (!PLAN_ARCHIVE_FILE.test(name))
+                continue;
+            const archivePath = path.join(archiveDirectory, name);
+            if (isFile(archivePath))
+                artifacts.push(archivePath);
+        }
+    }
+    catch {
+        // A missing archive directory is normal before the first archive.
+    }
+    return artifacts.map((artifactPath) => lifecycleMigrationItem(root, artifactPath));
+}
+export function hasPendingPlanLifecycleMigration(project) {
+    return lifecyclePlanArtifacts(project).some((item) => item.status === "pending");
+}
 function emptySummary() {
-    return { pending: 0, applied: 0, noop: 0, blocked: 0, failed: 0, skipped: 0 };
+    return { pending: 0, applied: 0, noop: 0, blocked: 0, failed: 0 };
 }
 export function summarizePhase(name, items, message = "") {
     const summary = emptySummary();
@@ -50,24 +165,11 @@ export function summarizePhase(name, items, message = "") {
     else if (summary.applied > 0) {
         status = "applied";
     }
-    else if (summary.skipped > 0 && summary.noop === 0 && summary.applied === 0) {
-        status = "skipped";
-    }
     else {
         status = "noop";
     }
     return { name, status, summary, items, message };
 }
-export function detectV1ArtifactPairs(project) {
-    const root = resolvePath(project);
-    const found = [];
-    for (const [md, yaml] of V1_ARTIFACT_PAIRS) {
-        if (isFile(path.join(root, md)) && !isFile(path.join(root, yaml))) {
-            found.push(md);
-        }
-    }
-    return found;
-}
 function listV2YamlArtifacts(project) {
     const root = resolvePath(project);
     const agenteraDir = path.join(root, ".agentera");
@@ -98,36 +200,81 @@ export function planArtifactsPhase(project) {
             },
         ]);
     }
-    const v1Pairs = detectV1ArtifactPairs(root);
-    if (v1Pairs.length > 0) {
-        return planV1ArtifactsPhase(root);
-    }
     const yamlArtifacts = listV2YamlArtifacts(root);
-    if (yamlArtifacts.length === 0) {
+    const lifecycleItems = lifecyclePlanArtifacts(root);
+    if (yamlArtifacts.length === 0 && lifecycleItems.length === 0) {
         return summarizePhase("artifacts", [], "no project artifacts found");
     }
-    const items = yamlArtifacts.map((source) => ({
-        status: "noop",
-        action: "preserve",
-        source,
-        message: "v2 YAML artifact preserved; no v2→v3 schema migration required",
-    }));
+    const lifecycleSources = new Set(lifecycleItems.flatMap((item) => item.source ? [item.source] : []));
+    const items = [
+        ...yamlArtifacts.filter((source) => !lifecycleSources.has(source)).map((source) => ({
+            status: "noop",
+            action: "preserve",
+            source,
+            message: "v2 YAML artifact preserved; no v2→v3 schema migration required",
+        })),
+        ...lifecycleItems,
+    ];
     return summarizePhase("artifacts", items);
 }
-export function applyArtifactsPhase(phase, project, force = false) {
+export function applyArtifactsPhase(phase, project, _force = false) {
     const root = resolvePath(project);
-    const hasV1Migration = phase.items.some((item) => item.action === "migrate");
-    if (hasV1Migration) {
-        applyV1ArtifactsPhase(phase, root, force);
-        return;
+    for (const item of phase.items) {
+        if (item.status !== "pending" || item.action !== PLAN_LIFECYCLE_ACTION || !item.source)
+            continue;
+        const sourcePath = path.join(root, item.source);
+        const current = lifecycleMigrationItem(root, sourcePath);
+        if (current.status !== "pending") {
+            item.status = current.status;
+            item.message = current.message;
+            item.collisions = current.collisions;
+            continue;
+        }
+        if (current.newText !== item.newText) {
+            item.status = "blocked";
+            item.message = "plan changed after migration preview; rerun dry-run before applying";
+            continue;
+        }
+        try {
+            writeFileAtomic(sourcePath, current.newText, "utf8");
+            item.status = "applied";
+            item.message = "migrated plan lifecycle without changing retained evidence";
+        }
+        catch (error) {
+            item.status = "failed";
+            item.message = `plan lifecycle migration failed: ${error.message}`;
+        }
     }
-    phase.status = summarizePhase("artifacts", phase.items, phase.message).status;
+    const updated = summarizePhase("artifacts", phase.items, phase.message);
+    phase.status = updated.status;
+    phase.summary = updated.summary;
 }
-export function planRuntimeRewirePhase(ctx) {
+export function delegatePlanLifecycleToEntityCutover(phase) {
+    for (const item of phase.items) {
+        if (item.status !== "pending" || item.action !== PLAN_LIFECYCLE_ACTION)
+            continue;
+        item.status = "noop";
+        item.message = "entity cutover normalizes plan lifecycle while retaining the legacy source as recovery evidence";
+    }
+    const updated = summarizePhase("artifacts", phase.items, phase.message);
+    phase.status = updated.status;
+    phase.summary = updated.summary;
+}
+export function planRuntimeRetirementPhase(ctx, _resolvedChannel) {
     const items = planRuntimeMigrationItems(ctx);
-    return summarizePhase("runtime", items, items.length === 0 ? "no runtime configs with Python managed app-home references found" : "");
+    const blockedPaths = new Set(items
+        .filter((item) => item.status === "blocked")
+        .flatMap((item) => [item.source, item.target])
+        .filter((value) => typeof value === "string"));
+    for (const item of items) {
+        if (item.status !== "pending" || ![item.source, item.target].some((value) => value && blockedPaths.has(value)))
+            continue;
+        item.status = "blocked";
+        item.message = "action required before Agentera can modify this runtime resource";
+    }
+    return summarizePhase("runtime", items, items.length === 0 ? "no retired native Agentera hooks found" : "");
 }
-export function applyRuntimeRewirePhase(phase, ctx) {
+export function applyRuntimeRetirementPhase(phase, ctx) {
     if (ctx) {
         applyRuntimeMigrationItems(phase.items, ctx);
     }
@@ -144,13 +291,72 @@ export function applyRuntimeRewirePhase(phase, ctx) {
 }
 /** Whether `app/` under app-home still carries a managed bundle worth removing during v2→v3 cleanup. */
 export function hasManagedBundleEvidence(managedAppRoot) {
-    // v3 npm-managed installs write BUNDLE_MARKER at pack/refresh time.
-    if (isFile(path.join(managedAppRoot, BUNDLE_MARKER))) {
-        return true;
+    const marker = path.join(managedAppRoot, BUNDLE_MARKER);
+    if (!isFile(marker))
+        return false;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(marker, "utf8"));
+        return parsed.schemaVersion === "agentera.bundle.v1" && typeof parsed.version === "string";
+    }
+    catch {
+        return false;
     }
-    // Legacy v2 Python-managed installs lacked the marker but always shipped this pair.
-    return (isFile(path.join(managedAppRoot, "scripts", "agentera")) &&
-        isFile(path.join(managedAppRoot, "skills", "agentera", "SKILL.md")));
+}
+const SUPPORTED_V2_BUNDLE_INVENTORY_BY_MAJOR = {
+    "2": {
+        [BUNDLE_MARKER]: "file",
+        "registry.json": "file",
+        scripts: "directory",
+        "scripts/agentera": "file",
+        skills: "directory",
+        "skills/agentera": "directory",
+        "skills/agentera/SKILL.md": "file",
+    },
+};
+function markedBundleInventoryViolations(managedAppRoot) {
+    let version;
+    try {
+        const marker = JSON.parse(fs.readFileSync(path.join(managedAppRoot, BUNDLE_MARKER), "utf8"));
+        version = typeof marker.version === "string" ? marker.version : "";
+    }
+    catch {
+        return ["bundle marker is unreadable"];
+    }
+    const inventory = SUPPORTED_V2_BUNDLE_INVENTORY_BY_MAJOR[version.split(".")[0] ?? ""];
+    if (!inventory)
+        return [`bundle version ${version || "missing"} has no supported cleanup inventory`];
+    const actual = new Map();
+    const walk = (directory, prefix = "") => {
+        for (const name of fs.readdirSync(directory).sort()) {
+            const destination = path.join(directory, name);
+            const relative = prefix ? `${prefix}/${name}` : name;
+            const stat = fs.lstatSync(destination);
+            const kind = stat.isSymbolicLink()
+                ? "symlink"
+                : stat.isFile()
+                    ? "file"
+                    : stat.isDirectory()
+                        ? "directory"
+                        : "other";
+            actual.set(relative, kind);
+            if (kind === "directory")
+                walk(destination, relative);
+        }
+    };
+    walk(managedAppRoot);
+    const violations = [];
+    for (const [relative, kind] of actual) {
+        const expected = inventory[relative];
+        if (!expected)
+            violations.push(`unknown ${kind} ${relative}`);
+        else if (expected !== kind)
+            violations.push(`${relative} must be ${expected}, found ${kind}`);
+    }
+    for (const [relative, kind] of Object.entries(inventory)) {
+        if (!actual.has(relative))
+            violations.push(`missing ${kind} ${relative}`);
+    }
+    return violations.sort();
 }
 function listManagedBundlePreview(managedAppRoot, limit = 20) {
     if (!pathExists(managedAppRoot)) {
@@ -185,7 +391,17 @@ export function planCleanupPhase(ctx) {
         env: ctx.env,
     });
     const preserved = preflight.preservedAbsolutePaths;
-    const unknown = appHomeHasUnrecognizedEntriesWithPreflight(appHome, preflight);
+    const installedHookItems = planInstalledHooksRetirementItems(ctx).filter((item) => item.status !== "noop"
+        && item.source !== undefined
+        && !item.source.startsWith(`${managedAppRoot}${path.sep}`));
+    const hasOwnedRootHooks = installedHookItems.some((item) => item.source?.startsWith(`${path.join(appHome, "hooks")}${path.sep}`));
+    const unknown = appHomeHasUnrecognizedEntriesWithPreflight(appHome, preflight)
+        .filter((name) => !(name === "hooks" && hasOwnedRootHooks));
+    const managedBundle = hasManagedBundleEvidence(managedAppRoot);
+    const refreshAuthorized = managedBundle
+        || hasBundleRootEvidence(roots.activeBundleRoot)
+        || (pathExists(appHome) && fs.readdirSync(appHome).length === 0);
+    const appRootUnknown = managedBundle ? markedBundleInventoryViolations(managedAppRoot) : [];
     const items = [
         ...preflight.handoffCatalog.map((entry) => ({
             status: "noop",
@@ -194,9 +410,12 @@ export function planCleanupPhase(ctx) {
             preserved: entry.entries,
             message: handoffCatalogMessage(entry),
         })),
-        ...planAppContentRefreshItems(ctx),
         ...planLegacyAgentCleanupItems(ctx),
         ...planLegacyCapabilityAgentCleanupItems(ctx),
+        ...installedHookItems,
+        ...(refreshAuthorized
+            ? planAppContentRefreshItems(ctx).filter((item) => item.action === "refresh-app-content")
+            : []),
     ];
     if (unknown.length > 0 && !ctx.force) {
         items.push({
@@ -204,18 +423,39 @@ export function planCleanupPhase(ctx) {
             action: "remove-managed-app-home",
             source: appHome,
             preserved,
-            message: "app home contains unrecognized entries outside preserved user state; cleanup blocked without --force",
+            message: `app home has unrecognized entries (not preserved user state or managed app content): ${unknown.join(", ")}; cleanup blocked without --force`,
+        });
+        return summarizePhase("cleanup", items);
+    }
+    if (appRootUnknown.length > 0) {
+        items.push({
+            status: "blocked",
+            action: "remove-managed-app-home",
+            source: managedAppRoot,
+            target: appHome,
+            preserved: [managedAppRoot],
+            message: `managed app bundle does not match the supported v2 recursive inventory (${appRootUnknown.slice(0, 10).join(", ")}${appRootUnknown.length > 10 ? `; ${appRootUnknown.length - 10} more` : ""}); cleanup preserved the entire app directory for manual review`,
         });
         return summarizePhase("cleanup", items);
     }
-    if (!hasManagedBundleEvidence(managedAppRoot)) {
+    if (!managedBundle) {
+        if (pathExists(managedAppRoot)) {
+            items.push({
+                status: "blocked",
+                action: "remove-managed-app-home",
+                source: managedAppRoot,
+                target: appHome,
+                message: `app directory preserved because ${BUNDLE_MARKER} ownership evidence is missing or invalid; review it manually`,
+            });
+            return summarizePhase("cleanup", items);
+        }
         if (items.length === 0) {
             return summarizePhase("cleanup", [], "no managed Python app-home bundle to remove");
         }
         return summarizePhase("cleanup", items);
     }
     const removedPreview = listManagedBundlePreview(managedAppRoot);
-    items.push({
+    const cleanupItem = {
         status: "pending",
         action: "remove-managed-app-home",
         source: managedAppRoot,
@@ -223,32 +463,36 @@ export function planCleanupPhase(ctx) {
         preserved,
         removedPreview,
         message: "will remove managed Python app-home bundle under app/ while preserving user state at app-home root",
-    });
-    return summarizePhase("cleanup", items);
-}
-function removeDirectoryRecursive(dir) {
-    if (!pathExists(dir)) {
-        return;
+    };
+    const evidenceError = bindMigrationTree(cleanupItem, managedAppRoot, [appHome]);
+    if (evidenceError) {
+        cleanupItem.status = "blocked";
+        cleanupItem.message = `managed app cleanup preserved the bundle: ${evidenceError}; review the unsafe path manually`;
     }
-    fs.rmSync(dir, { recursive: true, force: true });
+    items.push(cleanupItem);
+    return summarizePhase("cleanup", items);
 }
 export function applyCleanupPhase(phase, ctx) {
     if (ctx) {
+        applyLegacyAgentCleanupItems(phase.items, ctx);
+        applyInstalledHooksRetirementItems(phase.items, ctx);
         applyAppContentRefreshItems(phase.items, ctx);
     }
-    applyLegacyAgentCleanupItems(phase.items);
     for (const item of phase.items) {
         if (item.status !== "pending" || item.action !== "remove-managed-app-home" || !item.source) {
             continue;
         }
         try {
-            removeDirectoryRecursive(item.source);
+            if (process.env.NODE_ENV === "test" && process.env.AGENTERA_FAULT_INJECT_V2_CLEANUP_FAILURE === "1") {
+                throw new Error("simulated post-marker cleanup failure");
+            }
+            removeBoundMigrationTree(item);
             item.status = "applied";
             item.message = "managed Python app-home bundle removed; user state preserved";
         }
         catch (exc) {
-            item.status = "failed";
-            item.message = `cleanup failed: ${exc.message}`;
+            item.status = "blocked";
+            item.message = `cleanup preserved the managed app bundle: ${exc.message}; rerun migration and review it manually`;
         }
     }
     const updated = summarizePhase("cleanup", phase.items, phase.message);
@@ -258,25 +502,24 @@ export function applyCleanupPhase(phase, ctx) {
 export function dryRunMigration(ctx) {
     return {
         artifacts: planArtifactsPhase(ctx.project),
-        runtime: planRuntimeRewirePhase(ctx),
+        runtime: planRuntimeRetirementPhase(ctx),
         cleanup: planCleanupPhase(ctx),
     };
 }
 export function applyMigrationPhases(ctx, preview, only = ["artifacts", "runtime", "cleanup"]) {
     const result = {
-        artifacts: { ...preview.artifacts, items: preview.artifacts.items.map((item) => ({ ...item })) },
-        runtime: { ...preview.runtime, items: preview.runtime.items.map((item) => ({ ...item })) },
-        cleanup: { ...preview.cleanup, items: preview.cleanup.items.map((item) => ({ ...item })) },
+        artifacts: { ...preview.artifacts, items: preview.artifacts.items.map(cloneMigrationItem) },
+        runtime: { ...preview.runtime, items: preview.runtime.items.map(cloneMigrationItem) },
+        cleanup: { ...preview.cleanup, items: preview.cleanup.items.map(cloneMigrationItem) },
     };
     if (only.includes("artifacts")) {
         applyArtifactsPhase(result.artifacts, ctx.project, ctx.force);
     }
     if (only.includes("runtime")) {
-        applyRuntimeRewirePhase(result.runtime, ctx);
+        applyRuntimeRetirementPhase(result.runtime, ctx);
     }
     if (only.includes("cleanup")) {
         applyCleanupPhase(result.cleanup, ctx);
     }
     return result;
 }
-//# sourceMappingURL=migrateArtifactsV2ToV3.js.map

package/dist/upgrade/migrationPublication.js

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import { observeLifecyclePath, publishLifecycleResource, removeLifecycleResource, verifyLifecycleResourceAtPublication, withPinnedLifecycleDirectory, } from "../runtime/lifecyclePublication.js";
+const evidenceByItem = new WeakMap();
+const MIGRATION_EVIDENCE = Symbol.for("agentera.migrationMutationEvidence");
+function evidenceFor(item) {
+    const existing = evidenceByItem.get(item) ?? item[MIGRATION_EVIDENCE];
+    if (existing)
+        return existing;
+    const created = { resources: {} };
+    evidenceByItem.set(item, created);
+    item[MIGRATION_EVIDENCE] = created;
+    return created;
+}
+function readEvidence(item) {
+    return evidenceByItem.get(item) ?? item[MIGRATION_EVIDENCE];
+}
+export function cloneMigrationItem(item) {
+    const clone = { ...item };
+    const evidence = readEvidence(item);
+    if (evidence) {
+        evidenceByItem.set(clone, evidence);
+        clone[MIGRATION_EVIDENCE] = evidence;
+    }
+    return clone;
+}
+function observationError(destination, observation, expectedKind) {
+    if (observation.unsafeReason)
+        return observation.unsafeReason;
+    if (!observation.parentComplete)
+        return `parent chain is incomplete for ${destination}`;
+    if (observation.kind !== expectedKind || !observation.identity || !observation.fingerprint) {
+        return `${destination} is not an observable ${expectedKind}`;
+    }
+    return null;
+}
+export function bindMigrationResource(item, role, destination, allowedRoots, kind) {
+    const observation = observeLifecyclePath(destination, allowedRoots);
+    const error = observationError(destination, observation, kind);
+    if (error)
+        return error;
+    evidenceFor(item).resources[role] = { destination, kind, observation };
+    return null;
+}
+function boundResource(item, role) {
+    const resource = readEvidence(item)?.resources[role];
+    if (!resource)
+        throw new Error(`migration ${role} publication evidence is missing`);
+    return resource;
+}
+export function verifyBoundMigrationResource(item, role) {
+    const resource = boundResource(item, role);
+    verifyLifecycleResourceAtPublication({ id: `${item.action}.${role}`, destination: resource.destination, kind: resource.kind }, resource.observation);
+}
+export function withBoundMigrationDirectory(item, role, callback, hook) {
+    const resource = boundResource(item, role);
+    if (resource.kind !== "directory")
+        throw new Error(`migration ${role} is not a directory`);
+    return withPinnedLifecycleDirectory({ id: `${item.action}.${role}`, destination: resource.destination, kind: "directory" }, resource.observation, callback, hook);
+}
+export function updateBoundMigrationFile(item, role, content) {
+    const resource = boundResource(item, role);
+    if (resource.kind !== "file")
+        throw new Error(`migration ${role} is not a file`);
+    publishLifecycleResource({ id: `${item.action}.${role}`, destination: resource.destination, kind: "file", content }, "update", resource.observation);
+}
+export function removeBoundMigrationResource(item, role) {
+    const resource = boundResource(item, role);
+    removeLifecycleResource({ id: `${item.action}.${role}`, destination: resource.destination, kind: resource.kind }, resource.observation);
+}
+function walkTree(root) {
+    const entries = [];
+    const walk = (destination) => {
+        const stat = fs.lstatSync(destination);
+        const kind = stat.isSymbolicLink()
+            ? "symlink"
+            : stat.isFile()
+                ? "file"
+                : stat.isDirectory()
+                    ? "directory"
+                    : (() => { throw new Error(`unsupported bundle entry type at ${destination}`); })();
+        entries.push({ destination, kind });
+        if (kind === "directory") {
+            for (const name of fs.readdirSync(destination).sort())
+                walk(path.join(destination, name));
+        }
+    };
+    walk(root);
+    return entries;
+}
+export function bindMigrationTree(item, root, allowedRoots) {
+    try {
+        const tree = walkTree(root).map(({ destination, kind }) => {
+            const observation = observeLifecyclePath(destination, allowedRoots);
+            const error = observationError(destination, observation, kind);
+            if (error)
+                throw new Error(error);
+            return { destination, kind, observation };
+        });
+        evidenceFor(item).tree = tree;
+        return null;
+    }
+    catch (error) {
+        return error.message;
+    }
+}
+export function removeBoundMigrationTree(item) {
+    const tree = readEvidence(item)?.tree;
+    if (!tree)
+        throw new Error("migration cleanup tree evidence is missing");
+    const current = walkTree(tree[0].destination);
+    if (current.length !== tree.length
+        || current.some((entry, index) => entry.destination !== tree[index]?.destination || entry.kind !== tree[index]?.kind)) {
+        throw new Error("managed app cleanup set changed after preview");
+    }
+    for (const entry of tree) {
+        verifyLifecycleResourceAtPublication({ id: `${item.action}.verify`, destination: entry.destination, kind: entry.kind }, entry.observation);
+    }
+    for (const entry of [...tree].reverse()) {
+        removeLifecycleResource({ id: `${item.action}.remove`, destination: entry.destination, kind: entry.kind }, entry.observation);
+    }
+}