@xenonbyte/da-vinci-workflow 0.2.4 → 0.2.6

package/lib/workflow-persisted-state.js

@@ -1,8 +1,11 @@
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 const { writeFileAtomic, pathExists, readTextIfExists } = require("./utils");
 
-const WORKFLOW_STATE_VERSION = 2;
+// Route snapshot schema version; task-group metadata keeps its own version in workflow-state.js.
+const WORKFLOW_STATE_VERSION = 3;
+const SUPPORTED_WORKFLOW_STATE_VERSIONS = new Set([2, WORKFLOW_STATE_VERSION]);
 const DEFAULT_STALE_WINDOW_MS = 24 * 60 * 60 * 1000;
 const PERSISTED_NOTE_EXCLUDE_PATTERNS = [
   /^No persisted workflow state found for this change; deriving from artifacts\.$/i,
@@ -19,16 +22,29 @@ function resolveTaskGroupMetadataPath(projectRoot, changeId) {
   return path.join(projectRoot, ".da-vinci", "state", "task-groups", `${changeId}.json`);
 }
 
+function hashContent(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function digestForPath(targetPath) {
+  if (!pathExists(targetPath)) {
+    return null;
+  }
+  try {
+    return hashContent(fs.readFileSync(targetPath));
+  } catch (_error) {
+    return null;
+  }
+}
+
 function fingerprintForPath(targetPath) {
   if (!pathExists(targetPath)) {
     return null;
   }
   try {
-    const stat = fs.statSync(targetPath);
     return {
       path: targetPath,
-      mtimeMs: stat.mtimeMs,
-      size: stat.size
+      digest: digestForPath(targetPath)
     };
   } catch (_error) {
     return null;
@@ -46,8 +62,7 @@ function buildWorkflowFingerprint(projectRoot, changeId) {
     path.join(changeRoot, "pencil-design.md"),
     path.join(changeRoot, "pencil-bindings.md"),
     path.join(changeRoot, "tasks.md"),
-    path.join(changeRoot, "verification.md"),
-    path.join(changeRoot, "workflow.json")
+    path.join(changeRoot, "verification.md")
   ];
 
   const specRoot = path.join(changeRoot, "specs");
@@ -96,8 +111,7 @@ function stableFingerprintHash(fingerprint) {
   return JSON.stringify(
     (fingerprint || []).map((entry) => ({
       path: entry.path,
-      mtimeMs: entry.mtimeMs,
-      size: entry.size
+      digest: entry.digest
     }))
   );
 }
@@ -163,7 +177,7 @@ function selectPersistedStateForChange(projectRoot, changeId, options = {}) {
     };
   }
 
-  if (loaded.state.version !== WORKFLOW_STATE_VERSION) {
+  if (!SUPPORTED_WORKFLOW_STATE_VERSIONS.has(Number(loaded.state.version))) {
     return {
       usable: false,
       reason: "version-mismatch",
@@ -183,25 +197,6 @@ function selectPersistedStateForChange(projectRoot, changeId, options = {}) {
     };
   }
 
-  const persistedAt = Date.parse(String(changeRecord.persistedAt || ""));
-  if (!Number.isFinite(persistedAt)) {
-    return {
-      usable: false,
-      reason: "invalid-timestamp",
-      statePath: loaded.statePath,
-      persisted: loaded.state
-    };
-  }
-
-  if (Date.now() - persistedAt > staleWindowMs) {
-    return {
-      usable: false,
-      reason: "time-stale",
-      statePath: loaded.statePath,
-      persisted: loaded.state
-    };
-  }
-
   const currentFingerprint = buildWorkflowFingerprint(projectRoot, changeId);
   const currentHash = stableFingerprintHash(currentFingerprint);
   const persistedHash = String(changeRecord.fingerprintHash || "");
@@ -219,7 +214,20 @@ function selectPersistedStateForChange(projectRoot, changeId, options = {}) {
     reason: null,
     statePath: loaded.statePath,
     persisted: loaded.state,
-    changeRecord
+    changeRecord,
+    advisoryNotes:
+      (() => {
+        const persistedAt = Date.parse(String(changeRecord.persistedAt || ""));
+        if (!Number.isFinite(persistedAt)) {
+          return [];
+        }
+        if (Date.now() - persistedAt > staleWindowMs) {
+          return [
+            "Persisted workflow state is older than the historical stale-time threshold but remains usable because artifact content digests still match."
+          ];
+        }
+        return [];
+      })()
   };
 }
 
@@ -234,6 +242,14 @@ function persistDerivedWorkflowResult(projectRoot, changeId, workflowResult, opt
   }
 
   const fingerprint = buildWorkflowFingerprint(projectRoot, changeId);
+  const metadataRefsNormalized =
+    metadataRefs && typeof metadataRefs === "object"
+      ? {
+          ...metadataRefs,
+          taskGroupsPath: metadataRefs.taskGroupsPath || null,
+          taskGroupsDigest: metadataRefs.taskGroupsDigest || null
+        }
+      : {};
   changes[changeId] = {
     stage: workflowResult.stage,
     checkpointState: workflowResult.checkpointState,
@@ -243,8 +259,7 @@ function persistDerivedWorkflowResult(projectRoot, changeId, workflowResult, opt
     failures: workflowResult.failures,
     warnings: workflowResult.warnings,
     notes: sanitizePersistedNotes(workflowResult.notes),
-    taskGroups: workflowResult.taskGroups || null,
-    metadataRefs,
+    metadataRefs: metadataRefsNormalized,
     fingerprintHash: stableFingerprintHash(fingerprint),
     persistedAt: new Date().toISOString()
   };
@@ -264,7 +279,10 @@ function writeTaskGroupMetadata(projectRoot, changeId, metadataPayload) {
   const targetPath = resolveTaskGroupMetadataPath(projectRoot, changeId);
   fs.mkdirSync(path.dirname(targetPath), { recursive: true });
   writeFileAtomic(targetPath, `${JSON.stringify(metadataPayload, null, 2)}\n`);
-  return targetPath;
+  return {
+    path: targetPath,
+    digest: digestForPath(targetPath)
+  };
 }
 
 function readTaskGroupMetadata(projectRoot, changeId) {
@@ -284,11 +302,13 @@ function readTaskGroupMetadata(projectRoot, changeId) {
 
 module.exports = {
   WORKFLOW_STATE_VERSION,
+  SUPPORTED_WORKFLOW_STATE_VERSIONS,
   DEFAULT_STALE_WINDOW_MS,
   resolveWorkflowStatePath,
   resolveTaskGroupMetadataPath,
   buildWorkflowFingerprint,
   stableFingerprintHash,
+  digestForPath,
   sanitizePersistedNotes,
   readPersistedWorkflowState,
   writePersistedWorkflowState,