@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/runtime/advice/record.js

@@ -0,0 +1,166 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { resolveStorePath } = require('../storage/roots.js');
+
+const RETAINED_DAYS = 90;
+const PARTITION_NAME = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+
+function timestamp(now      = () => new Date())                {
+  const value = typeof now === 'function' ? now() : now;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function selectedStore(roots     , requestedStore         )                                         {
+  if (requestedStore && roots?.[requestedStore]) return { store: requestedStore, root: roots[requestedStore] };
+  if (roots?.['project-state']) return { store: 'project-state', root: roots['project-state'] };
+  if (roots?.['user-state']) return { store: 'user-state', root: roots['user-state'] };
+  return null;
+}
+
+function appendLine({ roots, at, line, fsImpl = fs, store }     )                                         {
+  try {
+    const selected = selectedStore(roots, store);
+    if (!selected) return null;
+    const directory = resolveStorePath({ store: { root: selected.store, path: 'advice/picks' }, roots, fsImpl });
+    if (!directory) return null;
+    const file = path.join(directory, `${at.slice(0, 10)}.jsonl`);
+    try { if (fsImpl.lstatSync(file).isSymbolicLink()) return null; }
+    catch (error     ) { if (error.code !== 'ENOENT') return null; }
+    fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+    fsImpl.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
+    return { file, store: selected.store };
+  } catch {
+    return null;
+  }
+}
+
+function appendPick({
+  roots, now = () => new Date(), fsImpl = fs, kind, answer, question,
+  staticAnswer = null, provider = null, model = null, state, caller, taskId = null, durationMs = 0,
+}      = {})                                                         {
+  try {
+    if (typeof state !== 'string' || !answer || !question) return null;
+    const at = timestamp(now);
+    if (!at) return null;
+    const epoch = Date.parse(at);
+    const pickId = `adv-${String(epoch).padStart(13, '0')}-${crypto.randomBytes(3).toString('hex')}`;
+    const options = question.type === 'choice' ? Object.keys(question.options || {})
+      : question.type === 'score' ? [...(question.criteria || [])] : ['no', 'yes'];
+    const instructions = kind === 'adhoc' && typeof question.instructions === 'string'
+      ? question.instructions.slice(0, 500) : null;
+    const line      = {
+      schema: 1,
+      type: 'pick',
+      pickId,
+      at,
+      kind,
+      question: answer.name,
+      qtype: answer.type,
+      options,
+      instructions,
+      pick: answer.pick,
+      strength: answer.strength?.word ?? null,
+      between: answer.strength?.between ?? null,
+      probabilities: answer.probabilities,
+      confidence: answer.confidence ?? null,
+      static: staticAnswer ?? null,
+      provider: provider ?? null,
+      model: model ?? null,
+      stateDigest: `sha256:${crypto.createHash('sha256').update(state, 'utf8').digest('hex')}`,
+      stateBytes: Buffer.byteLength(state, 'utf8'),
+      caller,
+      taskId: taskId ?? null,
+      durationMs: Number.isFinite(durationMs) ? durationMs : 0,
+    };
+    if (answer.type === 'score') {
+      line.criteria = [...(question.criteria || [])];
+      line.pickIndex = answer.pickIndex;
+      line.score = answer.score;
+    }
+    const written = appendLine({ roots, at, line, fsImpl });
+    return written ? { pickId, file: written.file, store: written.store } : null;
+  } catch {
+    return null;
+  }
+}
+
+function appendMiss({ roots, now = () => new Date(), fsImpl = fs, kind, caller, reason, model = null, durationMs = 0 }      = {})      {
+  try {
+    const at = timestamp(now);
+    if (!at) return null;
+    const line = {
+      schema: 1, type: 'miss', at, kind, caller, reason,
+      model: model ?? null,
+      durationMs: Number.isFinite(durationMs) ? durationMs : 0,
+    };
+    return appendLine({ roots, at, line, fsImpl });
+  } catch { return null; }
+}
+
+function appendOutcome({ roots, now = () => new Date(), fsImpl = fs, pickId, actual, source, store }      = {})      {
+  try {
+    const at = timestamp(now);
+    if (!at) return null;
+    const line = { schema: 1, type: 'outcome', pickId, at, actual, source };
+    return appendLine({ roots, at, line, fsImpl, store });
+  } catch { return null; }
+}
+
+function cutoffDate(now     , maxAgeDays         = RETAINED_DAYS)                {
+  const at = timestamp(now);
+  if (!at) return null;
+  const cutoff = new Date(Date.parse(at) - maxAgeDays * 24 * 60 * 60 * 1000);
+  return cutoff.toISOString().slice(0, 10);
+}
+
+function partitionFiles(root                    , cutoff        , fsImpl     )        {
+  if (!root) return [];
+  const directory = path.join(root, 'advice', 'picks');
+  try {
+    return fsImpl.readdirSync(directory)
+      .filter((name        ) => PARTITION_NAME.test(name) && name.slice(0, 10) >= cutoff)
+      .sort()
+      .map((name        ) => path.join(directory, name));
+  } catch (error     ) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return [];
+    return [{ unreadable: true, file: directory }];
+  }
+}
+
+function readWindow({ roots, now = () => new Date(), maxAgeDays = RETAINED_DAYS, fsImpl = fs }      = {})                                         {
+  const cutoff = cutoffDate(now, maxAgeDays);
+  if (!cutoff) return { records: [], unreadable: 0 };
+  const records        = [];
+  let unreadable = 0;
+  for (const store of ['project-state', 'user-state']) {
+    for (const item of partitionFiles(roots?.[store], cutoff, fsImpl)) {
+      if (typeof item !== 'string') { unreadable += 1; continue; }
+      let contents        ;
+      try { contents = fsImpl.readFileSync(item, 'utf8'); } catch { unreadable += 1; continue; }
+      for (const line of contents.split(/\r?\n/)) {
+        if (!line.trim()) continue;
+        try {
+          const record = JSON.parse(line);
+          if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('record must be an object');
+          records.push({ record, file: item, store });
+        } catch { unreadable += 1; }
+      }
+    }
+  }
+  return { records, unreadable };
+}
+
+function findPick({ pickId, roots, now = () => new Date(), fsImpl = fs }      = {})      {
+  if (typeof pickId !== 'string') return null;
+  const window = readWindow({ roots, now, fsImpl });
+  const found = window.records.find((entry     ) => entry.record.type === 'pick' && entry.record.pickId === pickId);
+  return found ? { pick: found.record, file: found.file, store: found.store } : null;
+}
+
+module.exports = { appendPick, appendMiss, appendOutcome, readWindow, findPick };

