@nebulacomponents/citable 1.15.1 → 1.17.0

package/src/commands/edgeSecurity.js

@@ -0,0 +1,192 @@
+/**
+ * Security audit for generated and user-supplied edge code.
+ *
+ * Findings are deterministic pattern checks over the code text. A clean
+ * result means no listed risk pattern was found; it is not a substitute for
+ * human security review of deployed code.
+ */
+
+const WORKER_SIZE_LIMIT_BYTES = 1024 * 1024; // Cloudflare Workers ~1 MiB before compression (documented platform limit)
+
+const RULES = [
+  {
+    rule_id: 'EDGSEC-001',
+    name: 'Inline script requires CSP unsafe-inline',
+    applies: ['shopify-snippet', 'html'],
+    check(content) {
+      const inline = /<script(?![^>]*\ssrc\s*=)[^>]*>/i.test(content);
+      if (!inline) return null;
+      return {
+        severity: 'advisory',
+        summary: 'Generated code contains an inline <script> block; sites with a strict Content-Security-Policy will block it unless a nonce or hash is added.',
+        remediation: 'Prefer an external script file, or add the script hash/nonce to the CSP. Record the CSP implication in deployment notes.',
+      };
+    },
+  },
+  {
+    rule_id: 'EDGSEC-002',
+    name: 'HTMLRewriter html-mode append/setAttribute with dynamic content',
+    applies: ['cloudflare-worker', 'cloudflare-cro'],
+    check(content) {
+      const dynamicAppend = /\.append\(\s*(?!['"`]\s*[<A-Za-z])[^,)]*?,\s*\{\s*html:\s*true/i.test(content)
+        || /\.append\(\s*[A-Za-z_$][\w$.\[\]]*\s*,\s*\{\s*html:\s*true/i.test(content);
+      if (!dynamicAppend) return null;
+      return {
+        severity: 'high',
+        summary: 'HTMLRewriter append uses html:true with a non-literal argument; untrusted data reaching this sink becomes HTML injection.',
+        remediation: 'Only append static string literals with html:true, or escape all interpolated values with a strict HTML escaper before insertion.',
+      };
+    },
+  },
+  {
+    rule_id: 'EDGSEC-003',
+    name: 'Unescaped interpolation into HTML or script context',
+    applies: ['cloudflare-worker', 'cloudflare-cro', 'vercel-middleware', 'shopify-snippet', 'html'],
+    check(content, { format }) {
+      const problems = [];
+      // JS template literals inside generated HTML strings
+      const htmlTemplateLiteral = /`[^`]*<(?:div|span|aside|a|p|script)[^>]*>\$\{[^}]*\}/i.test(content);
+      if (htmlTemplateLiteral) problems.push('template literal interpolated into HTML markup');
+      // Liquid object output without escape filter inside script blocks (script context never auto-escapes)
+      if (format === 'shopify-snippet') {
+        const scripts = content.match(/<script\b[^>]*>[\s\S]*?<\/script[^>]*>/gi) || [];
+        for (const block of scripts) {
+          for (const m of block.matchAll(/\{\{[^}]*\}\}/g)) {
+            if (!/\|\s*escape|json/.test(m[0])) problems.push(`Liquid output ${m[0]} inside <script> without escape filter`);
+          }
+        }
+        // also Liquid anywhere with raw/unsafe filters
+        for (const m of content.matchAll(/\{\{[^}]*(?:\|\s*raw|\|\s*strip_html)[^}]*\}\}/g)) {
+          problems.push(`Liquid output ${m[0]} uses a filter that disables escaping`);
+        }
+      }
+      if (problems.length === 0) return null;
+      return {
+        severity: 'high',
+        summary: `Unescaped dynamic interpolation in output context: ${problems.join('; ')}`,
+        remediation: 'Escape all dynamic values for the exact output context (HTML body, attribute, or JS string) or use static literals only.',
+      };
+    },
+  },
+  {
+    rule_id: 'EDGSEC-004',
+    name: 'Untrusted referral data written into the DOM',
+    applies: ['cloudflare-worker', 'cloudflare-cro', 'vercel-middleware', 'shopify-snippet', 'html'],
+    check(content) {
+      const readsReferral = /document\.referrer|location\.hash|searchParams\.get|URLSearchParams|\?~:text=:~:text/i.test(content)
+        || /:~:text=/i.test(content);
+      const dangerousSink = /innerHTML\s*=|document\.write\s*\(|insertAdjacentHTML\s*\(/.test(content);
+      if (readsReferral && dangerousSink) {
+        return {
+          severity: 'high',
+          summary: 'Code reads user-controlled referral data (referrer, URL hash, or text fragment) and also writes to HTML-parsing DOM sinks; referral fragments are attacker-controllable input.',
+          remediation: 'Render referral-derived values with textContent/createTextNode only, or never write them into the DOM. Treat referral fragments as untrusted data.',
+        };
+      }
+      if (readsReferral) {
+        return {
+          severity: 'advisory',
+          summary: 'Code reads user-controlled referral data (referrer or text fragment). Confirmed safe sinks in the current template, but any future change must keep this data out of HTML-parsing sinks and must not persist or transmit it without a documented consent basis.',
+          remediation: 'Keep referral fragments out of innerHTML/document.write; do not log, store, or transmit referral content; label analytics derived from it as untrusted input.',
+        };
+      }
+      return null;
+    },
+  },
+  {
+    rule_id: 'EDGSEC-005',
+    name: 'Potential PII collected by telemetry',
+    applies: ['cloudflare-worker', 'cloudflare-cro', 'vercel-middleware', 'shopify-snippet', 'html'],
+    check(content) {
+      // PII matters when used as data (object keys, assignments, values), not
+      // when it appears inside autocomplete/CSS selector hints.
+      const patterns = [
+        /\b(email|e_mail|fullname|first_name|last_name|phone|address|postal_code|postcode|ip_address|user_agent|birthdate|date_of_birth)\b\s*[:=]/gi,
+        /[:\{,]\s*["'](email|e_mail|fullname|first_name|last_name|phone|address|postal_code|postcode|ip_address|user_agent|birthdate|date_of_birth)["']\s*:/gi,
+      ];
+      const found = [];
+      for (const rx of patterns) {
+        for (const m of content.matchAll(rx)) found.push(m[0].trim());
+      }
+      if (found.length === 0) return null;
+      const unique = [...new Set(found)];
+      return {
+        severity: 'high',
+        summary: `Telemetry or edge code references potential PII fields (${unique.join(', ')}); accidental collection creates GDPR/CCPA exposure.`,
+        remediation: 'Remove PII from generated telemetry payloads; collect only aggregate experiment identifiers with a documented consent basis.',
+      };
+    },
+  },
+  {
+    rule_id: 'EDGSEC-006',
+    name: 'Per-request response variance without cache guidance',
+    applies: ['cloudflare-worker', 'cloudflare-cro', 'vercel-middleware'],
+    check(content) {
+      const variesOnRequest = /request\.headers\.get\(|cookies|cf-connecting-ip/i.test(content);
+      const setsCacheControl = /cache-control/i.test(content);
+      if (variesOnRequest && !setsCacheControl) {
+        return {
+          severity: 'medium',
+          summary: 'Edge code varies behavior per request (headers/cookies/IP) without setting explicit Cache-Control guidance; a shared cache may serve one visitor’s personalized response to others (cache poisoning of personalized variants).',
+        remediation: 'Add explicit Cache-Control (e.g. private, no-store for personalized responses) or move variance behind cacheable segmentation.',
+        };
+      }
+      return null;
+    },
+  },
+  {
+    rule_id: 'EDGSEC-007',
+    name: 'Worker size above documented platform limit',
+    applies: ['cloudflare-worker', 'cloudflare-cro'],
+    check(content) {
+      const size = Buffer.byteLength(content, 'utf8');
+      if (size <= WORKER_SIZE_LIMIT_BYTES) return null;
+      return {
+        severity: 'medium',
+        summary: `Generated worker is ${(size / 1024).toFixed(1)} KiB; Cloudflare Workers limit scripts to ~1 MiB before compression on many plans (documented platform limit, not a measurement).`,
+        remediation: 'Split the worker or strip unused remediations before deployment.',
+      };
+    },
+  },
+];
+
+/**
+ * Audit one edge/snippet code string. Returns findings with full provenance
+ * fields so results are citable evidence, not terminal commentary.
+ */
+export function auditEdgeCode(rawContent, { format = 'html', name = 'generated-edge-code', toolVersion = null, rules = RULES } = {}) {
+  const content = typeof rawContent === 'string' ? rawContent : String(rawContent);
+  const findings = [];
+  for (const rule of rules) {
+    if (rule.applies.length && !rule.applies.includes(format)) continue;
+    let hit = null;
+    try {
+      hit = rule.check(content, { format });
+    } catch (err) {
+      findings.push({
+        rule_id: `${rule.rule_id}-ERROR`,
+        severity: 'high',
+        summary: `security rule error: ${err.message}`,
+        remediation: 'Fix the audit rule before trusting a clean result (fail closed).',
+      });
+      continue;
+    }
+    if (hit) {
+      findings.push({ rule_id: rule.rule_id, rule_name: rule.name, ...hit });
+    }
+  }
+  const severityRank = { high: 0, medium: 1, advisory: 2 };
+  findings.sort((a, b) => severityRank[a.severity] - severityRank[b.severity]);
+  return {
+    target: name,
+    format,
+    byte_size: Buffer.byteLength(content, 'utf8'),
+    finding_count: findings.length,
+    high: findings.filter((f) => f.severity === 'high').length,
+    medium: findings.filter((f) => f.severity === 'medium').length,
+    advisory: findings.filter((f) => f.severity === 'advisory').length,
+    findings,
+    methodology: 'deterministic pattern audit of generated code; a clean result is not a substitute for human security review',
+    tool_version: toolVersion,
+  };
+}

package/src/commands/exceptions.js

@@ -0,0 +1,241 @@
+/**
+ * Governed Exception Lifecycle & Expiry Review.
+ *
+ * Provides inspection, renewal, and revocation of entries in .citable/exceptions.yaml
+ * under strict schema, reviewer authority, and audit trail rules.
+ *
+ * Governed Invariants:
+ * - Expired exceptions fail closed and are surfaced explicitly.
+ * - Renewals require an active, authorized reviewer and cannot exceed policy or renewal limits.
+ * - Revocations and renewals append immutable audit history events.
+ * - Candidate registries are validated against exception.schema.json before saving.
+ */
+
+import { loadRegistries, saveRegistry } from "../registries/index.js";
+import { validateAgainst } from "../shared/schemaValidator.js";
+import { parseRefDate, sha256 } from "../shared/io.js";
+
+export function listExceptions(root, {
+  expiredOnly = false,
+  expiringSoonDays = 14,
+  refDate = null,
+} = {}) {
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join("; ")}`);
+
+  const ref = parseRefDate(refDate);
+  const entries = registries.exceptions?.entries || [];
+
+  const evaluated = entries.map((entry) => {
+    const expiresAt = new Date(entry.expires_at);
+    const isExpired = expiresAt < ref;
+    const daysRemaining = Math.ceil((expiresAt.getTime() - ref.getTime()) / 86400000);
+    const isExpiringSoon = !isExpired && daysRemaining <= Number(expiringSoonDays) && daysRemaining >= 0;
+
+    let computedStatus = entry.status;
+    if (entry.status === "revoked") computedStatus = "revoked";
+    else if (entry.status === "superseded") computedStatus = "superseded";
+    else if (isExpired) computedStatus = "expired";
+    else if (isExpiringSoon) computedStatus = "expiring_soon";
+
+    return {
+      exception_id: entry.exception_id,
+      policy_id: entry.policy_id,
+      status: entry.status,
+      computed_status: computedStatus,
+      is_expired: isExpired,
+      is_expiring_soon: isExpiringSoon,
+      days_remaining: daysRemaining,
+      created_at: entry.created_at,
+      expires_at: entry.expires_at,
+      renewal_count: entry.renewal_count,
+      renewal_limit: entry.renewal_limit,
+      owner_reviewer_id: entry.owner_reviewer_id,
+      reason: entry.reason,
+      finding_ids: entry.finding_ids,
+    };
+  });
+
+  const filtered = expiredOnly
+    ? evaluated.filter((e) => e.is_expired)
+    : evaluated;
+
+  const summary = {
+    total: evaluated.length,
+    active: evaluated.filter((e) => e.computed_status === "approved").length,
+    expiring_soon: evaluated.filter((e) => e.is_expiring_soon).length,
+    expired: evaluated.filter((e) => e.is_expired).length,
+    revoked: evaluated.filter((e) => e.status === "revoked").length,
+    superseded: evaluated.filter((e) => e.status === "superseded").length,
+  };
+
+  return {
+    exceptions: filtered,
+    summary,
+  };
+}
+
+export function renewException(root, {
+  id,
+  until,
+  reviewer,
+  evidence = null,
+  note = null,
+  write = false,
+  refDate = null,
+} = {}) {
+  if (!id) throw new Error("--id <exception-id> is required to renew an exception");
+  if (!until) throw new Error("--until <YYYY-MM-DD> is required to renew an exception");
+  if (!reviewer) throw new Error("--reviewer <reviewer-id> is required to renew an exception");
+
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join("; ")}`);
+
+  const exceptions = registries.exceptions?.entries || [];
+  const entryIndex = exceptions.findIndex((e) => e.exception_id === id);
+  if (entryIndex === -1) throw new Error(`exception not found: ${id}`);
+
+  const entry = structuredClone(exceptions[entryIndex]);
+  if (entry.status === "revoked") throw new Error(`cannot renew revoked exception: ${id}`);
+  if (entry.status === "superseded") throw new Error(`cannot renew superseded exception: ${id}`);
+
+  // Verify reviewer authority
+  const reviewers = registries.reviewers?.entries || [];
+  const rev = reviewers.find((r) => r.reviewer_id === reviewer);
+  if (!rev || rev.status !== "active") {
+    throw new Error(`reviewer not found or inactive: ${reviewer}`);
+  }
+
+  // Check renewal limits
+  if (entry.renewal_count >= entry.renewal_limit) {
+    throw new Error(`exception ${id} has reached its renewal limit (${entry.renewal_limit})`);
+  }
+
+  const ref = parseRefDate(refDate);
+  const untilIso = until.includes("T") ? until : `${until}T23:59:59.999Z`;
+  const newExpiry = new Date(untilIso);
+
+  if (Number.isNaN(newExpiry.getTime())) {
+    throw new Error(`invalid renewal date format: ${until}`);
+  }
+  if (newExpiry <= ref) {
+    throw new Error("renewal date must be in the future relative to the reference date");
+  }
+  if (newExpiry <= new Date(entry.expires_at)) {
+    throw new Error("renewal date must extend past current expiration date");
+  }
+
+  // Check review policy limits if defined
+  const policies = registries.review_policies?.entries || [];
+  const policy = policies.find((p) => p.policy_id === entry.policy_id);
+  if (policy) {
+    if (entry.renewal_count + 1 > policy.max_renewals) {
+      throw new Error(`renewal would exceed policy max_renewals (${policy.max_renewals})`);
+    }
+    const durationDays = (newExpiry.getTime() - new Date(entry.created_at).getTime()) / 86400000;
+    if (durationDays > policy.max_exception_days) {
+      throw new Error(`renewal would exceed policy max_exception_days (${policy.max_exception_days} days)`);
+    }
+  }
+
+  entry.renewal_count += 1;
+  entry.expires_at = newExpiry.toISOString();
+
+  if (evidence && !entry.evidence_ids.includes(evidence)) {
+    entry.evidence_ids.push(evidence);
+    entry.evidence_hashes[evidence] = sha256(evidence);
+  }
+
+  entry.audit_history.push({
+    timestamp: new Date().toISOString(),
+    actor_reviewer_id: reviewer,
+    action: "renewed",
+    note: note || `Renewed until ${until} by ${reviewer}`,
+  });
+
+  const updatedEntries = [...exceptions];
+  updatedEntries[entryIndex] = entry;
+
+  const candidate = {
+    ...registries.exceptions,
+    updated: new Date().toISOString(),
+    entries: updatedEntries,
+  };
+
+  const check = validateAgainst("exception.schema.json", candidate);
+  if (!check.valid) {
+    throw new Error(`renewed exception violates schema: ${check.errors.join("; ")}`);
+  }
+
+  if (write) {
+    saveRegistry(root, "exceptions", candidate);
+  }
+
+  return {
+    exception_id: id,
+    expires_at: entry.expires_at,
+    renewal_count: entry.renewal_count,
+    renewal_limit: entry.renewal_limit,
+    written: write,
+  };
+}
+
+export function invalidateException(root, {
+  id,
+  reason,
+  reviewer,
+  write = false,
+} = {}) {
+  if (!id) throw new Error("--id <exception-id> is required to invalidate an exception");
+  if (!reason) throw new Error("--reason <text> is required to invalidate an exception");
+  if (!reviewer) throw new Error("--reviewer <reviewer-id> is required to record who revoked the exception");
+
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join("; ")}`);
+
+  const exceptions = registries.exceptions?.entries || [];
+  const entryIndex = exceptions.findIndex((e) => e.exception_id === id);
+  if (entryIndex === -1) throw new Error(`exception not found: ${id}`);
+
+  const entry = structuredClone(exceptions[entryIndex]);
+  if (entry.status === "revoked") throw new Error(`exception ${id} is already revoked`);
+
+  // Verify reviewer authority
+  const reviewers = registries.reviewers?.entries || [];
+  const rev = reviewers.find((r) => r.reviewer_id === reviewer);
+  if (!rev || rev.status !== "active") {
+    throw new Error(`reviewer not found or inactive: ${reviewer}`);
+  }
+
+  entry.status = "revoked";
+  entry.audit_history.push({
+    timestamp: new Date().toISOString(),
+    actor_reviewer_id: reviewer,
+    action: "revoked",
+    note: reason,
+  });
+
+  const updatedEntries = [...exceptions];
+  updatedEntries[entryIndex] = entry;
+
+  const candidate = {
+    ...registries.exceptions,
+    updated: new Date().toISOString(),
+    entries: updatedEntries,
+  };
+
+  const check = validateAgainst("exception.schema.json", candidate);
+  if (!check.valid) {
+    throw new Error(`revoked exception violates schema: ${check.errors.join("; ")}`);
+  }
+
+  if (write) {
+    saveRegistry(root, "exceptions", candidate);
+  }
+
+  return {
+    exception_id: id,
+    status: "revoked",
+    written: write,
+  };
+}

package/src/commands/experimentGuardrails.js

@@ -0,0 +1,213 @@
+import { loadRegistries } from '../registries/index.js';
+
+/**
+ * Experiment safety guardrails.
+ *
+ * Lifecycle statuses are mutually exclusive and explicitly defined:
+ *   planned     — declared, not yet receiving traffic decisions
+ *   running     — receiving traffic, sample below the computed requirement and
+ *                 window not elapsed; no reading may be taken
+ *   inconclusive— window and sample satisfied, effect not statistically
+ *                 significant; absence of evidence is not evidence of absence
+ *   validated   — full window, full sample, no SRM, effect significant at the
+ *                 declared alpha for the primary metric ONLY
+ *
+ * Guardrails fail closed: missing observations, missing windows, or missing
+ * registry context produce `blocked` findings, never a silent pass.
+ */
+
+const MIN_WINDOW_DAYS = 7;
+const SRM_ALPHA = 0.001; // standard SRM alert threshold
+
+/** Abramowitz–Stegun normal CDF. */
+function normalCdf(z) {
+  const t = 1 / (1 + 0.2316419 * Math.abs(z));
+  const d = 0.3989423 * Math.exp((-z * z) / 2);
+  const p = d * t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274))));
+  return z >= 0 ? 1 - p : p;
+}
+
+function chiSquare1dfP(chi2) {
+  return 2 * (1 - normalCdf(Math.sqrt(chi2)));
+}
+
+export function requiredSamplePerVariant(baselineRate, mde, alpha = 0.05, power = 0.8) {
+  const p1 = baselineRate;
+  const p2 = p1 * (1 + mde);
+  const pBar = (p1 + p2) / 2;
+  const zAlpha = alpha === 0.01 ? 2.576 : alpha === 0.10 ? 1.645 : 1.96;
+  const zBeta = power === 0.9 ? 1.282 : power === 0.95 ? 1.645 : 0.8416;
+  const numerator = Math.pow(zAlpha * Math.sqrt(2 * pBar * (1 - pBar)) + zBeta * Math.sqrt(p1 * (1 - p1) + p2 * (1 - p2)), 2);
+  const denominator = Math.pow(p2 - p1, 2);
+  return Math.ceil(numerator / denominator);
+}
+
+function windowDays(str) {
+  const m = String(str || '').match(/(\d+)\s*d/i);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Core guardrail evaluation for one experiment record plus optional observed
+ * data: { control, variant, baseline_rate, mde, days_running, revenue_claimed,
+ * other_active_experiments: [{experiment_id, target_page}] }.
+ */
+export function evaluateExperiment(experiment, observed = {}) {
+  const findings = [];
+  const add = (guardrail_id, severity, summary, required_input = null) =>
+    findings.push({ guardrail_id, severity, summary, ...(required_input ? { required_input } : {}) });
+
+  const status = experiment.status || 'draft';
+  const declaredSplit = (experiment.variants || []).length
+    ? (experiment.variants.find((v) => v.traffic_pct) || {}).traffic_pct || 50
+    : 50;
+  const window = windowDays(experiment.evaluation_window || experiment.minimum_observation_window);
+  const baseline = observed.baseline_rate ?? experiment.baseline_rate ?? null;
+  const mde = observed.mde ?? experiment.mde ?? null;
+
+  // Underpowered / required sample
+  let requiredN = null;
+  if (baseline > 0 && baseline < 1 && mde > 0) {
+    requiredN = requiredSamplePerVariant(baseline, mde);
+    if (window && window < MIN_WINDOW_DAYS) {
+      add('EXP-WINDOW-TOO-SHORT', 'high',
+        `Evaluation window ${window}d is shorter than the ${MIN_WINDOW_DAYS}d minimum; day-of-week seasonality produces high false-positive risk.`);
+    }
+  } else {
+    add('EXP-BASELINE-MISSING', 'blocked',
+      'No usable baseline_rate/mde declared; sample-size and power requirements cannot be established (fail closed).',
+      'required_input: baseline_rate (0-1) and mde (relative)');
+  }
+
+  // Stopping early
+  if (status === 'active' || status === 'observing') {
+    const daysRunning = observed.days_running ?? null;
+    if (window && daysRunning !== null && daysRunning < window) {
+      add('EXP-STOPPING-EARLY', 'high',
+        `Experiment has run ${daysRunning}d of the declared ${window}d window; stopping now invalidates the design. No interim reading is decision-grade.`);
+    }
+  }
+
+  // Sample-ratio mismatch
+  if (observed.control !== undefined && observed.variant !== undefined) {
+    const c = Number(observed.control);
+    const v = Number(observed.variant);
+    if (!Number.isFinite(c) || !Number.isFinite(v) || c < 0 || v < 0) {
+      add('EXP-OBSERVATIONS-INVALID', 'blocked', 'Observed counts must be non-negative numbers (fail closed).');
+    } else if (c + v >= 100) {
+      const total = c + v;
+      const share = declaredSplit / 100;
+      const expectedC = total * share;
+      const expectedV = total * (1 - share);
+      const chi2 = ((c - expectedC) ** 2) / expectedC + ((v - expectedV) ** 2) / expectedV;
+      const p = chiSquare1dfP(chi2);
+      if (p < SRM_ALPHA) {
+        add('EXP-SRM-DETECTED', 'critical',
+          `Sample-ratio mismatch: observed ${c}/${v} vs declared ${declaredSplit}/${100 - declaredSplit} split (chi-square p=${p.toExponential(2)}). Instrumentation or routing is broken; all readings from this experiment are untrustworthy until fixed.`);
+      }
+    } else {
+      add('EXP-SAMPLE-TOO-SMALL-FOR-SRM', 'blocked',
+        'Fewer than 100 total observations; SRM cannot be assessed yet (fail closed).');
+    }
+  } else if (status === 'active' || status === 'observing') {
+    add('EXP-OBSERVATIONS-MISSING', 'blocked',
+      'Active experiment without observed variant counts; sample ratio, power, and stopping state cannot be verified (fail closed).',
+      'required_input: observed control and variant assignment counts');
+  }
+
+  // Power status against observed sample
+  if (requiredN !== null && observed.control !== undefined && observed.variant !== undefined) {
+    const perVariant = Math.min(Number(observed.control), Number(observed.variant));
+    if (perVariant < requiredN) {
+      add('EXP-UNDERPOWERED', 'medium',
+        `Current sample (${perVariant}/variant) is below the ${requiredN}/variant requirement for ${Math.round((mde ?? 0) * 100)}% MDE at 80% power; any observed difference is not decision-grade.`);
+    }
+  }
+
+  // Revenue attribution without sufficient evidence
+  if (observed.revenue_claimed || /revenue|aov|arp/i.test(experiment.primary_metric || '')) {
+    const hasConcluded = status === 'concluded';
+    const hasSrm = findings.some((f) => f.guardrail_id === 'EXP-SRM-DETECTED');
+    if (hasSrm || !hasConcluded) {
+      add('EXP-REVENUE-UNSUPPORTED', 'high',
+        'Revenue attribution asserted without a concluded, SRM-clean experiment and verified conversion instrumentation; this remains a modeled estimate, not a measured outcome.');
+    }
+  }
+
+  // Contamination across pages / incompatible variants
+  const others = observed.other_active_experiments || [];
+  for (const other of others) {
+    if (other.target_page && experiment.target_page && other.target_page === experiment.target_page) {
+      add('EXP-CONTAMINATION', 'high',
+        `Experiment ${other.experiment_id} is also active on ${other.target_page}; overlapping experiments contaminate each other's readings.`);
+    }
+    const sharedVariants = (other.variant_ids || []).filter((id) => (experiment.variant_ids || []).includes(id));
+    if (sharedVariants.length) {
+      add('EXP-VARIANT-COLLISION', 'high',
+        `Variant id(s) ${sharedVariants.join(', ')} collide with active experiment ${other.experiment_id}; assignment is ambiguous.`);
+    }
+  }
+
+  // Lifecycle status (mutually exclusive, explicitly derived)
+  let lifecycle;
+  const blocking = findings.some((f) => f.severity === 'blocked' || f.severity === 'critical');
+  if (status === 'draft' || status === 'observing' || (!observed.control && !observed.variant && status !== 'active')) {
+    lifecycle = 'planned';
+  } else if (blocking) {
+    lifecycle = 'inconclusive';
+  } else {
+    const perVariant = Math.min(Number(observed.control ?? 0), Number(observed.variant ?? 0));
+    const withinWindow = window ? (observed.days_running ?? Infinity) >= window : false;
+    const sampleMet = requiredN !== null ? perVariant >= requiredN : false;
+    const significant = typeof observed.p_value === 'number' ? observed.p_value < (observed.alpha ?? 0.05) : false;
+    if (withinWindow && sampleMet && significant) lifecycle = 'validated';
+    else if (withinWindow && sampleMet) lifecycle = 'inconclusive';
+    else lifecycle = 'running';
+  }
+
+  const definitions = {
+    planned: 'declared, not yet receiving traffic; no reading exists',
+    running: 'receiving traffic; sample/window incomplete; interim readings are not decision-grade',
+    inconclusive: 'window and sample satisfied but the effect is not statistically significant, or a blocking guardrail fired; absence of evidence is not evidence of absence',
+    validated: 'full window, sufficient sample, no SRM, primary metric significant at declared alpha — statistically validated for the primary metric only, never a conversion or revenue guarantee',
+  };
+
+  return {
+    experiment_id: experiment.experiment_id,
+    registry_status: status,
+    lifecycle,
+    lifecycle_definition: definitions[lifecycle],
+    required_sample_per_variant: requiredN,
+    declared_traffic_split: `${declaredSplit}/${100 - declaredSplit}`,
+    guardrail_count: findings.length,
+    findings,
+    lifecycle_definitions: definitions,
+    note: 'lifecycle labels describe statistical state only; Citable does not guarantee conversion, ranking, or citation outcomes',
+  };
+}
+
+/**
+ * `citable check experiment <id> [--observed-control N --observed-variant N]`
+ */
+export async function checkExperiment(root, options = {}) {
+  const { registries, problems } = loadRegistries(root);
+  const entries = registries?.experiments?.entries || [];
+  const id = options.experimentId || options.experiment_id;
+  if (!id) throw new Error('usage: citable check experiment <experiment-id> [--observed-control N --observed-variant N --days-running N]');
+  const experiment = entries.find((e) => e.experiment_id === id);
+  if (!experiment) {
+    throw new Error(`experiment "${id}" not found in experiments.yaml. Available: ${entries.map((e) => e.experiment_id).join(', ') || 'none'}`);
+  }
+  const observed = {
+    control: options.observedControl ?? options.observed_control,
+    variant: options.observedVariant ?? options.observed_variant,
+    days_running: options.daysRunning ?? options.days_running,
+    baseline_rate: options.baselineRate ? Number(options.baselineRate) : undefined,
+    mde: options.mde ? Number(options.mde) : undefined,
+    p_value: options.pValue ? Number(options.pValue) : undefined,
+    revenue_claimed: options.revenueClaimed ?? options.revenue_claimed ?? false,
+    other_active_experiments: entries.filter((e) => e.status === 'active' && e.experiment_id !== id),
+  };
+  const result = evaluateExperiment(experiment, observed);
+  return { ...result, registry_problems: problems };
+}