@deksden-com/dd-flow-cli 0.2.0 → 0.3.1

package/dist/services/version-status.js

@@ -22,7 +22,8 @@ export function getProjectVersionStatus(input) {
     const flowPack = readFlowPackMetadata(input.projectRoot, memoryBank.root);
     const memoryBankDrift = compareMemoryBankVersion(memoryBank.version, input.canon?.metadata.version ?? null, memoryBank.status);
     const flowPackDrift = compareFlowPackCommit(flowPack.source_commit, input.canon?.metadata.commit ?? null, input.canon?.root ?? null, flowPack.status);
-    const overall = overallDrift(memoryBankDrift, flowPackDrift, memoryBank.status, flowPack.status);
+    const flowContractDrift = compareFlowContract(flowPack.flow_contract, input.canon?.metadata.flow_contract ?? null, flowPack.status);
+    const overall = overallDrift(memoryBankDrift, flowPackDrift, flowContractDrift, memoryBank.status, flowPack.status);
     return {
         root: input.projectRoot,
         root_source: input.rootSource,
@@ -31,8 +32,9 @@ export function getProjectVersionStatus(input) {
         drift: {
             memory_bank_version: memoryBankDrift,
             flow_pack_commit: flowPackDrift,
+            flow_contract: flowContractDrift,
             overall,
-            next_action: nextAction(overall, memoryBank.status, flowPack.status)
+            next_action: nextAction(overall, memoryBank.status, flowPack.status, flowContractDrift.status)
         }
     };
 }
@@ -62,8 +64,12 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
             manifest_path: null,
             schema_id: null,
             pack_version: null,
+            canon_root: null,
+            canon_memory_bank_root: null,
+            canon_flow_root: null,
             source_commit: null,
             canon_version_at_source_commit: null,
+            flow_contract: null,
             status: "missing",
             reason: "no_memory_bank",
             canonical_only_files: []
@@ -77,8 +83,12 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
             manifest_path: path.relative(projectRoot, manifestPath),
             schema_id: null,
             pack_version: null,
+            canon_root: null,
+            canon_memory_bank_root: null,
+            canon_flow_root: null,
             source_commit: null,
             canon_version_at_source_commit: null,
+            flow_contract: null,
             status: "missing",
             reason: "flow_pack_manifest_missing",
             canonical_only_files: canonicalOnlyFiles
@@ -96,8 +106,12 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
             manifest_path: path.relative(projectRoot, manifestPath),
             schema_id: null,
             pack_version: null,
+            canon_root: null,
+            canon_memory_bank_root: null,
+            canon_flow_root: null,
             source_commit: null,
             canon_version_at_source_commit: null,
+            flow_contract: null,
             status: "invalid",
             reason: "flow_pack_manifest_invalid_json",
             canonical_only_files: canonicalOnlyFiles
@@ -106,14 +120,35 @@ function readFlowPackMetadata(projectRoot, memoryBankRoot) {
     const schemaId = stringOrNull(manifest.schema_id);
     const canonVersion = stringOrNull(manifest.canon_version_at_source_commit) ?? stringOrNull(manifest.canon_version);
     const sourceCommit = stringOrNull(manifest.source_commit);
-    const status = schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion ? "present" : schemaId === "dd-flow/project-flow-pack-manifest@1" ? "degraded" : "invalid";
-    const reason = status === "degraded" ? "legacy_flow_pack_manifest" : status === "invalid" ? "flow_pack_manifest_schema_unknown" : undefined;
+    const canonRoot = stringOrNull(manifest.canon_root);
+    const canonMemoryBankRoot = stringOrNull(manifest.canon_memory_bank_root);
+    const canonFlowRoot = stringOrNull(manifest.canon_flow_root);
+    const flowContract = stringOrNull(manifest.flow_contract);
+    const status = schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion && canonMemoryBankRoot && canonFlowRoot && flowContract
+        ? "present"
+        : schemaId === "dd-flow/project-flow-pack-manifest@1" ||
+            (schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion && (!canonMemoryBankRoot || !canonFlowRoot || !flowContract))
+            ? "degraded"
+            : "invalid";
+    const reason = status === "degraded" && schemaId === "dd-flow/project-flow-pack-manifest@2" && (!canonMemoryBankRoot || !canonFlowRoot)
+        ? "flow_pack_manifest_missing_explicit_canon_roots"
+        : status === "degraded" && schemaId === "dd-flow/project-flow-pack-manifest@2" && !flowContract
+            ? "flow_pack_manifest_missing_flow_contract"
+            : status === "degraded"
+                ? "legacy_flow_pack_manifest"
+                : status === "invalid"
+                    ? "flow_pack_manifest_schema_unknown"
+                    : undefined;
     return {
         manifest_path: path.relative(projectRoot, manifestPath),
         schema_id: schemaId,
         pack_version: stringOrNull(manifest.pack_version),
+        canon_root: canonRoot,
+        canon_memory_bank_root: canonMemoryBankRoot,
+        canon_flow_root: canonFlowRoot,
         source_commit: sourceCommit,
         canon_version_at_source_commit: canonVersion,
+        flow_contract: flowContract,
         status,
         ...(reason ? { reason } : {}),
         canonical_only_files: canonicalOnlyFiles
@@ -190,28 +225,43 @@ function compareFlowPackCommit(current, target, canonRoot, artifactStatus) {
         target
     };
 }
-function overallDrift(memoryBank, flowPack, memoryStatus, flowStatus) {
+function compareFlowContract(current, target, artifactStatus) {
+    if (artifactStatus === "missing")
+        return { status: "missing", confidence: "none", reason: "flow_pack_manifest_missing", current, target };
+    if (artifactStatus === "invalid")
+        return { status: "invalid", confidence: "none", reason: "flow_pack_manifest_invalid", current, target };
+    if (!current)
+        return { status: "unknown", confidence: "none", reason: "flow_pack_flow_contract_missing", current, target };
+    if (!target)
+        return { status: "unknown", confidence: "none", reason: "canon_flow_contract_unknown", current, target };
+    if (current === target)
+        return { status: "same", confidence: "exact", reason: "flow_contract_equal", current, target };
+    return { status: "diverged", confidence: "declared", reason: "flow_contract_mismatch", current, target };
+}
+function overallDrift(memoryBank, flowPack, flowContract, memoryStatus, flowStatus) {
     if (memoryStatus === "missing")
         return "not_applicable";
-    if (memoryBank.status === "invalid" || flowPack.status === "invalid")
+    if (memoryBank.status === "invalid" || flowPack.status === "invalid" || flowContract.status === "invalid")
         return "invalid";
-    if (memoryBank.status === "missing" || flowPack.status === "missing")
+    if (memoryBank.status === "missing" || flowPack.status === "missing" || flowContract.status === "missing")
         return "missing";
     if (memoryBank.status === "ahead" || flowPack.status === "ahead")
         return "ahead";
     if (memoryBank.status === "behind" || flowPack.status === "behind")
         return "behind";
-    if (memoryBank.status === "diverged" || flowPack.status === "diverged")
+    if (memoryBank.status === "diverged" || flowPack.status === "diverged" || flowContract.status === "diverged")
         return "diverged";
     if (memoryBank.status === "same" && (flowPack.status === "same" || flowStatus === "degraded"))
         return flowStatus === "degraded" ? "unknown" : "same";
     return "unknown";
 }
-function nextAction(overall, memoryStatus, flowStatus) {
+function nextAction(overall, memoryStatus, flowStatus, flowContractStatus) {
     if (overall === "same")
         return "no_action";
     if (overall === "not_applicable" && memoryStatus === "missing")
         return "run_mb_init_if_project_needs_memory_bank";
+    if (flowContractStatus === "diverged" || flowContractStatus === "unknown")
+        return "run_canonical_mb_upgrade_before_lifecycle_mutations";
     if (overall === "behind" || flowStatus === "degraded")
         return "run_canonical_mb_upgrade";
     if (overall === "missing")

package/dist/storage/database.js

@@ -134,10 +134,34 @@ function migrate(db) {
       FOREIGN KEY(project_id) REFERENCES projects(id)
     );
 
+    CREATE TABLE IF NOT EXISTS lane_waiters (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id TEXT NOT NULL,
+      lane TEXT NOT NULL,
+      worker_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      queued_at TEXT NOT NULL,
+      acquired_at TEXT,
+      cancelled_at TEXT,
+      expires_at TEXT,
+      reason TEXT,
+      metadata_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      FOREIGN KEY(project_id) REFERENCES projects(id)
+    );
+
     CREATE UNIQUE INDEX IF NOT EXISTS idx_lane_locks_one_active
       ON lane_locks(project_id, lane)
       WHERE status = 'active';
 
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_lane_waiters_one_queued_worker
+      ON lane_waiters(project_id, lane, worker_id)
+      WHERE status = 'queued';
+
+    CREATE INDEX IF NOT EXISTS idx_lane_waiters_fifo
+      ON lane_waiters(project_id, lane, status, queued_at, id);
+
     CREATE TABLE IF NOT EXISTS hook_installations (
       project_id TEXT NOT NULL,
       scope TEXT NOT NULL,
@@ -243,6 +267,9 @@ function migrate(db) {
       runtime_path TEXT NOT NULL,
       run_dir TEXT NOT NULL,
       run_index_path TEXT NOT NULL,
+      run_home_path TEXT,
+      layout_version TEXT,
+      artifact_root_kind TEXT,
       index_json TEXT NOT NULL,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL,
@@ -318,6 +345,10 @@ function migrate(db) {
     ensureColumn(db, "flow_sessions", "next_action", "ALTER TABLE flow_sessions ADD COLUMN next_action TEXT");
     ensureColumn(db, "flow_sessions", "metadata_json", "ALTER TABLE flow_sessions ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}'");
     ensureColumn(db, "flow_sessions", "run_id", "ALTER TABLE flow_sessions ADD COLUMN run_id TEXT");
+    ensureColumn(db, "flow_runs", "run_home_path", "ALTER TABLE flow_runs ADD COLUMN run_home_path TEXT");
+    ensureColumn(db, "flow_runs", "layout_version", "ALTER TABLE flow_runs ADD COLUMN layout_version TEXT");
+    ensureColumn(db, "flow_runs", "artifact_root_kind", "ALTER TABLE flow_runs ADD COLUMN artifact_root_kind TEXT");
+    ensureColumn(db, "lane_waiters", "expires_at", "ALTER TABLE lane_waiters ADD COLUMN expires_at TEXT");
 }
 function ensureColumn(db, table, column, sql) {
     const columns = db.prepare(`PRAGMA table_info(${table})`).all();

package/dist/storage/paths.js

@@ -33,12 +33,30 @@ export function runtimeRunDir(ddFlowHome, projectId, runId) {
 export function runtimeRunJsonPath(ddFlowHome, projectId, runId) {
     return path.join(runtimeRunDir(ddFlowHome, projectId, runId), "run.json");
 }
+export function projectRunHome(ddFlowHome, projectId, runId) {
+    return path.join(projectHome(ddFlowHome, projectId), "runs", runId);
+}
+export function projectRunJsonPath(ddFlowHome, projectId, runId) {
+    return path.join(projectRunHome(ddFlowHome, projectId, runId), "run.json");
+}
+export function projectRunIndexPath(ddFlowHome, projectId, runId) {
+    return path.join(projectRunHome(ddFlowHome, projectId, runId), "run-index.json");
+}
+export function projectRunStageDir(ddFlowHome, projectId, runId, stageDir) {
+    return path.join(projectRunHome(ddFlowHome, projectId, runId), stageDir);
+}
 export function userFacingRunDir(workspaceRoot, runId) {
     return path.join(workspaceRoot, ".tasks", "dd-flow-runs", runId);
 }
+export function legacyWorkspaceRunDir(workspaceRoot, runId) {
+    return userFacingRunDir(workspaceRoot, runId);
+}
 export function userFacingRunIndexPath(workspaceRoot, runId) {
     return path.join(userFacingRunDir(workspaceRoot, runId), "run-index.json");
 }
+export function userFacingRunStageDir(workspaceRoot, runId, stageDir) {
+    return path.join(userFacingRunDir(workspaceRoot, runId), stageDir);
+}
 export function stateJsonPath(projectRoot, protocolId) {
     return path.join(protocolDir(projectRoot, protocolId), "state.json");
 }
@@ -54,3 +72,18 @@ export function projectRuntimeRoot(ddFlowHome, projectId) {
 export function projectCheckoutRoot(ddFlowHome, projectId) {
     return path.join(projectHome(ddFlowHome, projectId), "checkouts");
 }
+export function projectFeatureWorktreePath(ddFlowHome, projectId, runOrProtocolId, repoName) {
+    return path.join(projectCheckoutRoot(ddFlowHome, projectId), "worktrees", runOrProtocolId, repoName);
+}
+export function engineStoreRoot(ddFlowHome) {
+    return path.join(ddFlowHome, "engines");
+}
+export function packageEngineRoot(ddFlowHome, packageName) {
+    return path.join(engineStoreRoot(ddFlowHome), safePathSegment(packageName));
+}
+export function engineVersionRoot(ddFlowHome, packageName, version) {
+    return path.join(packageEngineRoot(ddFlowHome, packageName), safePathSegment(version));
+}
+function safePathSegment(value) {
+    return value.replace(/[^a-zA-Z0-9_.@-]+/g, "_");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=26.0.0",