ai-maestro 1.0.0

package/src/schema.mjs

@@ -0,0 +1,371 @@
+export const SCHEMA_VERSION = 1;
+
+export function stampSchemaVersion(obj) {
+  return { ...obj, schemaVersion: SCHEMA_VERSION };
+}
+
+const TASK_STATUSES = new Set(['pending', 'in_progress', 'completed', 'completed_with_warnings', 'failed', 'blocked', 'needs_human', 'archived']);
+
+export function validateTask(task) {
+  const errors = [];
+  if (!task || typeof task !== 'object') {
+    return { ok: false, errors: ['task is not an object'] };
+  }
+  if (task.id === undefined || task.id === null) {
+    errors.push('missing id');
+  }
+  if (typeof task.description !== 'string' || !task.description) {
+    errors.push('missing description');
+  }
+  if (typeof task.status !== 'string' || !TASK_STATUSES.has(task.status)) {
+    errors.push('invalid status: ' + task.status);
+  }
+  if (task.createdAt !== undefined && typeof task.createdAt !== 'string') {
+    errors.push('createdAt must be a string');
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+const RUN_STATUSES = new Set(['completed', 'completed_with_warnings', 'failed', 'blocked', 'needs_human']);
+
+export function validateRunEntry(entry) {
+  const errors = [];
+  if (!entry || typeof entry !== 'object') {
+    return { ok: false, errors: ['run entry is not an object'] };
+  }
+  if (entry.taskId === undefined || entry.taskId === null) {
+    errors.push('missing taskId');
+  }
+  if (typeof entry.status !== 'string' || !RUN_STATUSES.has(entry.status)) {
+    errors.push('invalid status: ' + entry.status);
+  }
+  if (typeof entry.startTime !== 'string') {
+    errors.push('missing startTime');
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+const ORCHESTRATION_EVENT_TYPES = new Set(['orchestration_started', 'orchestration_blocked', 'orchestration_finished']);
+
+export function validateOrchestrationEvent(event) {
+  const errors = [];
+  if (!event || typeof event !== 'object' || Array.isArray(event)) {
+    return { ok: false, errors: ['orchestration event is not an object'] };
+  }
+  if (event.schemaVersion !== SCHEMA_VERSION) {
+    errors.push('invalid schemaVersion: ' + event.schemaVersion);
+  }
+  if (typeof event.orchestrationId !== 'string' || event.orchestrationId.trim().length === 0) {
+    errors.push('missing orchestrationId');
+  }
+  if (event.parentTaskId === undefined || event.parentTaskId === null || String(event.parentTaskId).trim().length === 0) {
+    errors.push('missing parentTaskId');
+  }
+  if (typeof event.attempt !== 'number' || !Number.isInteger(event.attempt) || event.attempt < 1) {
+    errors.push('invalid attempt: ' + event.attempt);
+  }
+  if (event.mode !== 'real') {
+    errors.push('invalid mode: ' + event.mode);
+  }
+  if (typeof event.eventType !== 'string' || !ORCHESTRATION_EVENT_TYPES.has(event.eventType)) {
+    errors.push('invalid eventType: ' + event.eventType);
+  }
+  if (typeof event.startTime !== 'string') {
+    errors.push('missing startTime');
+  }
+  if (typeof event.timestamp !== 'string') {
+    errors.push('missing timestamp');
+  }
+  if (event.eventType === 'orchestration_blocked') {
+    if (!['blocked', 'needs_human'].includes(event.status)) {
+      errors.push('invalid blocked status: ' + event.status);
+    }
+    if (typeof event.reason !== 'string') {
+      errors.push('missing blocked reason');
+    }
+  }
+  if (event.eventType === 'orchestration_finished') {
+    if (typeof event.endTime !== 'string') {
+      errors.push('missing endTime');
+    }
+    if (typeof event.status !== 'string' || !TASK_STATUSES.has(event.status)) {
+      errors.push('invalid status: ' + event.status);
+    }
+    if (!Array.isArray(event.children)) {
+      errors.push('children must be an array');
+    }
+    if (event.consolidation !== null && event.consolidation !== undefined && typeof event.consolidation !== 'object') {
+      errors.push('consolidation must be an object or null');
+    }
+    if (event.verification !== null && event.verification !== undefined && typeof event.verification !== 'object') {
+      errors.push('verification must be an object or null');
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateUsageSummary(summary) {
+  const errors = [];
+  if (!summary || typeof summary !== 'object') {
+    return { ok: false, errors: ['usage summary is not an object'] };
+  }
+  for (const field of ['totalRuns', 'completed', 'failed', 'blocked']) {
+    if (typeof summary[field] !== 'number') {
+      errors.push('missing numeric field: ' + field);
+    }
+  }
+  for (const field of ['preferFree', 'allowPaid', 'allowClaudeReview', 'allowDirectOpenAI']) {
+    if (typeof summary[field] !== 'boolean') {
+      errors.push('missing boolean field: ' + field);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+const COST_CLASSES = new Set(['free', 'free-tier', 'paid', 'local', 'unknown']);
+const CONFIDENCE_LEVELS = new Set(['confirmed', 'probable', 'unknown']);
+
+// Accepts a number in [0,5], the literal string 'unknown', or null/undefined
+// (all three mean "not scored"). Rejects fabricated out-of-range numbers,
+// but never requires a number to be present.
+function isScoreOrUnknown(value) {
+  if (value === null || value === undefined || value === 'unknown') return true;
+  return typeof value === 'number' && value >= 0 && value <= 5;
+}
+
+export function validateEngineFiche(engine) {
+  const errors = [];
+  if (!engine || typeof engine !== 'object') {
+    return { ok: false, errors: ['engine fiche is not an object'] };
+  }
+  if (typeof engine.id !== 'string' || !engine.id) {
+    errors.push('missing id');
+  }
+  if (typeof engine.provider !== 'string' || !engine.provider) {
+    errors.push('missing provider');
+  }
+  if (typeof engine.enabled !== 'boolean') {
+    errors.push('enabled must be boolean');
+  }
+  if (typeof engine.validated !== 'boolean') {
+    errors.push('validated must be boolean');
+  }
+  const cost = engine.cost || {};
+  if (!COST_CLASSES.has(cost.class)) {
+    errors.push('cost.class must be one of ' + [...COST_CLASSES].join('|'));
+  }
+  const caps = engine.capabilities || {};
+  for (const field of ['reasoning', 'planning', 'coding', 'debugging', 'review', 'writing', 'documentation', 'longContext']) {
+    if (!isScoreOrUnknown(caps[field])) {
+      errors.push('capabilities.' + field + ' must be a number 0-5 or null');
+    }
+  }
+  const confidence = engine.confidence || {};
+  for (const field of ['capabilities', 'cost', 'tools']) {
+    if (confidence[field] !== undefined && !CONFIDENCE_LEVELS.has(confidence[field])) {
+      errors.push('confidence.' + field + ' must be one of ' + [...CONFIDENCE_LEVELS].join('|'));
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateEnginesFile(value) {
+  const engines = Array.isArray(value) ? value : (value && Array.isArray(value.engines) ? value.engines : null);
+  if (!engines) {
+    return { ok: false, errors: ['engines.json must be an array of engine fiches, or an object with an "engines" array'] };
+  }
+  const errors = [];
+  const seenIds = new Set();
+  for (const engine of engines) {
+    const result = validateEngineFiche(engine);
+    if (!result.ok) {
+      errors.push('engine "' + (engine && engine.id) + '": ' + result.errors.join(', '));
+    }
+    if (engine && engine.id) {
+      if (seenIds.has(engine.id)) {
+        errors.push('duplicate engine id: ' + engine.id);
+      }
+      seenIds.add(engine.id);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateBudget(budget) {
+  const errors = [];
+  if (!budget || typeof budget !== 'object') {
+    return { ok: false, errors: ['budget is not an object'] };
+  }
+  for (const field of ['currencyBudget', 'estimatedTokenBudget', 'maxRunsPerTask', 'maxSubagentsPerTask', 'maxDepth']) {
+    if (typeof budget[field] !== 'number') {
+      errors.push('missing numeric field: ' + field);
+    }
+  }
+  for (const field of ['preferFree', 'allowPaid', 'allowClaudeReview', 'allowDirectOpenAI']) {
+    if (typeof budget[field] !== 'boolean') {
+      errors.push('missing boolean field: ' + field);
+    }
+  }
+  if (budget.allowHostValidationFallback !== undefined && typeof budget.allowHostValidationFallback !== 'boolean') {
+    errors.push('allowHostValidationFallback must be boolean');
+  }
+  if (budget.hostValidationCommands !== undefined) {
+    if (!Array.isArray(budget.hostValidationCommands)) {
+      errors.push('hostValidationCommands must be an array');
+    } else {
+      const allowed = new Set(['npm-test', 'npm-run-check', 'node-check']);
+      for (const commandId of budget.hostValidationCommands) {
+        if (!allowed.has(commandId)) errors.push('unknown hostValidationCommand: ' + commandId);
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+const FAILURE_CATEGORIES = new Set([
+  'quota_exceeded', 'rate_limit', 'provider_unavailable', 'network_error',
+  'authentication_error', 'missing_tool', 'insufficient_capability',
+  'context_too_small', 'invalid_output', 'syntax_failure', 'test_failure',
+  'policy_violation', 'budget_exceeded', 'safety_blocked', 'needs_human',
+  'windows_shell_mismatch', 'unsupported_tool_call', 'suspected_false_positive',
+  'windows_sandbox_acl_failure',
+  'nested_sandbox_process_failure',
+  'engine_resolution_cmd_only',
+  'process_terminated_unexpectedly',
+  'unknown_failure'
+]);
+
+const FALLBACK_ACTION_TYPES = new Set(['retry', 'switch_engine', 'ask_human', 'block', 'verify', 'fix', 'none']);
+
+export function validateFailureClassification(classification) {
+  const errors = [];
+  if (!classification || typeof classification !== 'object') {
+    return { ok: false, errors: ['failure classification is not an object'] };
+  }
+  if (!FAILURE_CATEGORIES.has(classification.category)) {
+    errors.push('unknown failure category: ' + classification.category);
+  }
+  if (!['low', 'medium', 'high', 'critical'].includes(classification.severity)) {
+    errors.push('invalid severity: ' + classification.severity);
+  }
+  if (typeof classification.retryable !== 'boolean') {
+    errors.push('retryable must be a boolean');
+  }
+  if (typeof classification.shouldFallback !== 'boolean') {
+    errors.push('shouldFallback must be a boolean');
+  }
+  if (typeof classification.shouldAskHuman !== 'boolean') {
+    errors.push('shouldAskHuman must be a boolean');
+  }
+  if (!Array.isArray(classification.reason)) {
+    errors.push('reason must be an array');
+  }
+  if (!Array.isArray(classification.evidence)) {
+    errors.push('evidence must be an array');
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateFallbackPlan(plan) {
+  const errors = [];
+  if (!plan || typeof plan !== 'object') {
+    return { ok: false, errors: ['fallback plan is not an object'] };
+  }
+  if (!FALLBACK_ACTION_TYPES.has(plan.action)) {
+    errors.push('unknown fallback action: ' + plan.action);
+  }
+  if (plan.successorEngine !== null && typeof plan.successorEngine !== 'string') {
+    errors.push('successorEngine must be a string or null');
+  }
+  if (plan.successorRole !== null && typeof plan.successorRole !== 'string') {
+    errors.push('successorRole must be a string or null');
+  }
+  if (!Array.isArray(plan.reason)) {
+    errors.push('reason must be an array');
+  }
+  if (typeof plan.allowed !== 'boolean') {
+    errors.push('allowed must be a boolean');
+  }
+  if (typeof plan.requiresHuman !== 'boolean') {
+    errors.push('requiresHuman must be a boolean');
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateExecutionContextSummary(summary) {
+  const errors = [];
+  if (!summary || typeof summary !== 'object') {
+    return { ok: false, errors: ['execution context summary is not an object'] };
+  }
+  if (typeof summary.projectRoot !== 'string') {
+    errors.push('missing projectRoot');
+  }
+  if (typeof summary.taskId !== 'string') {
+    errors.push('missing taskId');
+  }
+  if (typeof summary.runKind !== 'string') {
+    errors.push('missing runKind');
+  }
+  if (typeof summary.attemptNumber !== 'number') {
+    errors.push('missing attemptNumber');
+  }
+  if (typeof summary.orchestrationDepth !== 'number') {
+    errors.push('missing orchestrationDepth');
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+
+export function validateFallbackGraph(graph) {
+  const errors = [];
+  if (!graph || typeof graph !== 'object') {
+    return { ok: false, errors: ['fallback graph is not an object'] };
+  }
+  const rules = graph.rules || {};
+  for (const category of Object.keys(rules)) {
+    if (!FAILURE_CATEGORIES.has(category)) {
+      errors.push('unknown failure category: ' + category);
+    }
+    if (typeof rules[category].action !== 'string' || !FALLBACK_ACTION_TYPES.has(rules[category].action)) {
+      errors.push('rule for ' + category + ' is missing a valid action or has an unknown action');
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// Phase 14: what KIND of run produced a usage/RUNS.jsonl row. Older rows
+// predate this field entirely and must be treated as 'unknown', never
+// silently assumed to be 'task' — see .maestro/V0_5_CURRENT_ARCHITECTURE_AUDIT.md
+// section 8 for why retrofitting old rows is explicitly out of scope.
+const RUN_KINDS = new Set([
+  'task', 'diagnostic', 'doctor', 'codex-test', 'ui-command',
+  'release-check', 'preflight', 'verification', 'subagent'
+]);
+
+export function inferRunKind(command) {
+  switch (command) {
+    case 'run-task':
+    case 'run-all':
+    case 'run-one':
+    case 'retry':
+      return 'task';
+    case 'codex-test':
+      return 'codex-test';
+    case 'codex-compare':
+    case 'codex-home':
+    case 'codex-home-diff':
+    case 'codex-home-inventory':
+    case 'codex-home-probe':
+    case 'codex-home-repair':
+    case 'codex-debug':
+      return 'diagnostic';
+    case 'doctor':
+      return 'doctor';
+    case 'release-check':
+      return 'release-check';
+    default:
+      return 'unknown';
+  }
+}
+
+export { FAILURE_CATEGORIES, COST_CLASSES, CONFIDENCE_LEVELS, RUN_KINDS, FALLBACK_ACTION_TYPES, ORCHESTRATION_EVENT_TYPES };