@nebulacomponents/citable 1.15.0 → 1.16.0

package/src/commands/edgeRules.js

@@ -0,0 +1,120 @@
+import path from "node:path";
+import { loadRegistries } from "../registries/index.js";
+
+/**
+ * Generates edge rules (redirects, Cloudflare WAF expressions, or Worker scripts)
+ * from Citable registries.
+ */
+export async function exportEdgeRules(root, { format = "cloudflare-redirects", output = null } = {}) {
+  const { registries } = loadRegistries(root);
+  const crawlers = registries?.crawlers?.entries || [];
+  const pages = registries?.pages?.entries || [];
+
+  let content = "";
+
+  if (format === "cloudflare-redirects") {
+    const lines = ["# Cloudflare Pages / Edge _redirects generated by Citable", ""];
+    for (const page of pages) {
+      if (page.redirect_target) {
+        lines.push(`${page.path || page.url} ${page.redirect_target} 301`);
+      }
+    }
+    if (lines.length <= 2) {
+      lines.push("# No explicit redirects found in pages.yaml");
+    }
+    content = lines.join("\n") + "\n";
+  } else if (format === "cloudflare-waf") {
+    // Generate Cloudflare Firewall Expression for blocked crawler bots
+    const blockedBots = crawlers.filter((c) => c.status === "blocked" || c.policy === "disallow" || c.policy === "block");
+    if (blockedBots.length > 0) {
+      const expressions = blockedBots.map((c) => `(http.user_agent contains "${c.user_agent || c.crawler_id}")`);
+      content = `# Cloudflare Custom WAF Expression\nAction: Block\nExpression:\n${expressions.join(" or ")}\n`;
+    } else {
+      content = "# Cloudflare Custom WAF Expression\n# No crawlers marked as blocked in crawlers.yaml\n";
+    }
+  } else if (format === "cloudflare-worker") {
+    content = `// Cloudflare Worker generated by Citable Edge Adapter
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+
+    // Dynamic edge routing for /llms.txt
+    if (url.pathname === "/llms.txt") {
+      return fetch(new URL("/resources/citable/llms.txt", url.origin));
+    }
+
+    const response = await fetch(request);
+
+    // Apply security and canonical headers if missing
+    const newHeaders = new Headers(response.headers);
+    if (!newHeaders.has("X-Content-Type-Options")) {
+      newHeaders.set("X-Content-Type-Options", "nosniff");
+    }
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: newHeaders,
+    });
+  },
+};\n`;
+  } else {
+    throw new Error(`unsupported edge format "${format}". Supported: cloudflare-redirects, cloudflare-waf, cloudflare-worker`);
+  }
+
+  if (output) {
+    fs.writeFileSync(path.resolve(root, output), content, "utf8");
+  }
+
+  return {
+    format,
+    output_path: output,
+    content,
+    rules_count: content.split("\n").filter((l) => l && !l.startsWith("#")).length,
+  };
+}
+
+/**
+ * Tests edge routing and header preservation for Cloudflare-backed properties.
+ */
+export async function testEdgeRules(root, { provider = "cloudflare", baseUrl = "https://example.test", headers = {} } = {}) {
+  const checks = [];
+
+  // Check 1: Cloudflare Ray ID header expectation
+  const cfRayPresent = Boolean(headers["cf-ray"] || headers["CF-RAY"]);
+  checks.push({
+    check_id: "EDGE-CF-RAY",
+    name: "Cloudflare Edge Ray ID Header",
+    passed: provider === "cloudflare" ? cfRayPresent : true,
+    detail: cfRayPresent ? `Observed ${headers["cf-ray"] || headers["CF-RAY"]}` : "cf-ray header absent (expected behind Cloudflare edge)",
+  });
+
+  // Check 2: Content Type Options security header
+  const nosniff = (headers["x-content-type-options"] || "").toLowerCase() === "nosniff";
+  checks.push({
+    check_id: "EDGE-SEC-NOSNIFF",
+    name: "X-Content-Type-Options Header",
+    passed: nosniff,
+    detail: nosniff ? "nosniff header present" : "x-content-type-options: nosniff missing from edge response",
+  });
+
+  // Check 3: Bot Management / Challenge detection
+  const isChallenge = Boolean(headers["cf-mitigated"] === "challenge" || (headers["server"] || "").includes("cloudflare-challenge"));
+  checks.push({
+    check_id: "EDGE-BOT-CHALLENGE",
+    name: "Edge Bot Mitigation Status",
+    passed: !isChallenge,
+    detail: isChallenge ? "Edge presented CAPTCHA / Managed Challenge to probe" : "Clean pass-through without bot mitigation challenge",
+  });
+
+  const allPassed = checks.every((c) => c.passed);
+
+  return {
+    provider,
+    base_url: baseUrl,
+    status: allPassed ? "healthy" : "remediation_needed",
+    total_checks: checks.length,
+    passed_checks: checks.filter((c) => c.passed).length,
+    checks,
+  };
+}

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/fleet.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+import fs from "node:fs";
+import { loadRegistries, contextDir } from "../registries/index.js";
+import { audit } from "./audit.js";
+
+/**
+ * Returns summary of all properties defined in the fleet registry.
+ */
+export async function fleetSummary(root) {
+  const { registries } = loadRegistries(root);
+  const fleet = registries?.fleet?.entries || [];
+
+  const byEnv = {};
+  const byOwner = {};
+  for (const p of fleet) {
+    byEnv[p.environment] = (byEnv[p.environment] || 0) + 1;
+    if (p.owner) byOwner[p.owner] = (byOwner[p.owner] || 0) + 1;
+  }
+
+  return {
+    total_properties: fleet.length,
+    active_properties: fleet.filter((p) => p.status === "active").length,
+    by_environment: byEnv,
+    by_owner: byOwner,
+    properties: fleet.map((p) => ({
+      property_id: p.property_id,
+      name: p.name,
+      environment: p.environment,
+      primary_domain: p.primary_domain,
+      status: p.status,
+      owner: p.owner,
+    })),
+  };
+}
+
+/**
+ * Runs fleet-wide audit across registered fleet properties.
+ */
+export async function fleetAudit(root, { propertyId = null, environment = null, scope = null } = {}) {
+  const { registries } = loadRegistries(root);
+  const fleet = registries?.fleet?.entries || [];
+
+  if (fleet.length === 0) {
+    throw new Error("no fleet properties declared in registries (expected .citable/fleet.yaml)");
+  }
+
+  let targets = fleet.filter((p) => p.status === "active");
+  if (propertyId) {
+    targets = targets.filter((p) => p.property_id === propertyId || p.primary_domain === propertyId);
+    if (targets.length === 0) throw new Error(`property "${propertyId}" not found in active fleet`);
+  }
+  if (environment) {
+    targets = targets.filter((p) => p.environment === environment);
+  }
+
+  const results = [];
+  for (const prop of targets) {
+    const propTarget = prop.built_output_dir && fs.existsSync(path.resolve(root, prop.built_output_dir))
+      ? path.resolve(root, prop.built_output_dir)
+      : null;
+
+    let auditRes = null;
+    let error = null;
+
+    try {
+      if (propTarget || prop.base_url) {
+        auditRes = await audit(root, {
+          target: propTarget || prop.base_url,
+          baseUrl: prop.base_url,
+          scope,
+        });
+      }
+    } catch (err) {
+      error = err.message;
+    }
+
+    results.push({
+      property_id: prop.property_id,
+      name: prop.name,
+      primary_domain: prop.primary_domain,
+      environment: prop.environment,
+      status: auditRes ? "audited" : (error ? "error" : "skipped"),
+      findings_count: auditRes?.findings?.length ?? 0,
+      critical_count: auditRes?.findings?.filter((f) => f.severity === "critical").length ?? 0,
+      high_count: auditRes?.findings?.filter((f) => f.severity === "high").length ?? 0,
+      medium_count: auditRes?.findings?.filter((f) => f.severity === "medium").length ?? 0,
+      low_count: auditRes?.findings?.filter((f) => f.severity === "low").length ?? 0,
+      error,
+    });
+  }
+
+  const totalFindings = results.reduce((acc, r) => acc + r.findings_count, 0);
+  const totalCritical = results.reduce((acc, r) => acc + r.critical_count, 0);
+  const totalHigh = results.reduce((acc, r) => acc + r.high_count, 0);
+
+  return {
+    fleet_size: targets.length,
+    total_findings: totalFindings,
+    total_critical: totalCritical,
+    total_high: totalHigh,
+    fleet_health: totalCritical === 0 && totalHigh === 0 ? "healthy" : (totalCritical > 0 ? "critical" : "needs_attention"),
+    properties: results,
+  };
+}

