@nebulacomponents/citable 1.12.0 → 1.13.0

package/src/detectors/tech.js

@@ -1,4 +1,4 @@
-import { defineDetector, indexTargets, registryPageFor, pageSubject, safePath } from './framework.js';
+import { defineDetector, hasHtmlDocumentMarkup, indexTargets, isHtmlDocument, isHtmlDocumentUrl, registryPageFor, pageSubject, safePath } from './framework.js';
 import { isAllowed } from '../crawler/robots.js';
 
 const D = [];
@@ -177,7 +177,9 @@ D.push(defineDetector({
     for (const sm of ctx.site.sitemaps) {
       for (const u of sm.parsed.urls) {
         const page = ctx.site.byUrl.get(ctx.site.normalize(u.loc));
-        if (!page) {
+        if (!page && ctx.site.mode === 'url' && ctx.site.crawl?.truncated) {
+          continue;
+        } else if (!page) {
           hits.push({
             subject: { type: 'url', identifier: u.loc, url: u.loc, source_location: sm.source },
             summary: 'Sitemap URL not present in audited output',
@@ -227,7 +229,7 @@ D.push(defineDetector({
   verification: 'Inspect the Content-Type response header.',
   check(ctx) {
     return indexTargets(ctx)
-      .filter((p) => p.status === 200 && p.contentType && !p.contentType.includes('text/html'))
+      .filter((p) => p.status === 200 && p.contentType && (isHtmlDocumentUrl(p.url) || hasHtmlDocumentMarkup(p)) && !isHtmlDocument(p))
       .map((p) => ({
         subject: pageSubject(p),
         summary: `HTML page served with Content-Type "${p.contentType}"`,

package/src/extractor/site.js

@@ -59,6 +59,7 @@ export function buildSiteFromDir(dir, { baseUrl = 'https://example.test' } = {})
 export async function buildSiteFromUrl(startUrl, {
   maxPages = 50, userAgent, pageMaxBytes = 5 * 1024 * 1024,
   robotsMaxBytes = 512 * 1024, sitemapMaxBytes = 5 * 1024 * 1024,
+  fetcher = fetchUrl,
 } = {}) {
   const origin = new URL(startUrl).origin;
   const seen = new Set();
@@ -71,7 +72,7 @@ export async function buildSiteFromUrl(startUrl, {
     if (seen.has(key)) continue;
     seen.add(key);
     try {
-      const res = await fetchUrl(url, { userAgent, maxBodyBytes: pageMaxBytes });
+      const res = await fetcher(url, { userAgent, maxBodyBytes: pageMaxBytes });
       const page = extractPage({
         url: res.url, html: res.body, status: res.status, headers: res.headers, redirectChain: res.redirectChain,
       });
@@ -81,7 +82,8 @@ export async function buildSiteFromUrl(startUrl, {
         for (const l of page.links) {
           try {
             const u = new URL(l.href, res.url);
-            if (u.origin === origin && !seen.has(u.href.replace(/#.*$/, ''))) queue.push(u.href);
+            u.hash = '';
+            if (u.origin === origin && !isProviderUtilityPath(u.pathname) && !seen.has(u.href)) queue.push(u.href);
           } catch { /* unresolvable href — surfaced by LINK detectors */ }
         }
       }
@@ -92,7 +94,7 @@ export async function buildSiteFromUrl(startUrl, {
   let robotsText = null;
   const sitemaps = [];
   try {
-    const r = await fetchUrl(new URL('/robots.txt', origin).href, { userAgent, maxBodyBytes: robotsMaxBytes });
+    const r = await fetcher(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];
@@ -103,16 +105,24 @@ export async function buildSiteFromUrl(startUrl, {
         errors.push(`${sitemapUrl.href}: sitemap URL leaves audited origin`);
         continue;
       }
-      const r = await fetchUrl(sitemapUrl.href, { userAgent, maxBodyBytes: sitemapMaxBytes });
+      const r = await fetcher(sitemapUrl.href, { userAgent, maxBodyBytes: sitemapMaxBytes });
       if (r.status === 200) sitemaps.push({ source: sm, parsed: parseSitemap(r.body) });
     } catch { /* absence handled by TECH detectors */ }
   }
-  const site = assembleSite({ baseUrl: origin, pages, robotsText, sitemaps, transport: {}, mode: 'url', location: startUrl });
+  const pendingUrls = [...new Set(queue.map((url) => url.replace(/#.*$/, '')).filter((url) => !seen.has(url)))];
+  const crawl = {
+    maxPages,
+    pagesFetched: pages.length,
+    truncated: pages.length >= maxPages && pendingUrls.length > 0,
+    pendingUrlCount: pendingUrls.length,
+    pendingUrls,
+  };
+  const site = assembleSite({ baseUrl: origin, pages, robotsText, sitemaps, transport: {}, mode: 'url', location: startUrl, crawl });
   site.fetchErrors = errors;
   return site;
 }
 
-function assembleSite({ baseUrl, pages, robotsText, sitemaps, transport, mode, location }) {
+function assembleSite({ baseUrl, pages, robotsText, sitemaps, transport, mode, location, crawl = null }) {
   const byUrl = new Map();
   for (const p of pages) byUrl.set(normalize(p.url), p);
 
@@ -168,9 +178,14 @@ function assembleSite({ baseUrl, pages, robotsText, sitemaps, transport, mode, l
     outbound,
     depth,
     normalize,
+    crawl,
   };
 }
 
+function isProviderUtilityPath(pathname) {
+  return pathname === '/cdn-cgi' || pathname.startsWith('/cdn-cgi/');
+}
+
 export function normalize(url) {
   try {
     const u = new URL(url);

package/src/observations/browserJourney.js

@@ -0,0 +1,167 @@
+import { envelope, observationRun, readInput } from './common.js';
+import { fetchUrl } from '../crawler/fetch.js';
+import { sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+async function executeStep(page, step) {
+  const locator = step.locator ? page.locator(step.locator).first() : null;
+  if (step.action === 'navigate') await page.goto(step.url, { waitUntil: 'networkidle' });
+  else if (step.action === 'click') await locator.click();
+  else if (step.action === 'fill') {
+    const value = process.env[step.value_env];
+    if (value == null) throw new Error(`environment input ${step.value_env} is unavailable`);
+    await locator.fill(value);
+  } else if (step.action === 'select_option') {
+    const value = process.env[step.value_env];
+    if (value == null) throw new Error(`environment input ${step.value_env} is unavailable`);
+    await locator.selectOption(value);
+  } else if (step.action === 'check') await locator.check();
+  else if (step.action === 'press') await locator.press(step.key);
+  else if (step.action === 'wait_for') await locator.waitFor({ state: 'visible' });
+  else if (step.action === 'assert_visible' && !(await locator.isVisible())) throw new Error(`locator is not visible: ${step.locator}`);
+  else if (step.action === 'scroll') await locator.scrollIntoViewIfNeeded();
+}
+
+async function playwrightCapture(profile, plan, playwright) {
+  if (profile.authentication_state !== 'anonymous') throw new Error(`authentication state ${profile.authentication_state} requires a disclosed custom adapter`);
+  const browserType = playwright[profile.browser.engine];
+  if (!browserType) throw new Error(`Playwright engine ${profile.browser.engine} is unavailable`);
+  const browser = await browserType.launch({ headless: true });
+  try {
+    const context = await browser.newContext({
+      viewport: profile.device.viewport,
+      isMobile: profile.device.is_mobile,
+      javaScriptEnabled: profile.javascript_enabled,
+      locale: profile.locale,
+    });
+    try {
+      const page = await context.newPage();
+      const consoleErrors = [], networkFailures = [], steps = [], stepScreenshots = {};
+      page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()); });
+      page.on('requestfailed', (request) => networkFailures.push({ url: request.url(), error: request.failure()?.errorText || 'unknown' }));
+      const response = await page.goto(plan.target, { waitUntil: 'networkidle' });
+      for (const step of profile.steps) {
+        const record = { step_id: step.step_id, action: step.action, status: 'completed', failure: null, screenshot_ref: null };
+        try {
+          await executeStep(page, step);
+          if (step.capture_screenshot) {
+            record.screenshot_ref = `journeys/${profile.profile_id}/steps/${step.step_id}.png`;
+            stepScreenshots[record.screenshot_ref] = await page.screenshot({ fullPage: true });
+          }
+        } catch (error) {
+          record.status = 'failed';
+          record.failure = error.message;
+          steps.push(record);
+          if (step.required) throw Object.assign(new Error(`required step ${step.step_id} failed: ${error.message}`), { steps, stepScreenshots });
+          continue;
+        }
+        steps.push(record);
+      }
+      const dom = await page.content();
+      const text = await page.locator('body').innerText();
+      const accessibilityTree = typeof page.locator('body').ariaSnapshot === 'function' ? await page.locator('body').ariaSnapshot() : null;
+      return {
+        final_url: page.url(), status: response?.status() ?? null, browser_version: browser.version(),
+        dom, text, accessibility_tree: accessibilityTree, screenshot: await page.screenshot({ fullPage: true }),
+        console_errors: consoleErrors, network_failures: networkFailures, steps, step_screenshots: stepScreenshots,
+      };
+    } finally {
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+export async function observeBrowserPlan(root, options) {
+  const input = readInput(options.input);
+  const plan = input.value;
+  const check = validateAgainst('browser-evidence-plan.schema.json', plan);
+  if (!check.valid) throw new Error(`browser evidence plan violates contract: ${check.errors.join('; ')}`);
+  if (options.target && options.target !== plan.target) throw new Error('browser evidence target differs from the plan target');
+  const profileIds = plan.profiles.map((item) => item.profile_id);
+  if (new Set(profileIds).size !== profileIds.length) throw new Error('browser evidence plan contains duplicate profile ids');
+  const targetOrigin = new URL(plan.target).origin;
+  for (const profile of plan.profiles) {
+    const stepIds = profile.steps.map((item) => item.step_id);
+    if (new Set(stepIds).size !== stepIds.length) throw new Error(`${profile.profile_id}: duplicate journey step ids`);
+    for (const step of profile.steps) {
+      if (step.action === 'navigate') {
+        if (!step.url) throw new Error(`${profile.profile_id}/${step.step_id}: navigate requires url`);
+        if (new URL(step.url).origin !== targetOrigin) throw new Error(`${profile.profile_id}/${step.step_id}: cross-origin navigation is not allowed`);
+      } else if (!step.locator) throw new Error(`${profile.profile_id}/${step.step_id}: ${step.action} requires locator`);
+      if (['fill', 'select_option'].includes(step.action) && !step.value_env) throw new Error(`${profile.profile_id}/${step.step_id}: ${step.action} requires value_env`);
+      if (step.action === 'press' && !step.key) throw new Error(`${profile.profile_id}/${step.step_id}: press requires key`);
+    }
+  }
+
+  let playwright = options.playwright;
+  if (!options.captureJourney && !playwright) {
+    try { playwright = await import('playwright'); } catch {
+      const item = envelope('browser_journey', { plan_id: plan.plan_id, target: plan.target }, { method: 'browser', source: 'playwright', state: 'not_evidenced', confidence: 'unknown', limitations: ['Optional Playwright dependency is not installed.'] });
+      return observationRun(root, 'observe render', plan.target, [item], { rawInputs: { browser_evidence_plan: input.raw }, incomplete: ['Cross-browser journey collection unavailable: install Playwright and browser engines.'] });
+    }
+  }
+
+  const initial = await (options.fetchUrl || fetchUrl)(plan.target, { maxRetries: 1 });
+  const observations = [], incomplete = [], artifacts = {
+    'initial/response.html': initial.body,
+    'initial/headers.json': initial.headers || {},
+  };
+  for (const profile of plan.profiles) {
+    const prefix = `journeys/${profile.profile_id}`;
+    try {
+      const capture = options.captureJourney
+        ? await options.captureJourney(profile, plan)
+        : await playwrightCapture(profile, plan, playwright);
+      if (!capture || typeof capture.dom !== 'string' || typeof capture.text !== 'string' || typeof capture.browser_version !== 'string' || capture.screenshot == null) {
+        throw new Error('browser adapter returned an incomplete capture contract');
+      }
+      const refs = {
+        raw_response: 'initial/response.html',
+        rendered_dom: `${prefix}/dom.html`,
+        rendered_text: `${prefix}/text.txt`,
+        accessibility_tree: capture.accessibility_tree == null ? null : `${prefix}/accessibility-tree.txt`,
+        screenshot: `${prefix}/final.png`,
+        failures: `${prefix}/failures.json`,
+        interactions: `${prefix}/steps.json`,
+      };
+      artifacts[refs.rendered_dom] = capture.dom;
+      artifacts[refs.rendered_text] = capture.text;
+      if (refs.accessibility_tree) artifacts[refs.accessibility_tree] = capture.accessibility_tree;
+      artifacts[refs.screenshot] = capture.screenshot;
+      artifacts[refs.failures] = { console_errors: capture.console_errors || [], network_failures: capture.network_failures || [] };
+      artifacts[refs.interactions] = capture.steps || [];
+      for (const [name, value] of Object.entries(capture.step_screenshots || {})) {
+        if (!name.startsWith(`${prefix}/steps/`) || name.includes('..')) throw new Error(`browser adapter returned unsafe artifact path: ${name}`);
+        artifacts[name] = value;
+      }
+      const versionMatches = profile.browser.expected_version == null || profile.browser.expected_version === capture.browser_version;
+      const data = {
+        plan_id: plan.plan_id, target: plan.target, profile_id: profile.profile_id,
+        browser: { ...profile.browser, observed_version: capture.browser_version, version_matches_expectation: versionMatches },
+        device: profile.device, javascript_enabled: profile.javascript_enabled, locale: profile.locale,
+        consent_state: profile.consent_state, authentication_state: profile.authentication_state,
+        final_url: capture.final_url, status: capture.status, dom_hash: sha256(capture.dom), text_hash: sha256(capture.text),
+        steps: capture.steps || [], artifact_refs: refs,
+        interpretation_boundary: 'Observed differences do not establish semantic, retrieval, citation, ranking, or business impact.',
+      };
+      const limitations = [...plan.limitations, ...profile.limitations];
+      if (!versionMatches) limitations.push('Observed browser version differs from the planned version.');
+      observations.push(envelope('browser_journey', data, { method: 'browser', source: `playwright/${profile.browser.engine}`, raw: capture.dom, limitations }));
+    } catch (error) {
+      incomplete.push(`${profile.profile_id}: ${error.message}`);
+      const failureRef = `${prefix}/failure.json`;
+      artifacts[failureRef] = { profile_id: profile.profile_id, error: error.message, completed_steps: error.steps || [] };
+      for (const [name, value] of Object.entries(error.stepScreenshots || {})) artifacts[name] = value;
+      observations.push(envelope('browser_journey', {
+        plan_id: plan.plan_id, target: plan.target, profile_id: profile.profile_id, browser: profile.browser,
+        device: profile.device, javascript_enabled: profile.javascript_enabled, locale: profile.locale,
+        consent_state: profile.consent_state, authentication_state: profile.authentication_state,
+        steps: error.steps || [], artifact_refs: { failure: failureRef },
+        interpretation_boundary: 'Profile failure does not invalidate successful profiles or establish semantic impact.',
+      }, { method: 'browser', source: `playwright/${profile.browser.engine}`, state: 'failed', confidence: 'confirmed', raw: error.message, limitations: [...plan.limitations, ...profile.limitations, error.message] }));
+    }
+  }
+  return observationRun(root, 'observe render', plan.target, observations, { rawInputs: { browser_evidence_plan: input.raw }, incomplete, artifacts });
+}

package/src/observations/media.js

@@ -29,7 +29,14 @@ async function pdfEvidence(item, file, artifacts) {
 
 function transcriptEvidence(item, file, artifacts) {
   const raw = fs.readFileSync(file, 'utf8');
-  const cues = raw.split(/\r?\n\r?\n/).map((block) => { const lines = block.split(/\r?\n/).filter(Boolean); const timing = lines.find((line) => line.includes('-->')) || null; const text = lines.filter((line) => line !== 'WEBVTT' && line !== timing && !/^\d+$/.test(line)).join(' ').replace(/<[^>]+>/g, '').trim(); return text ? { timing, text } : null; }).filter(Boolean);
+  const cues = raw.split(/\r?\n\r?\n/).map((block) => {
+    const lines = block.split(/\r?\n/).filter(Boolean);
+    const timing = lines.find((line) => line.includes('-->')) || null;
+    const fragment = parse(lines.filter((line) => line !== 'WEBVTT' && line !== timing && !/^\d+$/.test(line)).join(' '));
+    for (const node of fragment.querySelectorAll('script,style')) node.remove();
+    const text = fragment.textContent.replace(/\s+/g, ' ').trim();
+    return text ? { timing, text } : null;
+  }).filter(Boolean);
   const text = cues.map((cue) => cue.text).join(' ');
   artifacts[`media/${item.media_id}/transcript.txt`] = text;
   return envelope('media_transcript', { media_id: item.media_id, source_url: item.source_url, page_url: item.page_url, claim_ids: item.claim_ids, permission_status: item.permission_status, language: item.language || null, published_at: item.published_at || null, cues, word_count: text ? text.split(/\s+/).length : 0 }, { method: 'owner_import', source: file, raw, limitations: ['Speaker identity, transcription accuracy, timing accuracy, and media parity require human verification.', 'Transcript ingestion does not establish that linked claims are supported.'] });

package/src/registries/index.js

@@ -23,6 +23,16 @@ export const REGISTRY_SPECS = [
   { file: 'review-items.yaml', kind: 'review_items', schema: 'review-item.schema.json', idField: 'review_item_id' },
   { file: 'sampling-plans.yaml', kind: 'sampling_plans', schema: 'sampling-plan.schema.json', idField: 'sampling_plan_id' },
   { file: 'schedules.yaml', kind: 'schedules', schema: 'schedule.schema.json', idField: 'schedule_id' },
+  // Executive reporting suite — governed inputs (Phase 1)
+  { file: 'kpis.yaml',              kind: 'kpis',              schema: 'kpi.schema.json',             idField: 'metric_id' },
+  { file: 'variances.yaml',         kind: 'variances',         schema: 'variance.schema.json',        idField: 'variance_id' },
+  { file: 'customer-outcomes.yaml', kind: 'customer-outcomes', schema: 'customer-outcome.schema.json', idField: 'outcome_id' },
+  { file: 'risks.yaml',             kind: 'risks',             schema: 'risk.schema.json',            idField: 'risk_id' },
+  // Executive reporting suite — decision support (Phase 2)
+  { file: 'decisions.yaml',    kind: 'decisions',   schema: 'decision.schema.json',   idField: 'decision_id' },
+  { file: 'assumptions.yaml',  kind: 'assumptions', schema: 'assumption.schema.json', idField: 'assumption_id' },
+  { file: 'scenarios.yaml',    kind: 'scenarios',   schema: 'scenario.schema.json',   idField: 'scenario_id' },
+  { file: 'initiatives.yaml',  kind: 'initiatives', schema: 'initiative.schema.json', idField: 'initiative_id' },
 ];
 
 export function contextDir(root) {
@@ -33,6 +43,31 @@ export function emptyRegistry(kind) {
   return { version: 1, kind, updated: nowIso(), entries: [] };
 }
 
+const LOAD_PROBLEMS = Symbol('registryLoadProblems');
+
+/** Read one registry without allowing malformed YAML to crash a command. */
+export function loadRegistryFile(file, kind) {
+  let data = emptyRegistry(kind);
+  const problems = [];
+  if (fs.existsSync(file)) {
+    try {
+      data = readYaml(file) ?? emptyRegistry(kind);
+      if (typeof data !== 'object' || data === null || !Array.isArray(data.entries)) {
+        problems.push(`${path.basename(file)}: YAML does not match expected registry shape`);
+        data = emptyRegistry(kind);
+      }
+    } catch (error) {
+      problems.push(`${path.basename(file)}: YAML parse failure: ${error.message}`);
+    }
+  }
+  Object.defineProperty(data, LOAD_PROBLEMS, { value: problems, enumerable: false });
+  return data;
+}
+
+export function registryLoadProblems(data) {
+  return data?.[LOAD_PROBLEMS] ?? [];
+}
+
 /** Load all registries under <root>/.citable. Missing files load as empty. */
 export function loadRegistries(root) {
   const dir = contextDir(root);
@@ -63,13 +98,21 @@ export function checkReferentialIntegrity(registries) {
   const problems = [];
   const ids = {};
   for (const spec of REGISTRY_SPECS) {
-    ids[spec.kind] = new Set((registries[spec.kind]?.entries || []).map((e) => e[spec.idField]));
-    const seen = new Set();
-    for (const e of registries[spec.kind]?.entries || []) {
-      const id = e[spec.idField];
-      if (seen.has(id)) problems.push(`${spec.kind}: duplicate id ${id}`);
-      seen.add(id);
+    const registry = registries[spec.kind] ?? emptyRegistry(spec.kind);
+    const schemaValid = (registry.entries || []).filter((entry) =>
+      validateAgainst(spec.schema, { ...registry, entries: [entry] }).valid);
+    const counts = new Map();
+    for (const entry of schemaValid) {
+      const id = entry[spec.idField];
+      counts.set(id, (counts.get(id) ?? 0) + 1);
     }
+    for (const [id, count] of counts) {
+      if (count > 1) problems.push(`${spec.kind}/${id}: duplicate id ${id}`);
+    }
+    // Only schema-valid, unambiguous records may satisfy references.
+    ids[spec.kind] = new Set(schemaValid
+      .map((entry) => entry[spec.idField])
+      .filter((id) => counts.get(id) === 1));
   }
   const refChecks = [
     ['claims', 'evidence', 'evidence', 'claim_id'],
@@ -131,6 +174,64 @@ export function checkReferentialIntegrity(registries) {
   }
   const reviewItemIds = ids.review_items || new Set();
   for (const plan of registries.sampling_plans?.entries || []) for (const ref of plan.selected_item_ids || []) if (!reviewItemIds.has(ref)) problems.push(`sampling_plans/${plan.sampling_plan_id}: references unknown review item id "${ref}"`);
+
+  // ── Executive reporting suite cross-registry checks ────────────────────────
+  const kpiIds        = ids.kpis            || new Set();
+  const outcomeIds    = ids['customer-outcomes'] || new Set();
+  const decisionIds   = ids.decisions       || new Set();
+  const assumptionIds = ids.assumptions     || new Set();
+  const riskIds       = ids.risks           || new Set();
+  const initiativeIds = ids.initiatives     || new Set();
+
+  // variances must reference a known KPI metric_id
+  for (const v of registries.variances?.entries || []) {
+    if (v.metric_id && !kpiIds.has(v.metric_id))
+      problems.push(`variances/${v.variance_id}: metric_id "${v.metric_id}" references unknown kpi`);
+  }
+
+  // decisions: supporting/contradicting evidence can reference outcome IDs
+  for (const d of registries.decisions?.entries || []) {
+    const prefix = `decisions/${d.decision_id}`;
+    for (const ref of d.supporting_evidence || []) {
+      if (typeof ref === 'string' && ref.startsWith('OUT-') && !outcomeIds.has(ref))
+        problems.push(`${prefix}: supporting_evidence references unknown customer-outcome "${ref}"`);
+    }
+    for (const ref of d.contradicting_evidence || []) {
+      if (typeof ref === 'string' && ref.startsWith('OUT-') && !outcomeIds.has(ref))
+        problems.push(`${prefix}: contradicting_evidence references unknown customer-outcome "${ref}"`);
+    }
+    for (const ref of d.assumptions || []) {
+      if (typeof ref === 'string' && ref.startsWith('ASMP-') && !assumptionIds.has(ref))
+        problems.push(`${prefix}: assumptions references unknown assumption "${ref}"`);
+    }
+  }
+
+  // initiatives: linked_kpis, linked_outcomes, linked_risks, linked_decisions
+  for (const i of registries.initiatives?.entries || []) {
+    const prefix = `initiatives/${i.initiative_id}`;
+    for (const ref of i.linked_kpis || [])
+      if (!kpiIds.has(ref)) problems.push(`${prefix}: linked_kpis references unknown kpi "${ref}"`);
+    for (const ref of i.linked_outcomes || [])
+      if (!outcomeIds.has(ref)) problems.push(`${prefix}: linked_outcomes references unknown customer-outcome "${ref}"`);
+    for (const ref of i.linked_risks || [])
+      if (!riskIds.has(ref)) problems.push(`${prefix}: linked_risks references unknown risk "${ref}"`);
+    for (const ref of i.linked_decisions || [])
+      if (!decisionIds.has(ref)) problems.push(`${prefix}: linked_decisions references unknown decision "${ref}"`);
+  }
+
+  // scenarios: variable_ids should reference known KPIs or risks
+  for (const s of registries.scenarios?.entries || []) {
+    const prefix = `scenarios/${s.scenario_id}`;
+    for (const v of s.variables || []) {
+      const ref = v.variable_id;
+      if (!ref) continue;
+      if (ref.startsWith('KPI-') && !kpiIds.has(ref))
+        problems.push(`${prefix}: variable "${ref}" references unknown kpi`);
+      if (ref.startsWith('RISK-') && !riskIds.has(ref))
+        problems.push(`${prefix}: variable "${ref}" references unknown risk`);
+    }
+  }
+
   return problems;
 }