@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/task-scope.js

@@ -6,14 +6,15 @@ const fs = require('node:fs');
 const path = require('node:path');
 const featureResolve = require('./feature-resolve.js');
 
-// Which feature a task record belongs to (feature 045, IC-001/IC-002).
+// Which feature a task record belongs to (feature 045 IC-001/IC-002, 115 IC-004).
 //
 // Task ids are short and repeat across features (`A.1` exists in every feature that has a Phase A),
-// and the stores key records by the bare id. A task in one feature therefore read the evidence,
-// claims and outcome another feature had written under the same id. A feature that has a decision
-// register now keeps its records in a subdirectory named for the feature; a feature without one,
-// and a task id that is the feature's own slug, keep the flat layout, so no existing record is
-// moved, renamed or rewritten (FR-007) and a namespaced read never falls back to the flat file.
+// and the stores key records by the bare id. Every task record therefore lives under a subdirectory
+// named for its feature whenever a feature slug resolves (`--slug`, else the branch's), with or
+// without a decision register and wherever the feature folder is; a task id that is the feature's
+// own slug, and a call with no feature at all, keep the flat layout. Records written flat before
+// this rule stay readable in place: a namespaced read falls back to the flat file when it is this
+// feature's or names no feature, and the first write lands in the namespace (D-3). Nothing is moved.
 
 const SAFE_SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const SLUG_RULE = 'use letters, digits, dot, underscore or dash, start with a letter or digit, and no ".."';
@@ -34,19 +35,29 @@ function invalidSlugRefusal(slug     )
   return { error: 'invalid-slug', message: `slug "${slug}" is not a valid feature slug: ${SLUG_RULE}`, hint: SLUG_RULE };
 }
 
-/** (projectRoot, slug) -> { slug, hasRegister } | { reason }. One resolver spawn per key per process. */
-const featureCache = new Map             ();
+/** projectRoot -> the branch's feature slug or null. One resolver spawn per root per process. */
+const featureCache = new Map                       ();
 
 /** The resolver's raw answer, including thrown failures, shared by every consumer in this process. */
 const resolvedFeatureCache = new Map                                             ();
 
-/** A slug the CLI named explicitly (`--slug`), applied to every store call in this process that was
- * not given its own. The dispatcher sets it once so the verbs whose handlers build their ledger
- * internally (readiness, evidence) route the same way as the ones that take `slug` directly. */
-let defaultSlug                = null;
+/** The record slug of the CLI call in progress (115 C-1): `--slug`, else the feature of the checkout
+ * the verb runs in, computed once by the dispatcher (a function is called on first use, then kept)
+ * and used by every store the call touches. `undefined` means no dispatcher call is in progress, and
+ * a store resolves the branch of its own project root. */
+let callSlug                                                    = undefined;
 
