@nebulacomponents/citable 1.15.1 → 1.17.0

package/src/monitoring/alertDelivery.js

@@ -18,6 +18,16 @@ export function filterAlerts(alerts = [], minSeverity = 'informational') {
 
 export function buildAlertPayload({ runA, runB, source = 'monitor', summary = {}, alerts = [], timestamp = nowIso() } = {}) {
   const critOrHigh = alerts.filter((a) => ['critical', 'high'].includes(a.severity)).length;
+  const regressionCount = alerts.filter((a) => [
+    'index_loss',
+    'canonical_regression',
+    'citation_presence_change',
+    'representation_divergence_observed',
+    'state_change',
+    'observation_missing',
+    'share_of_voice_drop',
+    'stance_regression',
+  ].includes(a.type)).length;
   return {
     event: 'citable.regression_alert',
     source,
@@ -26,6 +36,7 @@ export function buildAlertPayload({ runA, runB, source = 'monitor', summary = {}
     run_b: runB,
     summary: {
       total_alerts: alerts.length,
+      regression_count: regressionCount,
       critical_or_high: critOrHigh,
       ...summary,
     },
@@ -36,6 +47,7 @@ export function buildAlertPayload({ runA, runB, source = 'monitor', summary = {}
 export async function dispatchAlertWebhook(root, payload, {
   webhookUrl,
   headers = {},
+  secret = process.env.CITABLE_WEBHOOK_SECRET,
   timeoutMs = 10000,
   fetchImpl = globalThis.fetch,
   lookup,
@@ -50,7 +62,23 @@ export async function dispatchAlertWebhook(root, payload, {
   const payloadString = JSON.stringify(payload);
   const payloadHash = sha256(Buffer.from(payloadString));
   const deliveriesDir = path.join(root, '.citable', 'monitoring', 'deliveries');
+  const dispatchesDir = path.join(root, '.citable', 'monitoring', 'dispatches');
   const receiptFile = path.join(deliveriesDir, `${deliveryId}.json`);
+  const dispatchFile = path.join(dispatchesDir, `${deliveryId}.json`);
+
+  const requestHeaders = {
+    'content-type': 'application/json',
+    'x-citable-event': 'citable.regression_alert',
+    'x-citable-delivery': deliveryId,
+    ...headers,
+  };
+
+  let signature = null;
+  if (secret) {
+    const hmac = crypto.createHmac('sha256', secret).update(payloadString).digest('hex');
+    signature = `sha256=${hmac}`;
+    requestHeaders['x-citable-signature'] = signature;
+  }
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -62,12 +90,7 @@ export async function dispatchAlertWebhook(root, payload, {
   try {
     const res = await fetchImpl(webhookUrl, {
       method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        'x-citable-event': 'citable.regression_alert',
-        'x-citable-delivery': deliveryId,
-        ...headers,
-      },
+      headers: requestHeaders,
       body: payloadString,
       signal: controller.signal,
     });
@@ -89,10 +112,81 @@ export async function dispatchAlertWebhook(root, payload, {
     status_code: statusCode,
     success,
     payload_hash: payloadHash,
+    signature,
     error: errorMessage,
     summary: payload.summary,
   };
 
   writeJson(receiptFile, receipt);
-  return { ...receipt, receipt_file: receiptFile };
+  writeJson(dispatchFile, receipt);
+  return { ...receipt, receipt_file: receiptFile, dispatch_file: dispatchFile };
+}
+
+export function formatSlackPayload(payload) {
+  const summary = payload.summary || {};
+  const alertLines = (payload.alerts || []).slice(0, 5).map((a) => `• *[${a.severity.toUpperCase()}]* ${a.message || a.detail || a.type}`);
+  return {
+    text: `Citable Alert: ${summary.total_alerts || 0} alerts detected (${summary.critical_or_high || 0} critical/high)`,
+    blocks: [
+      {
+        type: 'header',
+        text: { type: 'plain_text', text: '🚨 Citable Search & AEO Governance Alert', emoji: true },
+      },
+      {
+        type: 'section',
+        fields: [
+          { type: 'mrkdwn', text: `*Total Alerts:* ${summary.total_alerts || 0}` },
+          { type: 'mrkdwn', text: `*Critical / High:* ${summary.critical_or_high || 0}` },
+          { type: 'mrkdwn', text: `*Source:* ${payload.source || 'monitor'}` },
+          { type: 'mrkdwn', text: `*Generated At:* ${payload.generated_at}` },
+        ],
+      },
+      ...(alertLines.length > 0 ? [{
+        type: 'section',
+        text: { type: 'mrkdwn', text: alertLines.join('\n') },
+      }] : []),
+    ],
+  };
 }
+
+export function formatTeamsPayload(payload) {
+  const summary = payload.summary || {};
+  return {
+    '@type': 'MessageCard',
+    '@context': 'http://schema.org/extensions',
+    summary: 'Citable Search & AEO Governance Alert',
+    themeColor: summary.critical_or_high > 0 ? 'D9381E' : '0076D7',
+    title: 'Citable Governance Alert',
+    sections: [
+      {
+        activityTitle: `Total Alerts: ${summary.total_alerts || 0} (${summary.critical_or_high || 0} critical/high)`,
+        facts: [
+          { name: 'Source', value: payload.source || 'monitor' },
+          { name: 'Timestamp', value: payload.generated_at },
+        ],
+        text: (payload.alerts || []).slice(0, 5).map((a) => `**[${a.severity.toUpperCase()}]** ${a.message || a.detail || a.type}`).join('\n\n'),
+      },
+    ],
+  };
+}
+
+export function formatDiscordPayload(payload) {
+  const summary = payload.summary || {};
+  return {
+    content: `🚨 **Citable Alert**: ${summary.total_alerts || 0} alerts detected`,
+    embeds: [
+      {
+        title: 'Citable Search & AEO Governance Alert',
+        color: summary.critical_or_high > 0 ? 14232606 : 3447003,
+        fields: [
+          { name: 'Total Alerts', value: String(summary.total_alerts || 0), inline: true },
+          { name: 'Critical/High', value: String(summary.critical_or_high || 0), inline: true },
+          { name: 'Source', value: payload.source || 'monitor', inline: true },
+        ],
+        description: (payload.alerts || []).slice(0, 5).map((a) => `• **[${a.severity.toUpperCase()}]** ${a.message || a.detail || a.type}`).join('\n'),
+        timestamp: payload.generated_at,
+      },
+    ],
+  };
+}
+

package/src/observations/attribution.js

@@ -0,0 +1,217 @@
+/**
+ * Citation Attribution and Claim Entailment Verification.
+ *
+ * Evaluates whether generative engine answers accurately reflect registered
+ * claim assertions or attribute distorted, negated, or contradicted claims to
+ * an entity or brand.
+ *
+ * Governed Invariants:
+ * - Does not guess or extrapolate; evaluates strictly against registered claims.
+ * - Distinguishes between supported claims, distorted claims, and unsupported claims.
+ * - Emits schema-validated attribution observation envelopes.
+ */
+
+import { envelope, observationRun, readInput } from "./common.js";
+import { matchClaim } from "./claimDiff.js";
+import { substantiate } from "../commands/substantiate.js";
+import { loadRegistries } from "../registries/index.js";
+
+const NEGATION_PATTERNS = [
+  /\b(?:does\s+not|doesn't|cannot|can't|fails\s+to|lacks|missing|no\s+longer|unable\s+to|without|refuses\s+to|not\s+supported)\b/i,
+];
+
+function splitSentences(text) {
+  if (!text) return [];
+  return String(text)
+    .replace(/([.?!])\s+/g, "$1|§|")
+    .split("|§|")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 5);
+}
+
+function hasNegation(text) {
+  return NEGATION_PATTERNS.some((p) => p.test(text));
+}
+
+export function evaluateAnswerAttribution(answerText, entity, {
+  claims = [],
+  citationUrl = null,
+  assessmentByClaimId = new Map(),
+  reviewer = null,
+} = {}) {
+  const names = [entity.canonical_name, ...(entity.aliases || [])].map((n) => n.toLowerCase());
+  const lowerAnswer = String(answerText || "").toLowerCase();
+  const mentioned = names.some((n) => lowerAnswer.includes(n));
+
+  if (!mentioned) {
+    return {
+      mentioned: false,
+      entity_id: entity.entity_id,
+      evaluations: [],
+      has_distorted_claims: false,
+      supported_count: 0,
+      distorted_count: 0,
+      unsupported_count: 0,
+    };
+  }
+
+  const sentences = splitSentences(answerText);
+  const evaluations = [];
+  const relevantClaims = claims.filter((c) => !c.entity || c.entity === entity.entity_id);
+
+  for (const sentence of sentences) {
+    const sentenceMentionsEntity = names.some((n) => sentence.toLowerCase().includes(n));
+    if (!sentenceMentionsEntity && sentences.length > 1) continue;
+
+    const matched = matchClaim(sentence, relevantClaims, citationUrl);
+    if (!matched) continue;
+
+    const assessment = assessmentByClaimId.get(matched.claim_id);
+    const claimContradicted = matched.status === "contradicted" ||
+      assessment?.outcome === "contradicted" ||
+      (matched.contradictory_sources && matched.contradictory_sources.length > 0);
+    const claimExpired = matched.status === "expired" || (matched.expires && new Date(matched.expires) < new Date());
+    const sentenceNegated = hasNegation(sentence);
+
+    let attributionStatus;
+    const reasons = [];
+
+    if (claimContradicted) {
+      attributionStatus = "distorted";
+      reasons.push(`Answer cites claim "${matched.claim_id}" which is contradicted in registry.`);
+    } else if (sentenceNegated) {
+      attributionStatus = "distorted";
+      reasons.push(`Answer negates registered capability declared in claim "${matched.claim_id}".`);
+    } else if (claimExpired) {
+      attributionStatus = "distorted";
+      reasons.push(`Answer asserts claim "${matched.claim_id}" which has expired (${matched.expires}).`);
+    } else if (matched.status === "unverified" || assessment?.outcome === "unsupported") {
+      attributionStatus = "unsupported";
+      reasons.push(`Answer attributes unverified claim "${matched.claim_id}".`);
+    } else {
+      attributionStatus = "supported";
+      reasons.push(`Answer accurately attributes verified claim "${matched.claim_id}".`);
+    }
+
+    // Check exclusion violations
+    if (matched.exclusions && matched.exclusions.length > 0) {
+      for (const exclusion of matched.exclusions) {
+        if (sentence.toLowerCase().includes(exclusion.toLowerCase())) {
+          attributionStatus = "distorted";
+          reasons.push(`Answer asserts feature listed under exclusions: "${exclusion}".`);
+        }
+      }
+    }
+
+    evaluations.push({
+      claim_id: matched.claim_id,
+      claim_text: matched.claim,
+      assertion_excerpt: sentence,
+      attribution_status: attributionStatus,
+      reasons,
+    });
+  }
+
+  const supportedCount = evaluations.filter((e) => e.attribution_status === "supported").length;
+  const distortedCount = evaluations.filter((e) => e.attribution_status === "distorted").length;
+  const unsupportedCount = evaluations.filter((e) => e.attribution_status === "unsupported").length;
+
+  return {
+    mentioned: true,
+    entity_id: entity.entity_id,
+    canonical_name: entity.canonical_name,
+    evaluations,
+    has_distorted_claims: distortedCount > 0,
+    supported_count: supportedCount,
+    distorted_count: distortedCount,
+    unsupported_count: unsupportedCount,
+  };
+}
+
+export async function observeAttribution(root, options = {}) {
+  const input = readInput(options.input);
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join("; ")}`);
+
+  const entities = (registries.entities?.entries || []).filter((e) => e.status !== "retired");
+  if (!entities.length) throw new Error("no active entities found in entity registry");
+
+  const claims = registries.claims?.entries || [];
+
+  // Build claim assessments
+  const assessmentMap = new Map();
+  try {
+    const subRes = substantiate(root);
+    for (const item of subRes.assessments || []) {
+      assessmentMap.set(item.claim_id, item);
+    }
+  } catch {}
+
+  const targetEntities = options.entity
+    ? entities.filter((e) => e.entity_id === options.entity || e.canonical_name.toLowerCase() === options.entity.toLowerCase())
+    : entities;
+
+  if (options.entity && !targetEntities.length) {
+    throw new Error(`entity not found: ${options.entity}`);
+  }
+
+  const doc = input.value;
+  const items = Array.isArray(doc)
+    ? doc
+    : doc.observations || doc.items || doc.answers || doc.prompts || [doc];
+
+  const observations = [];
+  for (const item of items) {
+    const answerText = item.answer_text || item.answer || item.text || item.data?.answer_text || "";
+    if (!answerText) continue;
+
+    const promptId = item.prompt_id || item.data?.prompt_id || "unknown";
+    const promptText = item.prompt_text || item.data?.prompt_text || null;
+    const engine = item.provider || item.engine || item.data?.provider || item.data?.engine || "unknown";
+    const citationUrl = item.citations?.[0]?.url || item.url || null;
+    const reviewer = options.reviewer || item.reviewer || item.evaluator || null;
+
+    for (const entity of targetEntities) {
+      const evaluation = evaluateAnswerAttribution(answerText, entity, {
+        claims,
+        citationUrl,
+        assessmentByClaimId: assessmentMap,
+        reviewer,
+      });
+
+      if (!evaluation.mentioned) continue;
+
+      const data = {
+        prompt_id: promptId,
+        prompt_text: promptText,
+        engine,
+        entity_id: entity.entity_id,
+        canonical_name: entity.canonical_name,
+        citation_url: citationUrl,
+        evaluations: evaluation.evaluations,
+        has_distorted_claims: evaluation.has_distorted_claims,
+        supported_count: evaluation.supported_count,
+        distorted_count: evaluation.distorted_count,
+        unsupported_count: evaluation.unsupported_count,
+        reviewer,
+      };
+
+      const raw = JSON.stringify({ item, evaluation });
+      observations.push(envelope("attribution", data, {
+        method: reviewer ? "human_review" : "static_analysis",
+        source: input.file,
+        state: evaluation.has_distorted_claims ? "review_required" : "observed",
+        confidence: reviewer ? "confirmed" : "medium",
+        raw,
+        limitations: [
+          "Claim attribution evaluation maps extracted generative assertions against registered claims.",
+          "Attribution findings require human review for authoritative legal or compliance determination.",
+        ],
+      }));
+    }
+  }
+
+  return observationRun(root, "observe attribution", input.file, observations, {
+    rawInputs: { attribution_input: input.raw },
+  });
+}

package/src/registries/index.js

@@ -33,6 +33,10 @@ export const REGISTRY_SPECS = [
   { 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' },
+  // Conversion Rate Optimization suite — funnels
+  { file: 'funnels.yaml',      kind: 'funnels',     schema: 'funnel.schema.json',     idField: 'funnel_id' },
+  // Multi-property fleet governance
+  { file: 'fleet.yaml',        kind: 'fleet',       schema: 'fleet.schema.json',      idField: 'property_id' },
 ];
 
 export function contextDir(root) {
@@ -232,6 +236,16 @@ export function checkReferentialIntegrity(registries) {
     }
   }
 
+  // funnels: step.page_id should reference known pages
+  for (const fn of registries.funnels?.entries || []) {
+    const prefix = `funnels/${fn.funnel_id}`;
+    for (const step of fn.steps || []) {
+      if (step.page_id && !ids.pages?.has(step.page_id)) {
+        problems.push(`${prefix}: step "${step.step_id}" references unknown page id "${step.page_id}"`);
+      }
+    }
+  }
+
   return problems;
 }