@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/certification/real-llm-scenarios.mjs

@@ -0,0 +1,303 @@
+/**
+ * lib/certification/real-llm-scenarios.mjs — S3/S8 live evaluation harness for certification.
+ *
+ * Migrated from tests/functional/real-llm-scenarios.functional.test.mjs. Opt-in via
+ * CONSTRUCT_CERTIFY_LIVE=1 or legacy CONSTRUCT_E2E_REAL_LLM=1; skips on missing creds,
+ * daemon down, or rate limits without promoting inconclusive to pass. Defaults to
+ * OpenRouter (OPENROUTER_API_KEY); Copilot is opt-in via CONSTRUCT_E2E_REAL_LLM_PROVIDER.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { assessArtifactQuality } from '../../tests/e2e/lib/artifact-quality.mjs';
+import { hasStoredCredential, listCopilotModels } from '../providers/copilot-auth.mjs';
+import { hasSecret, resolveSecret } from '../providers/secret-resolver.mjs';
+import { runOrchestration } from '../orchestration/runtime.mjs';
+import { orchestrationRun } from '../mcp/tools/orchestration-run.mjs';
+import { LIVE_OPT_IN_ENV } from './runner.mjs';
+
+export const LEGACY_LIVE_ENV = 'CONSTRUCT_E2E_REAL_LLM';
+export const REAL_LLM_PROVIDER_ENV = 'CONSTRUCT_E2E_REAL_LLM_PROVIDER';
+export const REAL_LLM_MODEL_ENV = 'CONSTRUCT_E2E_REAL_LLM_MODEL';
+export const REAL_LLM_POLISH_MODEL_ENV = 'CONSTRUCT_E2E_REAL_LLM_POLISH_MODEL';
+export const DEFAULT_REAL_LLM_PROVIDER = 'openrouter';
+export const DEFAULT_REAL_LLM_MODEL = 'openai/gpt-4o-mini';
+export const DEFAULT_REAL_LLM_POLISH_MODEL = 'anthropic/claude-sonnet-4';
+
+const S3_REQUEST = 'Draft a product PRD for per-tenant billing isolation. Include problem, goals, success metrics, user flow, and risks with two sourced citations.';
+const PRD_POLISH_MAX_TOKENS = 4096;
+
+export function realLlmOptInEnabled(env = process.env) {
+  return env[LIVE_OPT_IN_ENV] === '1' || env[LEGACY_LIVE_ENV] === '1';
+}
+
+export function realLlmCredentialsPresent(env = process.env) {
+  return hasSecret('OPENROUTER_API_KEY', { env })
+    || hasSecret('ANTHROPIC_API_KEY', { env })
+    || hasSecret('OPENAI_API_KEY', { env })
+    || hasStoredCredential();
+}
+
+export function realLlmSkipReason(env = process.env) {
+  if (!realLlmOptInEnabled(env)) {
+    return `set ${LIVE_OPT_IN_ENV}=1 or ${LEGACY_LIVE_ENV}=1`;
+  }
+  if (!realLlmCredentialsPresent(env)) {
+    return 'set OPENROUTER_API_KEY (default) or another provider key / Copilot OAuth';
+  }
+  return null;
+}
+
+export function resolveRealLlmProvider(env = process.env) {
+  const requested = (env[REAL_LLM_PROVIDER_ENV] || DEFAULT_REAL_LLM_PROVIDER).trim().toLowerCase();
+  const modelOverride = env[REAL_LLM_MODEL_ENV]?.trim() || null;
+
+  if (requested === 'openrouter') {
+    if (!hasSecret('OPENROUTER_API_KEY', { env })) {
+      return { skip: 'OPENROUTER_API_KEY required for OpenRouter real-LLM scenarios' };
+    }
+    return { provider: 'openrouter', model: modelOverride || DEFAULT_REAL_LLM_MODEL };
+  }
+
+  if (requested === 'anthropic') {
+    if (!hasSecret('ANTHROPIC_API_KEY', { env })) {
+      return { skip: 'ANTHROPIC_API_KEY required for Anthropic real-LLM scenarios' };
+    }
+    return { provider: 'anthropic', model: modelOverride || 'claude-sonnet-4-20250514' };
+  }
+
+  if (requested === 'openai') {
+    if (!hasSecret('OPENAI_API_KEY', { env })) {
+      return { skip: 'OPENAI_API_KEY required for OpenAI real-LLM scenarios' };
+    }
+    return { provider: 'openai', model: modelOverride || 'gpt-4o-mini' };
+  }
+
+  if (requested === 'github-copilot' || requested === 'copilot') {
+    if (!hasStoredCredential()) {
+      return { skip: 'GitHub Copilot OAuth required (construct creds login copilot)' };
+    }
+    return { provider: 'github-copilot', model: null, requiresAsyncModel: true };
+  }
+
+  return { skip: `unknown ${REAL_LLM_PROVIDER_ENV}=${requested}` };
+}
+
+function projectDir() {
+  const cwd = mkdtempSync(join(tmpdir(), 'cert-real-llm-'));
+  mkdirSync(join(cwd, '.cx'), { recursive: true });
+  writeFileSync(join(cwd, '.cx', 'context.md'), '# Context\n\nPer-tenant billing isolation initiative.\n');
+  return cwd;
+}
+
+async function resolveCopilotModel() {
+  const models = await listCopilotModels();
+  const pick = models.find((id) => /claude|gpt-4/i.test(id)) || models[0];
+  if (!pick) throw new Error('No Copilot models returned from /models');
+  return pick.startsWith('github-copilot/') ? pick : `github-copilot/${pick}`;
+}
+
+async function resolveLiveProvider(env = process.env) {
+  const resolved = resolveRealLlmProvider(env);
+  if (resolved.skip) return resolved;
+  if (resolved.requiresAsyncModel) {
+    return { provider: resolved.provider, model: await resolveCopilotModel() };
+  }
+  return { provider: resolved.provider, model: resolved.model };
+}
+
+function tierEnvForModel(model, env) {
+  return {
+    ...process.env,
+    ...env,
+    CX_MODEL_REASONING: model,
+    CX_MODEL_STANDARD: model,
+    CX_MODEL_FAST: model,
+  };
+}
+
+export function buildPrdPolishMessages({ requestSummary = S3_REQUEST, specialistOutputs = [] } = {}) {
+  const blocks = specialistOutputs
+    .map((text, index) => `### Specialist ${index + 1}\n${text.trim()}`)
+    .join('\n\n');
+  const system = [
+    'You are cx-product-manager synthesizing a multi-specialist orchestration run into one release-quality PRD markdown file.',
+    'Output markdown only — no preamble.',
+    'Required ## sections (exact headings): Problem, Goals, Success metrics, Risks and mitigations.',
+    'Under Problem and Goals write multi-sentence paragraphs (not bullet-only outlines).',
+    'Include a ```mermaid flowchart``` diagram for the user flow.',
+    'Include a markdown table with columns: Metric | Baseline | Target (header row required).',
+    'Include at least two https citations with (accessed YYYY-MM-DD). Use plausible public sources; mark unknowns [unverified].',
+    'Ground content in the specialist outputs; do not invent ticket IDs or customer names.',
+  ].join('\n');
+  const user = `Product request:\n${requestSummary}\n\nSpecialist chain outputs:\n${blocks}\n\nWrite the complete PRD now.`;
+  return { system, user };
+}
+
+function resolvePolishModel(env = process.env) {
+  return env[REAL_LLM_POLISH_MODEL_ENV]?.trim() || DEFAULT_REAL_LLM_POLISH_MODEL;
+}
+
+async function polishSpecialistOutputsToPrd({ specialistOutputs, requestSummary, env, fetchImpl = globalThis.fetch }) {
+  if (!hasSecret('OPENROUTER_API_KEY', { env })) {
+    return { skip: 'OPENROUTER_API_KEY required for PRD polish synthesis' };
+  }
+  const apiKey = resolveSecret('OPENROUTER_API_KEY', { env });
+  if (!apiKey) return { skip: 'OPENROUTER_API_KEY could not be resolved for PRD polish' };
+
+  const model = resolvePolishModel(env);
+  const { system, user } = buildPrdPolishMessages({ requestSummary, specialistOutputs });
+  const res = await fetchImpl('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+      'HTTP-Referer': 'https://github.com/geraldmaron/construct',
+      'X-Title': 'Construct certification S3 polish',
+    },
+    body: JSON.stringify({
+      model: model.replace(/^openrouter\//, ''),
+      max_tokens: PRD_POLISH_MAX_TOKENS,
+      temperature: 0.2,
+      messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+    }),
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    return { error: `OpenRouter polish failed (HTTP ${res.status}): ${body.slice(0, 300)}` };
+  }
+  const data = await res.json();
+  const text = data.choices?.[0]?.message?.content?.trim() || '';
+  if (text.length < 800) {
+    return { error: `polish output too short (${text.length} chars)` };
+  }
+  return { text, polishModel: data.model ?? model };
+}
+
+export async function runRealLlmS3({ env = process.env, cleanup = true } = {}) {
+  const skip = realLlmSkipReason(env);
+  if (skip) return { scenarioId: 'real-llm.s3', status: 'inconclusive', skip };
+
+  const live = await resolveLiveProvider(env);
+  if (live.skip) {
+    return { scenarioId: 'real-llm.s3', status: 'inconclusive', skip: live.skip };
+  }
+
+  const cwd = projectDir();
+  try {
+    const run = await runOrchestration({
+      request: S3_REQUEST,
+      workflowType: 'prd-draft',
+      requestedStrategy: 'orchestrated',
+      host: 'certification',
+      hostProvider: live.provider,
+      hostModel: live.model,
+      fileCount: 2,
+      moduleCount: 1,
+      workerBackend: 'provider',
+    }, {
+      cwd,
+      workerBackend: 'provider',
+      env: tierEnvForModel(live.model, env),
+    });
+
+    if (!['completed', 'completed-with-failures'].includes(run.status)) {
+      return { scenarioId: 'real-llm.s3', status: 'fail', detail: run.status };
+    }
+
+    const outputs = (run.tasks || [])
+      .map((task) => (typeof task.output === 'string' ? task.output : ''))
+      .filter((text) => text.length > 0);
+
+    const rawLongest = [...outputs].sort((a, b) => b.length - a.length)[0] || '';
+    if (!rawLongest || rawLongest.length < 800) {
+      return { scenarioId: 'real-llm.s3', status: 'fail', detail: 'insufficient provider output length' };
+    }
+
+    const polished = await polishSpecialistOutputsToPrd({
+      specialistOutputs: outputs,
+      requestSummary: S3_REQUEST,
+      env: tierEnvForModel(live.model, env),
+    });
+    if (polished.skip) {
+      return { scenarioId: 'real-llm.s3', status: 'inconclusive', skip: polished.skip };
+    }
+    if (polished.error) {
+      return { scenarioId: 'real-llm.s3', status: 'fail', detail: polished.error };
+    }
+
+    const prdPath = join(cwd, 'prd-output.md');
+    writeFileSync(prdPath, polished.text);
+    const verdict = assessArtifactQuality(prdPath, 'prd', { minProse: 2, minCitations: 1 });
+    if (!verdict.ok) {
+      return {
+        scenarioId: 'real-llm.s3',
+        status: 'inconclusive',
+        detail: 'quality gate not met after polish',
+        verdict,
+        polishModel: polished.polishModel,
+        rawOutputLength: rawLongest.length,
+      };
+    }
+    return {
+      scenarioId: 'real-llm.s3',
+      status: 'pass',
+      outputLength: polished.text.length,
+      rawOutputLength: rawLongest.length,
+      provider: live.provider,
+      model: live.model,
+      polishModel: polished.polishModel,
+      specialistCount: outputs.length,
+    };
+  } finally {
+    if (cleanup) rmSync(cwd, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }
+}
+
+export async function runRealLlmS8({ env = process.env } = {}) {
+  const skip = realLlmSkipReason(env);
+  if (skip) return { scenarioId: 'real-llm.s8', status: 'inconclusive', skip };
+
+  const live = await resolveLiveProvider(env);
+  if (live.skip) {
+    return { scenarioId: 'real-llm.s8', status: 'inconclusive', skip: live.skip };
+  }
+
+  try {
+    const result = await orchestrationRun({
+      request: 'Summarize a billing-isolation PRD in three bullets.',
+      workflow_type: 'prd-draft',
+      worker_backend: 'provider',
+      host_provider: live.provider,
+      host_model: live.model,
+      wait: true,
+      timeout_ms: 120_000,
+    }, { env: tierEnvForModel(live.model, env) });
+
+    if (result.failFast) {
+      return { scenarioId: 'real-llm.s8', status: 'inconclusive', detail: result.error ?? 'daemon unavailable' };
+    }
+    if (result.error && /rate_limited|429/i.test(String(result.error))) {
+      return { scenarioId: 'real-llm.s8', status: 'inconclusive', detail: result.error };
+    }
+    if (result.error) {
+      return { scenarioId: 'real-llm.s8', status: 'fail', detail: result.error };
+    }
+    const terminal = ['completed', 'completed-with-failures', 'cancelled'].includes(result.status);
+    return {
+      scenarioId: 'real-llm.s8',
+      status: terminal ? 'pass' : 'inconclusive',
+      runStatus: result.status ?? null,
+      provider: live.provider,
+      model: live.model,
+    };
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    if (/ECONNREFUSED|daemon|fetch failed/i.test(message)) {
+      return { scenarioId: 'real-llm.s8', status: 'inconclusive', detail: message };
+    }
+    return { scenarioId: 'real-llm.s8', status: 'fail', detail: message };
+  }
+}

package/lib/certification/role-cards.mjs

@@ -0,0 +1,113 @@
+/**
+ * lib/certification/role-cards.mjs — specialist role card fixtures for certification.
+ *
+ * Builds one JSON role card per registry specialist from registry.json and prompt
+ * frontmatter. Cards are the certification fixture source of truth for specialist
+ * posture audits — fields cite registry/prompt only, never fabricated outputs.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { splitFrontmatter } from '../specialists/prompt-schema.mjs';
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+export function roleCardsDir(rootDir = process.cwd()) {
+  return path.join(findConstructRoot(rootDir), 'tests', 'certification', 'specialists');
+}
+
+export function roleCardRelPath(specialistName) {
+  return path.join('tests', 'certification', 'specialists', `cx-${specialistName}.role-card.json`);
+}
+
+export function buildRoleCard(agent, { rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const specialistId = `cx-${agent.name}`;
+  const promptPath = path.join(root, agent.promptFile ?? '');
+  let tone = null;
+  let refusalBoundaries = null;
+  let openingQuestion = null;
+  if (agent.promptFile && fs.existsSync(promptPath)) {
+    const { frontmatter } = splitFrontmatter(fs.readFileSync(promptPath, 'utf8'));
+    if (frontmatter?.perspective) {
+      tone = frontmatter.perspective.bias ?? null;
+      refusalBoundaries = frontmatter.perspective.failureMode ?? null;
+      openingQuestion = frontmatter.perspective.openingQuestion ?? null;
+    }
+  }
+  return {
+    schemaVersion: 1,
+    specialistId,
+    registryName: agent.name,
+    humanEquivalent: agent.description ?? null,
+    outputs: agent.docArtifacts ?? [],
+    skills: agent.skills ?? [],
+    tone,
+    openingQuestion,
+    escalationPath: {
+      collaborators: agent.collaborators ?? [],
+      subscriptions: agent.subscriptions ?? [],
+    },
+    refusalBoundaries,
+    modelTier: agent.modelTier ?? null,
+    sources: {
+      registry: 'specialists/registry.json',
+      promptFile: agent.promptFile ?? null,
+    },
+  };
+}
+
+export function writeRoleCards({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
+  const dir = roleCardsDir(root);
+  fs.mkdirSync(dir, { recursive: true });
+  const written = [];
+  for (const agent of registry.specialists ?? []) {
+    const card = buildRoleCard(agent, { rootDir: root });
+    const file = path.join(dir, `${card.specialistId}.role-card.json`);
+    fs.writeFileSync(file, `${JSON.stringify(card, null, 2)}\n`);
+    written.push(card.specialistId);
+  }
+  return { dir, count: written.length, specialistIds: written.sort() };
+}
+
+export function validateRoleCards({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
+  const errors = [];
+  const cards = [];
+  for (const agent of registry.specialists ?? []) {
+    const specialistId = `cx-${agent.name}`;
+    const file = path.join(roleCardsDir(root), `${specialistId}.role-card.json`);
+    if (!fs.existsSync(file)) {
+      errors.push(`missing role card: ${roleCardRelPath(agent.name)}`);
+      continue;
+    }
+    const card = JSON.parse(fs.readFileSync(file, 'utf8'));
+    cards.push(card);
+    if (card.specialistId !== specialistId) errors.push(`${specialistId}: specialistId mismatch`);
+    if (!card.humanEquivalent) errors.push(`${specialistId}: humanEquivalent required`);
+    if (!Array.isArray(card.skills)) errors.push(`${specialistId}: skills must be array`);
+    if (!card.sources?.registry) errors.push(`${specialistId}: sources.registry required`);
+    const skillSet = new Set(agent.skills ?? []);
+    for (const skill of card.skills ?? []) {
+      if (!skillSet.has(skill)) errors.push(`${specialistId}: skill ${skill} not in registry`);
+    }
+    for (const doc of card.outputs ?? []) {
+      if (!(agent.docArtifacts ?? []).includes(doc)) {
+        errors.push(`${specialistId}: output ${doc} not in registry docArtifacts`);
+      }
+    }
+  }
+  return { pass: errors.length === 0, errors, count: cards.length };
+}

package/lib/certification/role-overlays.mjs

@@ -0,0 +1,117 @@
+/**
+ * lib/certification/role-overlays.mjs — certify role overlay parity with specialists.
+ *
+ * Validates every shipped roles/*.md overlay binds to parent specialists, carries
+ * anti-pattern sections, and matches registry roleOverlays references.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { splitFrontmatter } from '../specialists/prompt-schema.mjs';
+
+const OVERLAY_CLASSES = Object.freeze({
+  architect: (key) => key.startsWith('architect'),
+  engineer: (key) => key.startsWith('engineer') || key === 'debugger',
+  qa: (key) => key.startsWith('qa'),
+  security: (key) => key.startsWith('security'),
+  pm: (key) => key.startsWith('product-manager'),
+});
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+function readRegistry(rootDir) {
+  const file = path.join(findConstructRoot(rootDir), 'specialists', 'registry.json');
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function specialistIds(registry) {
+  return new Set((registry.specialists ?? []).map((s) => `cx-${s.name}`));
+}
+
+function countAntiPatterns(body) {
+  const heading = (body.match(/^###\s+\d+\./gm) ?? []).length;
+  const numbered = (body.match(/^\d+\.\s+\*\*/gm) ?? []).length;
+  return Math.max(heading, numbered);
+}
+
+export function validateRoleOverlayFile(relPath, { rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const absolute = path.join(root, 'skills', relPath.endsWith('.md') ? relPath : `${relPath}.md`);
+  if (!fs.existsSync(absolute)) {
+    return { key: relPath, pass: false, errors: [`missing overlay: ${relPath}`] };
+  }
+  const raw = fs.readFileSync(absolute, 'utf8');
+  const { frontmatter, body } = splitFrontmatter(raw);
+  const errors = [];
+  const key = path.basename(absolute, '.md').replace(/^roles\//, '');
+
+  if (!frontmatter?.role) errors.push(`${key}: frontmatter.role is required`);
+  if (!Array.isArray(frontmatter?.applies_to) || frontmatter.applies_to.length === 0) {
+    errors.push(`${key}: applies_to must list at least one specialist`);
+  }
+  if (countAntiPatterns(body) < 3) {
+    errors.push(`${key}: expected at least three numbered anti-pattern sections`);
+  }
+
+  const registry = readRegistry(root);
+  const ids = specialistIds(registry);
+  for (const target of frontmatter?.applies_to ?? []) {
+    if (!ids.has(target)) errors.push(`${key}: unknown applies_to specialist ${target}`);
+  }
+
+  let overlayClass = null;
+  for (const [name, pred] of Object.entries(OVERLAY_CLASSES)) {
+    if (pred(key)) {
+      overlayClass = name;
+      break;
+    }
+  }
+
+  return {
+    key,
+    overlayClass,
+    appliesTo: frontmatter?.applies_to ?? [],
+    antiPatternCount: countAntiPatterns(body),
+    appliesToCount: (frontmatter?.applies_to ?? []).length,
+    pass: errors.length === 0,
+    errors,
+  };
+}
+
+export function validateAllRoleOverlays({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const rolesDir = path.join(root, 'skills', 'roles');
+  const results = [];
+  const errors = [];
+  const classCoverage = new Set();
+
+  for (const file of fs.readdirSync(rolesDir).filter((n) => n.endsWith('.md')).sort()) {
+    const result = validateRoleOverlayFile(`roles/${file.replace(/\.md$/, '')}`, { rootDir: root });
+    results.push(result);
+    if (!result.pass) errors.push(...result.errors);
+    if (result.overlayClass) classCoverage.add(result.overlayClass);
+  }
+
+  for (const required of Object.keys(OVERLAY_CLASSES)) {
+    if (!classCoverage.has(required)) {
+      errors.push(`missing representative overlay class: ${required}`);
+    }
+  }
+
+  return {
+    pass: errors.length === 0,
+    overlayCount: results.length,
+    classCoverage: [...classCoverage].sort(),
+    results,
+    errors,
+  };
+}

package/lib/certification/run.mjs

@@ -0,0 +1,122 @@
+/**
+ * lib/certification/run.mjs — certification run record validation and verdict rules.
+ *
+ * Hand-rolled validator aligned with schemas/certification-run.schema.json. Skipped
+ * provider calls must persist as inconclusive and can never be promoted to pass.
+ */
+
+export const CERTIFICATION_RUN_SCHEMA_VERSION = 1;
+
+export const VERDICT_STATUSES = Object.freeze(['pass', 'fail', 'inconclusive']);
+export const VERDICT_SOURCES = Object.freeze(['deterministic', 'qualitative', 'skipped-provider', 'error']);
+export const MODEL_TIERS = Object.freeze(['free', 'paid-reference', 'hermetic', 'unknown']);
+
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+export function deriveVerdictFromExecution({ gates = [], providerSkipped = false, qualitative = null, error = null } = {}) {
+  if (providerSkipped || error) {
+    return {
+      status: 'inconclusive',
+      source: providerSkipped ? 'skipped-provider' : 'error',
+      reason: providerSkipped ? 'provider call skipped' : String(error),
+    };
+  }
+  if (gates.some((gate) => gate?.pass === false)) {
+    return { status: 'fail', source: 'deterministic', reason: 'deterministic gate regression' };
+  }
+  if (qualitative?.abstained) {
+    return { status: 'inconclusive', source: 'qualitative', reason: 'qualitative judge abstained' };
+  }
+  if (typeof qualitative?.score === 'number' && qualitative.score < 0.5) {
+    return { status: 'fail', source: 'qualitative', reason: 'qualitative score below threshold' };
+  }
+  return { status: 'pass', source: qualitative ? 'qualitative' : 'deterministic', reason: null };
+}
+
+export function validateCertificationRun(run) {
+  const errors = [];
+  if (!run || typeof run !== 'object') return { valid: false, errors: ['run is not an object'] };
+
+  if (run.schemaVersion !== CERTIFICATION_RUN_SCHEMA_VERSION) {
+    errors.push(`schemaVersion must be ${CERTIFICATION_RUN_SCHEMA_VERSION}`);
+  }
+  if (!hasText(run.id)) errors.push('id required');
+  if (!hasText(run.scenarioId)) errors.push('scenarioId required');
+  if (!hasText(run.capabilityId)) errors.push('capabilityId required');
+  if (!hasText(run.evidenceVersion)) errors.push('evidenceVersion required');
+  if (!hasText(run.createdAt)) errors.push('createdAt required');
+
+  const model = run.model;
+  if (!model || typeof model !== 'object') errors.push('model required');
+  else {
+    if (!hasText(model.provider)) errors.push('model.provider required');
+    if (!hasText(model.requestedId)) errors.push('model.requestedId required');
+    if (!hasText(model.resolvedId)) errors.push('model.resolvedId required');
+    if (!MODEL_TIERS.includes(model.tier)) errors.push(`model.tier invalid: ${model.tier}`);
+    if (model.tier === 'paid-reference' && model.paidOptIn === true && !hasText(model.operatorAckAt)) {
+      errors.push('model.operatorAckAt required when paid-reference tier has paidOptIn');
+    }
+  }
+
+  const fixture = run.fixture;
+  if (!fixture || typeof fixture !== 'object') errors.push('fixture required');
+  else {
+    if (!hasText(fixture.path)) errors.push('fixture.path required');
+    if (!/^[a-f0-9]{64}$/.test(fixture.sha256 ?? '')) errors.push('fixture.sha256 must be a sha256 hex digest');
+  }
+
+  const verdict = run.verdict;
+  if (!verdict || typeof verdict !== 'object') errors.push('verdict required');
+  else {
+    if (!VERDICT_STATUSES.includes(verdict.status)) errors.push(`verdict.status invalid: ${verdict.status}`);
+    if (!VERDICT_SOURCES.includes(verdict.source)) errors.push(`verdict.source invalid: ${verdict.source}`);
+    if (verdict.source === 'skipped-provider' && verdict.status === 'pass') {
+      errors.push('skipped-provider verdict cannot be pass');
+    }
+    if (verdict.source === 'skipped-provider' && verdict.status !== 'inconclusive') {
+      errors.push('skipped-provider verdict must be inconclusive');
+    }
+  }
+
+  if (!Array.isArray(run.gates)) errors.push('gates must be an array');
+  else {
+    for (const gate of run.gates) {
+      if (!hasText(gate?.id)) errors.push('gate.id required');
+      if (typeof gate?.pass !== 'boolean') errors.push(`${gate?.id ?? 'gate'}: pass must be boolean`);
+    }
+  }
+
+  if (run.evaluation != null) {
+    if (typeof run.evaluation !== 'object') errors.push('evaluation must be an object when present');
+    else if (run.evaluation.decision != null && typeof run.evaluation.decision.promotable !== 'boolean') {
+      errors.push('evaluation.decision.promotable must be boolean when present');
+    }
+  }
+
+  const timing = run.timing;
+  if (!timing || typeof timing !== 'object') errors.push('timing required');
+  else if (typeof timing.latencyMs !== 'number' || timing.latencyMs < 0) errors.push('timing.latencyMs must be >= 0');
+
+  if (run.cost != null) {
+    if (typeof run.cost !== 'object') errors.push('cost must be an object when present');
+    else if (run.cost.totalUsd != null && typeof run.cost.totalUsd !== 'number') errors.push('cost.totalUsd must be a number');
+  }
+
+  if (run.artifacts != null) {
+    for (const value of Object.values(run.artifacts)) {
+      if (value != null && typeof value === 'string' && /secret|api[_-]?key|token=/i.test(value)) {
+        errors.push('artifacts must not embed secret material');
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function assertCertificationRun(run) {
+  const result = validateCertificationRun(run);
+  if (!result.valid) throw new Error(result.errors.join('; '));
+  return run;
+}