@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/profiles/resolve.js

@@ -0,0 +1,244 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { checkRollbackState } = require('./rollback.js');
+const { shouldSample } = require('./sampler.js');
+const { configHome } = require('../config-home.js');
+
+                                                                           
+
+                                          
+                                                                           
+                                               
+                                                 
+                                                   
+                              
+ 
+
+                                         
+                           
+           
+                                                                
+                          
+    
+                                        
+                                                        
+ 
+
+                                        
+                              
+                                           
+               
+ 
+
+const PROFILE_CAPABILITIES                                                      = Object.freeze({
+  baseline: {
+    retrieval: 'lexical',
+    advisor: 'off',
+    graph: 'off',
+    verification: 'L0',
+    telemetryCanaryTag: false,
+  },
+  canary: {
+    retrieval: 'canary-hybrid',
+    advisor: 'shadow',
+    graph: 'advisory',
+    verification: 'L0-L1',
+    telemetryCanaryTag: true,
+  },
+  staged: {
+    retrieval: 'staged-hybrid',
+    advisor: 'staged',
+    graph: 'bounded',
+    verification: 'L0-L2',
+    telemetryCanaryTag: false,
+  },
+  full: {
+    retrieval: 'full-hybrid',
+    advisor: 'act',
+    graph: 'full',
+    verification: 'L0-L3',
+    telemetryCanaryTag: false,
+  },
+});
+
+const VALID_PROFILES = new Set                    (['baseline', 'canary', 'staged', 'full']);
+
+function getSettingValue(obj     , key        )      {
+  if (!obj || typeof obj !== 'object') return undefined;
+  if (Object.hasOwn(obj, key)) return obj[key];
+  const parts = key.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length; i++) {
+    if (!cur || typeof cur !== 'object') return undefined;
+    const p = parts[i];
+    if (Object.hasOwn(cur, p)) {
+      cur = cur[p];
+    } else {
+      const rest = parts.slice(i).join('.');
+      if (Object.hasOwn(cur, rest)) return cur[rest];
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+function readJsonFile(filePath        , fsImpl     )      {
+  try {
+    const text = fsImpl.readFileSync(filePath, 'utf8');
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolves the effective rollout profile by consulting:
+ * 1. Rollback Controller (checkRollbackState - forces baseline if active)
+ * 2. Environment override (DOFLOW_ROLLOUT_PROFILE)
+ * 3. Layered settings (.doflow/settings.local.json -> settings.json -> user settings)
+ * 4. Registry default (baseline)
+ *
+ * Guarantees <= 5ms evaluation latency. Never throws.
+ */
+function resolveRolloutProfile(options                        )                         {
+  const fsImpl = options?.fsImpl || fs;
+  const env = options?.env ?? process.env;
+  const projectRoot = options?.projectRoot ? path.resolve(options.projectRoot) : process.cwd();
+
+  // 1. Check Rollback Controller (forces baseline on trip)
+  const rollback = checkRollbackState({ projectRoot, env, fsImpl });
+  if (rollback.active) {
+    const originSource                     = rollback.origin === 'env' ? 'env' : 'sentinel';
+    return {
+      name: 'baseline',
+      origin: {
+        source: originSource,
+        detail: rollback.reason || (rollback.origin === 'env' ? 'DOFLOW_ROLLOUT_PROFILE=baseline' : 'rollback-sentinel-active'),
+      },
+      capabilities: PROFILE_CAPABILITIES.baseline,
+      canarySampleRate: 0.10,
+    };
+  }
+
+  // 2. Environment Override Fast-Path
+  const envProfile = env.DOFLOW_ROLLOUT_PROFILE;
+  if (typeof envProfile === 'string' && envProfile.trim()) {
+    const clean = envProfile.trim()                      ;
+    if (VALID_PROFILES.has(clean)) {
+      return {
+        name: clean,
+        origin: {
+          source: 'env',
+          detail: 'DOFLOW_ROLLOUT_PROFILE',
+        },
+        capabilities: PROFILE_CAPABILITIES[clean],
+        canarySampleRate: 0.10,
+      };
+    } else {
+      // Invalid env profile falls safe to baseline
+      return {
+        name: 'baseline',
+        origin: {
+          source: 'default',
+          detail: `invalid-profile-value:${clean}`,
+        },
+        capabilities: PROFILE_CAPABILITIES.baseline,
+        canarySampleRate: 0.10,
+      };
+    }
+  }
+
+  // 3. Inspect Candidate Layered Settings Files (local -> project -> user)
+  const candidateFiles                                                     = [];
+  if (projectRoot) {
+    candidateFiles.push({
+      layer: 'project',
+      path: path.join(projectRoot, '.doflow', 'settings.local.json'),
+    });
+    candidateFiles.push({
+      layer: 'project',
+      path: path.join(projectRoot, '.doflow', 'settings.json'),
+    });
+  }
+
+  const userHome = configHome(env).dir;
+  const userConfigDir = userHome;
+
+  if (userConfigDir) {
+    candidateFiles.push({
+      layer: 'user',
+      path: path.join(userConfigDir, 'settings.json'),
+    });
+  }
+
+  for (const { layer, path: filePath } of candidateFiles) {
+    const content = readJsonFile(filePath, fsImpl);
+    if (!content) continue;
+
+    const rawVal = getSettingValue(content, 'rollout.profile');
+    if (typeof rawVal === 'string' && rawVal.trim()) {
+      const clean = rawVal.trim()                      ;
+      if (VALID_PROFILES.has(clean)) {
+        return {
+          name: clean,
+          origin: {
+            source: layer,
+            detail: `${layer}:${filePath}`,
+          },
+          capabilities: PROFILE_CAPABILITIES[clean],
+          canarySampleRate: 0.10,
+        };
+      } else {
+        // Unknown or invalid profile fails safe to baseline (ERR_PROFILE_INVALID)
+        return {
+          name: 'baseline',
+          origin: {
+            source: 'default',
+            detail: `invalid-profile-value:${clean}`,
+          },
+          capabilities: PROFILE_CAPABILITIES.baseline,
+          canarySampleRate: 0.10,
+        };
+      }
+    }
+  }
+
+  // 4. Default baseline fallback
+  return {
+    name: 'baseline',
+    origin: {
+      source: 'default',
+      detail: 'registry-default',
+    },
+    capabilities: PROFILE_CAPABILITIES.baseline,
+    canarySampleRate: 0.10,
+  };
+}
+
+/**
+ * Checks whether a specific feature capability is active under the current profile.
+ */
+function isCapabilityActive(
+  capability                               ,
+  options                        
+)          {
+  const profile = resolveRolloutProfile(options);
+  const val = profile.capabilities[capability];
+
+  if (capability === 'retrieval') return val !== 'lexical';
+  if (capability === 'advisor') return val !== 'off';
+  if (capability === 'graph') return val !== 'off';
+  if (capability === 'verification') return val !== 'L0';
+  if (capability === 'telemetryCanaryTag') return Boolean(val);
+
+  return false;
+}
+
+module.exports = {
+  resolveRolloutProfile,
+  isCapabilityActive,
+  PROFILE_CAPABILITIES,
+  VALID_PROFILES,
+};

package/src/runtime/profiles/rollback.js

@@ -0,0 +1,254 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+                                
+                  
+                        
+                                           
+                                                          
+                            
+ 
+
+                                      
+                 
+                       
+               
+ 
+
+function resolveSentinelPath(projectRoot         )         {
+  const root = projectRoot ? path.resolve(projectRoot) : process.cwd();
+  return path.join(root, '.doflow', 'state', 'rollback.json');
+}
+
+function resolveCircuitBreakerPath(projectRoot         )         {
+  const root = projectRoot ? path.resolve(projectRoot) : process.cwd();
+  return path.join(root, '.doflow', 'state', 'circuit-breaker.json');
+}
+
+/**
+ * Checks whether rollback mode is active.
+ * Checked at process start and before every major subsystem dispatch.
+ * Sub-5ms evaluation latency. Never throws.
+ */
+function checkRollbackState(options    
+                       
+                                           
+               
+ )                {
+  try {
+    const env = options?.env || process.env;
+
+    // 1. Tier 1: Ephemeral Env Fast-Path (0ms, 0 I/O)
+    if (env.DOFLOW_ROLLOUT_PROFILE === 'baseline') {
+      return {
+        active: true,
+        reason: 'DOFLOW_ROLLOUT_PROFILE=baseline',
+        triggeredAt: null,
+        origin: 'env',
+        targetProfile: 'baseline',
+      };
+    }
+
+    const fsImpl = options?.fsImpl || fs;
+    const sentinelPath = resolveSentinelPath(options?.projectRoot);
+
+    // 2. Tier 2: Sentinel State Fast-Path (.doflow/state/rollback.json)
+    // Read it directly: existsSync reports false for an unreadable path (EACCES), which would hide a
+    // tripped rollback. Only a sentinel that is absent means no rollback; any other read error fails closed.
+    let raw                = null;
+    try {
+      raw = fsImpl.readFileSync(sentinelPath, 'utf8');
+    } catch (error     ) {
+      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
+    }
+    if (raw !== null) {
+      let data     ;
+      try {
+        data = JSON.parse(raw);
+      } catch {
+        // Corrupt sentinel fails closed to active rollback
+        return {
+          active: true,
+          reason: 'unparseable-rollback-sentinel',
+          triggeredAt: null,
+          origin: 'sentinel',
+          targetProfile: 'baseline',
+        };
+      }
+      if (data && data.active !== false) {
+        return {
+          active: true,
+          reason: data.reason || 'manual-sentinel',
+          triggeredAt: data.triggeredAt || null,
+          origin: data.origin === 'circuit-breaker' ? 'circuit-breaker' : 'sentinel',
+          targetProfile: 'baseline',
+        };
+      }
+    }
+
+    return {
+      active: false,
+      reason: null,
+      triggeredAt: null,
+      origin: 'none',
+      targetProfile: 'baseline',
+    };
+  } catch {
+    // The rollback state could not be read: fail closed, as for a corrupt sentinel.
+    return {
+      active: true,
+      reason: 'rollback-state-unavailable',
+      triggeredAt: null,
+      origin: 'sentinel',
+      targetProfile: 'baseline',
+    };
+  }
+}
+
+/**
+ * Trips instant rollback by writing the sentinel .doflow/state/rollback.json.
+ * Does NOT touch any git-tracked files or require git commits.
+ */
+function tripRollback(options                     )                                {
+  const sentinelPath = resolveSentinelPath(options.projectRoot);
+  const fsImpl = options.fsImpl || fs;
+  try {
+    const dir = path.dirname(sentinelPath);
+    fsImpl.mkdirSync(dir, { recursive: true });
+
+    const payload = {
+      schema: 1,
+      active: true,
+      reason: options.reason || 'manual-rollback',
+      triggeredAt: new Date().toISOString(),
+      origin: 'sentinel',
+      targetProfile: 'baseline',
+    };
+
+    const tmpPath = `${sentinelPath}.${process.pid}.${Date.now()}.tmp`;
+    fsImpl.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf8');
+    try {
+      fsImpl.renameSync(tmpPath, sentinelPath);
+    } catch {
+      fsImpl.writeFileSync(sentinelPath, JSON.stringify(payload, null, 2), 'utf8');
+      try { fsImpl.unlinkSync(tmpPath); } catch {}
+    }
+
+    return { ok: true, path: sentinelPath };
+  } catch {
+    return { ok: false, path: sentinelPath };
+  }
+}
+
+/**
+ * Resets rollback mode by removing the sentinel file.
+ */
+function resetRollback(options                                         )                  {
+  const sentinelPath = resolveSentinelPath(options?.projectRoot);
+  const cbPath = resolveCircuitBreakerPath(options?.projectRoot);
+  const fsImpl = options?.fsImpl || fs;
+
+  // A file already gone is the goal; any other failure leaves rollback mode on and is reported.
+  let ok = true;
+  for (const file of [sentinelPath, cbPath]) {
+    try {
+      fsImpl.unlinkSync(file);
+    } catch (error     ) {
+      if (error?.code !== 'ENOENT') ok = false;
+    }
+  }
+
+  return { ok };
+}
+
+/**
+ * Records a provider failure (Ollama, Semble, Graphify) and trips the
+ * circuit breaker if consecutive failures exceed the threshold (default: 3).
+ */
+function recordProviderFailure(
+  providerId        ,
+  error                ,
+  options                                                             
+)                                             {
+  const fsImpl = options?.fsImpl || fs;
+  const cbPath = resolveCircuitBreakerPath(options?.projectRoot);
+  const threshold = options?.threshold ?? 3;
+  const errorMsg = typeof error === 'string' ? error : error?.message || 'unknown error';
+
+  let cbData                                                                                     = {};
+  try {
+    if (fsImpl.existsSync(cbPath)) {
+      cbData = JSON.parse(fsImpl.readFileSync(cbPath, 'utf8')) || {};
+    }
+  } catch {
+    cbData = {};
+  }
+
+  const currentCount = (cbData[providerId]?.failureCount || 0) + 1;
+  cbData[providerId] = {
+    failureCount: currentCount,
+    lastError: errorMsg,
+    lastFailureAt: new Date().toISOString(),
+  };
+
+  try {
+    const dir = path.dirname(cbPath);
+    fsImpl.mkdirSync(dir, { recursive: true });
+    fsImpl.writeFileSync(cbPath, JSON.stringify(cbData, null, 2), 'utf8');
+  } catch {}
+
+  if (currentCount >= threshold) {
+    // Trip circuit-breaker rollback sentinel
+    const sentinelPath = resolveSentinelPath(options?.projectRoot);
+    try {
+      const dir = path.dirname(sentinelPath);
+      fsImpl.mkdirSync(dir, { recursive: true });
+      const payload = {
+        schema: 1,
+        active: true,
+        reason: `Provider '${providerId}' failed ${currentCount} consecutive times: ${errorMsg}`,
+        triggeredAt: new Date().toISOString(),
+        origin: 'circuit-breaker',
+        targetProfile: 'baseline',
+      };
+      fsImpl.writeFileSync(sentinelPath, JSON.stringify(payload, null, 2), 'utf8');
+    } catch {}
+
+    return { tripped: true, failureCount: currentCount };
+  }
+
+  return { tripped: false, failureCount: currentCount };
+}
+
+/**
+ * Records provider success to reset consecutive failure count.
+ */
+function recordProviderSuccess(
+  providerId        ,
+  options                                         
+)                           {
+  const fsImpl = options?.fsImpl || fs;
+  const cbPath = resolveCircuitBreakerPath(options?.projectRoot);
+
+  try {
+    if (fsImpl.existsSync(cbPath)) {
+      const cbData = JSON.parse(fsImpl.readFileSync(cbPath, 'utf8')) || {};
+      if (cbData[providerId]) {
+        cbData[providerId].failureCount = 0;
+        fsImpl.writeFileSync(cbPath, JSON.stringify(cbData, null, 2), 'utf8');
+      }
+    }
+  } catch {}
+
+  return { failureCount: 0 };
+}
+
+module.exports = {
+  checkRollbackState,
+  tripRollback,
+  resetRollback,
+  recordProviderFailure,
+  recordProviderSuccess,
+};

package/src/runtime/profiles/sampler.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+/**
+ * Deterministic canary sampler based on consistent hashing of unitKey.
+ * Pure Node.js with zero external dependencies.
+ */
+function hashKey(key        )         {
+  if (typeof key !== 'string' || !key) return 0;
+  const hash = crypto.createHash('sha256').update(key).digest('hex').slice(0, 8);
+  return parseInt(hash, 16);
+}
+
+/**
+ * Deterministic sampling check.
+ * @param unitKey Distinct identifier (e.g. session ID, task ID, query hash)
+ * @param sampleRate Number between 0.0 and 1.0 (e.g. 0.10 for 10%)
+ */
+function shouldSample(unitKey        , sampleRate        )          {
+  if (typeof sampleRate !== 'number' || Number.isNaN(sampleRate) || sampleRate <= 0) return false;
+  if (sampleRate >= 1.0) return true;
+  const hashVal = hashKey(unitKey);
+  const normalized = (hashVal % 10000) / 10000;
+  return normalized < sampleRate;
+}
+
+class CanarySampler {
+  shouldSample(unitKey        , sampleRate         = 0.10)          {
+    return shouldSample(unitKey, sampleRate);
+  }
+  hashKey(key        )         {
+    return hashKey(key);
+  }
+}
+
+module.exports = {
+  hashKey,
+  shouldSample,
+  CanarySampler,
+};

package/src/runtime/readiness-record.js

@@ -5,7 +5,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { updateTaskState } = require('./task-state.js');
-const { resolveTaskScope } = require('./task-scope.js');
+const { resolveTaskScope, flatRecordIsOurs } = require('./task-scope.js');
 const { findStateFile } = require('./checkouts.js');
 
 // The readiness record: the latest evaluation of one task, kept where `readiness` ran.
@@ -20,7 +20,7 @@ const STORE = path.join('.doflow', 'state', 'readiness');
 
 /**
  * Where a task's record may be under one checkout, in the order every reader takes them: under the
- * feature's namespace, then flat. The writer, `verify`, `orchestrate` and the edit hook all use this
+ * feature's namespace, then flat. `verify`, `orchestrate` and the edit hook all read through this
  * one list, so a record written anywhere is found by each of them from any checkout.
  * @param {string} taskId
  * @param {string|null} slug the task's feature slug, when one is known
@@ -89,10 +89,10 @@ function priorRecord(file     , fsImpl     ) {
 function writeReadinessRecord({ stateRoot, taskId, slug = null, report, inputs, declaredScope = null, mode, now = new Date(), fsImpl = fs }     ) {
   const scope = resolveTaskScope({ projectRoot: stateRoot, taskId, slug });
   const recordSlug = scope.slug || slug || null;
-  // The record a reader would find in this checkout is the one replaced; with none, the record goes
-  // where the task's evidence goes (under the feature's namespace when it has a register).
-  const file = recordCandidates(taskId, recordSlug).map((rel) => path.join(stateRoot, rel)).find((f) => fsImpl.existsSync(f))
-    || path.join(stateRoot, STORE, ...(scope.namespace ? [scope.namespace] : []), `${taskId}.json`);
+  // Written where the task's evidence goes (115 C-1): under the feature's namespace whenever one
+  // applies. A flat record of the task from before that rule stays where it is, and is no longer
+  // read once this one exists.
+  const file = path.join(stateRoot, STORE, ...(scope.namespace ? [scope.namespace] : []), `${taskId}.json`);
   const record = {
     version: RECORD_VERSION,
     taskId,
@@ -124,20 +124,25 @@ function writeReadinessRecord({ stateRoot, taskId, slug = null, report, inputs,
 }
 
 /**
- * The task's record in this checkout, else in exactly one other checkout, at the first of
- * `recordCandidates` that exists in each. No resolver is run: the candidates depend only on the
- * task id and the slug the caller names.
+ * The task's record where `findStateFile` looks (the main checkout first from a linked worktree),
+ * at the first of `recordCandidates` that exists in each checkout; the flat candidate of a
+ * namespaced task only when it is this feature's or names none (D-3). No resolver is run: the
+ * candidates depend only on the task id and the slug the caller names. `conflict` is a worktree
+ * copy that differs from the main checkout's (115 C-3).
  * @param {Object} options
  * @param {string} options.stateRoot
  * @param {string} options.taskId
  * @param {string|null} [options.slug]
  * @param {Function} [options.exec]
  * @param {Object} [options.fsImpl]
- * @returns {{status: 'found'|'missing'|'ambiguous'|'unreadable', record: Object|null, file: string|null,
+ * @returns {{status: 'found'|'missing'|'ambiguous'|'conflict'|'unreadable', record: Object|null, file: string|null,
  *   origin: 'current'|'other'|null, candidates: Array<string>, detail: string|null}}
  */
 function readReadinessRecord({ stateRoot, taskId, slug = null, exec, fsImpl = fs }     ) {
-  const found = findStateFile({ stateRoot, relPath: recordCandidates(taskId, slug), ...(exec ? { exec } : {}), fsImpl });
+  const [first, flat] = recordCandidates(taskId, slug);
+  const relPath = flat === undefined ? first
+    : (root        ) => (fsImpl.existsSync(path.join(root, first)) ? first : flatRecordIsOurs(path.join(root, flat), slug, fsImpl) ? flat : null);
+  const found = findStateFile({ stateRoot, relPath, ...(exec ? { exec } : {}), fsImpl });
   const base = { record: null, file: found.file, origin: found.origin, candidates: found.candidates, detail: null };
   if (found.status !== 'found') return { ...base, status: found.status };
   try {