@nebulacomponents/citable 1.1.0 → 1.3.0

package/src/commands/selfUpgrade.js

@@ -0,0 +1,155 @@
+/**
+ * self-upgrade command
+ *
+ * Checks npm for the latest @nebulacomponents/citable version and upgrades
+ * the running npx cache if a newer version is available.
+ *
+ * Usage:
+ *   npx @nebulacomponents/citable self-upgrade
+ *   npx @nebulacomponents/citable self-upgrade --check   (check only, no upgrade)
+ *   npx @nebulacomponents/citable self-upgrade --json    (machine-readable output)
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const PACKAGE_NAME = '@nebulacomponents/citable';
+const REGISTRY = 'https://registry.npmjs.org';
+const FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * Fetch the latest published version from the npm registry.
+ * Uses Node's built-in fetch (Node 22+); no extra dependencies.
+ *
+ * @returns {Promise<string>} latest semver string
+ */
+async function fetchLatestVersion() {
+  const url = `${REGISTRY}/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      headers: { Accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) throw new Error(`registry returned ${res.status}`);
+    const data = await res.json();
+    if (!data.version) throw new Error('no version field in registry response');
+    return data.version;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Compare two semver strings. Returns:
+ *   1  if a > b
+ *   0  if a === b
+ *  -1  if a < b
+ */
+function compareSemver(a, b) {
+  const parse = (v) => v.replace(/^v/, '').split('.').map(Number);
+  const [aMaj, aMin, aPatch] = parse(a);
+  const [bMaj, bMin, bPatch] = parse(b);
+  if (aMaj !== bMaj) return aMaj > bMaj ? 1 : -1;
+  if (aMin !== bMin) return aMin > bMin ? 1 : -1;
+  if (aPatch !== bPatch) return aPatch > bPatch ? 1 : -1;
+  return 0;
+}
+
+/**
+ * Re-execute the current command via npx at the new version.
+ * Used to trigger the npx cache refresh as a side-effect.
+ */
+function triggerNpxRefresh(latestVersion) {
+  // npx --yes ensures no prompt; @version pins to latest
+  const result = spawnSync(
+    'npx',
+    ['--yes', `${PACKAGE_NAME}@${latestVersion}`, '--version'],
+    { stdio: 'pipe', timeout: 60_000 },
+  );
+  return result.status === 0;
+}
+
+export async function selfUpgradeCommand(args) {
+  const checkOnly = args.includes('--check');
+  const jsonOutput = args.includes('--json');
+
+  // Resolve current version from our own package.json
+  let currentVersion;
+  try {
+    const req = createRequire(import.meta.url);
+    const pkgPath = path.resolve(fileURLToPath(import.meta.url), '../../../package.json');
+    currentVersion = req(pkgPath).version;
+  } catch {
+    const err = { ok: false, error: 'could not read local package.json version' };
+    if (jsonOutput) return JSON.stringify(err, null, 2);
+    return `error: ${err.error}`;
+  }
+
+  // Fetch latest from registry
+  let latestVersion;
+  try {
+    latestVersion = await fetchLatestVersion();
+  } catch (err) {
+    const result = { ok: false, current: currentVersion, error: `registry fetch failed: ${err.message}` };
+    if (jsonOutput) return JSON.stringify(result, null, 2);
+    return `error: ${result.error}\nCurrent version: ${currentVersion}`;
+  }
+
+  const cmp = compareSemver(latestVersion, currentVersion);
+
+  if (cmp <= 0) {
+    // Already current or ahead (local dev)
+    const result = { ok: true, current: currentVersion, latest: latestVersion, status: 'current' };
+    if (jsonOutput) return JSON.stringify(result, null, 2);
+    return `citable ${currentVersion} is already up to date (latest: ${latestVersion})`;
+  }
+
+  // Update available
+  if (checkOnly) {
+    const result = { ok: true, current: currentVersion, latest: latestVersion, status: 'update-available' };
+    if (jsonOutput) return JSON.stringify(result, null, 2);
+    return [
+      `Update available: ${currentVersion} → ${latestVersion}`,
+      `Run: npx ${PACKAGE_NAME}@latest self-upgrade`,
+    ].join('\n');
+  }
+
+  // Perform upgrade: warm the npx cache at the new version
+  const refreshed = triggerNpxRefresh(latestVersion);
+
+  const result = {
+    ok: refreshed,
+    current: currentVersion,
+    latest: latestVersion,
+    status: refreshed ? 'upgraded' : 'upgrade-failed',
+  };
+
+  if (jsonOutput) return JSON.stringify(result, null, 2);
+
+  if (refreshed) {
+    return [
+      `citable upgraded: ${currentVersion} → ${latestVersion}`,
+      `Run your next command with:  npx ${PACKAGE_NAME}@latest <command>`,
+      `Or pin globally:             npm install -g ${PACKAGE_NAME}@latest`,
+    ].join('\n');
+  }
+
+  return [
+    `Upgrade attempt failed (npx returned non-zero).`,
+    `Current: ${currentVersion}  Latest: ${latestVersion}`,
+    `Manual upgrade:  npx ${PACKAGE_NAME}@${latestVersion} <command>`,
+  ].join('\n');
+}
+
+export function selfUpgradeExitCode(output) {
+  try {
+    const parsed = JSON.parse(output);
+    return parsed.ok === false ? 1 : 0;
+  } catch {
+    return /^(error:|Upgrade attempt failed)/.test(output) ? 1 : 0;
+  }
+}

package/src/commands/substantiate.js

@@ -1,5 +1,5 @@
 import { loadRegistries, saveRegistry, diffRegistries } from '../registries/index.js';
-import { isPastDate, nowIso } from '../shared/io.js';
+import { isPastDate, nowIso, parseRefDate } from '../shared/io.js';
 
 const REGULATED = new Set(['legal_regulatory', 'security', 'commercial']);
 
@@ -17,7 +17,7 @@ const REGULATED = new Set(['legal_regulatory', 'security', 'commercial']);
  */
 export function substantiate(root, { write = false, refDate } = {}) {
   const { registries, problems } = loadRegistries(root);
-  const ref = refDate ? new Date(refDate) : new Date();
+  const ref = parseRefDate(refDate);
   const evidence = new Map(registries.evidence.entries.map((e) => [e.evidence_id, e]));
   const before = JSON.parse(JSON.stringify(registries.claims));
   const assessments = [];

package/src/crawler/fetch.js

@@ -1,63 +1,120 @@
-/**
- * Fetch a URL capturing status, headers, body, and redirect chain.
- * Used only when the operator supplies a deployed target and fetching is permitted.
- */
-export async function fetchUrl(url, { userAgent = 'CitableAudit/0.1', maxRedirects = 10, timeoutMs = 20000, maxRetries = 3, retryDelayMs = 1000 } = {}) {
+import dns from 'node:dns';
+import net from 'node:net';
+
+const blockedAddresses = new net.BlockList();
+for (const [network, prefix] of [
+  ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
+  ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.168.0.0', 16], ['224.0.0.0', 4],
+]) blockedAddresses.addSubnet(network, prefix, 'ipv4');
+for (const [network, prefix] of [['::', 128], ['::1', 128], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8]]) {
+  blockedAddresses.addSubnet(network, prefix, 'ipv6');
+}
+
+function isBlockedAddress(address) {
+  const family = net.isIP(address);
+  if (!family) return true;
+  if (family === 6 && address.toLowerCase().startsWith('::ffff:')) {
+    return blockedAddresses.check(address.slice(7), 'ipv4');
+  }
+  return blockedAddresses.check(address, family === 4 ? 'ipv4' : 'ipv6');
+}
+
+async function validateDestination(url, lookup) {
+  const parsed = new URL(url);
+  if (!['http:', 'https:'].includes(parsed.protocol)) throw new Error(`unsupported URL protocol: ${parsed.protocol}`);
+  if (parsed.username || parsed.password) throw new Error('URL credentials are not permitted');
+  const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+  const literalFamily = net.isIP(hostname);
+  const addresses = literalFamily
+    ? [{ address: hostname, family: literalFamily }]
+    : await lookup(hostname, { all: true, verbatim: true });
+  if (!addresses.length || addresses.some(({ address }) => isBlockedAddress(address))) {
+    throw new Error(`refusing private, loopback, or non-public destination: ${hostname}`);
+  }
+  return parsed;
+}
+
+async function readBodyLimited(res, maxBodyBytes) {
+  const declared = Number(res.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > maxBodyBytes) {
+    throw new Error(`response body exceeds ${maxBodyBytes} bytes`);
+  }
+  if (!res.body) return '';
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBodyBytes) throw new Error(`response body exceeds ${maxBodyBytes} bytes`);
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  return new TextDecoder().decode(bytes);
+}
+
+/** Fetch a public URL with bounded retries, redirects, time, and response size. */
+export async function fetchUrl(url, {
+  userAgent = 'CitableAudit/0.1', maxRedirects = 10, timeoutMs = 20000,
+  maxRetries = 3, retryDelayMs = 1000, maxBodyBytes = 5 * 1024 * 1024,
+  fetchImpl = globalThis.fetch, lookup = dns.promises.lookup,
+} = {}) {
+  const requested = await validateDestination(url, lookup);
+  const allowedOrigin = requested.origin;
   const chain = [];
-  let current = url;
-  
-  for (let i = 0; i <= maxRedirects; i++) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let current = requested.href;
+
+  for (let redirects = 0; redirects <= maxRedirects; redirects += 1) {
+    await validateDestination(current, lookup);
     let res;
     let lastError;
-    
-    // Retry loop for transient failures
-    for (let attempt = 0; attempt < maxRetries; attempt++) {
+    for (let attempt = 0; attempt < Math.max(1, maxRetries); attempt += 1) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(new Error(`request timeout after ${timeoutMs}ms`)), timeoutMs);
       try {
-        res = await fetch(current, {
+        res = await fetchImpl(current, {
           redirect: 'manual',
           headers: { 'user-agent': userAgent },
           signal: controller.signal,
         });
-        lastError = null;
-        break; // Success, break retry loop
+        if (res.status < 500 || attempt === Math.max(1, maxRetries) - 1) {
+          lastError = null;
+          break;
+        }
+        await res.body?.cancel();
+        lastError = new Error(`server returned ${res.status}`);
       } catch (err) {
         lastError = err;
-        // Only retry on network errors or 5xx, not on 4xx
-        if (err.name === 'AbortError') {
-          throw err; // Timeout, don't retry
-        }
-        // Exponential backoff with jitter
-        const delay = retryDelayMs * Math.pow(2, attempt) + Math.random() * retryDelayMs;
-        if (attempt < maxRetries - 1) {
-          await new Promise(resolve => setTimeout(resolve, delay));
-        }
+        if (controller.signal.aborted) throw controller.signal.reason ?? err;
       } finally {
         clearTimeout(timer);
       }
+      if (attempt < Math.max(1, maxRetries) - 1) {
+        const delay = retryDelayMs * (2 ** attempt) + Math.random() * retryDelayMs;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
     }
-    
-    if (lastError) {
-      throw lastError;
-    }
-    
+    if (lastError) throw lastError;
+
     const headers = Object.fromEntries(res.headers.entries());
     if (res.status >= 300 && res.status < 400 && headers.location) {
+      if (redirects === maxRedirects) break;
+      const next = new URL(headers.location, current);
+      if (next.origin !== allowedOrigin) throw new Error(`redirect leaves audited origin: ${next.href}`);
+      await validateDestination(next.href, lookup);
       chain.push({ url: current, status: res.status, location: headers.location });
-      current = new URL(headers.location, current).href;
-      continue;
-    }
-    
-    // Retry on 5xx with one less attempt (already used retry loop above)
-    if (res.status >= 500 && i < maxRedirects) {
-      // Treat 5xx as transient, add to chain and retry same URL
-      chain.push({ url: current, status: res.status, location: null, error: 'server error' });
-      await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+      current = next.href;
+      await res.body?.cancel();
       continue;
     }
-    
-    const body = await res.text();
+    const body = await readBodyLimited(res, maxBodyBytes);
     return { url: current, requestedUrl: url, status: res.status, headers, body, redirectChain: chain };
   }
   throw new Error(`redirect chain exceeded ${maxRedirects} hops for ${url}`);

package/src/detectors/ans.js

@@ -216,4 +216,47 @@ D.push(defineDetector({
   },
 }));
 
+D.push(defineDetector({
+  id: 'ANS-009', name: 'Answer-target page has no prompt coverage', namespace: 'ANS',
+  description: 'An answer-bearing page is intended for discovery but is not mapped to any prompt in the governed prompt corpus.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: true, requires: ['site', 'registries'],
+  impact: { citation: 'high', representation: 'medium', maintainability: 'medium' },
+  applicable_requirement: 'AEO §1 governed question corpus and §13 page acceptance; GEO §1 prompt registry and §19 page acceptance',
+  remediation: 'Map the page to at least one reviewed prompt via target_prompts, then verify that the page answers the prompt without broadening registered claims.',
+  verification: 'Page registry target_prompts is non-empty and every referenced prompt exists.',
+  check(ctx) {
+    const answerTypes = new Set(['definition', 'problem', 'solution', 'comparison', 'recommendation', 'implementation', 'evidence', 'faq', 'glossary', 'documentation', 'article', 'product']);
+    return indexTargets(ctx).flatMap((p) => {
+      const reg = registryPageFor(ctx, p);
+      if (!reg || !answerTypes.has(reg.page_type) || (reg.target_prompts || []).length > 0) return [];
+      return [{
+        subject: pageSubject(p),
+        summary: `${reg.page_type} page ${reg.page_id} has no governed target prompt`,
+        evidence: ['target_prompts is empty or absent'],
+      }];
+    });
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ANS-010', name: 'Published claims lack page evidence mapping', namespace: 'ANS',
+  description: 'A page publishes governed claims but records no page-level evidence references, preventing evidence-adjacency review.',
+  discipline: ['aeo', 'geo'], severity: 'high', deterministic: true, requires: ['site', 'registries'],
+  impact: { citation: 'high', representation: 'high', legal: 'medium', reputational: 'medium' },
+  applicable_requirement: 'AEO §4 evidence adjacency and atomic claims; GEO §4 claim registry and §5 claim-evidence proximity',
+  remediation: 'Map supporting evidence in evidence_references and place the relevant source or methodology adjacent to each material claim.',
+  verification: 'Page registry contains evidence_references and claim/evidence referential integrity passes.',
+  check(ctx) {
+    return indexTargets(ctx).flatMap((p) => {
+      const reg = registryPageFor(ctx, p);
+      if (!reg || !(reg.published_claims || []).length || (reg.evidence_references || []).length) return [];
+      return [{
+        subject: pageSubject(p),
+        summary: `Page ${reg.page_id} publishes claims without page-level evidence references`,
+        evidence: [`published_claims: ${reg.published_claims.join(', ')}`, 'evidence_references is empty or absent'],
+      }];
+    });
+  },
+}));
+
 export default D;

package/src/detectors/geoReco.js

@@ -175,6 +175,54 @@ D.push(defineDetector({
   },
 }));
 
+D.push(defineDetector({
+  id: 'GEO-005', name: 'Generative target lacks primary entity mapping', namespace: 'GEO',
+  description: 'A page intended to define, compare, categorize, or recommend entities does not declare its primary entities.',
+  discipline: ['geo', 'aeo'], severity: 'high', deterministic: true, requires: ['site', 'registries'],
+  impact: { representation: 'high', citation: 'medium', maintainability: 'medium' },
+  applicable_requirement: 'GEO §3 canonical entity registry and §19 page acceptance; AEO §3 entity architecture',
+  remediation: 'Map the page to canonical entity IDs in primary_entities and ensure visible names and structured-data @ids agree.',
+  verification: 'Page primary_entities is non-empty, referential integrity passes, and ENTITY detectors report no conflict.',
+  check(ctx) {
+    const entityTypes = new Set(['definition', 'product', 'service', 'comparison', 'recommendation', 'category', 'about']);
+    return indexTargets(ctx).flatMap((p) => {
+      const reg = registryPageFor(ctx, p);
+      if (!reg || !entityTypes.has(reg.page_type) || (reg.primary_entities || []).length) return [];
+      return [{
+        subject: pageSubject(p),
+        summary: `${reg.page_type} page ${reg.page_id} has no primary entity mapping`,
+        evidence: ['primary_entities is empty or absent'],
+      }];
+    });
+  },
+}));
+
+D.push(defineDetector({
+  id: 'GEO-006', name: 'Active prompt lacks evaluation brief', namespace: 'GEO',
+  description: 'An active prompt lacks the expected answer components, desired outcome, risk classification, or accountable owner needed for reproducible GEO evaluation.',
+  discipline: ['geo', 'aeo'], severity: 'medium', deterministic: true, requires: ['registries'],
+  impact: { representation: 'high', citation: 'medium', maintainability: 'high' },
+  applicable_requirement: 'GEO §1 prompt registry, §12 repeatable measurement, and §15 governance; AEO §1 question corpus',
+  remediation: 'Complete expected_answer_components, desired_outcome, risk_classification, and owner before using the prompt as an optimization target.',
+  verification: 'Every active prompt has a complete evaluation brief and passes registry validation.',
+  check(ctx) {
+    return (ctx.registries.prompts?.entries || [])
+      .filter((p) => !['retired', 'deprecated'].includes(p.status))
+      .flatMap((p) => {
+        const missing = [];
+        if (!(p.expected_answer_components || []).length) missing.push('expected_answer_components');
+        if (!p.desired_outcome) missing.push('desired_outcome');
+        if (!p.risk_classification) missing.push('risk_classification');
+        if (!p.owner) missing.push('owner');
+        return missing.length ? [{
+          subject: entrySubject('prompts', p.prompt_id),
+          summary: `Prompt ${p.prompt_id} lacks a complete evaluation brief`,
+          evidence: [`missing: ${missing.join(', ')}`],
+        }] : [];
+      });
+  },
+}));
+
 /* ---------------- RECO: recommendation eligibility ---------------- */
 
 const RECO_CHECKS = [

package/src/extractor/site.js

@@ -56,7 +56,10 @@ export function buildSiteFromDir(dir, { baseUrl = 'https://example.test' } = {})
 }
 
 /** Build a SiteModel by fetching a deployed URL set (target URL + same-origin discovery, bounded). */
-export async function buildSiteFromUrl(startUrl, { maxPages = 50, userAgent } = {}) {
+export async function buildSiteFromUrl(startUrl, {
+  maxPages = 50, userAgent, pageMaxBytes = 5 * 1024 * 1024,
+  robotsMaxBytes = 512 * 1024, sitemapMaxBytes = 5 * 1024 * 1024,
+} = {}) {
   const origin = new URL(startUrl).origin;
   const seen = new Set();
   const queue = [startUrl];
@@ -68,7 +71,7 @@ export async function buildSiteFromUrl(startUrl, { maxPages = 50, userAgent } =
     if (seen.has(key)) continue;
     seen.add(key);
     try {
-      const res = await fetchUrl(url, { userAgent });
+      const res = await fetchUrl(url, { userAgent, maxBodyBytes: pageMaxBytes });
       const page = extractPage({
         url: res.url, html: res.body, status: res.status, headers: res.headers, redirectChain: res.redirectChain,
       });
@@ -89,13 +92,18 @@ export async function buildSiteFromUrl(startUrl, { maxPages = 50, userAgent } =
   let robotsText = null;
   const sitemaps = [];
   try {
-    const r = await fetchUrl(new URL('/robots.txt', origin).href, { userAgent });
+    const r = await fetchUrl(new URL('/robots.txt', origin).href, { userAgent, maxBodyBytes: robotsMaxBytes });
     if (r.status === 200) robotsText = r.body;
   } catch { /* recorded as missing robots */ }
   const smUrls = robotsText ? parseRobots(robotsText).sitemaps : [new URL('/sitemap.xml', origin).href];
   for (const sm of smUrls) {
     try {
-      const r = await fetchUrl(sm, { userAgent });
+      const sitemapUrl = new URL(sm, origin);
+      if (sitemapUrl.origin !== origin) {
+        errors.push(`${sitemapUrl.href}: sitemap URL leaves audited origin`);
+        continue;
+      }
+      const r = await fetchUrl(sitemapUrl.href, { userAgent, maxBodyBytes: sitemapMaxBytes });
       if (r.status === 200) sitemaps.push({ source: sm, parsed: parseSitemap(r.body) });
     } catch { /* absence handled by TECH detectors */ }
   }

package/src/reporting/report.js

@@ -1,6 +1,45 @@
 const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, informational: 4, experimental: 5 };
 
-export function summarize(findings) {
+const RETRIEVAL_NAMESPACES = new Set(['TECH', 'CRAWL', 'LINK', 'HREFLANG']);
+const SOURCE_NAMESPACES = new Set(['PAGE', 'ANS', 'ENTITY', 'CLAIM', 'EVD', 'SCHEMA', 'ARCH', 'GEO', 'RECO', 'LIFE', 'EXT']);
+
+function namespace(detectorId) {
+  return detectorId.split('-')[0];
+}
+
+function readinessPosture(findings, detectorsRun, detectorsSkipped, namespaces) {
+  const relevant = findings.filter((finding) => namespaces.has(namespace(finding.detector_id)));
+  const skipped = detectorsSkipped.filter((check) => namespaces.has(namespace(check.detector_id)));
+  const ran = detectorsRun.some((detectorId) => namespaces.has(namespace(detectorId)));
+  let result;
+  if (!ran || skipped.length) result = 'not_established';
+  else if (relevant.some((finding) => ['critical', 'high'].includes(finding.classification.severity))) result = 'fail';
+  else if (relevant.length) result = 'partial';
+  else result = 'pass';
+  return {
+    result,
+    finding_count: relevant.length,
+    skipped_checks: skipped.map((check) => check.detector_id),
+  };
+}
+
+function citationPosture(promptResults, targetOrigin) {
+  if (!promptResults.length) {
+    return { result: 'not_evidenced', finding_count: 0, observations: 0, property_citations: 0, citation_presence_rate: null };
+  }
+  const cited = promptResults.filter((observation) => (observation.citations || []).some((citation) => {
+    try { return targetOrigin && new URL(citation).origin === targetOrigin; } catch { return false; }
+  })).length;
+  return {
+    result: 'observed',
+    finding_count: 0,
+    observations: promptResults.length,
+    property_citations: cited,
+    citation_presence_rate: cited / promptResults.length,
+  };
+}
+
+export function summarize(findings, { detectorsRun = [], detectorsSkipped = [], promptResults = [], targetOrigin = null } = {}) {
   const bySeverity = {};
   const byNamespace = {};
   const byDiscipline = { seo: 0, aeo: 0, geo: 0 };
@@ -19,6 +58,11 @@ export function summarize(findings) {
     by_severity: bySeverity,
     by_namespace: byNamespace,
     by_discipline: byDiscipline,
+    posture: {
+      retrieval_eligibility: readinessPosture(findings, detectorsRun, detectorsSkipped, RETRIEVAL_NAMESPACES),
+      source_extraction_and_support: readinessPosture(findings, detectorsRun, detectorsSkipped, SOURCE_NAMESPACES),
+      observed_citation_behavior: citationPosture(promptResults, targetOrigin),
+    },
   };
 }
 
@@ -45,6 +89,19 @@ export function renderMarkdownReport({ findings, manifest, summary, detectorsSki
     lines.push(`| ${sev} | ${n} |`);
   }
   lines.push('');
+  lines.push('## Separate eligibility and observation states');
+  lines.push('');
+  lines.push('| Dimension | Result | Evidence |');
+  lines.push('| --- | --- | --- |');
+  const retrieval = summary.posture.retrieval_eligibility;
+  const source = summary.posture.source_extraction_and_support;
+  const citation = summary.posture.observed_citation_behavior;
+  lines.push(`| Retrieval eligibility | ${retrieval.result} | ${retrieval.finding_count} finding(s); ${retrieval.skipped_checks.length} skipped check(s) |`);
+  lines.push(`| Source extraction and support | ${source.result} | ${source.finding_count} finding(s); ${source.skipped_checks.length} skipped check(s) |`);
+  lines.push(`| Observed citation behavior | ${citation.result} | ${citation.observations} controlled observation(s); property citation rate: ${citation.citation_presence_rate == null ? 'not evidenced' : `${(citation.citation_presence_rate * 100).toFixed(1)}%`} |`);
+  lines.push('');
+  lines.push('These states are not combined into an AI visibility score. Readiness does not establish retrieval selection or citation behavior.');
+  lines.push('');
   if (detectorsSkipped.length) {
     lines.push(`## Skipped checks`);
     lines.push('');

package/src/shared/io.js

@@ -37,6 +37,18 @@ export function nowIso() {
   return new Date().toISOString();
 }
 
+export function parseRefDate(value) {
+  if (value == null) return new Date();
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new Error('ref-date must be a valid date in YYYY-MM-DD format');
+  }
+  const date = new Date(`${value}T00:00:00Z`);
+  if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== value) {
+    throw new Error('ref-date must be a valid date in YYYY-MM-DD format');
+  }
+  return date;
+}
+
 export function isPastDate(isoDate, ref = new Date()) {
   if (!isoDate) return false;
   const d = new Date(String(isoDate).slice(0, 10) + 'T23:59:59Z');