@surlymochan/evalid 0.0.0-stage → 0.4.1

package/src/core/pending-gates.js

@@ -0,0 +1,66 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+export function resolvePendingGatesDir(projectRoot = process.cwd()) {
+  return resolve(projectRoot, '.as-xflow', 'pending-gates');
+}
+
+function readGateFile(filePath) {
+  try {
+    const payload = JSON.parse(readFileSync(filePath, 'utf8'));
+    return payload && typeof payload === 'object' ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+export function listPendingGates(projectRoot = process.cwd()) {
+  const dir = resolvePendingGatesDir(projectRoot);
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  return readdirSync(dir)
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => {
+      const gate = readGateFile(resolve(dir, entry));
+      return gate ? { ...gate, gate_file: resolve(dir, entry) } : null;
+    })
+    .filter((gate) => gate && gate.status !== 'approved')
+    .sort((left, right) => String(right.created_at || '').localeCompare(String(left.created_at || '')));
+}
+
+export function readPendingGate(projectRoot = process.cwd(), phase) {
+  const gateFile = resolve(resolvePendingGatesDir(projectRoot), `${phase}.json`);
+  if (!existsSync(gateFile)) {
+    return null;
+  }
+  const gate = readGateFile(gateFile);
+  return gate ? { ...gate, gate_file: gateFile } : null;
+}
+
+export function ackPendingGate(projectRoot = process.cwd(), phase, options = {}) {
+  const gateFile = resolve(resolvePendingGatesDir(projectRoot), `${phase}.json`);
+  if (!existsSync(gateFile)) {
+    throw new Error(`Pending gate not found: ${gateFile}`);
+  }
+
+  const pending = readGateFile(gateFile);
+  if (!pending) {
+    throw new Error(`Pending gate is invalid JSON: ${gateFile}`);
+  }
+
+  mkdirSync(resolvePendingGatesDir(projectRoot), { recursive: true });
+  const approved = {
+    ...pending,
+    status: 'approved',
+    approved_at: nowIso(),
+    approved_by: options.approved_by || options.approvedBy || 'control-plane',
+  };
+  writeFileSync(gateFile, `${JSON.stringify(approved, null, 2)}\n`, 'utf8');
+  return { ...approved, gate_file: gateFile };
+}

package/src/core/phase-cost.js

@@ -0,0 +1,116 @@
+/**
+ * Phase cost accounting (issue #5 P1-1).
+ *
+ * A workflow run records one entry per executed phase: how long the phase
+ * took and, when an atom reported usage, how many tokens it burned. The
+ * report compares the sum of phase durations against the run's wall clock;
+ * the two must agree within tolerance (default 5%) or the accounting itself
+ * is flagged as incomplete — an overhead number that cannot account for the
+ * wall clock is not evidence.
+ */
+
+export const PHASE_COST_TOLERANCE_PCT = 5;
+
+const TOTAL_KEYS = ['total_tokens', 'totalTokens', 'tokens_total', 'tokens'];
+const INPUT_KEYS = ['input_tokens', 'inputTokens', 'prompt_tokens', 'promptTokens'];
+const OUTPUT_KEYS = ['output_tokens', 'outputTokens', 'completion_tokens', 'completionTokens'];
+
+function pickNumber(source, keys) {
+  if (!source || typeof source !== 'object') return null;
+  for (const key of keys) {
+    const value = Number(source[key]);
+    if (Number.isFinite(value) && value >= 0) return value;
+  }
+  return null;
+}
+
+/**
+ * Extract a normalized { input, output, total } token usage from an atom
+ * result, looking at the result itself and at common nested containers
+ * (`usage`, `token_usage`, `metrics`). Returns null when the atom reported
+ * nothing usable.
+ */
+export function extractTokenUsage(result) {
+  if (!result || typeof result !== 'object') return null;
+  const containers = [result, result.usage, result.token_usage, result.metrics];
+  for (const container of containers) {
+    if (!container || typeof container !== 'object') continue;
+    const input = pickNumber(container, INPUT_KEYS);
+    const output = pickNumber(container, OUTPUT_KEYS);
+    let total = pickNumber(container, TOTAL_KEYS);
+    if (total === null && (input !== null || output !== null)) {
+      total = (input || 0) + (output || 0);
+    }
+    if (total !== null || input !== null || output !== null) {
+      return { input: input || 0, output: output || 0, total: total || 0 };
+    }
+  }
+  return null;
+}
+
+export function emptyTokenUsage() {
+  return { input: 0, output: 0, total: 0 };
+}
+
+export function addTokenUsage(accumulator, usage) {
+  if (!usage) return accumulator;
+  accumulator.input += usage.input || 0;
+  accumulator.output += usage.output || 0;
+  accumulator.total += usage.total || 0;
+  return accumulator;
+}
+
+/**
+ * Build the per-phase cost report for one workflow run.
+ *
+ * phases: [{ phase_id, status, duration_ms, tokens? }]
+ * wallClockMs: measured wall clock of the whole run.
+ */
+export function buildPhaseCostReport({ phases = [], wallClockMs = null, tolerancePct = PHASE_COST_TOLERANCE_PCT, recordedAt = null } = {}) {
+  const entries = phases.map((phase) => {
+    const durationMs = Number.isFinite(Number(phase.duration_ms)) ? Math.max(0, Math.round(Number(phase.duration_ms))) : 0;
+    return {
+      phase_id: phase.phase_id || phase.id || 'unknown',
+      status: phase.status || 'completed',
+      duration_ms: durationMs,
+      tokens: phase.tokens
+        ? {
+            input: phase.tokens.input || 0,
+            output: phase.tokens.output || 0,
+            total: phase.tokens.total || 0,
+          }
+        : null,
+    };
+  });
+
+  const totalPhaseMs = entries.reduce((sum, entry) => sum + entry.duration_ms, 0);
+  const wall = Number.isFinite(Number(wallClockMs)) && Number(wallClockMs) >= 0 ? Math.round(Number(wallClockMs)) : null;
+  const unaccountedMs = wall === null ? null : wall - totalPhaseMs;
+  const driftPct = wall !== null && wall > 0
+    ? Math.round((Math.abs(unaccountedMs) / wall) * 10000) / 100
+    : null;
+
+  for (const entry of entries) {
+    entry.duration_share = totalPhaseMs > 0
+      ? Math.round((entry.duration_ms / totalPhaseMs) * 10000) / 100
+      : 0;
+  }
+
+  const tokens = entries.reduce(
+    (acc, entry) => (entry.tokens ? addTokenUsage(acc, entry.tokens) : acc),
+    emptyTokenUsage(),
+  );
+  const anyTokens = entries.some((entry) => entry.tokens && entry.tokens.total > 0);
+
+  return {
+    phases: entries,
+    total_phase_ms: totalPhaseMs,
+    wall_clock_ms: wall,
+    unaccounted_ms: unaccountedMs,
+    drift_pct: driftPct,
+    tolerance_pct: tolerancePct,
+    within_tolerance: driftPct === null ? null : driftPct <= tolerancePct,
+    tokens: anyTokens ? tokens : null,
+    recorded_at: recordedAt || new Date().toISOString(),
+  };
+}

package/src/core/phase-run-read.js

@@ -0,0 +1,27 @@
+import { listPhaseRunSessions } from './mission-state.js';
+
+function ensureArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+export function getMissionPhaseRuns(state, missionId) {
+  return ensureArray(state.phase_runs)
+    .filter((phaseRun) => phaseRun.mission_id === missionId)
+    .sort((left, right) => String(right.completed_at || right.started_at || '').localeCompare(String(left.completed_at || left.started_at || '')));
+}
+
+export function getLatestPhaseRun(state, missionId) {
+  return getMissionPhaseRuns(state, missionId)[0] || null;
+}
+
+export function getLatestPhaseEntry(phaseRun, phase) {
+  if (!phaseRun || !phase) {
+    return null;
+  }
+  const entries = ensureArray(phaseRun.phases).filter((entry) => entry.phase === phase);
+  return entries.sort((left, right) => String(right.updated_at || '').localeCompare(String(left.updated_at || '')))[0] || null;
+}
+
+export function getLatestMissionSession(state, missionId) {
+  return listPhaseRunSessions(state, missionId)[0] || null;
+}

package/src/core/policy-overlay.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import { resolveChangePath, writeJsonFile } from './change-artifacts.js';
+
+const DEFAULT_PROFILE = {
+  version: 1,
+  execution_mode: 'personal',
+  workflow_tracks: {
+    personal: 'yolo|corps',
+    team: 'yolo|corps',
+  },
+};
+
+function readJson(path, fallback = null) {
+  if (!existsSync(path)) return fallback;
+  try {
+    const raw = readFileSync(path, 'utf8');
+    return raw.trim() ? JSON.parse(raw) : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, payload) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return path;
+}
+
+export function resolveProfilePath(projectRoot) {
+  return resolve(projectRoot, '.xflow', 'profile.json');
+}
+
+export function resolveTeamPolicyPath(projectRoot) {
+  return resolve(projectRoot, '.xflow', 'team-policy.json');
+}
+
+export function readProfile(projectRoot) {
+  const profile = readJson(resolveProfilePath(projectRoot), {});
+  return mergePolicy(DEFAULT_PROFILE, profile || {});
+}
+
+export function writeProfile(projectRoot, patch = {}) {
+  const current = readProfile(projectRoot);
+  const next = mergePolicy(current, patch);
+  writeJson(resolveProfilePath(projectRoot), next);
+  return next;
+}
+
+export function readTeamPolicy(projectRoot) {
+  return readJson(resolveTeamPolicyPath(projectRoot), null);
+}
+
+export function validateTeamPolicy(policy = {}) {
+  const errors = [];
+  const coverage = policy?.coding?.min_changed_line_coverage;
+  if (coverage !== undefined && (!Number.isFinite(Number(coverage)) || Number(coverage) < 0 || Number(coverage) > 100)) {
+    errors.push('coding.min_changed_line_coverage must be a number between 0 and 100');
+  }
+  const reviewers = policy?.review?.min_reviewers;
+  if (reviewers !== undefined && (!Number.isFinite(Number(reviewers)) || Number(reviewers) < 0)) {
+    errors.push('review.min_reviewers must be a non-negative number');
+  }
+  const smoke = policy?.deploy?.required_smoke_pass_rate;
+  if (smoke !== undefined && (!Number.isFinite(Number(smoke)) || Number(smoke) < 0 || Number(smoke) > 100)) {
+    errors.push('deploy.required_smoke_pass_rate must be a number between 0 and 100');
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function mergePolicy(personal = {}, team = {}) {
+  const merged = mergeValue(personal || {}, team || {});
+  merged.workflow_tracks = {
+    personal: 'yolo|corps',
+    team: 'yolo|corps',
+    ...(merged.workflow_tracks || {}),
+  };
+  return merged;
+}
+
+function mergeValue(personal, team) {
+  if (team === undefined || team === null) return cloneValue(personal);
+  if (personal === undefined || personal === null) return cloneValue(team);
+
+  if (Array.isArray(personal) || Array.isArray(team)) {
+    return mergeLists(team, personal);
+  }
+  if (typeof personal === 'number' || typeof team === 'number') {
+    const personalNumber = Number(personal);
+    const teamNumber = Number(team);
+    if (Number.isFinite(personalNumber) && Number.isFinite(teamNumber)) {
+      return Math.max(personalNumber, teamNumber);
+    }
+    return cloneValue(team);
+  }
+  if (isPlainObject(personal) && isPlainObject(team)) {
+    const result = {};
+    for (const key of new Set([...Object.keys(personal), ...Object.keys(team)])) {
+      result[key] = mergeValue(personal[key], team[key]);
+    }
+    return result;
+  }
+  return cloneValue(team);
+}
+
+function mergeLists(teamList, personalList) {
+  const values = [
+    ...(Array.isArray(teamList) ? teamList : [teamList]),
+    ...(Array.isArray(personalList) ? personalList : [personalList]),
+  ].filter((value) => value !== undefined && value !== null);
+  const seen = new Set();
+  const merged = [];
+  for (const value of values) {
+    const key = JSON.stringify(value);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(cloneValue(value));
+  }
+  return merged;
+}
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cloneValue(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function resolveEffectivePolicy({ projectRoot, changeId = null, executionMode = null, writeArtifact = true } = {}) {
+  const profile = readProfile(projectRoot);
+  if (executionMode) {
+    profile.execution_mode = executionMode;
+  }
+
+  const mode = profile.execution_mode || 'personal';
+  const teamPolicy = readTeamPolicy(projectRoot);
+  if (mode === 'team' && !teamPolicy) {
+    return {
+      ok: false,
+      error: {
+        code: 'team_policy_missing',
+        message: 'execution_mode=team requires .xflow/team-policy.json',
+      },
+      profile,
+      policy: null,
+    };
+  }
+
+  const validation = teamPolicy ? validateTeamPolicy(teamPolicy) : { ok: true, errors: [] };
+  if (!validation.ok) {
+    return {
+      ok: false,
+      error: {
+        code: 'team_policy_invalid',
+        message: 'team policy failed validation',
+        errors: validation.errors,
+      },
+      profile,
+      policy: null,
+    };
+  }
+
+  const policy = mode === 'team' ? mergePolicy(profile, teamPolicy) : mergePolicy(DEFAULT_PROFILE, profile);
+  policy.execution_mode = mode;
+  policy.generated_at = new Date().toISOString();
+  policy.source = {
+    profile: resolveProfilePath(projectRoot),
+    team_policy: teamPolicy ? resolveTeamPolicyPath(projectRoot) : null,
+  };
+  policy.authority = 'policy_overlay_only_workflows_remain_yolo_corps';
+
+  const result = { ok: true, profile, team_policy: teamPolicy, policy };
+  if (writeArtifact && changeId) {
+    result.policy_effective_file = writeJsonFile(resolveChangePath(projectRoot, changeId, 'policy_effective.json'), policy);
+  }
+  return result;
+}

package/src/core/state-store.js

@@ -0,0 +1,201 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+export const DEFAULT_STATE = {
+  version: 1,
+  missions: [],
+  tasks: [],
+  events: [],
+  memories: [],
+  gate_decisions: [],
+  interventions: [],
+  phase_runs: [],
+  phase_run_sessions: [],
+  reruns: [],
+  operator_actions: [],
+  mission_controls: [],
+};
+
+const mutationQueue = new Map();
+const SNAPSHOT_RETENTION_LIMIT = 200;
+
+function sqlitePathFor(requestedPath) {
+  if (requestedPath.endsWith('.sqlite') || requestedPath.endsWith('.db')) {
+    return requestedPath;
+  }
+  if (requestedPath.endsWith('.json')) {
+    return requestedPath.replace(/\.json$/u, '.sqlite');
+  }
+  return `${requestedPath}.sqlite`;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function mergeState(parsed = {}) {
+  return {
+    ...structuredClone(DEFAULT_STATE),
+    ...parsed,
+    missions: parsed.missions ?? [],
+    tasks: parsed.tasks ?? [],
+    events: parsed.events ?? [],
+    memories: parsed.memories ?? [],
+    gate_decisions: parsed.gate_decisions ?? [],
+    interventions: parsed.interventions ?? [],
+    phase_runs: parsed.phase_runs ?? [],
+    phase_run_sessions: parsed.phase_run_sessions ?? [],
+    reruns: parsed.reruns ?? [],
+    operator_actions: parsed.operator_actions ?? [],
+    mission_controls: parsed.mission_controls ?? [],
+  };
+}
+
+function openStateDatabase(file) {
+  const database = new DatabaseSync(file);
+  database.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA busy_timeout = 5000;
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS current_state (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      state_json TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS state_snapshots (
+      snapshot_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      state_json TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+  `);
+  return database;
+}
+
+function readCurrentStateRow(database) {
+  return database.prepare('SELECT state_json FROM current_state WHERE id = 1').get() || null;
+}
+
+function writeStateSnapshot(database, state, timestamp = nowIso()) {
+  const serialized = JSON.stringify(state, null, 2);
+  database.prepare(`
+    INSERT INTO current_state (id, state_json, updated_at)
+    VALUES (1, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      state_json = excluded.state_json,
+      updated_at = excluded.updated_at
+  `).run(serialized, timestamp);
+  database.prepare('INSERT INTO state_snapshots (state_json, created_at) VALUES (?, ?)').run(serialized, timestamp);
+  database.prepare(`
+    DELETE FROM state_snapshots
+    WHERE snapshot_id NOT IN (
+      SELECT snapshot_id
+      FROM state_snapshots
+      ORDER BY snapshot_id DESC
+      LIMIT ?
+    )
+  `).run(SNAPSHOT_RETENTION_LIMIT);
+  database.prepare(`
+    INSERT INTO meta (key, value)
+    VALUES ('store_backend', 'sqlite')
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run();
+}
+
+function initializeDatabase(file) {
+  const database = openStateDatabase(file);
+  try {
+    if (!readCurrentStateRow(database)) {
+      writeStateSnapshot(database, structuredClone(DEFAULT_STATE));
+    }
+  } finally {
+    database.close();
+  }
+}
+
+export function resolveDataFile({ projectRoot = process.cwd(), explicitPath = null } = {}) {
+  const requested = explicitPath || process.env.AS_XFLOW_DATA_FILE || resolve(projectRoot, '.as-xflow', 'state.sqlite');
+  return sqlitePathFor(requested);
+}
+
+export async function ensureStore(dataFile = resolveDataFile()) {
+  const file = resolveDataFile({ explicitPath: dataFile });
+  await mkdir(dirname(file), { recursive: true });
+  initializeDatabase(file);
+  return file;
+}
+
+export async function readStore(dataFile = resolveDataFile()) {
+  const file = await ensureStore(dataFile);
+  const database = openStateDatabase(file);
+  try {
+    const row = readCurrentStateRow(database);
+    if (!row) {
+      return structuredClone(DEFAULT_STATE);
+    }
+    const parsed = row.state_json.trim() ? JSON.parse(row.state_json) : structuredClone(DEFAULT_STATE);
+    return mergeState(parsed);
+  } finally {
+    database.close();
+  }
+}
+
+export async function writeStore(state, dataFile = resolveDataFile()) {
+  const file = await ensureStore(dataFile);
+  const database = openStateDatabase(file);
+  try {
+    database.exec('BEGIN IMMEDIATE');
+    writeStateSnapshot(database, state);
+    database.exec('COMMIT');
+  } catch (error) {
+    try {
+      database.exec('ROLLBACK');
+    } catch {
+      // Ignore rollback failures; the original error is the useful one.
+    }
+    throw error;
+  } finally {
+    database.close();
+  }
+}
+
+export async function mutateStore(mutator, dataFile = resolveDataFile()) {
+  const file = resolveDataFile({ explicitPath: dataFile });
+  const previous = mutationQueue.get(file) ?? Promise.resolve();
+  const current = previous.then(async () => {
+    await ensureStore(file);
+    const database = openStateDatabase(file);
+    try {
+      database.exec('BEGIN IMMEDIATE');
+      const row = readCurrentStateRow(database);
+      const parsed = row?.state_json?.trim() ? JSON.parse(row.state_json) : structuredClone(DEFAULT_STATE);
+      const state = mergeState(parsed);
+      const result = await mutator(state);
+      writeStateSnapshot(database, state);
+      database.exec('COMMIT');
+      return result;
+    } catch (error) {
+      try {
+        database.exec('ROLLBACK');
+      } catch {
+        // Ignore rollback failures; the original error is the useful one.
+      }
+      throw error;
+    } finally {
+      database.close();
+    }
+  });
+
+  mutationQueue.set(file, current);
+
+  try {
+    return await current;
+  } finally {
+    if (mutationQueue.get(file) === current) {
+      mutationQueue.delete(file);
+    }
+  }
+}