@surlymochan/evalid 0.0.0-stage → 0.4.1

package/src/core/workflow-integrity.js

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+
+export const STRICT_CORPS_FORBIDDEN_ADAPTERS = new Set(['stub']);
+export const STRICT_CORPS_FORBIDDEN_STATUSES = new Set(['task_queued', 'pencil_stubbed']);
+
+export function stableStringify(value) {
+  return JSON.stringify(sortForStableStringify(value));
+}
+
+function sortForStableStringify(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => sortForStableStringify(entry));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entry]) => [key, sortForStableStringify(entry)]),
+    );
+  }
+  return value;
+}
+
+export function hashPayload(value) {
+  return createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+export function buildLogEntryHash(entry) {
+  const { entry_hash: _entryHash, ...payload } = entry || {};
+  return hashPayload(payload);
+}
+
+export function validateExecutionLogChain(entries = [], options = {}) {
+  const issues = [];
+  let previousHash = options.initialPreviousHash || null;
+  const allowExternalPreviousHash = options.allowExternalPreviousHash === true;
+  entries.forEach((entry, index) => {
+    const expectedPrevious = previousHash || null;
+    if (!(index === 0 && allowExternalPreviousHash) && (entry.prev_hash || null) !== expectedPrevious) {
+      issues.push(`execution_log_chain_prev_mismatch:${index}`);
+    }
+    const expectedHash = buildLogEntryHash(entry);
+    if (entry.entry_hash !== expectedHash) {
+      issues.push(`execution_log_chain_hash_mismatch:${index}`);
+    }
+    previousHash = entry.entry_hash || expectedHash;
+  });
+  return {
+    ok: issues.length === 0,
+    issues,
+    entries_checked: entries.length,
+  };
+}
+
+export function buildWorkflowManifest({ workflowPath = null, workflow = {}, phases = [], registry = {} }) {
+  const referencedAtomIds = new Set();
+  for (const phase of phases) {
+    for (const atomRef of phase.atoms || []) {
+      referencedAtomIds.add(atomRef.id);
+    }
+    if (phase.gate?.atom) {
+      referencedAtomIds.add(phase.gate.atom);
+    }
+  }
+
+  const atomEntries = [...referencedAtomIds].sort().map((atomId) => {
+    const def = registry.atoms?.[atomId] || {};
+    return {
+      id: atomId,
+      track: def.track || null,
+      type: def.type || null,
+      script: def.script || null,
+      module: def.module || null,
+      export: def.export || null,
+      expected_artifact: def.expected_artifact || null,
+      prompt_template: def.prompt_template || null,
+      agent_adapter: def.agent_config?.adapter || null,
+      requires_http: def.requires_http === true,
+    };
+  });
+
+  const body = {
+    version: 1,
+    workflow_name: workflow.name || null,
+    track: workflow.track || null,
+    phase_count: phases.length,
+    phase_ids: phases.map((phase) => phase.id),
+    phases: phases.map((phase) => ({
+      id: phase.id,
+      required: phase.required !== false,
+      atom_ids: (phase.atoms || []).map((atomRef) => atomRef.id),
+      gate: {
+        type: phase.gate?.type || 'skip',
+        atom: phase.gate?.atom || null,
+        on_fail: phase.gate?.on_fail || null,
+      },
+      artifacts: (phase.artifacts || []).map((artifact) => ({
+        path: artifact.path || null,
+        optional: artifact.optional === true,
+      })),
+    })),
+    atoms: atomEntries,
+  };
+
+  return {
+    ...body,
+    workflow_path: workflowPath ? resolve(workflowPath) : null,
+    digest: hashPayload(body),
+  };
+}

package/src/core/workflow-loader.js

@@ -0,0 +1,163 @@
+/**
+ * XFlow Workflow Loader
+ *
+ * Responsibilities:
+ *   1. Load and validate a workflow YAML against schemas/workflow.schema.json
+ *   2. Resolve every atom ID through atoms/registry.json
+ *   3. Verify track constraints (lite atoms must not appear in heavy-only positions)
+ *   4. Check runtime preconditions (agentos_http, gh, etc.)
+ *   5. Provide a WorkflowRunner that iterates phases and dispatches atoms
+ *
+ * E6 ≡ E1+E2 invariant: this loader does NOT perform structural artifact checks
+ * directly — it always routes through E6.gate.local_precheck (Python) for
+ * deterministic gate checks, regardless of track. Single source of truth.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+import Ajv from 'ajv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..', '..');
+
+// ─── Schema + Registry ───────────────────────────────────────────────────────
+
+function loadSchema() {
+  const path = resolve(ROOT, 'schemas', 'workflow.schema.json');
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function loadRegistry() {
+  const path = resolve(ROOT, 'atoms', 'registry.json');
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+// ─── Core loader ─────────────────────────────────────────────────────────────
+
+/**
+ * Load and validate a workflow YAML file.
+ * Returns { workflow, phases, registry } ready for execution.
+ *
+ * @param {string} workflowPath - absolute or relative path to .yaml file
+ * @param {object} options
+ * @param {boolean} options.skipRuntimeChecks - skip gh/agentos-bin checks (for testing)
+ * @returns {{ workflow, phases, registry, errors }}
+ */
+export function load(workflowPath, { skipRuntimeChecks = false } = {}) {
+  const absPath = resolve(process.cwd(), workflowPath);
+  if (!existsSync(absPath)) {
+    throw new Error(`Workflow file not found: ${absPath}`);
+  }
+
+  const raw = readFileSync(absPath, 'utf8');
+  const workflow = yaml.load(raw);
+
+  // 1. Schema validation
+  const schema = loadSchema();
+  const ajv = new Ajv({ allErrors: true });
+  const validate = ajv.compile(schema);
+  if (!validate(workflow)) {
+    const errors = validate.errors.map(e => `  ${e.instancePath} ${e.message}`).join('\n');
+    throw new Error(`Workflow schema validation failed for ${absPath}:\n${errors}`);
+  }
+
+  // 2. Registry resolution + track checks
+  const registry = loadRegistry();
+  const errors = [];
+
+  for (const phase of workflow.phases) {
+    for (const atomRef of (phase.atoms || [])) {
+      const atomDef = registry.atoms[atomRef.id];
+      if (!atomDef) {
+        errors.push(`Phase "${phase.id}": unknown atom "${atomRef.id}"`);
+        continue;
+      }
+      // Track constraint: lite workflow cannot use heavy atoms
+      if (workflow.track === 'lite' && atomDef.track === 'heavy') {
+        errors.push(`Phase "${phase.id}": lite workflow cannot use heavy atom "${atomRef.id}"`);
+      }
+    }
+    // Gate atom check
+    if (phase.gate?.atom) {
+      const gateAtom = registry.atoms[phase.gate.atom];
+      if (!gateAtom) {
+        errors.push(`Phase "${phase.id}" gate: unknown atom "${phase.gate.atom}"`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Workflow validation errors in ${absPath}:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+  }
+
+  // 3. Runtime requirement checks
+  if (!skipRuntimeChecks) {
+    const req = workflow.requires || {};
+    if (req.agentos_bin) {
+      checkBinOnPath('xflow', 'xflow CLI on PATH');
+    }
+    if (req.gh) {
+      checkBinOnPath('gh', 'GitHub CLI (brew install gh)');
+    }
+  }
+
+  return { workflow, phases: workflow.phases, registry };
+}
+
+// ─── Runtime checks ──────────────────────────────────────────────────────────
+
+import { spawnSync } from 'child_process';
+
+function checkBinOnPath(bin, description) {
+  const result = spawnSync('which', [bin], { encoding: 'utf8' });
+  if (result.status !== 0) {
+    throw new Error(`Required binary not found: ${bin} (${description})`);
+  }
+}
+
+// ─── WorkflowRunner ──────────────────────────────────────────────────────────
+
+/**
+ * Dry-run: resolve all phases and atoms, print what would execute.
+ * Does not mutate any state.
+ */
+export function dryRun(workflowPath, input = {}) {
+  const { workflow, phases, registry } = load(workflowPath, { skipRuntimeChecks: true });
+
+  console.log(`\n── Workflow: ${workflow.name} (${workflow.track}) ──`);
+  console.log(`   requires: ${JSON.stringify(workflow.requires)}`);
+  console.log(`   phases: ${phases.length}\n`);
+
+  for (let i = 0; i < phases.length; i++) {
+    const phase = phases[i];
+    const atoms = (phase.atoms || []).map(a => {
+      const def = registry.atoms[a.id];
+      const impl = def?.script || def?.module || 'unknown';
+      return `${a.id} [${def?.track || '?'}] → ${impl}`;
+    });
+
+    console.log(`  ${String(i + 1).padStart(2)}. [${phase.required ? 'required' : 'optional'}] ${phase.id}`);
+    if (phase.label) console.log(`       ${phase.label}`);
+    for (const a of atoms) {
+      console.log(`       atom: ${a}`);
+    }
+    if (phase.gate) {
+      console.log(`       gate: ${phase.gate.type}${phase.gate.atom ? ` via ${phase.gate.atom}` : ''}`);
+    }
+    console.log('');
+  }
+
+  return { workflow, phases };
+}
+
+/**
+ * Resolve a single atom from the registry to its invocation descriptor.
+ * Used by the execution layer to dispatch atoms.
+ */
+export function resolveAtom(atomId, registry) {
+  const def = registry.atoms[atomId];
+  if (!def) throw new Error(`Unknown atom: ${atomId}`);
+  return { ...def, id: atomId };
+}

package/src/core/workflow-rerun.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function loadExecutorState(stateFile) {
+  if (!existsSync(stateFile)) {
+    return null;
+  }
+  try {
+    const raw = readFileSync(stateFile, 'utf8');
+    return raw.trim() ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function saveExecutorState(stateFile, state) {
+  mkdirSync(dirname(stateFile), { recursive: true });
+  writeFileSync(stateFile, `${JSON.stringify({ ...state, updated_at: nowIso() }, null, 2)}\n`, 'utf8');
+}
+
+function trimCompletedPhases(completedPhases = [], allowedPhaseIds = new Set()) {
+  return (Array.isArray(completedPhases) ? completedPhases : []).filter((entry) => {
+    if (typeof entry === 'string') {
+      return allowedPhaseIds.has(entry);
+    }
+    if (entry && typeof entry === 'object') {
+      return allowedPhaseIds.has(entry.phase);
+    }
+    return false;
+  });
+}
+
+export function prepareWorkflowRerun({
+  workflow,
+  phases,
+  projectRoot = process.cwd(),
+  changeId = null,
+  phaseId,
+  atomId = null,
+}) {
+  const targetPhase = phases.find((phase) => phase.id === phaseId);
+  if (!targetPhase) {
+    throw new Error(`Unknown rerun phase: ${phaseId}`);
+  }
+
+  if (atomId && !(targetPhase.atoms || []).some((atomRef) => atomRef.id === atomId)) {
+    throw new Error(`Atom "${atomId}" is not present in phase "${phaseId}"`);
+  }
+
+  const phaseOrder = phases.map((phase) => phase.id);
+  const phaseIndex = phaseOrder.indexOf(phaseId);
+  const previousPhase = phaseIndex > 0 ? phaseOrder[phaseIndex - 1] : null;
+  const allowedCompleted = new Set(previousPhase ? phaseOrder.slice(0, phaseIndex) : []);
+  const stateFile = resolve(projectRoot, '.as-xflow', 'workflow-state.json');
+  const current = loadExecutorState(stateFile) || {};
+  const nextState = {
+    workflow: workflow.name,
+    change_id: current.change_id || changeId || null,
+    started_at: current.started_at || nowIso(),
+    status: 'active',
+    completed_phases: trimCompletedPhases(current.completed_phases, allowedCompleted),
+    last_completed_phase: previousPhase,
+    rerun: {
+      phase_id: phaseId,
+      atom_id: atomId || null,
+      requested_at: nowIso(),
+    },
+  };
+
+  saveExecutorState(stateFile, nextState);
+
+  const pendingGateFile = resolve(projectRoot, '.as-xflow', 'pending-gates', `${phaseId}.json`);
+  rmSync(pendingGateFile, { force: true });
+
+  return {
+    state_file: stateFile,
+    state: nextState,
+    rerun: nextState.rerun,
+  };
+}

package/src/core/workflow-state.js

@@ -0,0 +1,119 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function makeId(prefix) {
+  return `${prefix}_${randomUUID().replace(/-/g, '').slice(0, 12)}`;
+}
+
+export function resolveWorkflowStateFile(projectRoot = process.cwd()) {
+  return resolve(projectRoot, '.as-xflow', 'workflow-state.json');
+}
+
+function normalizePhaseOrder(phaseOrder = [], fallbackPhase = null) {
+  const order = Array.isArray(phaseOrder) ? phaseOrder.filter(Boolean) : [];
+  if (order.length > 0) {
+    return order;
+  }
+  return fallbackPhase ? [fallbackPhase] : [];
+}
+
+function ensureStateDefaults(state = {}, { workflowName = null, changeId = null, phaseOrder = [], currentPhase = null } = {}) {
+  const now = nowIso();
+  const order = normalizePhaseOrder(phaseOrder, currentPhase || state.current_phase || state.last_completed_phase || null);
+  const phase = currentPhase || state.current_phase || state.last_completed_phase || order[0] || null;
+  const phaseIndex = phase ? order.indexOf(phase) : null;
+  return {
+    version: state.version || 1,
+    workflow_id: state.workflow_id || makeId('wf'),
+    workflow: state.workflow || workflowName || null,
+    change_id: state.change_id || changeId || null,
+    status: state.status || 'active',
+    started_at: state.started_at || now,
+    updated_at: now,
+    current_phase: phase,
+    current_phase_index: phaseIndex >= 0 ? phaseIndex : null,
+    completed_phases: Array.isArray(state.completed_phases) ? state.completed_phases : [],
+    phase_order: order,
+    current_artifact_path: state.current_artifact_path || null,
+    last_transition: state.last_transition || null,
+    last_completed_phase: state.last_completed_phase || null,
+    pending_gate_token: state.pending_gate_token || null,
+    pending_gate_phase: state.pending_gate_phase || null,
+    pending_gate_issued_at: state.pending_gate_issued_at || null,
+  };
+}
+
+export function loadWorkflowState(projectRoot = process.cwd(), options = {}) {
+  const file = resolveWorkflowStateFile(projectRoot);
+  if (!existsSync(file)) {
+    return ensureStateDefaults({}, options);
+  }
+
+  try {
+    const raw = readFileSync(file, 'utf8');
+    const parsed = raw.trim() ? JSON.parse(raw) : {};
+    return ensureStateDefaults(parsed, options);
+  } catch {
+    return ensureStateDefaults({}, options);
+  }
+}
+
+export function saveWorkflowState(projectRoot = process.cwd(), state = {}) {
+  const file = resolveWorkflowStateFile(projectRoot);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  return file;
+}
+
+export function advanceWorkflowState(projectRoot = process.cwd(), { expectedPhase = null, artifactPath = null, workflowName = null, changeId = null, phaseOrder = [] } = {}) {
+  const state = loadWorkflowState(projectRoot, { workflowName, changeId, phaseOrder, currentPhase: expectedPhase });
+  const currentPhase = expectedPhase || state.current_phase;
+  const order = normalizePhaseOrder(state.phase_order, currentPhase);
+  const currentIndex = currentPhase ? order.indexOf(currentPhase) : -1;
+
+  if (!currentPhase || currentIndex < 0) {
+    throw new Error(`Cannot advance workflow state from unknown phase: ${String(currentPhase || '')}`);
+  }
+
+  const nextPhase = order[currentIndex + 1] || null;
+  const timestamp = nowIso();
+  const completedEntry = {
+    phase: currentPhase,
+    artifact_path: artifactPath || state.current_artifact_path || null,
+    completed_at: timestamp,
+  };
+
+  const completedPhases = Array.isArray(state.completed_phases) ? [...state.completed_phases] : [];
+  completedPhases.push(completedEntry);
+
+  const nextState = {
+    ...state,
+    workflow: state.workflow || workflowName || null,
+    change_id: state.change_id || changeId || null,
+    phase_order: order,
+    completed_phases: completedPhases,
+    current_phase: nextPhase,
+    current_phase_index: nextPhase ? order.indexOf(nextPhase) : null,
+    current_artifact_path: null,
+    last_transition: {
+      from: currentPhase,
+      to: nextPhase,
+      artifact_path: artifactPath || null,
+      transitioned_at: timestamp,
+    },
+    last_completed_phase: currentPhase,
+    updated_at: timestamp,
+    status: nextPhase ? 'active' : 'complete',
+    pending_gate_token: null,
+    pending_gate_phase: null,
+    pending_gate_issued_at: null,
+  };
+
+  saveWorkflowState(projectRoot, nextState);
+  return nextState;
+}