@nebulacomponents/citable 1.18.1 → 1.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.18.1",
+  "version": "1.18.2",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",
@@ -52,6 +52,7 @@
     "test:integration": "node --test --test-concurrency=1 --test-reporter=spec 'tests/integration/**/*.test.js'",
     "test:e2e": "node --test --test-concurrency=1 'tests/e2e/**/*.test.js'",
     "build:dist": "node scripts/build-dist.js",
+    "validate:schemas": "node scripts/validate-schemas.js",
     "release:prepare": "node scripts/release-process.js prepare",
     "release:validate": "node scripts/release-process.js validate",
     "release:manifest": "node scripts/release-governance.js manifest",

package/schemas/cro-report.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/cro-report.schema.json",
+  "title": "Enterprise CRO & Journey Intelligence Executive Report",
+  "type": "object",
+  "required": [
+    "fact_status",
+    "report_title",
+    "client_name",
+    "target_domain",
+    "generated_at",
+    "overall_conversion_readiness",
+    "pillars",
+    "evidence_register",
+    "decision_summary",
+    "generation_provenance"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "fact_status": { "type": "string" },
+    "epistemic_status": { "type": "string" },
+    "report_title": { "type": "string" },
+    "client_name": { "type": "string" },
+    "target_domain": { "type": "string" },
+    "generated_at": { "type": "string" },
+    "overall_conversion_readiness": { "type": "number", "minimum": 0, "maximum": 100 },
+    "epistemological_framework": {
+      "type": "object",
+      "properties": {
+        "observation": { "type": "string" },
+        "hypothesis": { "type": "string" },
+        "causation": { "type": "string" },
+        "unknowns": { "type": "string" }
+      }
+    },
+    "pillars": {
+      "type": "object",
+      "required": [
+        "1", "2", "3", "4", "5", "6", "7", "8", "9", "10",
+        "11", "12", "13", "14", "15", "16", "17", "18", "19", "20",
+        "21", "22", "23", "24", "25"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[0-9]+$": {
+          "type": "object",
+          "required": ["name", "data"],
+          "properties": {
+            "name": { "type": "string" },
+            "data": {}
+          }
+        }
+      }
+    },
+    "evidence_register": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["evidence_id", "source", "methodology", "confidence_level"],
+        "properties": {
+          "evidence_id": { "type": "string", "pattern": "^EVD-CRO-[0-9]+$" },
+          "source": { "type": "string" },
+          "title": { "type": "string" },
+          "observation_date": { "type": "string" },
+          "methodology": { "type": "string" },
+          "confidence_level": { "type": "string" },
+          "data_snapshot": {}
+        }
+      }
+    },
+    "decision_summary": {
+      "type": "object",
+      "required": [
+        "observed_conversion_failures",
+        "evidence_supported_hypotheses",
+        "causal_findings",
+        "unresolved_unknowns",
+        "recommended_interventions"
+      ],
+      "properties": {
+        "observed_conversion_failures": { "type": "array", "items": { "type": "string" } },
+        "evidence_supported_hypotheses": { "type": "array", "items": { "type": "string" } },
+        "causal_findings": { "type": "array", "items": { "type": "string" } },
+        "unresolved_unknowns": { "type": "array", "items": { "type": "string" } },
+        "recommended_interventions": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "generation_provenance": {
+      "type": "object",
+      "required": [
+        "generated_at",
+        "generator_version",
+        "generation_mode",
+        "source_type",
+        "synthetic_evidence"
+      ],
+      "properties": {
+        "generated_at": { "type": "string" },
+        "generator_version": { "type": "string" },
+        "generation_mode": { "type": "string", "enum": ["CONTRACTUAL", "DRAFT", "NON_CONTRACTUAL_SAMPLE"] },
+        "source_type": { "type": "string" },
+        "source_identifier": { "type": ["string", "null"] },
+        "source_findings_count": { "type": "integer", "minimum": 0 },
+        "integrity_hash": { "type": ["string", "null"] },
+        "synthetic_evidence": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/search-report.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/search-report.schema.json",
+  "title": "Enterprise Search Intelligence & Governance Executive Report",
+  "type": "object",
+  "required": [
+    "fact_status",
+    "report_title",
+    "client_name",
+    "target_domain",
+    "generated_at",
+    "overall_readiness_score",
+    "pillars",
+    "evidence_register",
+    "decision_summary",
+    "generation_provenance"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "fact_status": { "type": "string" },
+    "epistemic_status": { "type": "string" },
+    "report_title": { "type": "string" },
+    "client_name": { "type": "string" },
+    "target_domain": { "type": "string" },
+    "generated_at": { "type": "string" },
+    "overall_readiness_score": { "type": "number", "minimum": 0, "maximum": 100 },
+    "pillars": {
+      "type": "object",
+      "required": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[0-9]+$": {
+          "type": "object",
+          "required": ["name", "data"],
+          "properties": {
+            "name": { "type": "string" },
+            "data": {}
+          }
+        }
+      }
+    },
+    "evidence_register": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["evidence_id", "source", "methodology", "confidence_level"],
+        "properties": {
+          "evidence_id": { "type": "string", "pattern": "^EVD-SRCH-[0-9]+$" },
+          "source": { "type": "string" },
+          "title": { "type": "string" },
+          "observation_date": { "type": "string" },
+          "methodology": { "type": "string" },
+          "confidence_level": { "type": "string" },
+          "data_snapshot": {}
+        }
+      }
+    },
+    "decision_summary": {
+      "type": "object",
+      "required": [
+        "confirmed_findings",
+        "inferred_opportunities",
+        "unresolved_unknowns",
+        "strategic_risks",
+        "actions_requiring_leadership_approval"
+      ],
+      "properties": {
+        "confirmed_findings": { "type": "array", "items": { "type": "string" } },
+        "inferred_opportunities": { "type": "array", "items": { "type": "string" } },
+        "unresolved_unknowns": { "type": "array", "items": { "type": "string" } },
+        "strategic_risks": { "type": "array", "items": { "type": "string" } },
+        "actions_requiring_leadership_approval": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "generation_provenance": {
+      "type": "object",
+      "required": [
+        "generated_at",
+        "generator_version",
+        "generation_mode",
+        "source_type",
+        "synthetic_evidence"
+      ],
+      "properties": {
+        "generated_at": { "type": "string" },
+        "generator_version": { "type": "string" },
+        "generation_mode": { "type": "string", "enum": ["CONTRACTUAL", "DRAFT", "NON_CONTRACTUAL_SAMPLE"] },
+        "source_type": { "type": "string" },
+        "source_identifier": { "type": ["string", "null"] },
+        "source_findings_count": { "type": "integer", "minimum": 0 },
+        "integrity_hash": { "type": ["string", "null"] },
+        "synthetic_evidence": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/sow.schema.json

@@ -52,7 +52,7 @@
       },
       "additionalProperties": false
     },
-    "effective_date": { "type": "string" },
+    "effective_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
     "term_days": { "type": "integer", "minimum": 1 },
     "currency": { "type": "string", "enum": ["USD"] },
     "currency_minor_unit_exponent": { "type": "integer", "enum": [2] },
@@ -377,7 +377,8 @@
           "evidence_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
           "severity": { "type": "string" },
           "target_subject": { "type": "string" },
-          "acceptance_criteria": { "type": "string" }
+          "acceptance_criteria": { "type": "string" },
+          "acceptance_basis": { "type": "string" }
         },
         "additionalProperties": false
       }

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.18.1
+version: 1.18.2
 ---
 
 # Citable — evidence and change control for search and AI citation readiness

package/skill/commands/artifact-interchange.md

@@ -7,6 +7,7 @@ external workspaces without changing its canonical bytes.
 citable artifacts export <run-id> --output <directory>
 citable artifacts verify --input <directory>
 citable artifacts import --input <directory>
+citable artifacts verify-customer <file>
 ```
 
 An export contains the original run package plus
@@ -26,3 +27,7 @@ was authentic, that external observations were representative or complete, or
 that an intervention caused an outcome. Hosted tenancy, authentication,
 storage, retention, billing, scheduling, and dashboards are outside this
 contract.
+
+Use `citable artifacts verify-customer <file>` to validate customer deliverables
+(SOW, Search, and CRO JSON reports) against their JSON Schemas, verify arithmetic
+consistency (e.g. minor-unit fee totals), and reject unescaped script or event handler injections.

package/skill/commands/remediation.md

@@ -12,7 +12,7 @@ The remediation suite provides safe, gated code fixes for deterministic technica
 
 ## 1. Safe Patch Application (`citable remediate`)
 
-1. **Framework Detection**: Identifies target source syntax (`jsx`, `tsx`, `vue`, `html`). Fails closed on unknown or ambiguous frameworks.
+1. **Framework Detection**: Identifies target source syntax (`jsx`, `tsx`, `vue`, `svelte`, `html`). Fails closed on unknown or ambiguous frameworks.
 2. **Idempotent AST Patching**: Patches are mathematically verified to be idempotent (`applyPatchDetailed`): applying the patch a second time produces an identical AST (a fixed point).
 3. **Structural Validation Gate**: Runs `validatePatchedSource` to confirm that the patch does not break AST structure, introduce syntax errors, or alter unrelated code blocks.
 4. **Confidence Threshold**: Computes an explicit multi-factor confidence score (`computeConfidence`). `--write` is refused if confidence falls below `0.70`.

package/skill/commands/sow.md

@@ -1,6 +1,6 @@
 ---
 command: /citable sow generate [--target <dir|url>] [--run <id>] [--budget <amount>] [--budget-minor <cents>] [--format md|html|json] [--output <path>] [--sample] [--draft]
-purpose: Generate a contractually binding, evidence-traceable enterprise Statement of Work (SOW) from verified audit findings through a formal 7-gate scope admissibility filter and 7-column traceability matrix.
+purpose: Generate a contractually binding, evidence-traceable enterprise Statement of Work (SOW) from verified audit findings through a formal 8-gate scope admissibility filter and 7-column traceability matrix.
 preconditions: [at least one finalized audit run with verified findings or live target; sample mode required for synthetic demonstrations]
 failure_behaviour: absent or unverified findings in contractual mode -> NoFindingsError; all findings refused -> NoAdmissibleRequirementsError; non-existent run -> RunNotFoundError; negative or sub-cent budget -> BudgetCalculationError; invariant drift -> SowInvariantError
 artifacts_created: [SOW.md, SOW.html, or SOW.json at specified output path]
@@ -34,7 +34,7 @@ Acceptance Test (automated closed-loop detector rerun)
 
 ## 2. The Scope Admissibility Gate
 
-Audit findings do NOT automatically become contractual obligations. Every candidate finding must pass 7 admissibility gates:
+Audit findings do NOT automatically become contractual obligations. Every candidate finding must pass 8 admissibility gates:
 
 | Gate | Verification Check | Failure Refusal Code | Contractual Handling |
 | :--- | :--- | :--- | :--- |

package/src/analysis/behavioral.js

@@ -2,10 +2,11 @@
  * Analyze behavioral interaction evidence across funnels, sessions, cohorts, and interaction signals.
  */
 export function analyzeBehavioralTelemetry(telemetryData = {}) {
-  const sessions = telemetryData.sessions || telemetryData.metrics || {};
-  const cohorts = telemetryData.cohorts || {};
-  const interactions = telemetryData.interactions || {};
-  const funnelSteps = telemetryData.funnel || [];
+  const data = telemetryData || {};
+  const sessions = data.sessions || data.metrics || {};
+  const cohorts = data.cohorts || {};
+  const interactions = data.interactions || {};
+  const funnelSteps = data.funnel || [];
 
   const findings = [];
   const frictionIndicators = [];

package/src/analysis/eeat.js

@@ -1,5 +1,6 @@
 import { parse as parseHtml } from 'node-html-parser';
 import { registryPageFor, safePath } from '../detectors/framework.js';
+import { isAuthoritativeDomain } from '../shared/domainUtils.js';
 
 /**
  * Evaluates on-page content against Google's E-E-A-T rubric on a 0.0 - 5.0 scale.
@@ -101,7 +102,7 @@ export function evaluateEeat(page, ctx = {}) {
   const BIO_RX = /\b(?:ph\.?d|m\.?d|engineer|architect|researcher|director|specialist|consultant|analyst|professor|founder|lead)\b/i;
   if (authorSameAs || BIO_RX.test(text)) {
     expertScore += 1.2;
-    expertSignals.push('Author credentials, professional title, or external disambiguation profiles verified');
+    expertSignals.push(authorSameAs ? 'Author disambiguation profile linked' : 'Author professional title or credentials indicator detected');
   } else {
     expertMissing.push('Link author to authoritative profile (sameAs: LinkedIn, ORCID, GitHub) and list credentials');
   }
@@ -132,12 +133,7 @@ export function evaluateEeat(page, ctx = {}) {
   }));
 
   const externalLinks = links.filter((l) => /^https?:\/\//i.test(l.href));
-  const authoritativeDomains = externalLinks.filter((l) => {
-    const u = l.href.toLowerCase();
-    return u.includes('.edu') || u.includes('.gov') || u.includes('.org') ||
-           u.includes('w3.org') || u.includes('rfc-editor.org') || u.includes('github.com') ||
-           u.includes('arxiv.org') || u.includes('developer.mozilla.org') || u.includes('web.dev');
-  });
+  const authoritativeDomains = externalLinks.filter((l) => isAuthoritativeDomain(l.href));
 
   if (authoritativeDomains.length >= 2) {
     authScore += 1.5;
@@ -150,9 +146,13 @@ export function evaluateEeat(page, ctx = {}) {
     authMissing.push('Add outbound citations to primary sources and industry standards');
   }
 
-  // Registry claim grounding
+  // Registry claim grounding (strictly page-scoped)
   const claims = ctx.registries?.claims?.entries || [];
-  const pageClaims = claims.filter((c) => c.canonical_url === page.url || c.claim_id);
+  const pageClaims = claims.filter((c) => {
+    if (!c) return false;
+    const target = c.canonical_url || c.subject?.url || c.page_id;
+    return Boolean(target && (target === page.url || target === page.canonicalUrl));
+  });
   const verifiedClaims = pageClaims.filter((c) => c.status === 'verified');
   if (verifiedClaims.length >= 1) {
     authScore += 1.5;
@@ -259,6 +259,7 @@ export function evaluateEeat(page, ctx = {}) {
   return {
     url: page.url,
     fact_status: 'modeled_rubric_evaluation',
+    epistemic_status: 'MODELED',
     methodology: 'Google Search Quality Rater Guidelines (E-E-A-T Evaluative Rubric)',
     disclaimer: 'E-E-A-T is an evaluative heuristic rubric modeled on Quality Rater Guidelines, not an algorithmic ranking score. Google does not calculate a single E-E-A-T metric.',
     composite_score: composite,

package/src/analysis/offpage.js

@@ -1,4 +1,5 @@
 import { URL } from 'node:url';
+import { extractHostname, extractRegistrableDomain, extractPublicSuffix } from '../shared/domainUtils.js';
 
 const SPAM_TLDS = new Set([
   'top', 'work', 'gdn', 'click', 'monster', 'buzz', 'cfd', 'sbs',
@@ -7,27 +8,6 @@ const SPAM_TLDS = new Set([
 
 const COMMERCIAL_SPAM_KEYWORDS = /\b(casino|viagra|cialis|payday\s*loans?|replica|cheap\s*essay|free\s*download|warez|crack|hack|gambling|betting|slots|crypto\s*airdrop)\b/i;
 
-function extractHostname(urlString) {
-  try {
-    return new URL(urlString).hostname.toLowerCase();
-  } catch {
-    return null;
-  }
-}
-
-function extractRootDomain(hostname) {
-  if (!hostname) return null;
-  const parts = hostname.split('.');
-  if (parts.length <= 2) return hostname;
-  return parts.slice(-2).join('.');
-}
-
-function extractTld(hostname) {
-  if (!hostname) return null;
-  const parts = hostname.split('.');
-  return parts.at(-1) || null;
-}
-
 /**
  * Audit an inbound backlink profile for authority distribution and toxic domain risks.
  */
@@ -59,18 +39,18 @@ export function auditBacklinkProfile(backlinks, { targetDomain = null } = {}) {
   for (const link of links) {
     const srcHost = extractHostname(link.source_url);
     if (!srcHost) continue;
-    const rootDomain = extractRootDomain(srcHost) || srcHost;
-    const tld = extractTld(srcHost);
+    const rootDomain = extractRegistrableDomain(srcHost) || srcHost;
+    const tld = extractPublicSuffix(srcHost);
     const anchor = (link.anchor_text || '').trim();
-    const rel = (link.rel || '').toLowerCase();
-    const isNofollow = rel.includes('nofollow');
-    const isUgc = rel.includes('ugc');
-    const isSponsored = rel.includes('sponsored');
+    const relTokens = (link.rel || '').toLowerCase().split(/\s+/).filter(Boolean);
+    const isNofollow = relTokens.includes('nofollow');
+    const isUgc = relTokens.includes('ugc');
+    const isSponsored = relTokens.includes('sponsored');
 
     if (isNofollow) nofollowCount++;
-    else if (isUgc) ugcCount++;
-    else if (isSponsored) sponsoredCount++;
-    else dofollowCount++;
+    if (isUgc) ugcCount++;
+    if (isSponsored) sponsoredCount++;
+    if (!isNofollow && !isUgc && !isSponsored) dofollowCount++;
 
     // Deep link vs homepage
     const targetPath = link.target_url ? (() => { try { return new URL(link.target_url).pathname; } catch { return '/'; } })() : '/';
@@ -78,13 +58,13 @@ export function auditBacklinkProfile(backlinks, { targetDomain = null } = {}) {
     else deepLinksCount++;
 
     // Anchor categorization
-    if (normalizedTarget && (anchor.toLowerCase().includes(normalizedTarget) || normalizedTarget.includes(anchor.toLowerCase()))) {
+    if (anchor && normalizedTarget && (anchor.toLowerCase().includes(normalizedTarget) || (anchor.length >= 3 && normalizedTarget.includes(anchor.toLowerCase())))) {
       anchorTypes.branded++;
-    } else if (/^https?:\/\//i.test(anchor) || anchor.includes('www.') || anchor.includes('.com') || anchor.includes('.org')) {
+    } else if (anchor && (/^https?:\/\//i.test(anchor) || anchor.includes('www.') || anchor.includes('.com') || anchor.includes('.org'))) {
       anchorTypes.naked_url++;
-    } else if (GENERIC_ANCHORS.test(anchor)) {
+    } else if (anchor && GENERIC_ANCHORS.test(anchor)) {
       anchorTypes.generic++;
-    } else if (COMMERCIAL_SPAM_KEYWORDS.test(anchor) || /\b(buy|best|cheap|discount|order)\b/i.test(anchor)) {
+    } else if (anchor && (COMMERCIAL_SPAM_KEYWORDS.test(anchor) || /\b(buy|best|cheap|discount|order)\b/i.test(anchor))) {
       anchorTypes.exact_match_commercial++;
     } else {
       anchorTypes.other++;
@@ -166,8 +146,9 @@ export function auditBacklinkProfile(backlinks, { targetDomain = null } = {}) {
     }
   }
 
-  // Sort toxic domains by severity (critical first)
-  toxicDomains.sort((a, b) => (a.risk_tier === 'critical' ? -1 : 1));
+  // Sort flagged domains by severity (critical first) with deterministic secondary key
+  const tierWeight = { critical: 2, high: 1, clean: 0 };
+  toxicDomains.sort((a, b) => (tierWeight[b.risk_tier] || 0) - (tierWeight[a.risk_tier] || 0) || a.domain.localeCompare(b.domain));
 
   const totalLinks = links.length;
   const totalDomains = referringDomains.size;
@@ -197,6 +178,7 @@ export function auditBacklinkProfile(backlinks, { targetDomain = null } = {}) {
 
   return {
     fact_status: 'observable_risk_indicators',
+    epistemic_status: 'DERIVED',
     target_domain: targetDomain,
     profile_health: profileHealth,
     summary: {
@@ -219,6 +201,7 @@ export function auditBacklinkProfile(backlinks, { targetDomain = null } = {}) {
       over_optimization_risk: commercialAnchorPct > 25 ? 'elevated' : 'normal',
     },
     toxic_domains: toxicDomains,
+    risk_indicators: toxicDomains,
     disavow_export: disavowLines.join('\n'),
     limitations: [
       'Search engines do not disclose algorithmic penalty thresholds; toxic classifications reflect observable risk patterns.',

package/src/analysis/readiness.js

@@ -217,10 +217,16 @@ export function evaluateAnswerEngineReadiness(page, ctx = {}) {
     });
   }
 
+  const boundedScore = Math.max(0, Math.min(100, Number.isFinite(compositeScore) ? Math.round(compositeScore) : 0));
+
   return {
     url: page.url,
-    fact_status: 'deterministic_engine_readiness_audit',
-    composite_readiness_score: compositeScore,
+    fact_status: 'modeled_extraction_readiness',
+    epistemic_status: 'MODELED',
+    evaluation_type: 'TECHNICAL_ELIGIBILITY',
+    score: boundedScore,
+    readiness_score: boundedScore,
+    composite_readiness_score: boundedScore,
     engines: {
       perplexity: {
         score: perplexityScore,