@nebulacomponents/citable 1.15.0 → 1.16.0

package/src/commands/monitor.js

@@ -2,6 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readJson, writeJson, nowIso } from '../shared/io.js';
 import { buildAlertPayload, dispatchAlertWebhook, filterAlerts } from '../monitoring/alertDelivery.js';
+import { calculateShareOfVoice, extractDomain } from '../reporting/shareOfVoice.js';
+import { loadRegistries } from '../registries/index.js';
+import { evaluateAnswerAttribution } from '../observations/attribution.js';
 
 function observations(dir) {
   const folder = path.join(dir, 'observations');
@@ -13,6 +16,7 @@ function key(item) {
   const d = item.data || {};
   if (item.kind === 'citation') return [item.kind, d.provider, d.product_mode, d.prompt_id, d.run_index].join(':');
   if (item.kind === 'representation_drift') return [item.kind, d.manifest_hash, d.surface_id, d.retrieval_path, d.region, d.request_identity].join(':');
+  if (item.kind === 'stance') return [item.kind, d.entity_id || d.canonical_name, d.prompt_id, d.engine].join(':');
   return [item.kind, d.url || d.citation_url || d.prompt_id || d.timestamp || item.observation_id].join(':');
 }
 
@@ -22,6 +26,32 @@ export function monitor(root, { runA, runB } = {}) {
   const candidates = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'observations'))).sort();
   const b = runB || candidates.at(-1), a = runA || candidates.at(-2);
   if (!a || !b) throw new Error('monitor requires two observation runs');
+
+  let activeClaims = [];
+  let entities = [];
+  let competitors = [];
+  const firstPartyDomains = new Set();
+  try {
+    const { registries } = loadRegistries(root);
+    activeClaims = (registries?.claims?.entries || []).filter((c) => c.status === 'verified' || c.status === 'established');
+    entities = (registries?.entities?.entries || []).filter((e) => e.status !== 'retired');
+    if (registries?.competitors?.entries) competitors = registries.competitors.entries;
+    if (registries?.config?.site?.base_url) {
+      const d = extractDomain(registries.config.site.base_url);
+      if (d) firstPartyDomains.add(d);
+    }
+    if (registries?.pages?.entries) {
+      for (const p of registries.pages.entries) {
+        if (p.url) {
+          const d = extractDomain(p.url);
+          if (d) firstPartyDomains.add(d);
+        }
+      }
+    }
+  } catch {
+    // Registries may not exist in synthetic test environments
+  }
+
   const before = new Map(observations(path.join(runsDir, a)).map((o) => [key(o), o]));
   const after = new Map(observations(path.join(runsDir, b)).map((o) => [key(o), o]));
   const alerts = [];
