@deksden-com/dd-flow-cli 0.9.0-beta.143 → 0.9.0-beta.145

package/dist/services/memory-verification-receipt.js

@@ -137,15 +137,16 @@ function accepted(context, scope) {
         return refuse("invalid_receipt_json");
     }
     if (!receipt || typeof receipt !== "object" || Array.isArray(receipt) || hybridDigest({ ...receipt, checks: undefined }) !== hybridDigest({ schema_id: "dd-flow/memory-verification-acceptance@1", run_id: scope.runId, stage: "verify", project_id: scope.projectId,
-        attempt: selected.attempt, input_sha256: selected.input_sha256, result_sha256: data.result.sha256 }) || data.data_schema_id !== "dd-flow/mb-init-verify-result@1"
+        attempt: selected.attempt, input_sha256: selected.input_sha256, result_sha256: data.result.sha256 }) || !["dd-flow/mb-init-verify-result@1", "dd-flow/mb-upgrade-stage-result@1"].includes(data.data_schema_id ?? "")
         || data.input_sha256 !== selected.input_sha256)
         refuse("accepted_receipt_changed");
     const value = JSON.parse(data.bytes.toString("utf8"));
-    const compose = readAcceptedStageData(context, { ...scope, stage: "compose" }), composed = JSON.parse(compose.bytes.toString("utf8"));
-    if (compose.data_schema_id !== "dd-flow/mb-init-compose-result@1"
-        || composed.schema_id !== compose.data_schema_id || composed.stage !== "compose" || composed.run_id !== scope.runId
+    const authoring = data.data_schema_id === "dd-flow/mb-upgrade-stage-result@1" ? "upgrade" : "compose";
+    const compose = readAcceptedStageData(context, { ...scope, stage: authoring }), composed = JSON.parse(compose.bytes.toString("utf8"));
+    if (compose.data_schema_id !== (authoring === "upgrade" ? data.data_schema_id : "dd-flow/mb-init-compose-result@1")
+        || composed.schema_id !== compose.data_schema_id || composed.stage !== authoring || composed.run_id !== scope.runId
         || composed.outcome !== "accepted" || composed.input_sha256 !== compose.input_sha256
-        || hybridDigest(value.predecessors) !== hybridDigest([{ stage: "compose", result: compose.result, input_sha256: compose.input_sha256 }]))
+        || hybridDigest(value.predecessors) !== hybridDigest([{ stage: authoring, result: compose.result, input_sha256: compose.input_sha256 }]))
         refuse("accepted_predecessor_changed");
     if (value.stage !== "verify" || value.run_id !== scope.runId || !["accepted", "needs_repair"].includes(value.outcome) || value.input_sha256 !== selected.input_sha256
         || !Array.isArray(receipt.checks) || receipt.checks.some(reference => !reference || typeof reference !== "object" || Array.isArray(reference)

package/dist/services/memory-verify-handler.js

@@ -24,14 +24,14 @@ function refuse(reason) {
  */
 export function runMemoryVerificationChecks(context, input) {
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.successor("compose", "accepted") !== "verify"
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || bundle.descriptor.successor(bundle.descriptor.descriptor.id === "mb-upgrade" ? "upgrade" : "compose", "accepted") !== "verify"
         || bundle.descriptor.successor("verify", "accepted") !== "review")
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
     const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
     if (index.current_stage !== "verify" || index.stage_runs.find((stage) => stage.stage === "verify")?.status !== "running")
         refuse("active_verification_required");
-    return PreparedMemoryVerificationChecks.prepare(context, { ...scope, execution: bundle.execution, flow: bundle.descriptor }).execute(context);
+    return PreparedMemoryVerificationChecks.prepare(context, { ...scope, execution: bundle.execution, flow: bundle.descriptor, bundle }).execute(context);
 }
 /** Productive entry implementation, not registered until the complete six-stage
  * memory group is ready. Checks and semantic assessment acceptance belong to
@@ -41,22 +41,23 @@ export function startMemoryVerification(context, input) {
     if (!(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
         refuse("invalid_input_bytes");
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.successor("compose", "accepted") !== "verify"
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || bundle.descriptor.successor(bundle.descriptor.descriptor.id === "mb-upgrade" ? "upgrade" : "compose", "accepted") !== "verify"
         || bundle.descriptor.successor("verify", "accepted") !== "review")
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId, stage: "verify" };
     const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
     if (index.stage_runs.find((stage) => stage.stage === "verify")?.status === "done")
         refuse("use_accepted_finish_replay");
-    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
-    const inherited = context.db.readSnapshot(() => ({ compose: readAcceptedStageData(context, { ...scope, stage: "compose" }), preflight: readAcceptedStageData(context, { ...scope, stage: "preflight" }) }));
+    const upgrade = bundle.descriptor.descriptor.id === "mb-upgrade", authoring = upgrade ? "upgrade" : "compose";
+    const preservation = upgrade ? PreparedAcceptedMemoryComposition.prepare(context, { scope, bundle }) : PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const inherited = context.db.readSnapshot(() => ({ compose: readAcceptedStageData(context, { ...scope, stage: authoring }), preflight: readAcceptedStageData(context, { ...scope, stage: "preflight" }) }));
     const compose = JSON.parse(inherited.compose.bytes.toString("utf8")), preflight = JSON.parse(inherited.preflight.bytes.toString("utf8"));
-    if (compose.schema_id !== "dd-flow/mb-init-compose-result@1" || compose.run_id !== input.runId || compose.outcome !== "accepted"
-        || preflight.schema_id !== "dd-flow/mb-init-preflight-result@1" || preflight.run_id !== input.runId || preflight.outcome !== "accepted")
+    if (compose.schema_id !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : "dd-flow/mb-init-compose-result@1") || compose.run_id !== input.runId || compose.outcome !== "accepted"
+        || preflight.schema_id !== (upgrade ? compose.schema_id : "dd-flow/mb-init-preflight-result@1") || preflight.run_id !== input.runId || preflight.outcome !== "accepted")
         refuse("accepted_composition_and_baseline_required");
     const fence = (writer) => {
         preservation.assertCustody(writer);
-        if (readAcceptedStageData(writer, { ...scope, stage: "compose" }).authority_sha256 !== inherited.compose.authority_sha256
+        if (readAcceptedStageData(writer, { ...scope, stage: authoring }).authority_sha256 !== inherited.compose.authority_sha256
             || readAcceptedStageData(writer, { ...scope, stage: "preflight" }).authority_sha256 !== inherited.preflight.authority_sha256)
             refuse("inherited_custody_changed");
     };
@@ -75,7 +76,7 @@ export function finishMemoryVerification(context, input) {
     if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
         refuse("invalid_result_bytes");
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.successor("compose", "accepted") !== "verify"
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || bundle.descriptor.successor(bundle.descriptor.descriptor.id === "mb-upgrade" ? "upgrade" : "compose", "accepted") !== "verify"
         || bundle.descriptor.successor("verify", "accepted") !== "review")
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
@@ -99,11 +100,11 @@ export function finishMemoryVerification(context, input) {
     }
     const composition = PreparedAcceptedMemoryComposition.prepare(context, { scope, bundle }), compose = composition.result();
     const composedUnits = compose.value().units;
-    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
-    const policy = PreparedMemoryVerificationChecks.prepare(context, { ...scope, execution: bundle.execution, flow: bundle.descriptor });
+    const preservation = bundle.descriptor.descriptor.id === "mb-upgrade" ? composition : PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const policy = PreparedMemoryVerificationChecks.prepare(context, { ...scope, execution: bundle.execution, flow: bundle.descriptor, bundle, composition });
     const checks = policy.evidence(context, "diagnostic");
     const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, stage: "verify", flow: bundle.descriptor, execution: bundle.execution, bundle,
-        sources: composition.captureSources(context, input.bytes, checks), checks });
+        sources: composition.captureSources(context, input.bytes, checks), checks, historicalEvidence: composition.historicalEvidence() });
     let proposal;
     try {
         proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes));
@@ -114,7 +115,8 @@ export function finishMemoryVerification(context, input) {
     }
     const references = checks.sourceReferences().map(({ path, sha256 }) => ({ path, sha256 }));
     const result = PreparedMemoryStageResult.prepare(Buffer.from(JSON.stringify(projectMemoryVerificationChecks(projectMemoryVerificationArtifacts(proposal, composedUnits, composition.outputReferences(), createHash("sha256").update(input.bytes).digest("hex")), references, bundle.descriptor.stage("verify").directory, createHash("sha256").update(input.bytes).digest("hex")))), bundle.descriptor, binding.binding());
-    const acceptance = PreparedMemoryVerificationAcceptance.prepare({ scope, result, compose, checks, composition, roots: bundle.execution.snapshot().scope });
+    const acceptance = PreparedMemoryVerificationAcceptance.prepare({ scope, result, compose, checks, composition, roots: bundle.execution.snapshot().scope,
+        proposalSha256: createHash("sha256").update(input.bytes).digest("hex") });
     const receipt = PreparedMemoryVerificationReceipt.prepare(context, { scope, result, checks, acceptance });
     const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "verify", bytes: result.bytes() });
     composition.revalidate(context);

package/dist/services/memory-work-result-json.js

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+/** Syntax only: the caller still owns bounds, assignment and evidence checks. */
+export function parseMemoryWorkResultProposal(bytes, code) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new AppError(code, "Memory result proposal is not valid UTF-8 JSON. Correct only this proposal using its assigned packet; do not rerun settled work or change retained inputs", 2, { reason: "invalid_result_json", phase: "prepare", effect: "no_effect", recoverable: true,
+            result_sha256: createHash("sha256").update(bytes).digest("hex") });
+    }
+}

