@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/storage/roots.js

@@ -3,16 +3,16 @@
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
+const { configHome } = require('../config-home.js');
 
 function absolute(value     )                { return typeof value === 'string' && path.isAbsolute(value) ? value : null; }
 
 /** Resolves IC-001's five physical roots; -g/global deliberately omits project roots. */
 function resolveRoots({ registry, projectRoot, global = false, env = process.env }      = {})                                {
-  const home = absolute(env.HOME) || os.homedir();
-  const xdgBase = env.XDG_CONFIG_HOME === undefined || env.XDG_CONFIG_HOME === ''
-    ? path.join(home, '.config') : absolute(env.XDG_CONFIG_HOME);
+  // No home variable means no home base and no config home: nothing falls back to the account home (DD-7).
+  const home = absolute(env.HOME);
+  const xdgBase = configHome(env).base;
   const project = global ? null : absolute(projectRoot);
   const bases                                = { project, home, 'xdg-config': xdgBase };
   return Object.fromEntries(Object.entries(registry.roots).map(([id, root]               ) => {
@@ -21,21 +21,71 @@ function resolveRoots({ registry, projectRoot, global = false, env = process.env
   }));
 }
 
-function readSetting(file        , fsImpl     )         {
-  try {
-    const first = fsImpl.readFileSync(file, 'utf8').split(/\r?\n/, 1)[0].trim().toLowerCase();
-    return first === 'on' || first === 'off' ? first : 'off';
-  } catch { return 'off'; }
+/** Creates one IC-014 resolver for all roots in a command; a project view can also read global scope. */
+function createPruneSettingsResolver({ roots, fsImpl = fs, onView }      = {})                                                                    {
+  const resolverEnv                         = {};
+  if (roots['config-home']) resolverEnv.XDG_CONFIG_HOME = path.dirname(roots['config-home']);
+  let view      = null;
+  let loadedView = false;
+  return (rootId        ) => {
+    if (!loadedView) {
+      loadedView = true;
+      try {
+        let settingsRegistry;
+        if (fsImpl !== fs) {
+          const { loadSettingsRegistry } = require('../settings/registry.js');
+          const loaded = loadSettingsRegistry({ fsImpl });
+          if (!loaded.ok) throw new Error(loaded.detail);
+          settingsRegistry = loaded.registry;
+        }
+        const { loadSettings } = require('../settings/resolve.js');
+        const projectRoot = roots['project-doflow'] ? path.dirname(roots['project-doflow']) : null;
+        view = loadSettings({ projectRoot, env: resolverEnv, fsImpl, ...(settingsRegistry ? { registry: settingsRegistry } : {}) });
+      } catch {
+        // A settings registry fault fails closed for every root, as it did for each old call.
+        view = null;
+      }
+      if (typeof onView === 'function') onView(view);
+    }
+    if (!view) return { setting: 'off', decidedBy: null };
+    try {
+      const usesProject = rootId === 'project-doflow' || rootId === 'project-state';
+      const resolved = view.get('storage.prune', usesProject ? 'project' : 'global');
+      return {
+        setting: resolved.value === 'on' ? 'on' : 'off',
+        decidedBy: resolved.origin.layer === 'default' ? null : resolved.origin.source,
+      };
+    } catch {
+      return { setting: 'off', decidedBy: null };
+    }
+  };
 }
 
 /** Reads IC-014 and reports exactly which present file made the decision, if any. */
-function readPruneSetting({ registry, roots, rootId, fsImpl = fs }      = {})                                                {
-  const projectFile = roots['project-doflow'] ? path.join(roots['project-doflow'], registry.settings.optOutFile) : null;
-  const userFile = roots['config-home'] ? path.join(roots['config-home'], registry.settings.optOutFile) : null;
+function readPruneSetting({ roots, rootId, fsImpl = fs }      = {})                                                {
   const usesProject = rootId === 'project-doflow' || rootId === 'project-state';
-  if (usesProject && projectFile && fsImpl.existsSync(projectFile)) return { setting: readSetting(projectFile, fsImpl), decidedBy: projectFile };
-  if (userFile && fsImpl.existsSync(userFile)) return { setting: readSetting(userFile, fsImpl), decidedBy: userFile };
-  return { setting: 'on', decidedBy: null };
+  const global = !usesProject;
+  const projectRoot = !global && roots['project-doflow'] ? path.dirname(roots['project-doflow']) : null;
+  const resolverEnv                         = {};
+  if (roots['config-home']) resolverEnv.XDG_CONFIG_HOME = path.dirname(roots['config-home']);
+  try {
+    let settingsRegistry;
+    if (fsImpl !== fs) {
+      const { loadSettingsRegistry } = require('../settings/registry.js');
+      const loaded = loadSettingsRegistry({ fsImpl });
+      if (!loaded.ok) throw new Error(loaded.detail);
+      settingsRegistry = loaded.registry;
+    }
+    const { loadSettings } = require('../settings/resolve.js');
+    const view = loadSettings({ projectRoot, global, env: resolverEnv, fsImpl, ...(settingsRegistry ? { registry: settingsRegistry } : {}) });
+    const resolved = view.get('storage.prune', global ? 'global' : 'project');
+    return {
+      setting: resolved.value === 'on' ? 'on' : 'off',
+      decidedBy: resolved.origin.layer === 'default' ? null : resolved.origin.source,
+    };
+  } catch {
+    return { setting: 'off', decidedBy: null };
+  }
 }
 
 function linked(file        , fsImpl     )          {
@@ -60,4 +110,4 @@ function resolveStorePath({ store, roots, fsImpl = fs }      = {})
   return current;
 }
 
-module.exports = { resolveRoots, readPruneSetting, resolveStorePath };
+module.exports = { resolveRoots, readPruneSetting, createPruneSettingsResolver, resolveStorePath };

package/src/runtime/storage/rules.js

@@ -4,7 +4,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { workStatus, createWorkCache, refreshedWorkCache } = require('./work-status.js');
+const { workStatus, recordExtension, createWorkCache, refreshedWorkCache } = require('./work-status.js');
 const { projectKey } = require('../lifecycle/report-store.js');
 const { readEvents } = require('../lifecycle/event-store.js');
 
@@ -50,7 +50,7 @@ function workCandidates(store     , entries     , context     ) {
   const project = projectRoot(roots);
   if (!project) return [];
   const cache = context.cache || createWorkCache({ projectRoot: project, fsImpl });
-  const recordMatch = new RegExp(store.match), selected        = [];
+  const recordMatch = new RegExp(store.match), extensionLength = recordExtension(store.match).length, selected        = [];
   const visit = (dir     , namespace      = null) => {
     let children;
     try { children = names(fsImpl, dir); } catch { return true; }
@@ -61,7 +61,7 @@ function workCandidates(store     , entries     , context     ) {
       if (TMP.test(name) && now - stat.mtimeMs > settings.staleTmpHours * HOUR) {
         selected.push({ name: namespace ? `${namespace}/${name}` : name, reason: 'stale-tmp', bytes: stat.size, mtimeMs: stat.mtimeMs, recordStat: stat });
       } else if (recordMatch.test(name)) {
-        const result = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: stat.mtimeMs, cache, fsImpl, shouldStop });
+        const result = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -extensionLength), namespace, mtimeMs: stat.mtimeMs, cache, fsImpl, shouldStop });
         if (result.incomplete || shouldStop?.()) return false;
         if (result.state === 'finished' && now - result.since > store.bound.finishedDays * DAY)
           selected.push({ name: namespace ? `${namespace}/${name}` : name, reason: 'finished-work', bytes: stat.size, mtimeMs: result.since, recordStat: stat });
@@ -92,7 +92,7 @@ function recordStillCandidate(store     , candidate     , info     , context
     if (!snapshot?.ok || JSON.stringify(current) !== JSON.stringify(snapshot.value)) return false;
   }
   const fresh = cache ? refreshedWorkCache(cache) : undefined;
-  const status = workStatus({ projectRoot: projectRoot(roots), store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: info.mtimeMs, cache: fresh, fsImpl, shouldStop });
+  const status = workStatus({ projectRoot: projectRoot(roots), store: store.id, taskId: name.slice(0, -recordExtension(store.match).length), namespace, mtimeMs: info.mtimeMs, cache: fresh, fsImpl, shouldStop });
   return !status.incomplete && !shouldStop?.() && status.state === 'finished'
     && status.since === candidate.mtimeMs && now - status.since > store.bound.finishedDays * DAY;
 }
@@ -138,7 +138,7 @@ function protectedLogs({ registry, roots, fsImpl, cache, shouldStop }     ) {
           continue;
         }
         if (!stat.isFile() || !recordMatch.test(name)) continue;
-        const status = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: stat.mtimeMs, cache: workCache, fsImpl, shouldStop });
+        const status = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -recordExtension(store.match).length), namespace, mtimeMs: stat.mtimeMs, cache: workCache, fsImpl, shouldStop });
         if (status.incomplete || shouldStop?.()) return false;
         if (status.state === 'finished') continue;
         try {
@@ -158,6 +158,73 @@ function protectedLogs({ registry, roots, fsImpl, cache, shouldStop }     ) {
   }
   return { names: protectedNames, incomplete: false };
 }