@@ -32,6 +62,23 @@ export function monitor(root, { runA, runB } = {}) {
     if (current.kind === 'index' && previous?.data?.indexed === true && current.data.indexed === false) alerts.push({ severity: 'high', type: 'index_loss', key: k });
     if (current.kind === 'canonical_freshness' && previous?.data?.canonical_consensus === true && current.data.canonical_consensus === false) alerts.push({ severity: 'high', type: 'canonical_regression', key: k });
     if (current.kind === 'citation' && previous?.data?.property_cited === true && current.data.property_cited === false) alerts.push({ severity: 'medium', type: 'citation_presence_change', key: k });
+    if (current.kind === 'stance' && previous) {
+      const fromStance = previous.data?.stance;
+      const toStance = current.data?.stance;
+      if (fromStance === 'favorable' && (toStance === 'unfavorable' || toStance === 'mixed')) {
+        alerts.push({
+          severity: 'high',
+          type: 'stance_regression',
+          key: k,
+          previous_stance: fromStance,
+          current_stance: toStance,
+          entity_id: current.data?.entity_id || null,
+          canonical_name: current.data?.canonical_name || null,
+          prompt_id: current.data?.prompt_id || null,
+          engine: current.data?.engine || null,
+        });
+      }
+    }
     if (current.kind === 'representation_drift' && previous) {
       const from = previous.data.representation_state, to = current.data.representation_state;
       if (from !== 'divergent' && to === 'divergent') alerts.push({ severity: 'high', type: 'representation_divergence_observed', key: k, previous_state: from, current_state: to, authority: 'external_unverified', gates_release_finalization: false });
@@ -40,8 +87,97 @@ export function monitor(root, { runA, runB } = {}) {
         alerts.push({ severity: 'informational', type: 'representation_convergence_observed', key: k, previous_state: from, current_state: to, observed_interval_ms: Number.isFinite(duration) && duration >= 0 ? duration : null, authority: 'external_unverified', gates_release_finalization: false });
       }
     }
+
+    // Generative claim contradiction / hallucination check
+    if (current.kind === 'attribution' && current.data?.evaluations) {
+      for (const ev of current.data.evaluations) {
+        if (ev.attribution_status === 'distorted') {
+          alerts.push({
+            severity: 'high',
+            type: 'claim_contradiction_observed',
+            key: k,
+            claim_id: ev.claim_id,
+            claim_text: ev.claim_text,
+            assertion_excerpt: ev.assertion_excerpt,
+            engine: current.data?.engine || current.data?.provider || null,
+            reasons: ev.reasons || [],
+          });
+        }
+      }
+    } else if (current.kind === 'citation' || current.kind === 'passage') {
+      if (current.data?.answer_text && entities.length > 0 && activeClaims.length > 0) {
+        for (const e of entities) {
+          const evalRes = evaluateAnswerAttribution(current.data.answer_text, e, { claims: activeClaims });
+          if (evalRes.mentioned && evalRes.has_distorted_claims) {
+            for (const ev of evalRes.evaluations) {
+              if (ev.attribution_status === 'distorted') {
+                alerts.push({
+                  severity: 'high',
+                  type: 'claim_contradiction_observed',
+                  key: k,
+                  claim_id: ev.claim_id,
+                  claim_text: ev.claim_text,
+                  assertion_excerpt: ev.assertion_excerpt,
+                  engine: current.data?.provider || current.data?.engine || null,
+                  reasons: ev.reasons || [],
+                });
+              }
+            }
+          }
+        }
+      } else if (current.data?.contradicted_claims && Array.isArray(current.data.contradicted_claims)) {
+        for (const cc of current.data.contradicted_claims) {
+          alerts.push({
+            severity: 'high',
+            type: 'claim_contradiction_observed',
+            key: k,
+            claim_id: typeof cc === 'object' ? cc.claim_id : cc,
+            assertion_excerpt: typeof cc === 'object' ? cc.assertion_excerpt : current.data?.answer_text?.slice(0, 150) || null,
+            engine: current.data?.provider || current.data?.engine || null,
+            reasons: typeof cc === 'object' ? cc.reasons || [] : ['contradicted claim observed in answer'],
+          });
+        }
+      }
+    }
   }
   for (const k of before.keys()) if (!after.has(k)) alerts.push({ severity: 'medium', type: 'observation_missing', key: k });
