@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/storage/work-status.js

@@ -13,23 +13,36 @@ const UNCHECKED = /^\s*- \[ \] /m;
 const UNCHECKED_TASK = /^\s*- \[ \] (\S+)/gm;
 const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
-function recordStorePaths(fsImpl     )                      {
+/** The record extension a store declares in its `match` pattern: `.jsonl` for a JSON-lines store, else `.json`. */
+function recordExtension(match     )         {
+  return typeof match === 'string' && /\\\.jsonl\$$/.test(match) ? '.jsonl' : '.json';
+}
+
+function workRecordStores(fsImpl     )        {
   try {
     const registry = loadStorageRegistry({ repoRoot: REPO_ROOT, fsImpl });
-    return new Map(registry.stores
-      .filter((store     ) => store.root === 'project-state' && store.entry === 'record' && store.rule === 'work')
-      .map((store     )                   => [store.id, store.path]));
+    return registry.stores.filter((store     ) => store.root === 'project-state' && store.entry === 'record' && store.rule === 'work');
   } catch {
-    return new Map();
+    return [];
   }
 }
 
+function recordStorePaths(fsImpl     )                      {
+  return new Map(workRecordStores(fsImpl).map((store     )                   => [store.id, store.path]));
+}
+
+function recordStoreExtensions(fsImpl     )                      {
+  return new Map(workRecordStores(fsImpl).map((store     )                   => [store.id, recordExtension(store.match)]));
+}
+
 function createWorkCache({ projectRoot, fsImpl = fs }                                       )      {
   return {
     projectRoot: path.resolve(projectRoot),
     fsImpl,
     recordStorePaths: recordStorePaths(fsImpl),
+    recordExtensions: recordStoreExtensions(fsImpl),
     runNames: null,
+    runLocations: null,
     runListError: false,
     featureNames: null,
     featureListError: false,
@@ -44,7 +57,7 @@ function createWorkCache({ projectRoot, fsImpl = fs }
  * taken at selection. A run reopened or a plan task unchecked after selection keeps the record.
  */
 function refreshedWorkCache(cache     )      {
-  return { ...cache, runNames: null, runListError: false, featureNames: null, featureListError: false,
+  return { ...cache, runNames: null, runLocations: null, runListError: false, featureNames: null, featureListError: false,
     runs: new Map(), plans: new Map() };
 }
 
@@ -63,6 +76,16 @@ function safeSegment(value     )          {
   return typeof value === 'string' && SAFE_SEGMENT.test(value) && !value.includes('..');
 }
 
+/** Whether `name` can be a run namespace directory (a feature slug), not a `<file>.lock` directory. */
+function isRunNamespaceDir(name        )          {
+  return safeSegment(name) && !name.endsWith('.lock');
+}
+
+/**
+ * Every run id the orchestration store holds, flat or under a `<slug>/` namespace (115 C-1: a task id
+ * other than its feature's slug lives in `orchestration/<slug>/`). `cache.runLocations` maps each id
+ * to the directories that hold it ('' is the flat store), namespaces sorted, flat last.
+ */
 function listRunNames(cache     , shouldStop                )                                           {
   if (shouldStop?.()) return { names: [], incomplete: true };
   if (cache.runNames !== null) return { names: cache.runNames, incomplete: false };
@@ -71,35 +94,115 @@ function listRunNames(cache     , shouldStop                )
   try { entries = cache.fsImpl.readdirSync(dir, { withFileTypes: true }); }
   catch (error     ) {
     if (error?.code === 'ENOENT') entries = [];
-    else { cache.runNames = []; cache.runListError = true; return { names: cache.runNames, incomplete: false }; }
+    else { cache.runNames = []; cache.runLocations = new Map(); cache.runListError = true; return { names: cache.runNames, incomplete: false }; }
   }
   if (shouldStop?.()) return { names: [], incomplete: true };
-  const names           = [];
+  const locations = new Map                  ();
+  const add = (id        , where        )       => {
+    if (!locations.has(id)) locations.set(id, []);
+    (locations.get(id)            ).push(where);
+  };
+  const namespaces           = [];
   for (const entry of entries) {
     if (shouldStop?.()) return { names: [], incomplete: true };
-    if (entry.name.endsWith('.json')) names.push(entry.name.slice(0, -5));
+    if (entry.name.endsWith('.json')) add(entry.name.slice(0, -5), '');
+    else if (entry.isDirectory() && isRunNamespaceDir(entry.name)) namespaces.push(entry.name);
+  }
+  for (const namespace of namespaces.sort()) {
+    let inner       ;
+    try { inner = cache.fsImpl.readdirSync(path.join(dir, namespace), { withFileTypes: true }); }
+    catch (error     ) {
+      if (error?.code === 'ENOENT') continue;
+      cache.runNames = []; cache.runLocations = new Map(); cache.runListError = true;
+      return { names: cache.runNames, incomplete: false };
+    }
+    for (const file of inner) {
+      if (shouldStop?.()) return { names: [], incomplete: true };
+      if (file.name.endsWith('.json')) add(file.name.slice(0, -5), namespace);
+    }
   }
   if (shouldStop?.()) return { names: [], incomplete: true };
-  cache.runNames = names;
-  return { names, incomplete: false };
+  // Namespaces come first in the order listed; the flat copy (a legacy or seed source) is last.
+  for (const where of locations.values()) where.sort((x, y) => (x === '' ? 1 : y === '' ? -1 : x < y ? -1 : x > y ? 1 : 0));
+  cache.runNames = [...locations.keys()];
+  cache.runLocations = locations;
+  return { names: cache.runNames, incomplete: false };
 }
 
-function readRun(cache     , runId        )      {
-  if (cache.runs.has(runId)) return cache.runs.get(runId);
-  const file = path.join(stateRoot(cache.projectRoot), 'orchestration', `${runId}.json`);
+function readRunAt(cache     , runId        , where        )      {
+  // The flat copy keeps its bare id as the key: the pruner reads that snapshot back by run id.
+  const key = where ? `${where}/${runId}` : runId;
+  if (cache.runs.has(key)) return cache.runs.get(key);
+  const file = path.join(stateRoot(cache.projectRoot), 'orchestration', ...(where ? [where] : []), `${runId}.json`);
   let result     ;
   try {
-    const value = JSON.parse(cache.fsImpl.readFileSync(file, 'utf8'));
+    // A namespaced copy is a file base never read (N-4): a link, a FIFO or a device there reads as
+    // unreadable (the record is kept) and never blocks. The flat copy keeps its plain read (FU-d88kp0).
+    const text = where && typeof cache.fsImpl.lstatSync === 'function' && typeof cache.fsImpl.openSync === 'function'
+      ? require('../task-scope.js').readRegularFileText(file, cache.fsImpl) : cache.fsImpl.readFileSync(file, 'utf8');
+    if (text === null) throw new Error('not a regular file');
+    const value = JSON.parse(text);
     result = value && typeof value === 'object' && !Array.isArray(value) && RUN_STATES.has(value.state)
-      ? { ok: true, value }
-      : { ok: false };
+      ? { ok: true, value, where }
+      : { ok: false, where };
   } catch {
-    result = { ok: false };
+    result = { ok: false, where };
   }
-  cache.runs.set(runId, result);
+  cache.runs.set(key, result);
   return result;
 }
 
+/**
+ * Whether a namespaced copy of a run keeps the record open (C-1, N-1). A namespaced copy may only
+ * keep a record: a record is judged as 135ce230 judged it, by the flat run copy alone, and a
+ * namespaced copy never makes a record finished. The copies a record owns are its own namespace's
+ * (a namespaced record) or the namespace named by its own `featureSlug`/`slug` (a flat record); it
+ * never owns another feature's copy. The run is chosen as a flat run is: the exact id, the record's
+ * namespace, then the longest delimited prefix. An owned copy that is RUNNING or AWAITING_GATE
+ * holds the record open and one that cannot be read keeps it undecidable. A flat record that names
+ * no namespace of its own and could be claimed by two or more namespaced copies is undecidable (fail
+ * closed), not guessed.
+ */
+function namespacedHold(cache     , taskId        , namespace     , recordValue     , shouldStop                )      {
+  const recordNs                = safeSegment(namespace) ? namespace : null;
+  const named = recordNs ? null : (stringField(recordValue, 'featureSlug') || stringField(recordValue, 'slug'));
+  const own                = recordNs || (named !== null && isRunNamespaceDir(named) ? named : null);
+  const locations                        = cache.runLocations || new Map();
+  const choose = (accept                            )                            => {
+    let exact = false, byNamespace = false, prefix                = null;
+    for (const [candidate, held] of locations) {
+      if (shouldStop?.()) return undefined;
+      if (!held.some((w        ) => w !== '' && accept(w))) continue;
+      if (candidate === taskId) exact = true;
+      else if (recordNs && candidate === recordNs) byNamespace = true;
+      else if ((taskId.startsWith(`${candidate}-`) || taskId.startsWith(`${candidate}.`))
+        && (!prefix || candidate.length > prefix.length || (candidate.length === prefix.length && candidate < prefix))) prefix = candidate;
+    }
+    return exact ? taskId : byNamespace ? recordNs : prefix;
+  };
+  if (own) {
+    const id = choose((w        ) => w === own);
+    if (id === undefined || shouldStop?.()) return { incomplete: true };
+    if (id) {
+      const read = readRunAt(cache, id, own);
+      if (shouldStop?.()) return { incomplete: true };
+      if (!read.ok) return { unreadable: true, id };
+      if (RUN_OPEN_STATES.includes(read.value.state)) return { open: true, id };
+    }
+  }
+  if (!recordNs && !own) {
+    const id = choose(() => true);
+    if (id === undefined || shouldStop?.()) return { incomplete: true };
+    if (id && (locations.get(id) || []).filter((w        ) => w !== '').length > 1) return { unreadable: true, id };
+  }
+  return {};
+}
+
+/** The flat run copy `runId`, the only copy a record is judged by (135ce230). */
+function readRun(cache     , runId        )      {
+  return readRunAt(cache, runId, '');
+}
+
 function resolveRun(cache     , taskId        , namespace     , shouldStop                )      {
   const listed = listRunNames(cache, shouldStop);
   if (listed.incomplete) return { id: null, unreadable: false, incomplete: true };
@@ -107,6 +210,7 @@ function resolveRun(cache     , taskId        , namespace     , shouldStop
   let exact = false, namespaced = false, prefix                = null;
   for (const candidate of listed.names) {
     if (shouldStop?.()) return { id: null, unreadable: false, incomplete: true };
+    if (!(cache.runLocations.get(candidate) || []).includes('')) continue;
     if (candidate === taskId) exact = true;
     else if (safeSegment(namespace) && candidate === namespace) namespaced = true;
     else if ((taskId.startsWith(`${candidate}-`) || taskId.startsWith(`${candidate}.`))
@@ -120,16 +224,26 @@ function resolveRun(cache     , taskId        , namespace     , shouldStop
   return read.ok ? { id, value: read.value, unreadable: false } : { id, value: null, unreadable: true };
 }
 
-function readRecord({ projectRoot, storePath, recordId, namespace, mtimeMs, fsImpl }     )      {
+function parseJsonLines(text        )      {
+  const lines = text.split('\n').filter((line        ) => line.trim() !== '');
+  if (lines.length === 0) throw new Error('empty JSON-lines record');
+  const values = lines.map((line        ) => JSON.parse(line));
+  return values[values.length - 1];
+}
+
+function readRecord({ projectRoot, storePath, recordId, namespace, mtimeMs, fsImpl, extension = '.json' }     )      {
   const storeSegments = typeof storePath === 'string' && storePath !== '' ? storePath.split('/') : [];
   if (typeof storePath !== 'string' || storeSegments.some((segment        ) => !safeSegment(segment))
       || !safeSegment(recordId)
       || (namespace !== null && namespace !== undefined && !safeSegment(namespace))) {
     return { ok: false };
   }
-  const file = path.join(stateRoot(projectRoot), ...storeSegments, ...(namespace ? [namespace] : []), `${recordId}.json`);
+  const file = path.join(stateRoot(projectRoot), ...storeSegments, ...(namespace ? [namespace] : []), `${recordId}${extension}`);
   try {
-    const value = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+    const text = fsImpl.readFileSync(file, 'utf8');
+    // A `.jsonl` record is one JSON value per line, appended over time: every line must parse (fail
+    // closed otherwise) and the last one is the record's current value.
+    const value = extension === '.jsonl' ? parseJsonLines(text) : JSON.parse(text);
     const mtime = mtimeMs === undefined ? fsImpl.statSync(file).mtimeMs : mtimeMs;
     if (!Number.isFinite(mtime)) return { ok: false };
     return { ok: true, value, mtimeMs: mtime };
@@ -226,6 +340,33 @@ function planWithUncheckedTask(cache     , taskId        , shouldStop
   return { found: false, unreadable: false };
 }
 
+/** IC-028: why a task-attempts ledger is open work, or null when it holds neither an active or
+ * uncleared cancelled attempt nor a run whose control is other than `running`. A cancel a resume has
+ * cleared (the same `clearedCancels` the resume report uses) is settled work, not open work. */
+function openLedgerReason(ledger     )                {
+  const tasks = ledger && typeof ledger.tasks === 'object' && ledger.tasks ? Object.entries     (ledger.tasks) : [];
+  let cleared                  = null;
+  for (const [, entry] of tasks) {
+    const attempts        = entry && Array.isArray(entry.attempts) ? entry.attempts : [];
+    for (const a of attempts) {
+      if (!a) continue;
+      if (a.state === 'active') return 'attempt-open';
+      if (a.state !== 'cancelled') continue;
+      // Loaded only when a cancelled attempt exists: task-run is a heavy module for a storage pass.
+      // Paired by the attempt object, not by (task, token): a malformed ledger can repeat or omit
+      // tokens, and an uncleared cancel must never be taken for a cleared one.
+      if (cleared === null) cleared = new Set(require('../task-run.js').clearedCancels(ledger).map((c     ) => c.attempt));
+      if (!cleared.has(a)) return 'attempt-open';
+    }
+  }
+  const runs = ledger && typeof ledger.runs === 'object' && ledger.runs ? Object.values     (ledger.runs) : [];
+  if (runs.some((run     ) => !run || run.control !== 'running')) return 'run-control-open';
+  return null;
+}
+
+/** IC-037: the dispatch run states that settle a dispatch store; any other run state is open. */
+const DISPATCH_RUN_SETTLED = Object.freeze(['completed', 'cancelled']);
+
 function answer(state        , reason        , run     , feature     , since                = null)      {
   return { state, since, reason, run, feature };
 }
@@ -234,6 +375,47 @@ function incompleteAnswer(run      = null, feature      = null)      {
   return { ...answer('undecidable', 'pass-budget-exhausted', run, feature), incomplete: true };
 }
 
+/**
+ * A loop run record (`roadmap/runs/<runId>.json`) is open while its `closedAt` is null (the loop
+ * resumes any such run), while it is the newest record in `runs/`, while a merge intent in
+ * `roadmap/intents/` names its `runId`, or while `roadmap/lease.json` names it. Any other record is
+ * finished as of its mtime. An unreadable source is never called finished.
+ */
+function roadmapRunStatus(project        , fileSystem     , runId     , mtimeMs     )      {
+  if (!safeSegment(runId)) return answer('undecidable', 'record-unreadable', null, null);
+  const dir = path.join(stateRoot(project), 'roadmap');
+  const unreadable = () => answer('undecidable', 'record-unreadable', runId, null);
+  let record     ;
+  try { record = JSON.parse(fileSystem.readFileSync(path.join(dir, 'runs', `${runId}.json`), 'utf8')); }
+  catch { return unreadable(); }
+  if (!record || typeof record !== 'object' || !Object.hasOwn(record, 'closedAt')) return unreadable();
+  if (record.closedAt === null) return answer('open', 'roadmap-run-open', runId, null);
+  const list = (folder        )                  => {
+    try { return fileSystem.readdirSync(folder); } catch (error     ) { return error.code === 'ENOENT' ? [] : null; }
+  };
+  const runs = list(path.join(dir, 'runs'));
+  if (runs === null) return unreadable();
+  let newest                                           = null;
+  for (const name of runs) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/.test(name)) continue;
+    let stat     ;
+    try { stat = fileSystem.statSync(path.join(dir, 'runs', name)); } catch { return unreadable(); }
+    if (!newest || stat.mtimeMs > newest.mtimeMs || (stat.mtimeMs === newest.mtimeMs && name > newest.name)) newest = { name, mtimeMs: stat.mtimeMs };
+  }
+  const open = answer('open', 'roadmap-run-open', runId, null);
+  if (newest?.name === `${runId}.json`) return open;
+  const intents = list(path.join(dir, 'intents'));
+  if (intents === null) return unreadable();
+  for (const name of intents) {
+    if (!name.endsWith('.json')) continue;
+    try { if (JSON.parse(fileSystem.readFileSync(path.join(dir, 'intents', name), 'utf8'))?.runId === runId) return open; }
+    catch { return unreadable(); }
+  }
+  try { if (JSON.parse(fileSystem.readFileSync(path.join(dir, 'lease.json'), 'utf8'))?.runId === runId) return open; }
+  catch (error     ) { if (error.code !== 'ENOENT') return unreadable(); }
+  return answer('finished', 'roadmap-run-finished', runId, null, Number.isFinite(mtimeMs) ? mtimeMs : null);
+}
+
 /**
  * The one definition of whether a per-task record is still open work (IC-004).
  * Reads fail closed: an unreadable run, record, or relevant plan is never called finished. An
@@ -243,11 +425,23 @@ function incompleteAnswer(run      = null, feature      = null)      {
 function workStatus({
   projectRoot, store, taskId, namespace = null, mtimeMs, cache, fsImpl, shouldStop,
 }     )      {
+  const recordId = taskId;
+  const workId = typeof taskId === 'string' ? taskId.replace(/_claims$/, '') : taskId;
+
+  // Roadmap archive location is authoritative: open intents never age out, while archived
+  // intents use their own mtime and do not depend on the feature plan remaining on disk.
+  if (store === 'roadmap' && namespace === 'intents')
+    return answer('open', 'roadmap-intent-open', workId, null);
+  if (store === 'roadmap' && namespace === 'done')
+    return answer('finished', 'roadmap-intent-done', workId, null, Number.isFinite(mtimeMs) ? mtimeMs : null);
+  // The tripwire's remembered event ids are tiny and bounded by those ids: kept.
+  if (store === 'roadmap' && namespace === 'tripwire')
+    return answer('open', 'roadmap-tripwire-kept', workId, null);
+
   const project = path.resolve(projectRoot);
   const fileSystem = fsImpl || cache?.fsImpl || fs;
+  if (store === 'roadmap' && namespace === 'runs') return roadmapRunStatus(project, fileSystem, workId, mtimeMs);
   const pass = cacheFor({ projectRoot: project, fsImpl: fileSystem, cache });
-  const recordId = taskId;
-  const workId = typeof taskId === 'string' ? taskId.replace(/_claims$/, '') : taskId;
 
   if (shouldStop?.()) return incompleteAnswer();
   if (!safeSegment(workId)) return answer('undecidable', 'record-unreadable', null, null);
@@ -274,7 +468,8 @@ function workStatus({
       record = { ok: false };
     }
   } else {
-    record = readRecord({ projectRoot: project, storePath, recordId, namespace, mtimeMs, fsImpl: fileSystem });
+    record = readRecord({ projectRoot: project, storePath, recordId, namespace, mtimeMs, fsImpl: fileSystem,
+      extension: pass.recordExtensions?.get(store) || '.json' });
   }
   if (shouldStop?.()) return incompleteAnswer(resolvedRun.id);
   if (!record.ok) return answer('undecidable', 'record-unreadable', resolvedRun.id, null);
@@ -284,6 +479,30 @@ function workStatus({
     return answer('open', 'run-open', resolvedRun.id, null);
   }
 
+  // N-1: a namespaced copy of a run may keep the record open or undecidable, never finished.
+  const hold = namespacedHold(pass, workId, namespace, record.value, shouldStop);
+  if (hold.incomplete || shouldStop?.()) return incompleteAnswer(resolvedRun.id);
+  if (hold.open) return answer('open', 'run-open', hold.id, null);
+  if (hold.unreadable) return answer('undecidable', 'run-unreadable', hold.id, null);
+
+  // IC-028: a task-attempts ledger stays open while any attempt is active or cancelled and not cleared
+  // by a resume, or any run is not `running`, so a paused or cancelled run whose boxes are all ticked
+  // is never pruned.
+  if (store === 'task-attempts') {
+    const ledgerOpen = openLedgerReason(record.value);
+    if (ledgerOpen) return answer('open', ledgerOpen, resolvedRun.id, null);
+  }
+
+  // IC-037 (mirrors IC-028): a dispatch store stays open while its run is not `completed` or
+  // `cancelled`, so a paused, blocked or resume-required run on a fully ticked plan keeps the
+  // record that names its kept worktrees.
+  if (store === 'dispatch') {
+    const dispatchRun = record.value && typeof record.value === 'object' ? record.value.run : null;
+    if (dispatchRun !== null && dispatchRun !== undefined && !DISPATCH_RUN_SETTLED.includes(dispatchRun?.state)) {
+      return answer('open', 'dispatch-run-open', resolvedRun.id, null);
+    }
+  }
+
   // W5: feature metadata is ordered; folder-name inference is the final fallback.
   let feature                = stringField(run, 'featureSlug')
     || stringField(record.value, 'featureSlug')
@@ -323,4 +542,4 @@ function workStatus({
   return answer('finished', run ? 'run-finished' : 'no-run', resolvedRun.id, feature, since);
 }
 
-module.exports = { workStatus, createWorkCache, refreshedWorkCache, RUN_OPEN_STATES };
+module.exports = { workStatus, recordExtension, createWorkCache, refreshedWorkCache, RUN_OPEN_STATES };