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

package/src/runtime/advice/providers/ollama-systemone.ts

@@ -0,0 +1,209 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const SYSTEMONE_PATH = '/v1/systemone';
+const VERSION_PATH = '/api/version';
+const TAGS_PATH = '/api/tags';
+const SHOW_PATH = '/api/show';
+
+function parseJson(bodyText: any): any {
+  if (typeof bodyText !== 'string') return null;
+  try {
+    const value = JSON.parse(bodyText);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function failure(reason: string, detail: string): { ok: false; reason: string; detail: string } {
+  return { ok: false, reason, detail };
+}
+
+function buildRequest(questionSet: any, { model }: any = {}): { method: string; path: string; body: any } {
+  const questions = Object.fromEntries(questionSet.questions.map((question: any) => {
+    if (question.type === 'choice') {
+      return [question.name, {
+        type: 'choice',
+        instructions: question.instructions,
+        criteria: question.options,
+      }];
+    }
+    if (question.type === 'score') {
+      return [question.name, {
+        type: 'score',
+        instructions: question.instructions,
+        criteria: question.criteria,
+      }];
+    }
+    return [question.name, {
+      type: 'noul',
+      instructions: question.instructions,
+      criteria: { false: question.no, true: question.yes },
+    }];
+  }));
+  return {
+    method: 'POST',
+    path: SYSTEMONE_PATH,
+    body: { model, state: questionSet.state, questions },
+  };
+}
+
+const SCORE_TOLERANCE = 1e-6;
+
+function inUnit(value: any): boolean {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function parseScore(question: any, value: any): any {
+  const bad = (detail: string) => failure('malformed-reply', detail);
+  const { criteria, name } = question;
+  const last = criteria.length - 1;
+  if (value.type !== 'score') return bad(`answer for ${name} is not a score`);
+  const keys: string[] = criteria.map((criterion: any, index: number) => String(index));
+  const exact = (object: any) => object && typeof object === 'object' && !Array.isArray(object)
+    && Object.keys(object).length === keys.length && keys.every((key) => Object.hasOwn(object, key));
+  if (!exact(value.legend) || keys.some((key: string, index: number) => value.legend[key] !== criteria[index])) {
+    return bad(`legend for ${name} does not match its criteria`);
+  }
+  if (!exact(value.probabilities)) return bad(`probabilities for ${name} do not match its criteria`);
+  if (keys.some((key) => !inUnit(value.probabilities[key]))) return bad(`probability for ${name} is not a number from 0 to 1`);
+  if (!inUnit(value.confidence)) return bad(`confidence for ${name} is not a number from 0 to 1`);
+  if (typeof value.score !== 'number' || !Number.isFinite(value.score) || value.score < 0 || value.score > last) {
+    return bad(`score for ${name} is outside 0 to ${last}`);
+  }
+  const sum = keys.reduce((total, key) => total + value.probabilities[key], 0);
+  if (Math.abs(sum - 1) > SCORE_TOLERANCE) return bad(`probabilities for ${name} do not sum to 1`);
+  const weighted = keys.reduce((total, key, index) => total + index * value.probabilities[key], 0);
+  if (Math.abs(weighted - value.score) > SCORE_TOLERANCE) return bad(`score for ${name} does not match its probabilities`);
+  let pickIndex = 0;
+  keys.forEach((key, index) => { if (value.probabilities[key] > value.probabilities[String(pickIndex)]) pickIndex = index; });
+  const probabilities = Object.fromEntries(keys.map((key) => [key, value.probabilities[key]]));
+  return {
+    ok: true,
+    answer: {
+      name, type: 'score', pick: criteria[pickIndex], pickIndex, score: value.score,
+      criteria: [...criteria], probabilities, confidence: value.confidence,
+    },
+  };
+}
+
+function parseReply(status: number, bodyText: any, questionSet: any): any {
+  if (status === 400) {
+    const parsed = parseJson(bodyText);
+    return failure('endpoint-rejected', typeof parsed?.error === 'string' ? parsed.error : 'Ollama rejected the request');
+  }
+  if (status === 404) {
+    const parsed = parseJson(bodyText);
+    if (typeof parsed?.error === 'string' && parsed.error) return failure('model-missing', parsed.error);
+    return failure('endpoint-missing', 'decision endpoint is missing');
+  }
+  if (status === 413) return failure('over-limit', 'request exceeds the server limit');
+  if (status >= 300 && status < 400) return failure('endpoint-rejected', `Ollama returned HTTP ${status}`);
+  if (status !== 200) return failure('server-error', `Ollama returned HTTP ${status}`);
+
+  const parsed = parseJson(bodyText);
+  if (!parsed || !parsed.answers || typeof parsed.answers !== 'object' || Array.isArray(parsed.answers)) {
+    return failure('malformed-reply', 'reply has no answers object');
+  }
+
+  const answers: any[] = [];
+  for (const question of questionSet.questions) {
+    const value = parsed.answers[question.name];
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return failure('malformed-reply', `answer missing for question ${question.name}`);
+    }
+    if (question.type === 'choice') {
+      const options = Object.keys(question.options);
+      if (typeof value.choice !== 'string' || !options.includes(value.choice)) {
+        return failure('malformed-reply', `choice for question ${question.name} is outside its options`);
+      }
+      const probabilities = value.probabilities;
+      if (!probabilities || typeof probabilities !== 'object' || Array.isArray(probabilities)) {
+        return failure('malformed-reply', `probabilities for ${question.name} are missing`);
+      }
+      for (const option of options) {
+        if (typeof probabilities[option] !== 'number' || !Number.isFinite(probabilities[option])
+          || probabilities[option] < 0 || probabilities[option] > 1) {
+          return failure('malformed-reply', `probability for ${question.name}.${option} is not a number from 0 to 1`);
+        }
+      }
+      if (typeof value.confidence !== 'number' || !Number.isFinite(value.confidence)
+        || value.confidence < 0 || value.confidence > 1) {
+        return failure('malformed-reply', `confidence for ${question.name} is not a number from 0 to 1`);
+      }
+      answers.push({ name: question.name, type: 'choice', pick: value.choice, probabilities, confidence: value.confidence });
+    } else if (question.type === 'score') {
+      const scored = parseScore(question, value);
+      if (!scored.ok) return scored;
+      answers.push(scored.answer);
+    } else {
+      const probability = value.noul;
+      if (typeof probability !== 'number' || !Number.isFinite(probability) || probability < 0 || probability > 1) {
+        return failure('malformed-reply', `noul for ${question.name} is not a probability from 0 to 1`);
+      }
+      answers.push({
+        name: question.name,
+        type: 'yesno',
+        pick: probability >= 0.5 ? 'yes' : 'no',
+        probabilities: { no: 1 - probability, yes: probability },
+        confidence: null,
+      });
+    }
+  }
+  return { ok: true, answers };
+}
+
+function versionRequest() {
+  return { method: 'GET', path: VERSION_PATH };
+}
+
+function parseVersion(status: number, bodyText: any): { version: string } | null {
+  const parsed = status === 200 ? parseJson(bodyText) : null;
+  return typeof parsed?.version === 'string' && parsed.version.trim() ? { version: parsed.version.trim() } : null;
+}
+
+function listRequest() {
+  return { method: 'GET', path: TAGS_PATH };
+}
+
+function parseList(status: number, bodyText: any): any[] {
+  const parsed = status === 200 ? parseJson(bodyText) : null;
+  if (!Array.isArray(parsed?.models)) return [];
+  return parsed.models
+    .filter((model: any) => model && typeof model.name === 'string' && model.name.trim())
+    .map((model: any) => ({
+      name: model.name,
+      capabilities: Array.isArray(model.capabilities) && model.capabilities.every((capability: any) => typeof capability === 'string')
+        ? model.capabilities : null,
+    }));
+}
+
+function showRequest(name: string): { method: string; path: string; body: any } {
+  return { method: 'POST', path: SHOW_PATH, body: { model: name } };
+}
+
+function parseShow(status: number, bodyText: any): { capabilities: string[] } | null {
+  const parsed = status === 200 ? parseJson(bodyText) : null;
+  return Array.isArray(parsed?.capabilities) && parsed.capabilities.every((capability: any) => typeof capability === 'string')
+    ? { capabilities: parsed.capabilities }
+    : null;
+}
+
+/** A configured name without a tag also matches Ollama's listed `<name>:latest` form. */
+function modelMatches(configured: any, listed: any): boolean {
+  return configured === listed || (typeof configured === 'string' && !configured.includes(':') && listed === `${configured}:latest`);
+}
+
+module.exports = {
+  buildRequest,
+  parseReply,
+  versionRequest,
+  parseVersion,
+  listRequest,
+  parseList,
+  showRequest,
+  parseShow,
+  modelMatches,
+};

package/src/runtime/advice/record.ts

@@ -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.ts');
+
+const RETAINED_DAYS = 90;
+const PARTITION_NAME = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+
+function timestamp(now: any = () => new Date()): string | null {
+  const value = typeof now === 'function' ? now() : now;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function selectedStore(roots: any, requestedStore?: string): { store: string; root: string } | null {
+  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 }: any): { file: string; store: string } | null {
+  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: any) { 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,
+}: any = {}): { pickId: string; file: string; store: string } | null {
+  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: any = {
+      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 }: any = {}): any {
+  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 }: any = {}): any {
+  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: any, maxAgeDays: number = RETAINED_DAYS): string | null {
+  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: string | undefined, cutoff: string, fsImpl: any): any[] {
+  if (!root) return [];
+  const directory = path.join(root, 'advice', 'picks');
+  try {
+    return fsImpl.readdirSync(directory)
+      .filter((name: string) => PARTITION_NAME.test(name) && name.slice(0, 10) >= cutoff)
+      .sort()
+      .map((name: string) => path.join(directory, name));
+  } catch (error: any) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return [];
+    return [{ unreadable: true, file: directory }];
+  }
+}
+
+function readWindow({ roots, now = () => new Date(), maxAgeDays = RETAINED_DAYS, fsImpl = fs }: any = {}): { records: any[]; unreadable: number } {
+  const cutoff = cutoffDate(now, maxAgeDays);
+  if (!cutoff) return { records: [], unreadable: 0 };
+  const records: any[] = [];
+  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: string;
+      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 }: any = {}): any {
+  if (typeof pickId !== 'string') return null;
+  const window = readWindow({ roots, now, fsImpl });
+  const found = window.records.find((entry: any) => 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.ts

@@ -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.ts');
+
+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: Record<string, string[]> = {
+  choice: ['clearAt', 'splitWithin'],
+  yesno: ['clearAbove', 'clearBelow', 'splitFrom', 'splitTo'],
+};
+
+function isObject(value: any): boolean {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function addError(errors: string[], key: string, message: string): void {
+  errors.push(`${key} ${message}`);
+}
+
+function validateAdviceRegistry(registry: any, { repoRoot = REPO_ROOT, models, fsImpl = fs }: any = {}): { ok: boolean; errors: string[] } {
+  const errors: string[] = [];
+  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: string) => 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: any) { addError(errors, MODELS_FILE, `could not be loaded: ${error.message}`); }
+  }
+  const modelProviders = Array.isArray(models?.providers) ? new Set(models.providers.map((provider: any) => provider?.id).filter((id: any) => 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: any, index: number) => {
+      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: any) => 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: any) => typeof caller !== 'string')) addError(errors, `${base}.askedBy`, 'must be an array of strings');
+    }
+
+    const tier = registry.kinds.find((kind: any) => 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 }: any = {}): { ok: boolean; registry?: any; reason?: string; detail?: string } {
+  const root = path.resolve(repoRoot);
+  const target = file || path.join(root, ADVICE_FILE);
+  let registry: any;
+  try {
+    registry = JSON.parse(fsImpl.readFileSync(target, 'utf8'));
+  } catch (error: any) {
+    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.ts

@@ -0,0 +1,66 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+function strengthOf(answer: any, bands: any): { word: string; between: string[] | null } {
+  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: any[] = Object.entries(probabilities)
+      .filter(([, probability]) => typeof probability === 'number' && Number.isFinite(probability))
+      .sort((left: any, right: any) => 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: any, index: number) => [criterion, probabilities[String(index)]])
+      .filter(([, probability]: any) => typeof probability === 'number' && Number.isFinite(probability))
+      .sort((left: any, right: any) => 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: any): string {
+  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 };