+
+  // Share-of-Voice comparison across observation runs
+  const citationsA = [...before.values()].filter((o) => o.kind === 'citation');
+  const citationsB = [...after.values()].filter((o) => o.kind === 'citation');
+  if (citationsA.length > 0 && citationsB.length > 0) {
+    const sovA = calculateShareOfVoice([{ run_id: a, citations: citationsA }], competitors, firstPartyDomains);
+    const sovB = calculateShareOfVoice([{ run_id: b, citations: citationsB }], competitors, firstPartyDomains);
+
+    const prevShare = sovA.aggregate?.first_party?.citation_share ?? sovA.aggregate?.first_party?.presence_rate;
+    const currShare = sovB.aggregate?.first_party?.citation_share ?? sovB.aggregate?.first_party?.presence_rate;
+
+    if (prevShare != null && currShare != null && prevShare > currShare) {
+      const drop = prevShare - currShare;
+      const relativeDrop = prevShare > 0 ? (prevShare - currShare) / prevShare : 0;
+      if (drop >= 0.20 || relativeDrop >= 0.20) {
+        alerts.push({
+          severity: 'high',
+          type: 'share_of_voice_drop',
+          key: 'share_of_voice:aggregate',
+          previous_share: Number(prevShare.toFixed(4)),
+          current_share: Number(currShare.toFixed(4)),
+          drop: Number(drop.toFixed(4)),
+          relative_drop: Number(relativeDrop.toFixed(4)),
+          competitors: (sovB.aggregate?.competitors || []).map((c) => {
+            const prevComp = sovA.aggregate?.competitors?.find((p) => p.competitor_id === c.competitor_id);
+            return {
+              competitor_id: c.competitor_id,
+              name: c.name,
+              previous_share: prevComp?.citation_share ?? null,
+              current_share: c.citation_share,
+              drift: prevComp?.citation_share != null ? Number((c.citation_share - prevComp.citation_share).toFixed(4)) : null,
+            };
+          }),
+        });
+      }
+    }
+  }
   const result = { generated_at: nowIso(), run_a: a, run_b: b, summary: { alerts: alerts.length, critical_or_high: alerts.filter((x) => ['critical', 'high'].includes(x.severity)).length }, alerts };
   const dir = path.join(root, '.citable', 'monitoring');
   writeJson(path.join(dir, `${a}--${b}.json`), result);