-function setDefaultSlug(slug     )       {
-  defaultSlug = typeof slug === 'string' && slug !== '' ? slug : null;
+function setRecordSlug(slug                                                   )       {
+  callSlug = slug === undefined || typeof slug === 'function' ? slug : (isSafeSlug(slug) ? slug : null);
+}
+
+function currentCallSlug()                            {
+  if (typeof callSlug === 'function') {
+    let value      = null;
+    try { value = callSlug(); } catch { /* a failed lookup routes nothing to a guessed feature */ }
+    callSlug = isSafeSlug(value) ? value : null;
+  }
+  return callSlug                             ;
 }
 
 function clearTaskScopeCache()       {
@@ -68,6 +79,12 @@ function resolveFeature({ projectRoot, slug = null }
   try {
     const value = featureResolve.resolveActiveFeature({ projectRoot, slug: slug || null });
     resolvedFeatureCache.set(key, { value });
+    // The branch's answer is also the answer for its own slug named explicitly: one spawn serves both.
+    const named = !slug && !value?.error ? value?.paths?.feature_slug : null;
+    if (isSafeSlug(named)) {
+      const namedKey = `${path.resolve(projectRoot)}\0${named}`;
+      if (!resolvedFeatureCache.has(namedKey)) resolvedFeatureCache.set(namedKey, { value });
+    }
     return value;
   } catch (error) {
     resolvedFeatureCache.set(key, { error });
@@ -75,73 +92,120 @@ function resolveFeature({ projectRoot, slug = null }
   }
 }
 
-/** The resolver reports the git top level, which is the project root or one of its ancestors, and
- * the feature folders live directly under it — so no `agent-docs/doflow` on the way up means there
- * is nothing to resolve and the spawn is skipped. */
-function hasFeatureFolderAbove(projectRoot        )          {
-  let dir = path.resolve(projectRoot);
-  for (;;) {
-    try {
-      if (fs.statSync(path.join(dir, 'agent-docs', 'doflow')).isDirectory()) return true;
-    } catch { /* not here */ }
-    const parent = path.dirname(dir);
-    if (parent === dir) return false;
-    dir = parent;
+/** Whether a branch or a feature folder could name a feature here: a `.git` or an
+ * `agent-docs/doflow` above the root. With neither the resolver has nothing to read and is skipped. */
+function mayNameFeature(projectRoot        )          {
+  for (let dir = path.resolve(projectRoot); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'agent-docs', 'doflow'))) return true;
+    if (path.dirname(dir) === dir) return false;
   }
 }
 
-function featureFor(projectRoot        , slug                           )      {
-  const key = `${path.resolve(projectRoot)}\0${slug || ''}`;
-  if (featureCache.has(key)) return featureCache.get(key);
-  let value      = { reason: 'no-feature' };
+/** The feature slug the resolver gives for a root's branch (or its one feature folder), else null. */
+function branchSlugFor(projectRoot        )                {
+  const key = path.resolve(projectRoot);
+  if (featureCache.has(key)) return featureCache.get(key) ;
+  let value                = null;
   try {
-    if (hasFeatureFolderAbove(projectRoot)) {
-      const found = resolveFeature({ projectRoot, slug: slug || null });
-      if (!found.error && found.paths && isSafeSlug(found.paths.feature_slug)) {
-        value = { slug: found.paths.feature_slug, hasRegister: found.paths.has_decisions === true, exists: fs.existsSync(found.featureDir) };
-      }
+    if (mayNameFeature(projectRoot)) {
+      const found = resolveFeature({ projectRoot });
+      if (!found.error && found.paths && isSafeSlug(found.paths.feature_slug)) value = found.paths.feature_slug;
     }
   } catch { /* a resolver failure is "no feature", never an exception */ }
   featureCache.set(key, value);
   return value;
 }
 
+/**
+ * The feature a call's records are keyed by when no `--slug` is given (115 C-1), as
+ * `featureSlugFor` names it but through the cached resolver: a task id that names a feature folder in
+ * the checkout is its own feature, else the branch's.
+ * @param {{projectRoot: string, taskId?: string|null}} options
+ * @returns {string|null}
+ */
+function callerFeatureSlug({ projectRoot, taskId = null }                                                 )                {
+  if (isSafeSlug(taskId)) {
+    try { if (fs.statSync(path.join(projectRoot, 'agent-docs', 'doflow', taskId          )).isDirectory()) return taskId          ; } catch { /* not a folder */ }
+  }
+  return branchSlugFor(projectRoot);
+}
+
 /**
  * @param {Object} options
  * @param {string} options.projectRoot
  * @param {string} options.taskId
- * @param {string|null} [options.slug] explicit feature; otherwise the `--slug` default, then the branch
+ * @param {string|null} [options.slug] explicit feature; otherwise the call's record slug, then the branch
  * @returns {{namespace: string|null, slug: string|null, reason: string}}
- *   `reason` is `namespaced` when a namespace applies, else `no-feature`, `no-register` or
- *   `feature-level-id`.
+ *   `reason` is `namespaced` when a namespace applies, else `no-feature` or `feature-level-id`.
  */
 function resolveTaskScope({ projectRoot, taskId, slug = null }                                                               )                                                                    {
-  const feature = featureFor(projectRoot, slug || defaultSlug);
-  if (feature.reason) return { namespace: null, slug: null, reason: feature.reason };
-  if (!feature.hasRegister) return { namespace: null, slug: feature.slug, reason: 'no-register' };
-  if (taskId === feature.slug) return { namespace: null, slug: feature.slug, reason: 'feature-level-id' };
-  return { namespace: feature.slug, slug: feature.slug, reason: 'namespaced' };
+  const call = slug ? undefined : currentCallSlug();
+  const feature = slug ? (isSafeSlug(slug) ? slug : null) : call !== undefined ? call : branchSlugFor(projectRoot);
+  if (!feature) return { namespace: null, slug: null, reason: 'no-feature' };
+  if (taskId === feature) return { namespace: null, slug: feature, reason: 'feature-level-id' };
+  return { namespace: feature, slug: feature, reason: 'namespaced' };
+}
+
+/** The largest record file `readRegularFileText` reads; a bigger one is refused (a record is a few KiB). */
+const MAX_RECORD_FILE_BYTES = 1024 * 1024;
+
+/** A record file's text, or null when it must not be read: not a regular file (a link, a FIFO, a
+ * device, a folder), larger than `MAX_RECORD_FILE_BYTES`, or any read error. The lifecycle reader's
+ * pattern (event-store.ts `readEventFile`): `lstat`, then `O_NOFOLLOW|O_NONBLOCK` so neither a link
+ * nor a FIFO swapped in after the `lstat` is followed or blocks, then `fstat` on the descriptor
+ * before reading. The one read every run-file probe and reader shares (FU-16c2wz). */
+function readRegularFileText(file        , fsImpl      = fs)                {
+  const flags = fs.constants;
+  let fd                    ;
+  try {
+    if (!fsImpl.lstatSync(file).isFile()) return null;
+    fd = fsImpl.openSync(file, flags.O_RDONLY | (flags.O_NOFOLLOW || 0) | (flags.O_NONBLOCK || 0));
+    const st = fsImpl.fstatSync(fd);
+    if (!st.isFile() || st.size > MAX_RECORD_FILE_BYTES) return null;
+    // Read at most one byte past the cap, so a file that grew after the fstat is still refused.
+    const buffer = Buffer.alloc(MAX_RECORD_FILE_BYTES + 1);
+    let length = 0;
+    for (let n = -1; n !== 0 && length <= MAX_RECORD_FILE_BYTES; length += n) {
+      n = fsImpl.readSync(fd, buffer, length, buffer.length - length, null);
+    }
+    return length > MAX_RECORD_FILE_BYTES ? null : buffer.subarray(0, length).toString('utf8');
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) { try { fsImpl.closeSync(fd); } catch { /* the read is done */ } }
+  }
 }
 
 /**
- * Whether an explicit slug, already known to be well-formed, names no feature folder here. The
- * records then go to the shared task store, which is today's behaviour and is worth one line to the
- * caller because the slug they typed did nothing.
- * @param {Object} options
- * @param {string} options.projectRoot
- * @param {string} options.slug
+ * Whether a flat record may be read as `slug`'s (D-3): it names that feature (`featureSlug` on a
+ * run, `slug` on a readiness record) or names none. A file that does not parse names nobody, so a
+ * namespaced read never falls back to it. The probe never blocks and follows no link: a flat file
+ * that is not a regular file of at most `MAX_RECORD_FILE_BYTES` is not read; `unsafeIsOurs` is then
+ * the answer, so a caller whose reader refuses such a file (the run store's `readRunRecord`) is
+ * pointed at it and reports it, and any other caller treats it as not ours.
+ * @param {string} file
+ * @param {string|null} slug
+ * @param {Object} [fsImpl]
+ * @param {boolean} [unsafeIsOurs]
  * @returns {boolean}
  */
-function slugNamesNoFeature({ projectRoot, slug }                                       )          {
-  const feature = featureFor(projectRoot, slug);
-  return Boolean(feature.reason) || feature.exists === false;
+function flatRecordIsOurs(file        , slug               , fsImpl      = fs, unsafeIsOurs = false)          {
+  let data     ;
+  try {
+    const text = typeof fsImpl.lstatSync === 'function' && typeof fsImpl.openSync === 'function'
+      ? readRegularFileText(file, fsImpl) : fsImpl.readFileSync(file, 'utf8');
+    if (text === null) return unsafeIsOurs;
+    data = JSON.parse(text);
+  } catch { return false; }
+  const named = [data?.featureSlug, data?.slug].find((value) => typeof value === 'string' && value !== '');
+  return named === undefined || named === slug;
 }
 
 /**
- * The directory a task's record file for one store lives in (IC-002).
+ * The directory a task's record file for one store is written in (IC-002, 115 IC-004).
  * @param {Object} options
  * @param {string} options.projectRoot
- * @param {string} options.store state subdirectory: evidence | research | outcome | retrieval
+ * @param {string} options.store state subdirectory: evidence | research | outcome | retrieval | ...
  * @param {string} options.taskId
  * @param {string|null} [options.slug]
  * @returns {string}
@@ -152,4 +216,61 @@ function taskStoreDir({ projectRoot, store, taskId, slug = null }
   return namespace ? path.join(base, namespace) : base;
 }
 
-module.exports = { resolveFeature, resolveTaskScope, taskStoreDir, setDefaultSlug, clearTaskScopeCache, isSafeSlug, invalidSlugRefusal, slugNamesNoFeature };
+/**
+ * One task record (115 C-1, D-3): `file`, where it is written (always the namespace when one
+ * applies); `read`, where it is read from (that file when it exists, else a flat file of the same
+ * name that `flatRecordIsOurs`); and `seed`, a `prepare` for the write lock that starts a namespaced
+ * file not written yet from that flat one, so a store that rebuilds from disk keeps what it read.
+ * @param {Object} options
+ * @param {string} options.projectRoot
+ * @param {string} options.store
+ * @param {string} options.taskId
+ * @param {string|null} [options.slug]
+ * @param {string} [options.name] the file name (default `<taskId>.json`)
+ * @param {Object} [options.fsImpl]
+ * @returns {{file: string, read: string, seed: () => void}}
+ */
+function taskRecord({ projectRoot, store, taskId, slug = null, name = null, fsImpl = fs }     )                                                   {
+  const scope = resolveTaskScope({ projectRoot, taskId, slug });
+  return recordIn({ base: path.join(projectRoot, '.doflow', 'state', store), namespace: scope.namespace, name: name || `${taskId}.json`, fsImpl });
+}
+
+/**
+ * `taskRecord` for a store directory and a namespace already known (the orchestrator's run journal).
+ * @param {{base: string, namespace: string|null, name: string, fsImpl?: Object, refuseUnsafeFlat?: boolean}} options
+ *   `refuseUnsafeFlat`: a flat file that is not a safely readable regular file is `read` (so the
+ *   caller's safe reader refuses it by name) instead of being skipped
+ * @returns {{file: string, read: string, seed: () => void}}
+ */
+function recordIn({ base, namespace, name, fsImpl = fs, refuseUnsafeFlat = false }     )                                                   {
+  const file = path.join(base, ...(namespace ? [namespace] : []), name);
+  const flat = path.join(base, name);
+  const fallback = ()                => (namespace && !fsImpl.existsSync(file) && fsImpl.existsSync(flat)
+    && flatRecordIsOurs(flat, namespace, fsImpl, refuseUnsafeFlat) ? flat : null);
+  const seed = () => {
+    const from = fallback();
+    // Required on use: the record mover (a declared writer of every task store) loads the storage registry.
+    if (from) require('./state-root.js').placeRecord(file, fsImpl.readFileSync(from), fsImpl);
+  };
+  return { file, read: fallback() || file, seed };
+}
+
+/**
+ * Whether an explicit, well-formed slug names no feature folder in any of the given checkouts. The
+ * records still go under that slug; a typo would start a namespace nobody reads, which is worth one
+ * line to the caller.
+ * @param {Object} options
+ * @param {Array<string>} options.projectRoots
+ * @param {string} options.slug
+ * @returns {boolean}
+ */
+function slugNamesNoFeature({ projectRoots, slug }                                          )          {
+  return !projectRoots.some((projectRoot) => {
+    try {
+      const found = resolveFeature({ projectRoot, slug });
+      return !found.error && fs.existsSync(found.featureDir);
+    } catch { return false; }
+  });
+}
+
+module.exports = { readRegularFileText, MAX_RECORD_FILE_BYTES, resolveFeature, resolveTaskScope, taskStoreDir, taskRecord, recordIn, flatRecordIsOurs, setRecordSlug, callerFeatureSlug, clearTaskScopeCache, isSafeSlug, invalidSlugRefusal, slugNamesNoFeature };

package/src/runtime/task-sources.js

@@ -0,0 +1,147 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Task source records (feature 080, design C5, IC-013): what a task's declared `files:` looked like
+// at claim, and how that compares with what they look like at resume.
+//
+// `measureSources` is a probe: it reads the filesystem, so the caller runs it before the ledger
+// lock (claim before `mutate()`, resume before any lock). It starts no process: each file is hashed
+// by 076's `sourceVersionFor` with a null tree state, which never runs git. `compareSources` is pure.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { sourceVersionFor } = require('./source-version.js');
+
+/** IC-013: a file larger than this is `unhashable`, `too-large`, and is never read. */
+const MAX_HASH_BYTES = 1024 * 1024;
+/** IC-013: only the first this-many `files:` entries are measured; more sets `sourcesTruncated`. */
+const MAX_SOURCES = 64;
+
+/** IC-013: `*`, `?`, whitespace or `(` anywhere, or a trailing `:<n>` / `:<n>-<n>` line annotation. */
+const PATTERN = /[*?\s(]|:\d+(?:-\d+)?$/;
+
+                        
+               
+                                                          
+                          
+                                                                      
+ 
+
+                             
+                          
+                            
+                                                                                          
+                                
+                                                                                                
+                               
+ 
+
+                                                                    
+
+                       
+                                     
+                                                                                  
+
+/** The entry as resolved on disk: trimmed, leading `./` dropped (the IC-016 normalisation). */
+function normalizeEntry(file        )         {
+  return String(file).trim().replace(/^(\.\/)+/, '');
+}
+
+function exists(dir                           )          {
+  if (!dir) return false;
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** One `lstat` per candidate root, in order; the first root holding the entry wins. */
+function locate(entry        , roots          )                                     {
+  for (const root of roots) {
+    try {
+      return { root, stat: fs.lstatSync(path.resolve(root, entry)) };
+    } catch {
+      // Not under this root: try the next.
+    }
+  }
+  return null;
+}
+
+function measureOne(declared        , roots          )               {
+  const file = String(declared);
+  const entry = normalizeEntry(file);
+  if (PATTERN.test(entry)) return { file, kind: 'unverifiable', fileHash: null, why: 'pattern' };
+
+  const found = locate(entry, roots);
+  if (!found) return { file, kind: 'absent', fileHash: null };
+  const { root, stat } = found;
+  if (stat.isSymbolicLink()) return { file, kind: 'unhashable', fileHash: null, why: 'link' };
+  if (stat.isDirectory()) return { file, kind: 'unhashable', fileHash: null, why: 'directory' };
+  if (!stat.isFile()) return { file, kind: 'unhashable', fileHash: null, why: 'read-error' };
+  // The size check precedes any read: an oversized file is never opened.
+  if (stat.size > MAX_HASH_BYTES) return { file, kind: 'unhashable', fileHash: null, why: 'too-large' };
+
+  const fileHash = sourceVersionFor(root, { file: entry }, null).fileHash;
+  if (!fileHash) return { file, kind: 'unhashable', fileHash: null, why: 'read-error' };
+  return { file, kind: 'file', fileHash };
+}
+
+/**
+ * IC-013: measures the task's first 64 `files:` entries, each resolved under `execWorktree` alone
+ * when one is given and exists (an entry absent there is `absent`), else under the `roots` (the
+ * `loadPlan` roots) in order where it exists. A missing `execWorktree` is reported as
+ * `execWorktreeMissing` and the roots are still measured.
+ */
+function measureSources(task                             , execWorktree               , roots           = [])                    {
+  const declared = Array.isArray(task?.files) ? task.files : [];
+  const execWorktreeMissing = Boolean(execWorktree) && !exists(execWorktree);
+  // An execution worktree that exists is the only place an entry is read: a file absent there is
+  // `absent` (a removal), never the main copy. Without one, or when it is gone, the plan roots serve.
+  const candidates = execWorktree && !execWorktreeMissing
+    ? [path.resolve(execWorktree)]
+    : [...new Set(roots.map((root) => path.resolve(root)))];
+  const sources = declared.slice(0, MAX_SOURCES).map((file) => measureOne(file, candidates));
+  return {
+    sources,
+    sourcesTruncated: declared.length > MAX_SOURCES,
+    sourcesUnverifiable: sources.filter(opaque).map((s) => s.file),
+    execWorktreeMissing,
+  };
+}
+
+function opaque(s              )          {
+  return s.kind === 'unhashable' || s.kind === 'unverifiable';
+}
+
+function changeOf(before              , after              )               {
+  if (before.kind === 'absent') return after.kind === 'absent' ? 'unchanged' : 'created';
+  if (after.kind === 'absent') return 'removed';
+  return before.fileHash === after.fileHash ? 'unchanged' : 'changed';
+}
+
+/**
+ * IC-013: compares an attempt's recorded `sources` with a fresh measurement of the same entries.
+ * The whole task is `unverifiable` when the attempt has no `sources`, was truncated, the execution
+ * worktree is gone, a recorded entry is missing from `after`, or any entry is `unhashable` or
+ * `unverifiable` at either time.
+ */
+function compareSources(
+  before                                                                        ,
+  after                   ,
+)                   {
+  const unverifiable                   = { unverifiable: true, files: [] };
+  if (!before || !Array.isArray(before.sources) || before.sourcesTruncated) return unverifiable;
+  if (!after || after.execWorktreeMissing || after.sourcesTruncated) return unverifiable;
+  const now = new Map(after.sources.map((s) => [s.file, s]));
+  const files                                                = [];
+  for (const was of before.sources) {
+    const is = now.get(was.file);
+    if (!is || opaque(was) || opaque(is)) return unverifiable;
+    files.push({ file: was.file, change: changeOf(was, is) });
+  }
+  return { unverifiable: false, files };
+}
+
+module.exports = { MAX_HASH_BYTES, MAX_SOURCES, measureSources, compareSources };