package/src/commands/generateLlmsTxt.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRegistries } from '../registries/index.js';
+
+/**
+ * Build spec-compliant /llms.txt and /llms-full.txt from Citable registries.
+ * Adheres to https://llmstxt.org/ standard:
+ * - H1 title with brand/project name
+ * - Blockquote summary
+ * - Markdown links with descriptions
+ * - Optional links section pointing to /llms-full.txt
+ */
+export function buildLlmsTxt(root, options = {}) {
+  const { registries } = loadRegistries(root);
+  const siteConfig = registries.config?.site || {};
+  const siteName = siteConfig.name || registries.entities?.entries?.[0]?.canonical_name || 'Project Documentation';
+  const siteUrl = options.siteUrl || siteConfig.base_url || 'https://example.test';
+  const description = siteConfig.description || registries.entities?.entries?.[0]?.description || 'Evidence-backed documentation and verified specifications.';
+
+  const pages = (registries.pages?.entries || []).filter((p) => !p.noindex);
+  const claims = (registries.claims?.entries || []).filter((c) => ['verified', 'verified_narrowed', 'stated'].includes(c.status));
+
+  // Build llms.txt
+  const lines = [];
+  lines.push(`# ${siteName}`);
+  lines.push('');
+  lines.push(`> ${description}`);
+  lines.push('');
+
+  if (pages.length > 0) {
+    lines.push('## Documentation & Key Pages');
+    lines.push('');
+    for (const p of pages) {
+      const url = p.url ? p.url : new URL(p.path || '/', siteUrl).href;
+      const title = p.title || p.page_id || 'Untitled page';
+      const desc = p.description ? `: ${p.description}` : '';
+      lines.push(`- [${title}](${url})${desc}`);
+    }
+    lines.push('');
+  }
+
+  if (claims.length > 0) {
+    lines.push('## Verified Capabilities & Claims');
+    lines.push('');
+    for (const c of claims) {
+      const target = c.publication_surfaces?.[0] || siteUrl;
+      const fullUrl = target.startsWith('http') ? target : new URL(target, siteUrl).href;
+      lines.push(`- [${c.claim}](${fullUrl}): Verified claim (${c.claim_type})`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Optional');
+  lines.push('');
+  const fullUrl = new URL('/llms-full.txt', siteUrl).href;
+  lines.push(`- [Full Content Directory](${fullUrl}): Complete uncompressed documentation representation`);
+  lines.push('');
+
+  const llmsTxt = lines.join('\n');
+
+  // Build llms-full.txt
+  const fullLines = [];
+  fullLines.push(`# ${siteName} (Full Text Specification)`);
+  fullLines.push('');
+  fullLines.push(`> Complete textual representation of ${siteName} for generative engines and autonomous agents.`);
+  fullLines.push('');
+  for (const p of pages) {
+    const url = p.url ? p.url : new URL(p.path || '/', siteUrl).href;
+    fullLines.push(`### ${p.title || p.page_id}`);
+    fullLines.push(`- URL: ${url}`);
+    if (p.description) fullLines.push(`- Description: ${p.description}`);
+    if (p.published_claims?.length) fullLines.push(`- Published Claims: ${p.published_claims.join(', ')}`);
+    fullLines.push('');
+  }
+  const llmsFullTxt = fullLines.join('\n');
+
+  return {
+    siteName,
+    siteUrl,
+    llmsTxt,
+    llmsFullTxt,
+    pageCount: pages.length,
+    claimCount: claims.length,
+  };
+}
+
+export function generateLlmsTxt(root, options = {}) {
+  const built = buildLlmsTxt(root, options);
+  const outDir = options.output || root;
+
+  let written = false;
+  let llmsTxtPath = null;
+  let llmsFullTxtPath = null;
+
+  if (options.write) {
+    fs.mkdirSync(outDir, { recursive: true });
+    llmsTxtPath = path.join(outDir, 'llms.txt');
+    llmsFullTxtPath = path.join(outDir, 'llms-full.txt');
+    fs.writeFileSync(llmsTxtPath, built.llmsTxt, 'utf8');
+    fs.writeFileSync(llmsFullTxtPath, built.llmsFullTxt, 'utf8');
+    written = true;
+  }
+
+  return {
+    ...built,
+    written,
+    outputDir: outDir,
+    llmsTxtPath,
+    llmsFullTxtPath,
+  };
+}

package/src/commands/inspectAeo.js

@@ -0,0 +1,74 @@
+import { buildContext } from './context.js';
+import { registryPageFor, safePath } from '../detectors/framework.js';
+import { selectDetectors } from '../detectors/index.js';
+import { runDetectors } from '../detectors/framework.js';
+
+/**
+ * `citable inspect aeo <page>` — evaluate page answer extractability, question density,
+ * direct lead conciseness, grounded quantitative metrics, and synthesis readiness.
+ */
+export async function inspectAeo(root, pageRef, { target, baseUrl, refDate } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) throw new Error('inspect aeo requires a site target (built output directory or URL)');
+  const wanted = safePath(pageRef, ctx.site.baseUrl);
+  const page = ctx.site.pages.find((p) => safePath(p.url) === wanted || p.sourceFile === pageRef);
+  if (!page) throw new Error(`page not found in audited output: ${pageRef}`);
+
+  const reg = registryPageFor(ctx, page);
+
+  // Evaluate findings for this single page across ANS namespace
+  const single = { ...ctx, site: { ...ctx.site, pages: [page] } };
+  const { findings } = runDetectors(selectDetectors({ namespaces: ['ANS'] }), single);
+  const aeoFindings = findings.filter((f) => f.subject.identifier === page.url || f.subject.url === page.url);
+
+  // Analyze question headings and answer leads
+  const QUESTION_RX = /^(?:how|what|why|when|where|who|can|is|does|which|should)\b|\?$/i;
+  const questionHeadings = (page.headings || []).filter((h) => QUESTION_RX.test(h.text.trim()));
+
+  // Definitional copula check
+  const COPULA_RX = /\b(?:is|are|refers\s+to|denotes|represents|means)\b/i;
+  const firstParagraph = (page.paragraphs && page.paragraphs[0]) || '';
+  const hasCopularDefinition = COPULA_RX.test(firstParagraph.slice(0, 140));
+
+  // Structured elements
+  const tablesCount = (page.tables || []).length;
+  const listsCount = (page.orderedLists || []).length;
+
+  // Executive summary
+  const SUMMARY_RX = /\b(?:executive\s+summary|key\s+takeaways?|summary|overview|at\s+a\s+glance|tl;?dr|quick\s+summary|highlights?)\b/i;
+  const hasExecutiveSummary = (page.headings || []).some((h) => SUMMARY_RX.test(h.text));
+
+  // Determine synthesis posture
+  let extractabilityStatus = 'optimal';
+  if (aeoFindings.some((f) => f.classification.severity === 'high')) {
+    extractabilityStatus = 'obstructed';
+  } else if (aeoFindings.length >= 2) {
+    extractabilityStatus = 'suboptimal';
+  } else if (aeoFindings.length === 1) {
+    extractabilityStatus = 'minor_improvements';
+  }
+
+  return {
+    url: page.url,
+    sourceFile: page.sourceFile,
+    status: page.status,
+    page_type: reg?.page_type ?? null,
+    word_count: page.rawVisibleWordCount || page.wordCount || 0,
+    extractability_status: extractabilityStatus,
+    headings: {
+      total: (page.headings || []).length,
+      questions: questionHeadings.map((h) => ({ level: h.level, text: h.text })),
+    },
+    answer_structure: {
+      has_copular_definition: hasCopularDefinition,
+      has_executive_summary: hasExecutiveSummary,
+      tables_count: tablesCount,
+      ordered_lists_count: listsCount,
+    },
+    findings: aeoFindings.map((f) => ({
+      detector_id: f.detector_id,
+      severity: f.classification.severity,
+      summary: f.observation.summary,
+    })),
+  };
+}