package/dist/services/memory-work-result-preparation.js

@@ -10,7 +10,7 @@ import { restoreMemoryRepairPublicationFromStage, prepareMemorySecondRepairPubli
  * from worker JSON, mutable schemas, caller profile or a supplied request key.
  * Preparation is read-only and occurs before the settlement writer.
  */
-export function prepareRegisteredMemoryWorkResult(context, work, result) {
+export function prepareRegisteredMemoryWorkResult(context, work, result, progress) {
     if (!["dd-flow/memory-composition-work-result@1", "dd-flow/memory-review-work-result@1", "dd-flow/memory-repair-work-result@1"].includes(work.result_schema ?? ""))
         return null;
     const bytes = Buffer.from(result, "utf8");
@@ -44,15 +44,16 @@ export function prepareRegisteredMemoryWorkResult(context, work, result) {
         return PreparedPublishedMemoryRepairWorkResult.prepare(context, publication);
     }
     if (work.result_schema === "dd-flow/memory-review-work-result@1") {
-        return PreparedRegisteredMemoryReviewWorkResult.prepare(context, { workId: work.work_id, bytes });
+        return PreparedRegisteredMemoryReviewWorkResult.prepare(context, { workId: work.work_id, bytes, ...(progress ? { progress } : {}) });
     }
     const run = context.db.get("SELECT project_root FROM runs WHERE project_id=? AND id=?", [work.project_id, work.run_id]);
     const bundle = run && readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: work.run_id });
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
         throw new AppError("memory_work_result_preparation_required", "Composition finish requires its retained memory flow", 1, { effect: "no_effect" });
+    const stage = bundle.descriptor.descriptor.id === "mb-init" ? "compose" : "upgrade";
     const custody = readWorkBatchCustody(context, work.work_id);
     const registration = selectMemoryCompositionRegistration(context, {
-        project_id: work.project_id, run_id: work.run_id, stage: "compose", attempt: custody.scope.attempt,
+        project_id: work.project_id, run_id: work.run_id, stage, attempt: custody.scope.attempt,
         cycle: custody.scope.cycle, parent_work_id: custody.scope.parent_work_id
     });
     return PreparedRegisteredMemoryCompositionWorkResult.prepareFromStageCustody(context, bytes, bundle.engine(), {

package/dist/services/merge-server.js

@@ -1,6 +1,6 @@
 import { managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
-import { continueProviderCapacity } from "./provider-capacity.js";
+import { continueProviderCapacity, ownedProviderBoundary } from "./provider-capacity.js";
 import { errorRecord } from "./run-controller-state.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -185,7 +185,9 @@ async function dispatch(context, input) {
                     if (!["created", "running", "paused", "completed"].includes(context.db.get("SELECT status FROM works WHERE work_id = ?", [input.request.executor_work_id])?.status ?? ""))
                         throw new AppError("capacity_continuation_blocked", "MERGE Work has failed or lost its binding", 1);
                 },
-                decision: () => {
+                decision: (boundary) => {
+                    if (boundary && !ownedProviderBoundary(context, { projectId: input.request.project_id, runId: input.request.run_id, stage: "merge", sessionId, generation, workId: input.request.executor_work_id, scope: "stage" }, boundary))
+                        return "reconciliation_blocked";
                     const status = context.db.get("SELECT status FROM merge_requests WHERE merge_request_id = ?", [input.request.merge_request_id])?.status;
                     const workStatus = context.db.get("SELECT status FROM works WHERE work_id = ?", [input.request.executor_work_id])?.status;
                     return status === "completed" ? "completed" : status === "action_required" || workStatus === "paused" ? "paused" : "continue";

package/dist/services/migrations.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import semver from "semver";
 import { AppError } from "../shared/errors.js";
 import { requireProjectByRoot } from "./projects.js";
 import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-status.js";
@@ -12,11 +14,16 @@ import { classifyCliOperation } from "./cli-operation-classifier.js";
 import { compatibilityContexts, selectEngine } from "./engines.js";
 import { getCliBuildInfo } from "./build-info.js";
 import { prepareJsonFile } from "../cli/input-preparation.js";
+import { validateSchema } from "./schema-validation.js";
+import { PreparedMemoryInitRuntimeStorage } from "./memory-init-storage.js";
+import { PreparedMemoryInitResourceStorage } from "./memory-init-resource-storage.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { resourceHome } from "./managed-processes.js";
 export function assessMigrationImpact(context, input) {
     const root = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd: process.cwd() });
     if (!root.root)
         throw new AppError("not_found", `Project root does not exist: ${input.projectRoot}`, 1);
-    const canon = resolveCanonRoot(context);
+    const canon = upgradeCanon(context);
     if (!canon.ok || !canon.canon)
         throw new AppError("canon_unavailable", "Cannot resolve canonical Memory Bank for upgrade impact assessment", 1, { blockers: canon.blockers, bootstrap: canon.bootstrap });
     const status = getProjectVersionStatus({ projectRoot: root.root, rootSource: root.root_source, canon: { root: canon.canon.root, metadata: canon.canon.metadata } });
@@ -24,53 +31,65 @@ export function assessMigrationImpact(context, input) {
     const to = input.targetVersion ?? canon.canon.version;
     const forced = input.mode === "full_migration";
     const impacts = readImpacts(path.join(canon.canon.memorybank_root, "release-impact"));
-    const chain = [];
+    const resolved = from && to ? adjacentMigrationChain(from, to, impacts) : null;
+    const chain = resolved?.status === "ok"
+        ? resolved.steps.map(step => impacts.find(item => item.from_version === step.from && item.to_version === step.to))
+        : [];
     const domains = new Set();
     const blockers = [];
     let mode = "patch";
     if (!from || !to)
         blockers.push("project or canonical Memory Bank version is unavailable");
-    let current = from;
-    while (current && to && current !== to) {
-        const impact = impacts.find((item) => item.from_version === current);
-        if (!impact) {
-            blockers.push(`missing adjacent release impact from ${current}`);
-            break;
-        }
-        chain.push(impact);
+    if (to !== canon.canon.version)
+        blockers.push("requested target version does not match the selected canon");
+    if (resolved?.status === "unsupported")
+        blockers.push(resolved.reason ?? "release impact chain is unsupported");
+    for (const impact of chain) {
         for (const domain of impact.domains)
             domains.add(domain);
         mode = stricterMode(mode, impact.minimum_upgrade_mode);
         if (impact.path_migration || impact.runtime_migration)
             mode = "full_migration";
-        current = impact.to_version;
     }
-    if (current && to && current !== to)
-        blockers.push(`release impact chain does not reach ${to}`);
-    if (status?.flow_pack.status !== "present" && from !== to)
+    if (status?.flow_pack.status !== "present")
         blockers.push("project flow-pack provenance is not present");
+    else {
+        try {
+            const file = path.resolve(root.root, status.flow_pack.manifest_path);
+            const prepared = prepareJsonFile(file, "Project flow-pack provenance");
+            validateSchema({ schemaName: "project-flow-pack-manifest", file, data: prepared.value,
+                schemaDir: fileURLToPath(new URL("../schemas/", import.meta.url)) });
+            if (!/^[a-f0-9]{40}$/.test(status.flow_pack.source_commit ?? "")
+                || status.flow_pack.canon_version_at_source_commit !== from)
+                blockers.push("project flow-pack provenance does not match its declared current version and commit");
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || !["schema_validation", "invalid_json", "validation"].includes(error.code)
+                && !error.code.startsWith("input_file_"))
+                throw error;
+            blockers.push("project flow-pack provenance is invalid");
+        }
+    }
     if (blockers.length > 0)
         mode = "full_migration";
     if (forced)
         mode = "full_migration";
     return { ok: true, schema_id: "dd-flow/mb-upgrade-impact-assessment@1", project_root: root.root, source_version: from, target_version: to, mode, forced_full_migration: forced, chain, domains: [...domains].sort(), blockers, required_checks: [...new Set(chain.flatMap((item) => item.required_checks))], next_action: mode === "full_migration" ? "run full mb-upgrade contour" : "run selected mb-upgrade contour" };
 }
-function readImpacts(dir) {
+export function readImpacts(dir) {
     if (!fs.existsSync(dir))
         return [];
-    return fs.readdirSync(dir).filter((file) => file.endsWith(".json")).flatMap((file) => {
+    return fs.readdirSync(dir).filter(file => file.endsWith(".json")).sort().map(file => {
+        const source = path.join(dir, file);
         try {
-            const value = JSON.parse(fs.readFileSync(path.join(dir, file), "utf8"));
-            if (value.schema_id !== "dd-flow/release-impact@1")
-                return [];
-            if (typeof value.from_version !== "string" || typeof value.to_version !== "string" || !Array.isArray(value.domains) || !Array.isArray(value.required_checks))
-                return [];
-            if (!["patch", "targeted_minor", "full_migration"].includes(String(value.minimum_upgrade_mode)))
-                return [];
-            return [{ from_version: value.from_version, to_version: value.to_version, minimum_upgrade_mode: value.minimum_upgrade_mode, domains: value.domains.filter((item) => typeof item === "string"), path_migration: value.path_migration === true, runtime_migration: value.runtime_migration === true, required_checks: value.required_checks.filter((item) => typeof item === "string") }];
+            const prepared = prepareJsonFile(source, "Canonical release impact");
+            validateSchema({ schemaName: "release-impact", file: prepared.file, data: prepared.value,
+                schemaDir: fileURLToPath(new URL("../schemas/", import.meta.url)) });
+            return { ...prepared.value, source_reference: { path: prepared.file,
+                    sha256: crypto.createHash("sha256").update(prepared.text).digest("hex") } };
         }
-        catch {
-            return [];
+        catch (error) {
+            throw new AppError("release_impact_invalid", "Canonical release impact is invalid; it cannot authorize a lightweight upgrade", 1, { file: source, effect: "no_effect", cause: error instanceof AppError ? error.code : "unreadable_release_impact" });
         }
     });
 }
@@ -267,7 +286,7 @@ function applyPreparedMigration(context, prepared, writeDb) {
     }
     return { ok: true, schema_id: "dd-flow/mb-upgrade-migration-apply@1", status: "applied", changed: true, backup: verifiedBackup, recovery: result };
 }
-export function assertUpgradeRunStorageReady(context, projectRoot) {
+export function assertUpgradeRunStorageReady(context, projectRoot, engine) {
     const project = context.db.get("SELECT id FROM projects WHERE root = ?", [resolveProjectRoot(projectRoot)]);
     if (!project)
         throw new AppError("migration_not_applied", "mb-upgrade RUN requires a registered project with explicit migration apply", 1);
@@ -277,12 +296,57 @@ export function assertUpgradeRunStorageReady(context, projectRoot) {
     if (!source || !target)
         throw new AppError("migration_not_applied", "mb-upgrade RUN requires source and target Memory Bank versions", 1);
     const applied = context.db.get("SELECT value_json FROM runtime_config WHERE key = ?", [applyKey(project.id, source, target)]);
-    if (!applied)
+    if (!applied || engine !== undefined) {
+        const assessment = assessMigrationImpact(context, { projectRoot });
+        const blockers = assessment.blockers;
+        const chain = assessment.chain;
+        if (!blockers.length && (engine !== undefined || chain.every(step => !step.runtime_migration))) {
+            const canon = upgradeCanon(context).canon;
+            const contract = prepareJsonFile(path.join(canon.flow_root, "flow-contract.json"), "Target flow contract");
+            let selectedEngineStorage;
+            if (engine !== undefined) {
+                if (!(engine instanceof AdmittedFrozenEngine))
+                    throw new AppError("upgrade_storage_incompatible", "Upgrade requires an admitted selected engine", 1, { effect: "no_effect" });
+                const compatibility = prepareJsonFile(path.join(canon.flow_root, "compatibility.json"), "Target engine compatibility");
+                validateSchema({ schemaName: "compatibility", file: compatibility.file, data: compatibility.value,
+                    schemaDir: fileURLToPath(new URL("../schemas/", import.meta.url)) });
+                const manifest = engine.manifest();
+                if (compatibility.value.memory_bank_version !== target || compatibility.value.dd_flow_cli.flow_contract !== contract.value.id
+                    || manifest.package_name !== compatibility.value.dd_flow_cli.package_name || !semver.valid(compatibility.value.dd_flow_cli.min_version)
+                    || semver.lt(manifest.package_version, compatibility.value.dd_flow_cli.min_version)
+                    || manifest.package_name !== compatibility.value.engine.package_name
+                    || !semver.satisfies(manifest.package_version, compatibility.value.engine.version_range, { includePrerelease: true }))
+                    throw new AppError("upgrade_storage_incompatible", "Selected engine is incompatible with target canon", 1, { effect: "no_effect" });
+                selectedEngineStorage = engine.admitMemoryUpgradeStorage(context.ddFlowHome, resourceHome(context));
+            }
+            // Reuse the executing CLI's physical compatibility checks, not version text
+            // or a synthetic apply marker. This does not authorize storage migration.
+            const runOwner = fs.lstatSync(context.db.path);
+            if (!runOwner.isFile() || runOwner.nlink !== 1)
+                throw new AppError("upgrade_storage_incompatible", "Upgrade requires a regular single-linked runtime store", 1, { effect: "no_effect" });
+            const run = PreparedMemoryInitRuntimeStorage.prepareUpgrade(context);
+            const resource = PreparedMemoryInitResourceStorage.prepare(context);
+            const currentOwner = fs.lstatSync(context.db.path);
+            if (currentOwner.dev !== runOwner.dev || currentOwner.ino !== runOwner.ino)
+                throw new AppError("upgrade_storage_changed", "Runtime store changed during upgrade admission", 1, { effect: "no_effect" });
+            const manifest = prepareJsonFile(path.resolve(projectRoot, status.flow_pack.manifest_path), "Current flow-pack provenance");
+            return { schema_id: "dd-flow/mb-upgrade-storage-readiness@1", route: "verified-no-op",
+                source_version: source, target_version: target, chain,
+                current_provenance: { path: manifest.file, sha256: crypto.createHash("sha256").update(manifest.text).digest("hex") },
+                target: { root: canon.root, commit: canon.commit, contract_sha256: crypto.createHash("sha256").update(contract.text).digest("hex") },
+                ...(selectedEngineStorage ? { selected_engine_storage: selectedEngineStorage } : {}),
+                stores: [{ ...run.facts(), store_dev: runOwner.dev, store_ino: runOwner.ino }, resource.facts()].map(store => ({ store_kind: store.store_kind,
+                    store_dev: store.store_dev, store_ino: store.store_ino,
+                    store_path: store.store_path, schema_sha256: store.schema_sha256,
+                    executing_writer_version: store.executing_writer_version })) };
+        }
         throw new AppError("migration_not_applied", "mb-upgrade RUN requires explicit migration apply before RUN creation", 1, {
             source_version: source,
             target_version: target,
+            blockers,
             next_action: "run migration plan, verify and explicit migration apply first"
         });
+    }
     const value = recordValue(parseJsonValue(applied.value_json));
     if (!value || !["applied", "verified_noop"].includes(stringValue(value.status) ?? "")) {
         throw new AppError("migration_not_applied", "mb-upgrade RUN has no successful explicit migration apply evidence", 1, {
@@ -290,6 +354,8 @@ export function assertUpgradeRunStorageReady(context, projectRoot) {
             target_version: target
         });
     }
+    return { schema_id: "dd-flow/mb-upgrade-storage-readiness@1", route: "existing-apply",
+        source_version: source, target_version: target, apply: value };
 }
 export function verifyMigrationReport(_context, input) {
     const filePath = path.resolve(input.file);
@@ -452,61 +518,45 @@ function hasActiveState(active) {
 function applyKey(projectId, source, target) {
     return `mb-upgrade.apply.${projectId}.${source}.${target}`;
 }
-function adjacentMigrationChain(source, target, impacts = []) {
-    if (source === target)
-        return { status: "ok", steps: [] };
-    const sourceParts = parseSemver(source);
-    const targetParts = parseSemver(target);
-    if (!sourceParts || !targetParts) {
+export function adjacentMigrationChain(source, target, impacts = []) {
+    if (semver.valid(source) !== source || semver.valid(target) !== target) {
         return { status: "unsupported", reason: "source or target version is not semver", steps: [] };
     }
-    if (impacts.length > 0) {
-        const steps = [];
-        const visited = new Set();
-        let current = source;
-        while (current !== target) {
-            if (visited.has(current))
-                return { status: "unsupported", reason: "release impact chain contains a cycle", steps: [] };
-            visited.add(current);
-            const impact = impacts.find((item) => item.from_version === current);
-            if (!impact)
-                return { status: "unsupported", reason: `missing adjacent release impact from ${current}`, steps: [] };
-            steps.push({
-                id: `${impact.from_version}-to-${impact.to_version}`,
-                from: impact.from_version,
-                to: impact.to_version,
-                status: "planned",
-                minimum_upgrade_mode: impact.minimum_upgrade_mode,
-                domains: impact.domains,
-                path_migration: impact.path_migration,
-                runtime_migration: impact.runtime_migration,
-                required_checks: impact.required_checks
-            });
-            current = impact.to_version;
-            const next = parseSemver(current);
-            if (!next || compareParts(next, targetParts) > 0) {
-                return { status: "unsupported", reason: `release impact chain overshoots target ${target}`, steps: [] };
-            }
-        }
-        return { status: "ok", steps };
-    }
-    if (sourceParts.major !== targetParts.major) {
-        return { status: "unsupported", reason: "major version migration requires canonical release-impact units", steps: [] };
-    }
-    if (targetParts.minor < sourceParts.minor || (targetParts.minor === sourceParts.minor && targetParts.patch < sourceParts.patch)) {
+    if (semver.gt(source, target))
         return { status: "unsupported", reason: "downgrade migrations are not supported", steps: [] };
-    }
+    if (source === target)
+        return { status: "ok", steps: [] };
     const steps = [];
-    let current = { ...sourceParts };
-    while (compareParts(current, targetParts) < 0) {
-        const next = nextAdjacent(current, targetParts);
+    const visited = new Set();
+    let current = source;
+    while (current !== target) {
+        if (visited.has(current))
+            return { status: "unsupported", reason: "release impact chain contains a cycle", steps: [] };
+        visited.add(current);
+        const matches = impacts.filter(item => item.from_version === current);
+        if (matches.length > 1)
+            return { status: "unsupported", reason: `ambiguous adjacent release impacts from ${current}`, steps: [] };
+        const impact = matches[0];
+        if (!impact)
+            return { status: "unsupported", reason: `missing adjacent release impact from ${current}`, steps: [] };
+        if (semver.valid(impact.to_version) !== impact.to_version || !semver.gt(impact.to_version, current)) {
+            return { status: "unsupported", reason: "release impact chain must advance through valid versions", steps: [] };
+        }
+        if (semver.gt(impact.to_version, target))
+            return { status: "unsupported", reason: `release impact chain overshoots target ${target}`, steps: [] };
         steps.push({
-            id: `${formatParts(current)}-to-${formatParts(next)}`,
-            from: formatParts(current),
-            to: formatParts(next),
-            status: "planned"
+            id: `${impact.from_version}-to-${impact.to_version}`,
+            from: impact.from_version,
+            to: impact.to_version,
+            status: "planned",
+            minimum_upgrade_mode: impact.minimum_upgrade_mode,
+            domains: impact.domains,
+            path_migration: impact.path_migration,
+            runtime_migration: impact.runtime_migration,
+            required_checks: impact.required_checks,
+            ...(impact.source_reference ? { source_reference: impact.source_reference } : {})
         });
-        current = next;
+        current = impact.to_version;
     }
     return { status: "ok", steps };
 }
@@ -556,24 +606,3 @@ function recordValue(value) {
 function stringValue(value) {
     return typeof value === "string" && value.length > 0 ? value : null;
 }
-function parseSemver(value) {
-    const match = value.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)/);
-    if (!match?.[1] || !match[2] || !match[3])
-        return null;
-    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
-}
-function compareParts(left, right) {
-    if (left.major !== right.major)
-        return left.major - right.major;
-    if (left.minor !== right.minor)
-        return left.minor - right.minor;
-    return left.patch - right.patch;
-}
-function nextAdjacent(current, target) {
-    if (current.minor < target.minor)
-        return { major: current.major, minor: current.minor + 1, patch: 0 };
-    return { major: current.major, minor: current.minor, patch: Math.min(current.patch + 1, target.patch) };
-}
-function formatParts(parts) {
-    return `${parts.major}.${parts.minor}.${parts.patch}`;
-}

package/dist/services/physical-startup.js

@@ -0,0 +1,45 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { AppError } from "../shared/errors.js";
+import { createRenewalState, maintenanceRetryable, renewalDelay, renewalFailure, RENEWAL_POLICY } from "../harness-runtime/lib/lease-renewal.mjs";
+import { processStartedAt } from "./managed-processes.js";
+/** Birth and confirmation share one startup horizon. Retrying observations
+ * neither launches another child nor renews an unconfirmed resource lease. */
+export function physicalStartup(databaseDeadlineAt) {
+    const deadline = performance.now() + RENEWAL_POLICY.startupMs;
+    const episode = createRenewalState();
+    const unavailable = () => new AppError("process_ownership_unknown", "Managed physical identity observation is unavailable", 1, { phase: "process_confirmation", effect: "no_effect", native_dispatch_started: false, reason: "physical_identity_unavailable" });
+    async function observe(operation, assertCurrent, leaseExpiresAt) {
+        let last;
+        const remaining = () => Math.max(0, Math.min(deadline - performance.now(), databaseDeadlineAt === undefined ? Infinity : databaseDeadlineAt - Date.now(), leaseExpiresAt === undefined ? Infinity : Date.parse(leaseExpiresAt) - Date.now() - RENEWAL_POLICY.safetyMs));
+        for (;;) {
+            assertCurrent();
+            if (!(remaining() > 0))
+                throw last ?? unavailable();
+            try {
+                const result = operation();
+                assertCurrent();
+                if (!(remaining() > 0))
+                    throw new AppError("process_startup_expired", "Physical observation completed after its original admission horizon", 1, { phase: "process_confirmation", effect: "unknown", native_dispatch_started: false });
+                return result;
+            }
+            catch (error) {
+                // A stale owner/cancellation wins over a transient observation error.
+                assertCurrent();
+                const details = error instanceof AppError ? error.details : null;
+                if (!(error instanceof AppError) || error.code !== "process_ownership_unknown" || details?.reason !== "physical_identity_unavailable" || !maintenanceRetryable(error))
+                    throw error;
+                last = error;
+                renewalFailure(episode);
+                if (!(remaining() > 0))
+                    throw error;
+                await delay(Math.min(renewalDelay(episode), remaining()));
+            }
+        }
+    }
+    return { observe, birth: (assertCurrent) => observe(() => {
+            const started = processStartedAt(process.pid);
+            if (!started)
+                throw unavailable();
+            return { pid: process.pid, pid_started_at: started };
+        }, assertCurrent) };
+}

package/dist/services/project-registry.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { projectRuntimeRoot, resolveProjectRoot } from "../storage/paths.js";
+import { formatFullId, parseFullEntityId, slugFromRoot } from "../domain/entity-ids.js";
+import { appendAudit } from "./audit.js";
+/** Resolve filesystem identity before entering a composite SQL writer. */
+export class PreparedProjectRegistration {
+    #root;
+    constructor(root) { this.#root = root; Object.freeze(this); }
+    static prepare(input) {
+        return new PreparedProjectRegistration(resolveProjectRoot(input.root));
+    }
+    root() { return this.#root; }
+}
+export function registerProject(context, input) {
+    return registerPreparedProject(context, PreparedProjectRegistration.prepare(input));
+}
+/** Metadata-only registration; the composite caller owns its SQL transaction. */
+export function registerPreparedProject(context, prepared) {
+    if (!(prepared instanceof PreparedProjectRegistration))
+        throw new AppError("validation", "Project registration must be prepared", 2);
+    const root = prepared.root();
+    const existing = context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
+    const now = context.now();
+    const project = existing ?? newProjectRecord(context, root, now);
+    if (existing) {
+        context.db.run("UPDATE projects SET status = 'active', updated_at = ? WHERE id = ?", [now, existing.id]);
+    }
+    else {
+        context.db.run("INSERT INTO projects (id, short_id, slug, root, status, state_root, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [
+            project.id,
+            project.short_id,
+            project.slug,
+            project.root,
+            project.status,
+            project.state_root,
+            project.created_at,
+            project.updated_at
+        ]);
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "project.registered",
+            payload: { project_id: project.id, root }
+        });
+    }
+    return { ok: true, project: { ...project, status: "active", updated_at: now }, db_path: context.db.path };
+}
+export function normalizeStoredRoot(root) {
+    const absolute = path.resolve(root);
+    if (fs.existsSync(absolute)) {
+        return fs.realpathSync(absolute);
+    }
+    const parent = path.dirname(absolute);
+    if (fs.existsSync(parent)) {
+        return path.join(fs.realpathSync(parent), path.basename(absolute));
+    }
+    return absolute;
+}
+export function findProjectByRoot(context, root) {
+    return context.db.get("SELECT * FROM projects WHERE root = ?", [root]);
+}
+export function requireProjectByRoot(context, root) {
+    // Callers may receive a path through a native adapter or shell.  Resolve
+    // aliases such as macOS `/var` -> `/private/var` before comparing with the
+    // canonical root persisted in the project registry.
+    const canonical = normalizeStoredRoot(root);
+    const project = findProjectByRoot(context, canonical);
+    if (!project) {
+        throw new AppError("not_found", `Project is not registered: ${canonical}`, 1);
+    }
+    return project;
+}
+export function newProjectRecord(context, root, now) {
+    const slug = slugFromRoot(root);
+    const id = nextFullProjectId(context, slug);
+    const { shortId } = parseFullEntityId(id);
+    return {
+        id,
+        short_id: shortId,
+        slug,
+        root,
+        status: "active",
+        state_root: projectRuntimeRoot(context.ddFlowHome, id),
+        created_at: now,
+        updated_at: now
+    };
+}
+export function nextFullProjectId(context, slug) {
+    const rows = context.db.all("SELECT id FROM projects WHERE id LIKE 'PRJ-%'");
+    const used = rows
+        .map((row) => /^PRJ-(\d{3})-/.exec(row.id)?.[1])
+        .filter((value) => Boolean(value))
+        .map((value) => Number(value));
+    const next = Math.max(0, ...used) + 1;
+    return formatFullId("PRJ", next, slug);
+}