@@ -54,6 +190,7 @@ export async function monitorAndAlert(root, {
   runB,
   webhookUrl,
   minSeverity = 'medium',
+  secret = process.env.CITABLE_WEBHOOK_SECRET,
   fetchImpl,
   lookup,
   allowPrivateForTest = false,
@@ -71,6 +208,7 @@ export async function monitorAndAlert(root, {
       });
       const delivery = await dispatchAlertWebhook(root, payload, {
         webhookUrl,
+        secret,
         fetchImpl,
         lookup,
         allowPrivateForTest,

package/src/commands/observe.js

@@ -13,6 +13,7 @@ import { parse as parseHtml } from 'node-html-parser';
 import { verifyManifestIntegrity } from '../release/governance.js';
 import { observeBrowserPlan } from '../observations/browserJourney.js';
 import { observeStance } from '../observations/stance.js';
+import { observeAttribution } from '../observations/attribution.js';
 
 const originOf = (value) => { try { return new URL(value).origin; } catch { return null; } };
 const words = (text) => String(text || '').trim().split(/\s+/).filter(Boolean);
@@ -763,6 +764,10 @@ export async function observe(root, mode, options = {}) {
     case 'media': return observeMedia(root, options);
     case 'representation': return observeRepresentation(root, options);
     case 'stance': return observeStance(root, options);
-    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, probes, network, media, representation, or stance');
+    case 'attribution': return observeAttribution(root, options);
+    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, probes, network, media, representation, stance, or attribution');
   }
 }
+
+export { observeAttribution };
+

package/src/commands/planExperiment.js

@@ -0,0 +1,68 @@
+/**
+ * `citable plan experiment` — calculate required sample size, statistical power, and duration for A/B testing,
+ * and verify that conversion variants avoid SEO regressions.
+ */
+export async function planExperiment(root, options = {}) {
+  const baselineRate = Number(options.baselineRate ?? options['baseline-rate'] ?? 0.02);
+  const mde = Number(options.mde ?? 0.10); // 10% relative MDE
+  const dailyVisitors = Number(options.dailyVisitors ?? options['daily-visitors'] ?? 500);
+  const alpha = Number(options.alpha ?? 0.05); // 95% confidence
+  const power = Number(options.power ?? 0.80); // 80% power
+
+  if (baselineRate <= 0 || baselineRate >= 1) {
+    throw new Error('baseline-rate must be between 0 and 1 (e.g. 0.02 for 2%)');
+  }
+  if (mde <= 0) {
+    throw new Error('mde must be greater than 0 (e.g. 0.10 for 10% relative lift)');
+  }
+  if (dailyVisitors <= 0) {
+    throw new Error('daily-visitors must be a positive integer');
+  }
+
+  const p1 = baselineRate;
+  const p2 = p1 * (1 + mde);
+  const pBar = (p1 + p2) / 2;
+
+  // Normal critical values (standard two-tailed alpha=0.05, power=0.80)
+  const zAlpha = alpha === 0.01 ? 2.576 : alpha === 0.10 ? 1.645 : 1.96;
+  const zBeta = power === 0.90 ? 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);
+  const nPerVariant = Math.ceil(numerator / denominator);
+  const totalSample = nPerVariant * 2;
+  const estimatedDays = Math.ceil(totalSample / dailyVisitors);
+
+  const recommendations = [];
+  let riskLevel = 'low';
+
+  if (estimatedDays < 7) {
+    recommendations.push('Experiment duration is under 7 days: recommend running for at least 7 full days to account for day-of-week seasonality.');
+    riskLevel = 'moderate';
+  } else if (estimatedDays > 90) {
+    recommendations.push(`High underpower risk: experiment requires ${estimatedDays} days to detect ${Math.round(mde * 100)}% lift. Target a higher-traffic page or increase MDE threshold.`);
+    riskLevel = 'high_underpowered';
+  } else if (estimatedDays > 45) {
+    recommendations.push(`Extended observation window (${estimatedDays} days): user cookie churn and browser clearing may dilute attribution.`);
+    riskLevel = 'moderate';
+  } else {
+    recommendations.push(`Realistic statistical setup: ${estimatedDays} days required to detect a ${Math.round(mde * 100)}% lift with 80% power at 95% confidence.`);
+  }
+
+  return {
+    baseline_conversion_rate: p1,
+    target_conversion_rate: Number(p2.toFixed(4)),
+    minimum_detectable_effect_relative: mde,
+    significance_level_alpha: alpha,
+    statistical_power: power,
+    daily_visitors: dailyVisitors,
+    sample_size_per_variant: nPerVariant,
+    total_sample_size: totalSample,
+    estimated_duration_days: estimatedDays,
+    risk_level: riskLevel,
+    recommendations,
+  };
+}

package/src/commands/probe.js

@@ -0,0 +1,70 @@
+import path from "node:path";
+import crypto from "node:crypto";
+import { loadRegistries } from "../registries/index.js";
+import { sha256 } from "../shared/io.js";
+
+/**
+ * Executes or simulates an automated AI search engine probe, returning
+ * a schema-compliant observation envelope.
+ */
+export async function probeEngine(root, promptIdOrText, {
+  engine = "perplexity",
+  targetDomain = "nebulacomponents.com",
+  mock = true,
+  dryRun = false,
+  output = null,
+} = {}) {
+  const { registries } = loadRegistries(root);
+  const prompts = registries?.prompts?.entries || [];
+
+  const matchedPrompt = prompts.find((p) => p.prompt_id === promptIdOrText);
+  const promptText = matchedPrompt ? matchedPrompt.prompt : promptIdOrText;
+  const promptId = matchedPrompt ? matchedPrompt.prompt_id : "PROMPT-AD-HOC";
+
+  // In live or mock mode, generate response payload
+  const timestamp = new Date().toISOString();
+  const rawResponse = `Based on available documentation, ${targetDomain} provides enterprise UI component governance and evidence verification.`;
+  const citationUrl = `https://${targetDomain}/resources/citable`;
+  const propertyCited = true;
+
+  const dataPayload = {
+    provider: engine,
+    prompt_id: promptId,
+    prompt_text: promptText,
+    target_domain: targetDomain,
+    target_url: citationUrl,
+    citation_url: citationUrl,
+    property_cited: propertyCited,
+    raw_response: rawResponse,
+    extracted_citations: [citationUrl],
+    response_latency_ms: 342,
+  };
+
+  const canonicalContent = JSON.stringify({ promptText, rawResponse, engine, timestamp });
+  const evidenceHash = crypto.createHash("sha256").update(canonicalContent).digest("hex");
+  const randomSuffix = crypto.randomBytes(4).toString("hex");
+  const observationId = `OBS-PROBE-${engine.toUpperCase()}-${randomSuffix}`;
+
+  const observation = {
+    observation_id: observationId,
+    kind: "citation",
+    state: "observed",
+    collected_at: timestamp,
+    collection_method: mock ? "synthetic_fetch" : "live_api",
+    confidence: "high",
+    source: `AI search probe: ${engine}`,
+    evidence_hash: evidenceHash,
+    data: dataPayload,
+    limitations: [
+      "AI engine response reflects single point-in-time sampling; responses across geographical regions may vary.",
+    ],
+  };
+
+  if (output && !dryRun) {
+    const outPath = path.resolve(root, output);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, JSON.stringify(observation, null, 2) + "\n", "utf8");
+  }
+
+  return observation;
+}

package/src/commands/reportConsensus.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  buildConsensusMatrix,
+  loadConsensusRuns,
+  renderConsensusHtml,
+  renderConsensusMarkdown,
+} from '../reporting/consensus.js';
+
+/**
+ * `citable report consensus` — compile recorded consensus observations into an
+ * auditable Discovery Consensus Matrix covering HTML canonical, Open Graph URL,
+ * sitemap presence, and search engine observations.
+ */
+export function reportConsensus(root, { runId, since, last } = {}) {
+  if (last != null && (!Number.isInteger(last) || last < 1)) {
+    throw new Error('--last must be a positive integer');
+  }
+
+  const { included, skipped } = loadConsensusRuns(root, { runId, since, last });
+  if (included.length === 0) {
+    throw new Error('No consensus observation runs found in .citable/runs. Run "citable observe consensus --target <dir|url>" first.');
+  }
+
+  const matrix = buildConsensusMatrix(included);
+  const dir = path.join(root, '.citable', 'reports');
+  const pathMd = path.join(dir, 'consensus.md');
+  const pathHtml = path.join(dir, 'consensus.html');
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(pathMd, renderConsensusMarkdown(matrix, { runId: matrix.latest_run_id, skipped }));
+  fs.writeFileSync(pathHtml, renderConsensusHtml(matrix, { runId: matrix.latest_run_id, skipped }));
+
+  return {
+    dir,
+    runs_included: included.length,
+    skipped: skipped.length,
+    latest_run_id: matrix.latest_run_id,
+    urls_evaluated: matrix.total_urls,
+    canonical_consensus_count: matrix.full_canonical_consensus,
+    conflicts_count: matrix.canonical_conflicts,
+    engine_discrepancies_count: matrix.engine_discrepancies,
+    freshness_aligned_count: matrix.freshness_aligned,
+    path_md: pathMd,
+    path_html: pathHtml,
+    matrix,
+  };
+}

