@khoavu882/doflow 2.0.0-beta.3 → 2.0.0-beta.5

package/src/runtime/{task-scope.ts → task-scope.js}

@@ -4,7 +4,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { resolveActiveFeature } = require('./feature-resolve.ts');
+const featureResolve = require('./feature-resolve.js');
 
 // Which feature a task record belongs to (feature 045, IC-001/IC-002).
 //
@@ -19,7 +19,7 @@ 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 ".."';
 
 /** The one shape check for a feature slug (IC-009); do-paths.sh applies the same rule in bash. */
-function isSafeSlug(slug: any): boolean {
+function isSafeSlug(slug     )          {
   return typeof slug === 'string' && SAFE_SLUG.test(slug) && !slug.includes('..');
 }
 
@@ -29,31 +29,56 @@ function isSafeSlug(slug: any): boolean {
  * @param {*} slug
  * @returns {{error: 'invalid-slug', message: string, hint: string}|null}
  */
-function invalidSlugRefusal(slug: any): { error: 'invalid-slug'; message: string; hint: string } | null {
+function invalidSlugRefusal(slug     )                                                                  {
   if (typeof slug !== 'string' || slug === '' || isSafeSlug(slug)) return null;
   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<string, any>();
+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: string | null = null;
+let defaultSlug                = null;
 
-function setDefaultSlug(slug: any): void {
+function setDefaultSlug(slug     )       {
   defaultSlug = typeof slug === 'string' && slug !== '' ? slug : null;
 }
 
-function clearTaskScopeCache(): void {
+function clearTaskScopeCache()       {
   featureCache.clear();
+  resolvedFeatureCache.clear();
+}
+
+/**
+ * Resolve once per process per (root, slug). The resolver spawns do-paths.sh, and every store and
+ * the decisions lookup must see the same answer.
+ */
+function resolveFeature({ projectRoot, slug = null }                                               )      {
+  const key = `${path.resolve(projectRoot)}\0${slug || ''}`;
+  if (resolvedFeatureCache.has(key)) {
+    const cached = resolvedFeatureCache.get(key) ;
+    if ('error' in cached) throw cached.error;
+    return cached.value;
+  }
+  try {
+    const value = featureResolve.resolveActiveFeature({ projectRoot, slug: slug || null });
+    resolvedFeatureCache.set(key, { value });
+    return value;
+  } catch (error) {
+    resolvedFeatureCache.set(key, { error });
+    throw error;
+  }
 }
 
 /** 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: string): boolean {
+function hasFeatureFolderAbove(projectRoot        )          {
   let dir = path.resolve(projectRoot);
   for (;;) {
     try {
@@ -65,13 +90,13 @@ function hasFeatureFolderAbove(projectRoot: string): boolean {
   }
 }
 
-function featureFor(projectRoot: string, slug: string | null | undefined): any {
+function featureFor(projectRoot        , slug                           )      {
   const key = `${path.resolve(projectRoot)}\0${slug || ''}`;
   if (featureCache.has(key)) return featureCache.get(key);
-  let value: any = { reason: 'no-feature' };
+  let value      = { reason: 'no-feature' };
   try {
     if (hasFeatureFolderAbove(projectRoot)) {
-      const found = resolveActiveFeature({ projectRoot, slug: slug || null });
+      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) };
       }
@@ -90,7 +115,7 @@ function featureFor(projectRoot: string, slug: string | null | undefined): any {
  *   `reason` is `namespaced` when a namespace applies, else `no-feature`, `no-register` or
  *   `feature-level-id`.
  */
-function resolveTaskScope({ projectRoot, taskId, slug = null }: { projectRoot: string; taskId: string; slug?: string | null }): { namespace: string | null; slug: string | null; reason: string } {
+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' };
@@ -107,7 +132,7 @@ function resolveTaskScope({ projectRoot, taskId, slug = null }: { projectRoot: s
  * @param {string} options.slug
  * @returns {boolean}
  */
-function slugNamesNoFeature({ projectRoot, slug }: { projectRoot: string; slug: string }): boolean {
+function slugNamesNoFeature({ projectRoot, slug }                                       )          {
   const feature = featureFor(projectRoot, slug);
   return Boolean(feature.reason) || feature.exists === false;
 }
@@ -121,10 +146,10 @@ function slugNamesNoFeature({ projectRoot, slug }: { projectRoot: string; slug:
  * @param {string|null} [options.slug]
  * @returns {string}
  */
-function taskStoreDir({ projectRoot, store, taskId, slug = null }: { projectRoot: string; store: string; taskId: string; slug?: string | null }): string {
+function taskStoreDir({ projectRoot, store, taskId, slug = null }                                                                              )         {
   const base = path.join(projectRoot, '.doflow', 'state', store);
   const { namespace } = resolveTaskScope({ projectRoot, taskId, slug });
   return namespace ? path.join(base, namespace) : base;
 }
 
-module.exports = { resolveTaskScope, taskStoreDir, setDefaultSlug, clearTaskScopeCache, isSafeSlug, invalidSlugRefusal, slugNamesNoFeature };
+module.exports = { resolveFeature, resolveTaskScope, taskStoreDir, setDefaultSlug, clearTaskScopeCache, isSafeSlug, invalidSlugRefusal, slugNamesNoFeature };

package/src/runtime/{task-state.ts → task-state.js}

@@ -28,8 +28,8 @@ const { isDeepStrictEqual } = require('node:util');
 
 /** Three-way merge against the reader's snapshot. Unchanged local records never overwrite a
  * newer disk version; concurrent edits to the same record must be retried after an explicit read. */
-function mergeRecords(local: any[], disk: any[], baseline: Map<any, any>): any[] {
-  const merged = new Map(disk.map((item: any) => [item.id, item]));
+function mergeRecords(local       , disk       , baseline               )        {
+  const merged = new Map(disk.map((item     ) => [item.id, item]));
   for (const item of local) {
     const previous = baseline.get(item.id);
     const current = merged.get(item.id);
@@ -48,7 +48,7 @@ const LOCK_RETRIES = 250;
 const LOCK_WAIT_MS = 20;
 
 /** Synchronous sleep without spinning: Atomics.wait on a throwaway buffer. */
-function sleep(ms: number): void {
+function sleep(ms        )       {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
@@ -59,28 +59,28 @@ function sleep(ms: number): void {
  * @param {string} file
  * @returns {(() => void)|null}
  */
-function tryAcquireLock(fsImpl: any, file: string): (() => void) | null {
+function tryAcquireLock(fsImpl     , file        )                      {
   const lockDir = `${file}.lock`;
   const release = () => { try { fsImpl.rmdirSync(lockDir); } catch { /* released is released */ } };
   try {
     fsImpl.mkdirSync(lockDir);
     return release;
-  } catch (error: any) {
+  } catch (error     ) {
     if (error.code !== 'EEXIST') throw error;
   }
-  let lock: any;
-  try { lock = fsImpl.statSync(lockDir); } catch (error: any) {
+  let lock     ;
+  try { lock = fsImpl.statSync(lockDir); } catch (error     ) {
     if (error.code !== 'ENOENT') return null;
-    try { fsImpl.mkdirSync(lockDir); return release; } catch (retryError: any) {
+    try { fsImpl.mkdirSync(lockDir); return release; } catch (retryError     ) {
       if (retryError.code === 'EEXIST') return null;
       throw retryError;
     }
   }
   if (Date.now() - lock.mtimeMs <= LOCK_STALE_MS) return null;
-  try { fsImpl.rmdirSync(lockDir); } catch (error: any) {
+  try { fsImpl.rmdirSync(lockDir); } catch (error     ) {
     if (error.code !== 'ENOENT') return null;
   }
-  try { fsImpl.mkdirSync(lockDir); return release; } catch (error: any) {
+  try { fsImpl.mkdirSync(lockDir); return release; } catch (error     ) {
     if (error.code === 'EEXIST') return null;
     throw error;
   }
@@ -93,7 +93,7 @@ function tryAcquireLock(fsImpl: any, file: string): (() => void) | null {
  * @param {string} file
  * @returns {() => void}
  */
-function acquireLock(fsImpl: any, file: string): () => void {
+function acquireLock(fsImpl     , file        )             {
   const lockDir = `${file}.lock`;
   // The stale rule below is wall-clock, so the wait must be too: on a host where each attempt costs
   // real time, counting attempts alone would outlive a live holder's staleness window and then
@@ -117,25 +117,66 @@ function acquireLock(fsImpl: any, file: string): () => void {
     + 'If no other session is running, the lock is leftover from a crash younger than its stale timeout; retry shortly.');
 }
 
+/**
+ * Takes the cross-process lock for one state file with a bounded wait.
+ * Makes 1 try plus `retries` retries (default 3) separated by `waitMs` (default 5).
+ * Throws an Error('store-locked') after one try plus retries.
+ * @param {Object} fsImpl
+ * @param {string} file
+ * @param {Object} [options]
+ * @param {number} [options.retries=3]
+ * @param {number} [options.waitMs=5]
+ * @returns {() => void} release function
+ */
+function boundedAcquire(
+  fsImpl     ,
+  file        ,
+  options   
+                     
+                    
+                                   
+                                                                          
+    = {}
+)             {
+  const retries = options?.retries ?? 3;
+  const waitMs = options?.waitMs ?? 5;
+  const sleepFn = options?.sleepFn ?? sleep;
+  const tryAcquire = options?.tryAcquireLockFn ?? tryAcquireLock;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const release = tryAcquire(fsImpl, file);
+    if (release) return release;
+    if (attempt < retries && waitMs > 0) {
+      sleepFn(waitMs);
+    }
+  }
+  const error = new Error('store-locked');
+  (error       ).code = 'store-locked';
+  throw error;
+}
+
 /**
  * Reads and validates one task-state file. Returns null when the file does not exist.
  * @param {Object} fsImpl
  * @param {string} file
  * @returns {Object|null} the parsed payload
  */
-function readTaskState(fsImpl: any, file: string): any {
+function readTaskState(fsImpl     , file        )      {
   if (!fsImpl.existsSync(file)) return null;
-  let data: any;
+  let data     ;
   try {
     data = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
-  } catch (error: any) {
-    throw new Error(`Failed to load state file '${file}': ${error.message}. The write path is atomic `
+  } catch (error     ) {
+    const failure      = new Error(`Failed to load state file '${file}': ${error.message}. The write path is atomic `
       + '(tmp + rename), so a torn file means outside interference; recover it from version control '
       + 'or move it aside and re-record the task\'s items.');
+    failure.code = 'store-unreadable';
+    throw failure;
   }
   if (data && typeof data === 'object' && data.version !== undefined && data.version !== SCHEMA_VERSION) {
-    throw new Error(`State file '${file}' has schema version ${data.version}; this runtime reads version ${SCHEMA_VERSION}. `
+    const failure      = new Error(`State file '${file}' has schema version ${data.version}; this runtime reads version ${SCHEMA_VERSION}. `
       + 'Refusing to guess at its shape — upgrade the runtime or migrate the file.');
+    failure.code = 'store-unreadable';
+    throw failure;
   }
   return data;
 }
@@ -151,16 +192,32 @@ function readTaskState(fsImpl: any, file: string): any {
  *   return the complete new payload (without `version`/`revision`, which are stamped here)
  * @param {() => void} [options.prepare] called INSIDE the lock before the file is read, for a store
  *   that must inspect or set aside what is there under the same exclusion as the write
- * @returns {string} the file path written
+ * @param {(fsImpl: Object, file: string) => () => void} [options.acquire] optional lock acquirer
+ *   defaulting to acquireLock
+ * @returns {string|null} the file path written, or null when build declines a write
  */
-function updateTaskState({ fsImpl, file, build, prepare }: { fsImpl: any; file: string; build: (disk: any) => any; prepare?: () => void }): string {
+function updateTaskState({
+  fsImpl,
+  file,
+  build,
+  prepare,
+  acquire = acquireLock,
+}   
+              
+               
+                            
+                       
+                                                      
+ )                {
   fsImpl.mkdirSync(path.dirname(file), { recursive: true });
-  const release = acquireLock(fsImpl, file);
+  const release = acquire(fsImpl, file);
   try {
     if (prepare) prepare();
     const disk = readTaskState(fsImpl, file);
+    const built = build(disk);
+    if (built === null) return null;
     const payload = {
-      ...build(disk),
+      ...built,
       version: SCHEMA_VERSION,
       revision: (disk && Number.isInteger(disk.revision) ? disk.revision : 0) + 1,
     };
@@ -173,4 +230,12 @@ function updateTaskState({ fsImpl, file, build, prepare }: { fsImpl: any; file:
   }
 }
 
-module.exports = { acquireLock, tryAcquireLock, updateTaskState, readTaskState, mergeRecords, SCHEMA_VERSION };
+module.exports = {
+  acquireLock,
+  tryAcquireLock,
+  boundedAcquire,
+  updateTaskState,
+  readTaskState,
+  mergeRecords,
+  SCHEMA_VERSION,
+};

package/src/runtime/trace/{indicators.ts → indicators.js}

@@ -26,16 +26,16 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { formatMs, finish } = require('./render.ts');
+const { formatMs, finish } = require('./render.js');
 
 const ORCHESTRATION_DIRNAME = 'orchestration';
 
 /** Mirrors resolveRunsLocation's shape, for the sibling state directory this reads. */
-function orchestrationDir(root: string): string {
+function orchestrationDir(root        )         {
   return path.join(root, '.doflow', 'state', ORCHESTRATION_DIRNAME);
 }
 
-function parseAt(value: any): number | null {
+function parseAt(value     )                {
   const ms = Date.parse(value);
   return Number.isNaN(ms) ? null : ms;
 }
@@ -43,10 +43,10 @@ function parseAt(value: any): number | null {
 /** Every record in a directory, plus the names of the ones that did not parse. A file that cannot be
  * read is counted and named rather than skipped: a report that quietly drops what it could not read
  * overstates its own coverage, which is the defect `malformedLines` already guards against for runs. */
-function readRecords(dir: string, fsImpl: any = fs): any {
+function readRecords(dir        , fsImpl      = fs)      {
   if (!fsImpl.existsSync(dir)) return { records: [], unreadable: [], exists: false };
-  const records: any[] = [];
-  const unreadable: any[] = [];
+  const records        = [];
+  const unreadable        = [];
   for (const name of fsImpl.readdirSync(dir).sort()) {
     if (!name.endsWith('.json')) continue;
     try {
@@ -56,7 +56,7 @@ function readRecords(dir: string, fsImpl: any = fs): any {
         continue;
       }
       records.push(parsed);
-    } catch (err: any) {
+    } catch (err     ) {
       unreadable.push({ file: name, reason: err.message });
     }
   }
@@ -65,11 +65,11 @@ function readRecords(dir: string, fsImpl: any = fs): any {
 
 /** A stage row is "not work done" when the orchestrator backfilled it or imported it rather than
  * executing it. Its duration measures when the record was written, so it is listed but never averaged. */
-function isSynthetic(entry: any): boolean {
+function isSynthetic(entry     )          {
   return Boolean(entry.backfilled) || (entry.executionStatus && entry.executionStatus !== 'completed');
 }
 
-function median(values: number[]): number | null {
+function median(values          )                {
   if (!values.length) return null;
   const sorted = [...values].sort((a, b) => a - b);
   const mid = Math.floor(sorted.length / 2);
@@ -77,11 +77,11 @@ function median(values: number[]): number | null {
 }
 
 /** One run's rows, walking history in recorded order with a cursor so no interval is counted twice. */
-function runRows(record: any): any {
+function runRows(record     )      {
   const history = Array.isArray(record.history) ? record.history : [];
   let cursor = parseAt(record.startedAt);
-  const stages: any[] = [];
-  const gates: any[] = [];
+  const stages        = [];
+  const gates        = [];
   let reruns = 0;
 
   for (const entry of history) {
@@ -131,13 +131,13 @@ function runRows(record: any): any {
 /** Median elapsed per stage id across runs of one class. Synthetic rows are excluded here and still
  * listed in their run: averaging the moment a file was written into the figure most likely to be
  * quoted would corrupt it. */
-function aggregateStages(runs: any[]): any[] {
-  const perStage = new Map<string, number[]>();
+function aggregateStages(runs       )        {
+  const perStage = new Map                  ();
   for (const run of runs) {
     for (const row of run.stages) {
       if (row.synthetic || row.elapsedMs === null || !row.stage) continue;
       if (!perStage.has(row.stage)) perStage.set(row.stage, []);
-      perStage.get(row.stage)!.push(row.elapsedMs);
+      perStage.get(row.stage) .push(row.elapsedMs);
     }
   }
   return [...perStage.entries()].map(([stage, values]) => ({
@@ -146,14 +146,14 @@ function aggregateStages(runs: any[]): any[] {
 }
 
 /** Pure. Reads nothing and writes nothing; takes already-parsed records. */
-function buildIndicators({ records = [], unreadable = [], exists = true } = {}): any {
-  const runs = (records as any[]).map(runRows);
-  const byClass = new Map<string, any>();
+function buildIndicators({ records = [], unreadable = [], exists = true } = {})      {
+  const runs = (records         ).map(runRows);
+  const byClass = new Map             ();
 
   for (const run of runs) {
     const key = run.taskClass || '(unclassified)';
     if (!byClass.has(key)) byClass.set(key, { taskClass: key, runs: [], stageAggregate: [] });
-    byClass.get(key)!.runs.push(run);
+    byClass.get(key) .runs.push(run);
   }
 
   for (const group of byClass.values()) group.stageAggregate = aggregateStages(group.runs);
@@ -176,7 +176,7 @@ function buildIndicators({ records = [], unreadable = [], exists = true } = {}):
 }
 
 /** One class block: its runs, each run's stage and gate rows, then the class median. */
-function printClass(group: any): void {
+function printClass(group     )       {
   console.log('─'.repeat(78));
   console.log(`CLASS: ${group.taskClass}   (${group.runs.length} run(s))`);
   for (const run of group.runs) {
@@ -195,7 +195,7 @@ function printClass(group: any): void {
   }
 }
 
-function handleIndicatorsCommand({ json = false, projectRoot = process.cwd() } = {}): number {
+function handleIndicatorsCommand({ json = false, projectRoot = process.cwd() } = {})         {
   const dir = orchestrationDir(projectRoot);
   const read = readRecords(dir);
   const view = buildIndicators(read);
@@ -220,7 +220,7 @@ function handleIndicatorsCommand({ json = false, projectRoot = process.cwd() } =
 
   console.log(`Runs:      ${view.runCount} across ${view.byClass.length} task class(es)`);
   if (view.unreadable.length) {
-    console.log(`Unreadable: ${view.unreadable.length} record(s) — ${view.unreadable.map((u: any) => u.file).join(', ')}`);
+    console.log(`Unreadable: ${view.unreadable.length} record(s) — ${view.unreadable.map((u     ) => u.file).join(', ')}`);
   }
 
   for (const group of view.byClass) printClass(group);