package/src/runtime/advice/registry.js

@@ -0,0 +1,170 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+const ADVICE_FILE = 'core/registry/advice.json';
+const MODELS_FILE = 'core/registry/models.json';
+const ADAPTER_DIR = 'src/runtime/advice/providers';
+const TIER_KIND = 'tier';
+const LIMIT_FIELDS = ['maxStateBytes', 'maxBodyBytes', 'minQuestions', 'maxQuestions', 'minOptions', 'maxOptions'];
+const BAND_FIELDS                           = {
+  choice: ['clearAt', 'splitWithin'],
+  yesno: ['clearAbove', 'clearBelow', 'splitFrom', 'splitTo'],
+};
+
+function isObject(value     )          {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function addError(errors          , key        , message        )       {
+  errors.push(`${key} ${message}`);
+}
+
+function validateAdviceRegistry(registry     , { repoRoot = REPO_ROOT, models, fsImpl = fs }      = {})                                    {
+  const errors           = [];
+  if (!isObject(registry)) return { ok: false, errors: ['registry must be an object'] };
+
+  if (registry.version !== 1) addError(errors, 'version', 'must be 1');
+  for (const key of ['timeoutMs', 'probeTimeoutMs']) {
+    if (!Number.isInteger(registry[key]) || registry[key] < 100 || registry[key] > 30000) {
+      addError(errors, key, 'must be an integer from 100 to 30000');
+    }
+  }
+  if (!Number.isInteger(registry.doctorBudgetMs) || registry.doctorBudgetMs <= 0) {
+    addError(errors, 'doctorBudgetMs', 'must be a positive integer');
+  }
+
+  const limits = registry.limits;
+  if (!isObject(limits)) {
+    addError(errors, 'limits', 'must be an object');
+  } else {
+    for (const field of LIMIT_FIELDS) {
+      if (!Number.isInteger(limits[field]) || limits[field] <= 0) addError(errors, `limits.${field}`, 'must be a positive integer');
+    }
+    for (const [min, max] of [['minQuestions', 'maxQuestions'], ['minOptions', 'maxOptions']]) {
+      if (Number.isInteger(limits[min]) && Number.isInteger(limits[max]) && limits[min] > limits[max]) {
+        addError(errors, `limits.${min}`, `must not exceed limits.${max}`);
+      }
+    }
+    if (Number.isInteger(limits.maxBodyBytes) && limits.maxBodyBytes >= 65536) {
+      addError(errors, 'limits.maxBodyBytes', 'must be below 65536');
+    }
+    if (Number.isInteger(limits.maxOptions) && limits.maxOptions > 26) {
+      addError(errors, 'limits.maxOptions', 'must be at most 26');
+    }
+    if (typeof limits.questionName !== 'string') {
+      addError(errors, 'limits.questionName', 'must be a regular expression string');
+    } else {
+      try { new RegExp(limits.questionName); } catch { addError(errors, 'limits.questionName', 'must compile'); }
+    }
+  }
+
+  const strength = registry.strength;
+  if (!isObject(strength)) {
+    addError(errors, 'strength', 'must be an object');
+  } else {
+    for (const [type, fields] of Object.entries(BAND_FIELDS)) {
+      const bands = strength[type];
+      if (!isObject(bands)) {
+        addError(errors, `strength.${type}`, 'must be an object');
+        continue;
+      }
+      for (const field of fields) {
+        if (typeof bands[field] !== 'number' || !Number.isFinite(bands[field]) || bands[field] < 0 || bands[field] > 1) {
+          addError(errors, `strength.${type}.${field}`, 'must be a number from 0 to 1');
+        }
+      }
+    }
+    const yesno = strength.yesno;
+    if (isObject(yesno) && ['clearBelow', 'splitFrom', 'splitTo', 'clearAbove'].every((field        ) => typeof yesno[field] === 'number')) {
+      if (!(yesno.clearBelow < yesno.splitFrom && yesno.splitFrom < yesno.splitTo && yesno.splitTo < yesno.clearAbove)) {
+        addError(errors, 'strength.yesno', 'bands must satisfy clearBelow < splitFrom < splitTo < clearAbove');
+      }
+    }
+  }
+
+  if (!models) {
+    try { models = JSON.parse(fsImpl.readFileSync(path.join(repoRoot, MODELS_FILE), 'utf8')); }
+    catch (error     ) { addError(errors, MODELS_FILE, `could not be loaded: ${error.message}`); }
+  }
+  const modelProviders = Array.isArray(models?.providers) ? new Set(models.providers.map((provider     ) => provider?.id).filter((id     ) => typeof id === 'string')) : new Set();
+
+  if (!Array.isArray(registry.providers) || registry.providers.length === 0) {
+    addError(errors, 'providers', 'must be a non-empty array');
+  } else {
+    const adapterRoot = path.resolve(repoRoot, ADAPTER_DIR);
+    registry.providers.forEach((provider     , index        ) => {
+      const base = `providers[${index}]`;
+      if (!isObject(provider)) { addError(errors, base, 'must be an object'); return; }
+      for (const field of ['id', 'adapter', 'modelProvider', 'defaultEndpoint', 'route', 'minVersion', 'capability']) {
+        if (typeof provider[field] !== 'string' || !provider[field].trim()) addError(errors, `${base}.${field}`, 'must be a non-empty string');
+      }
+      if (typeof provider.adapter === 'string') {
+        if (!/^[a-z][a-z0-9-]*$/.test(provider.adapter)) {
+          addError(errors, `${base}.adapter`, 'must be a safe adapter id');
+        } else {
+          const adapterFile = path.resolve(adapterRoot, `${provider.adapter}.ts`);
+          if (!adapterFile.startsWith(`${adapterRoot}${path.sep}`) || !fsImpl.existsSync(adapterFile)) {
+            addError(errors, `${base}.adapter`, `must name a file under ${ADAPTER_DIR}`);
+          }
+        }
+      }
+      if (typeof provider.modelProvider === 'string' && !modelProviders.has(provider.modelProvider)) {
+        addError(errors, `${base}.modelProvider`, `must name a provider in ${MODELS_FILE}`);
+      }
+    });
+  }
+
+  if (!Array.isArray(registry.kinds) || registry.kinds.length === 0) {
+    addError(errors, 'kinds', 'must be a non-empty array');
+  } else {
+    const ids = new Set();
+    for (const [index, kind] of registry.kinds.entries()) {
+      const base = `kinds[${index}]`;
+      if (!isObject(kind)) { addError(errors, base, 'must be an object'); continue; }
+      if (typeof kind.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(kind.id)) addError(errors, `${base}.id`, 'must be a safe kind id');
+      else if (ids.has(kind.id)) addError(errors, `${base}.id`, `duplicates '${kind.id}'`);
+      else ids.add(kind.id);
+      if (!['choice', 'yesno'].includes(kind.type)) addError(errors, `${base}.type`, 'must be choice or yesno');
+      if (typeof kind.instructions !== 'string' || !kind.instructions.trim()) addError(errors, `${base}.instructions`, 'must be a non-empty string');
+      if (Object.hasOwn(kind, 'criteria') === Object.hasOwn(kind, 'criteriaFrom')) addError(errors, base, 'must have exactly one of criteria or criteriaFrom');
+      if (Object.hasOwn(kind, 'criteria') && (!isObject(kind.criteria) || Object.values(kind.criteria).some((value     ) => typeof value !== 'string' || !value.trim()))) {
+        addError(errors, `${base}.criteria`, 'must map option ids to non-empty descriptions');
+      }
+      if (Object.hasOwn(kind, 'criteriaFrom') && (typeof kind.criteriaFrom !== 'string' || !kind.criteriaFrom.trim())) {
+        addError(errors, `${base}.criteriaFrom`, 'must be a non-empty string');
+      }
+      if (typeof kind.staticFrom !== 'string') addError(errors, `${base}.staticFrom`, 'must be a string');
+      if (!Array.isArray(kind.askedBy) || kind.askedBy.some((caller     ) => typeof caller !== 'string')) addError(errors, `${base}.askedBy`, 'must be an array of strings');
+    }
+
+    const tier = registry.kinds.find((kind     ) => kind?.id === TIER_KIND);
+    const dispatchTiers = models?.dispatchTiers?.tiers;
+    if (!tier || !isObject(tier.criteria) || !Array.isArray(dispatchTiers)
+      || JSON.stringify(Object.keys(tier.criteria)) !== JSON.stringify(dispatchTiers)) {
+      addError(errors, 'kinds.tier.criteria', 'keys must equal models.dispatchTiers.tiers in order');
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function loadAdviceRegistry({ repoRoot = REPO_ROOT, file, fsImpl = fs }      = {})                                                                    {
+  const root = path.resolve(repoRoot);
+  const target = file || path.join(root, ADVICE_FILE);
+  let registry     ;
+  try {
+    registry = JSON.parse(fsImpl.readFileSync(target, 'utf8'));
+  } catch (error     ) {
+    return { ok: false, reason: 'config-invalid', detail: `${target}: ${error.message}` };
+  }
+  const validation = validateAdviceRegistry(registry, { repoRoot: root, fsImpl });
+  if (!validation.ok) return { ok: false, reason: 'config-invalid', detail: validation.errors.join('; ') };
+  return { ok: true, registry };
+}
+
+module.exports = { loadAdviceRegistry, validateAdviceRegistry };

package/src/runtime/advice/strength.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+function strengthOf(answer     , bands     )                                             {
+  const type = answer?.type;
+  const thresholds = bands?.[type] || bands;
+  const probabilities = answer?.probabilities;
+  if (!thresholds || !probabilities || typeof probabilities !== 'object' || Array.isArray(probabilities)) {
+    return { word: 'leaning', between: null };
+  }
+
+  if (type === 'choice') {
+    const ordered        = Object.entries(probabilities)
+      .filter(([, probability]) => typeof probability === 'number' && Number.isFinite(probability))
+      .sort((left     , right     ) => right[1] - left[1]);
+    if (!ordered.length) return { word: 'leaning', between: null };
+    if (ordered[0][1] >= thresholds.clearAt) return { word: 'clear', between: null };
+    if (ordered.length > 1) {
+      const gap = ordered[0][1] - ordered[1][1];
+      const boundaryNoise = Number.EPSILON * Math.max(1, Math.abs(ordered[0][1]), Math.abs(ordered[1][1])) * 4;
+      if (gap < thresholds.splitWithin && thresholds.splitWithin - gap > boundaryNoise) {
+        return { word: 'split', between: [ordered[0][0], ordered[1][0]] };
+      }
+    }
+    return { word: 'leaning', between: null };
+  }
+
+  if (type === 'score') {
+    const choice = bands?.choice;
+    const criteria = answer.criteria;
+    if (!choice || !Array.isArray(criteria)) return { word: 'leaning', between: null };
+    const ordered = criteria.map((criterion     , index        ) => [criterion, probabilities[String(index)]])
+      .filter(([, probability]     ) => typeof probability === 'number' && Number.isFinite(probability))
+      .sort((left     , right     ) => right[1] - left[1]);
+    if (!ordered.length) return { word: 'leaning', between: null };
+    if (ordered[0][1] >= choice.clearAt) return { word: 'clear', between: null };
+    if (ordered.length > 1) {
+      const gap = ordered[0][1] - ordered[1][1];
+      const noise = Number.EPSILON * Math.max(1, Math.abs(ordered[0][1]), Math.abs(ordered[1][1])) * 4;
+      if (gap < choice.splitWithin && choice.splitWithin - gap > noise) {
+        return { word: 'split', between: [ordered[0][0], ordered[1][0]] };
+      }
+    }
+    return { word: 'leaning', between: null };
+  }
+
+  if (type === 'yesno') {
+    const probability = probabilities.yes;
+    if (typeof probability !== 'number' || !Number.isFinite(probability)) return { word: 'leaning', between: null };
+    if (probability >= thresholds.clearAbove || probability <= thresholds.clearBelow) return { word: 'clear', between: null };
+    if (probability >= thresholds.splitFrom && probability <= thresholds.splitTo) {
+      return { word: 'split', between: ['yes', 'no'] };
+    }
+  }
+  return { word: 'leaning', between: null };
+}
+
+function strengthWords(strength     )         {
+  if (strength?.word === 'split' && Array.isArray(strength.between) && strength.between.length === 2) {
+    return `split between ${strength.between[0]} and ${strength.between[1]}`;
+  }
+  return strength?.word === 'clear' ? 'clear' : 'leaning';
+}
+
+module.exports = { strengthOf, strengthWords };