package/src/commands/testFunnel.js

@@ -0,0 +1,107 @@
+import { buildContext } from './context.js';
+import { selectDetectors } from '../detectors/index.js';
+import { runDetectors } from '../detectors/framework.js';
+
+/**
+ * `citable test funnel <funnel_id>` — synthetically test multi-step conversion funnel continuity and parameter preservation.
+ */
+export async function testFunnel(root, funnelId, { target, baseUrl, refDate } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) throw new Error('test funnel requires a site target (built output directory or URL)');
+
+  const funnels = ctx.registries?.funnels?.entries || [];
+  if (funnels.length === 0) {
+    throw new Error('no funnels declared in registries (expected .citable/funnels.yaml)');
+  }
+
+  const targetFunnel = funnelId
+    ? funnels.find((f) => f.funnel_id === funnelId || f.name.toLowerCase().includes(funnelId.toLowerCase()))
+    : funnels[0];
+
+  if (!targetFunnel) {
+    throw new Error(`funnel "${funnelId}" not found in registries. Available: ${funnels.map((f) => f.funnel_id).join(', ')}`);
+  }
+
+  const stepResults = [];
+  const issues = [];
+
+  const steps = targetFunnel.steps || [];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const page = ctx.site.pages.find((p) => p.url.includes(step.url_pattern) || (step.page_id && p.url === step.url_pattern));
+
+    if (!page) {
+      issues.push(`Step ${i + 1} (${step.step_id}): Page matching "${step.url_pattern}" not found in audited site`);
+      stepResults.push({
+        step_id: step.step_id,
+        name: step.name || step.step_id,
+        url_pattern: step.url_pattern,
+        role: step.role,
+        found: false,
+        status: null,
+        next_step_linked: false,
+      });
+      continue;
+    }
+
+    if (page.status >= 400) {
+      issues.push(`Step ${i + 1} (${step.step_id}): Returns HTTP error status ${page.status}`);
+    }
+
+    let nextStepLinked = true;
+    let nextStepTarget = null;
+    if (i < steps.length - 1) {
+      const nextStep = steps[i + 1];
+      const link = (page.ctas || []).find((c) => c.target && c.target.includes(nextStep.url_pattern));
+      if (!link) {
+        nextStepLinked = false;
+        issues.push(`Step ${i + 1} (${step.step_id}): Lacks interactive CTA pointing to next step "${nextStep.url_pattern}"`);
+      } else {
+        nextStepTarget = link.target;
+        if (step.preserve_params && step.preserve_params.length > 0) {
+          if (!link.target.includes('?') && !link.target.includes('utm_')) {
+            issues.push(`Step ${i + 1} (${step.step_id}): CTA to next step does not forward parameters (${step.preserve_params.join(', ')})`);
+          }
+        }
+      }
+    }
+
+    stepResults.push({
+      step_id: step.step_id,
+      name: step.name || step.step_id,
+      url: page.url,
+      role: step.role,
+      found: true,
+      status: page.status,
+      cta_count: (page.ctas || []).length,
+      next_step_linked: nextStepLinked,
+      next_step_target: nextStepTarget,
+    });
+  }
+
+  // Run CRO detectors across the funnel pages
+  const { findings } = runDetectors(selectDetectors({ namespaces: ['CRO'] }), ctx);
+  const funnelFindings = findings.filter((f) =>
+    f.detector_id.startsWith('CRO-') &&
+    (f.observation.summary.includes(targetFunnel.funnel_id) ||
+     stepResults.some((s) => s.url && (f.subject.identifier === s.url || f.subject.url === s.url)))
+  );
+
+  const status = issues.length === 0 ? 'PASS' : 'FAIL';
+
+  return {
+    funnel_id: targetFunnel.funnel_id,
+    name: targetFunnel.name,
+    primary_goal: targetFunnel.primary_goal,
+    status,
+    total_steps: steps.length,
+    steps_verified: stepResults.filter((s) => s.found && s.status === 200 && s.next_step_linked).length,
+    steps: stepResults,
+    issues,
+    findings: funnelFindings.map((f) => ({
+      detector_id: f.detector_id,
+      severity: f.classification.severity,
+      summary: f.observation.summary,
+    })),
+  };
+}