+const WORKER_UNIT = /^L\.([A-Za-z0-9][A-Za-z0-9_-]{0,55})\.([A-Za-z0-9][A-Za-z0-9_-]{0,55})\.([1-9][0-9]{0,3})\.json$/;
+/** Every `<slug>.json` store file of `.doflow/state/<dir>` read by `read`; [] when the folder is
+ * absent, null when a link sits on the path or any file cannot be read (the caller fails closed). */
+function stateStores(project        , dir        , read                                    , fsImpl     , shouldStop     )               {
+  let current = project;
+  for (const segment of ['.doflow', 'state', dir]) {
+    current = path.join(current, segment);
+    let info;
+    try { info = fsImpl.lstatSync(current); }
+    catch (error     ) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return []; return null; }
+    if (info.isSymbolicLink() || !info.isDirectory()) return null;
+  }
+  const stores        = [];
+  let list;
+  try { list = names(fsImpl, current); } catch { return null; }
+  for (const name of list) {
+    if (shouldStop?.()) return null;
+    if (!name.endsWith('.json')) continue;
+    const info = safeStat(fsImpl, path.join(current, name));
+    if (!info || info.isSymbolicLink() || !info.isFile()) return null;
+    try { stores.push(read(path.join(current, name), fsImpl)); } catch { return null; }
+  }
+  return stores;
+}
+/**
+ * Protect kind `unfinished-run` (row 120 IC-005): of the candidate names `L.<run>.<lineage>.<attempt>.json`,
+ * the ones to keep. A name is released only when this project's worker run store holds at least one
+ * run whose `identity` is that unit and every such run is terminal, and no dispatch naming one of
+ * those runs (`workerRunId`) is still open. Terminal is the one end phase each store has: a worker
+ * run's `phase: 'ended'` (run-store.ts PHASES, which `transition` never leaves) and a dispatch's
+ * `phase: 'ended'` (dispatch/store.ts NEXT_PHASES, add-only once reached). Everything else is kept
+ * (fail closed): an unparsable name, no project, an unknown unit (another project's file, or a run
+ * record pruned first), a link on a store path or any store file that cannot be read.
+ */
+function unfinishedRuns({ roots, fsImpl, names: candidates, shouldStop }     )                                              {
+  const all = new Set        (candidates);
+  const project = projectRoot(roots);
+  if (!project) return { names: all, incomplete: false };
+  const { readRuns } = require('../worker/run-store.js');
+  const { readDispatch } = require('../dispatch/store.js');
+  const runStores = stateStores(project, 'worker-runs', (file, impl) => ({ runs: readRuns(file, impl) }), fsImpl, shouldStop);
+  if (shouldStop?.()) return { names: all, incomplete: true };
+  const dispatchStores = runStores && stateStores(project, 'dispatch', readDispatch, fsImpl, shouldStop);
+  if (shouldStop?.()) return { names: all, incomplete: true };
+  if (!runStores || !dispatchStores) return { names: all, incomplete: false };
+  const units = new Map                                              ();
+  for (const store of runStores) for (const [runId, run] of Object.entries(store.runs)                   ) {
+    const id = run?.identity;
+    if (!id || typeof id.run !== 'string' || typeof id.lineage !== 'string' || typeof id.attempt !== 'string') continue;
+    const key = `${id.run}.${id.lineage}.${id.attempt}`;
+    const unit = units.get(key) || { ended: true, runIds: [] };
+    unit.ended = unit.ended && run.phase === 'ended';
+    unit.runIds.push(runId);
+    units.set(key, unit);
+  }
+  const openRuns = new Set        ();
+  for (const store of dispatchStores) for (const dispatch of Object.values(store.dispatches)         ) {
+    if (dispatch.phase !== 'ended' && typeof dispatch.workerRunId === 'string') openRuns.add(dispatch.workerRunId);
+  }
+  const kept = new Set        ();
+  for (const name of candidates) {
+    const match = WORKER_UNIT.exec(name);
+    const unit = match && units.get(`${match[1]}.${match[2]}.${match[3]}`);
+    if (!unit || !unit.ended || unit.runIds.some((runId) => openRuns.has(runId))) kept.add(name);
+  }
+  return { names: kept, incomplete: false };
+}
 function lifecyclePathsSafe(project     , fsImpl     ) {
   for (const rel of [path.join('.doflow'), path.join('.doflow', 'state'), path.join('.doflow', 'state', 'lifecycle'), path.join('.doflow', 'state', 'lifecycle', 'events')]) {
     try { if (fsImpl.lstatSync(path.join(project, rel)).isSymbolicLink()) return false; }
@@ -236,14 +303,19 @@ function selectCandidates(store     , entries     , context     ) {
   const { now, fsImpl, storeDir, roots, shouldStop } = context;
   switch (store.rule) {
     case 'count-and-age': {
-      const ordered = [...entries].sort((a, b) => Number(b.name.slice(0, 13)) - Number(a.name.slice(0, 13)) || a.name.localeCompare(b.name));
+      const hasTimestamp = (entry     ) => /^[0-9]{13}/.test(entry.name);
+      const entryTime = (entry     ) => hasTimestamp(entry) ? Number(entry.name.slice(0, 13)) : entry.stat.mtimeMs;
+      const ordered = [...entries].sort((a, b) => entryTime(b) - entryTime(a) || a.name.localeCompare(b.name));
       if (stopped(context)) return null;
       const selected = [];
       for (let index = 0; index < ordered.length; index += 1) {
         if (shouldStop?.()) return null;
-        const entry = ordered[index], time = Number(entry.name.slice(0, 13));
-        if (index >= store.bound.keepNewest || now - time > store.bound.maxAgeDays * DAY)
-          selected.push({ name: entry.name, reason: index >= store.bound.keepNewest ? 'count' : 'age', bytes: entry.stat.size, mtimeMs: time });
+        const entry = ordered[index], time = entryTime(entry);
+        const beyondCount = index >= store.bound.keepNewest, beyondAge = now - time > store.bound.maxAgeDays * DAY;
+        // Preserve timestamped stores' count-or-age policy; mtime entries must exceed both bounds unless bound.either is set.
+        const eitherBound = hasTimestamp(entry) || store.bound?.either === true;
+        if (eitherBound ? beyondCount || beyondAge : beyondCount && beyondAge)
+          selected.push({ name: entry.name, reason: beyondCount ? 'count' : 'age', bytes: entry.stat.size, mtimeMs: time });
       }
       return selected;
     }
@@ -279,4 +351,4 @@ function selectCandidates(store     , entries     , context     ) {
     default: throw new Error(`Unknown storage rule '${store.rule}'`);
   }
 }
-module.exports={selectCandidates,recordStillCandidate,protectedLogs,removableRules,ruleOrder,projectRoot,BODY};
+module.exports={selectCandidates,recordStillCandidate,protectedLogs,unfinishedRuns,removableRules,ruleOrder,projectRoot,BODY};

package/src/runtime/storage/upkeep.js

@@ -9,7 +9,7 @@ const { REPO_ROOT } = require('../../helper/repo-root.js');
 const { loadStorageRegistry } = require('./registry.js');
 const { resolveRoots, readPruneSetting } = require('./roots.js');
 const engine = require('./engine.js');
-const { RunLedger } = require('../trace/ledger.js');
+const { RunLedger, outerProjectRoot } = require('../trace/ledger.js');
 
 // Load once: a not-due moment only reads the three small markers, never the catalogue again.
 let registry     ;
@@ -147,7 +147,10 @@ function passForRoot({ roots, rootId, stores, now, env, fsImpl, throttled = fals
 
 /** IC-009: silent throttled upkeep after a verb, using that verb's resolved store root. */
 function upkeepAfterVerb({ projectRoot, now = Date.now(), env = process.env, fsImpl = fs }      = {}) {
+  // IC-004: the read switch, exact `off` like DOFLOW_TELEMETRY; nothing at all is written.
+  if (env.DOFLOW_UPKEEP === 'off') return;
   return silently(() => {
+    projectRoot = projectRoot && outerProjectRoot(projectRoot);
     const roots = resolveRoots({ registry, projectRoot, env });
     for (const rootId of ['project-state', 'user-state']) {
       try { ensureIgnore({ roots, rootId, projectRoot, fsImpl }); } catch { /* continue other roots */ }
@@ -165,14 +168,19 @@ function upkeepAfterVerb({ projectRoot, now = Date.now(), env = process.env, fsI
 
 /** IC-010: the verify moment is project-only and unthrottled. Wiring belongs to D.3. */
 function upkeepAfterVerify({ projectRoot, now = Date.now(), env = process.env, fsImpl = fs }      = {}) {
+  // IC-004: the switch covers every upkeep moment, so `off` prunes, locks and writes nothing here either.
+  if (env.DOFLOW_UPKEEP === 'off') return;
   return silently(() => {
+    projectRoot = projectRoot && outerProjectRoot(projectRoot);
     const roots = resolveRoots({ registry, projectRoot, env });
-    return passForRoot({ roots, rootId: 'project-state', stores: ['verification-logs'], now, env, fsImpl });
+    return passForRoot({ roots, rootId: 'project-state', stores: ['verification-logs', 'verification-reuse'], now, env, fsImpl });
   });
 }
 
 /** IC-011: only this scope's recovery store; install/update call sites belong to D.4. */
 function storageAfterInstall({ scope, scopeRoot, now = Date.now(), env = process.env, fsImpl = fs }      = {}) {
+  // IC-004: no ignore file, prune pass or lock at install time under the switch either.
+  if (env.DOFLOW_UPKEEP === 'off') return;
   return silently(() => {
     if (!['project', 'global'].includes(scope)) return;
     const global = scope === 'global';