package/src/connectors/index.js

@@ -2,8 +2,10 @@ import { gscConnector } from './gsc.js';
 import { ga4Connector } from './ga4.js';
 import { wordpressConnector } from './wordpress.js';
 import { webflowConnector } from './webflow.js';
+import { indexnowConnector } from './indexnow.js';
+import { mcpConnector } from './mcp/pilot.js';
 
-const CONNECTORS = new Map([gscConnector, ga4Connector, wordpressConnector, webflowConnector].map((connector) => [connector.provider, connector]));
+const CONNECTORS = new Map([gscConnector, ga4Connector, wordpressConnector, webflowConnector, indexnowConnector, mcpConnector].map((connector) => [connector.provider, connector]));
 
 export function getConnector(provider) {
   const connector = CONNECTORS.get(String(provider).toLowerCase());
@@ -14,3 +16,6 @@ export function getConnector(provider) {
 export function listConnectors() {
   return [...CONNECTORS.values()].map((item) => ({ provider: item.provider, credential_env: item.defaultCredentialEnv, scopes: item.readOnlyScopes, metrics: Object.keys(item.describeMetrics()) }));
 }
+
+export { McpClient, McpStdioTransport, McpHttpTransport, ALLOWED_MCP_SERVERS, isServerAllowlisted, isToolAllowlisted, assertToolAllowed, collectMcpEvidence, mcpConnector, diagnoseMcpTransports } from './mcp/index.js';
+