@nebulacomponents/citable 0.1.0

package/src/detectors/entity.js

@@ -0,0 +1,202 @@
+import { defineDetector, indexTargets, pageSubject, entrySubject } from './framework.js';
+import { isPastDate } from '../shared/io.js';
+
+const D = [];
+
+function allJsonLdBlocks(site) {
+  const out = [];
+  for (const p of site.pages) {
+    for (const j of p.jsonLd) for (const b of j.blocks) out.push({ page: p, block: b });
+  }
+  return out;
+}
+
+D.push(defineDetector({
+  id: 'ENTITY-001', name: 'Entity missing canonical URL', namespace: 'ENTITY',
+  description: 'A registry entity has no canonical URL, so engines have no authoritative page to resolve it to.',
+  discipline: ['geo', 'aeo'], severity: 'medium', deterministic: true, requires: ['registries'],
+  impact: { representation: 'high' },
+  applicable_requirement: 'AEO §3 every entity should have one canonical URL; GEO §3 canonical entities',
+  remediation: 'Create or designate one canonical page for the entity and record it in the registry.',
+  verification: 'Registry entry has canonical_url set and resolvable.',
+  check(ctx) {
+    return (ctx.registries.entities?.entries || [])
+      .filter((e) => e.status !== 'retired' && !e.canonical_url)
+      .map((e) => ({
+        subject: entrySubject('entities', e.entity_id),
+        summary: `Entity "${e.canonical_name}" has no canonical URL`,
+        evidence: [`entities/${e.entity_id}: canonical_url empty`],
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ENTITY-002', name: 'Schema entity name conflicts with registry', namespace: 'ENTITY',
+  description: 'A JSON-LD Organization/Product name does not match the registry canonical name or a documented alias.',
+  discipline: ['geo', 'seo'], severity: 'high', deterministic: true, requires: ['site', 'registries'],
+  impact: { representation: 'high' },
+  applicable_requirement: 'GEO §3 required consistency; detector spec: schema entity differs from visible entity',
+  remediation: 'Emit the canonical name from the entity registry in structured data; add legitimate variants to aliases.',
+  verification: 'Compare schema names with registry canonical_name and aliases.',
+  check(ctx) {
+    const entities = (ctx.registries.entities?.entries || []).filter((e) => ['organization', 'product', 'product_family'].includes(e.entity_type));
+    if (entities.length === 0) return [];
+    const hits = [];
+    for (const { page, block } of allJsonLdBlocks(ctx.site)) {
+      const type = [].concat(block['@type'] || []).join(',');
+      if (!/Organization|Corporation|SoftwareApplication|Product/i.test(type) || !block.name) continue;
+      const match = entities.find(
+        (e) => e.canonical_name.toLowerCase() === String(block.name).toLowerCase() || (e.aliases || []).some((a) => a.toLowerCase() === String(block.name).toLowerCase())
+      );
+      if (!match) {
+        const nearest = entities.find((e) => String(block.name).toLowerCase().includes(e.canonical_name.toLowerCase().split(' ')[0]) || e.canonical_name.toLowerCase().includes(String(block.name).toLowerCase().split(' ')[0]));
+        if (nearest) {
+          hits.push({
+            subject: { type: 'schema_block', identifier: `${page.url}#${block['@id'] || block.name}`, url: page.url },
+            summary: `Schema ${type} name "${block.name}" is not the canonical name "${nearest.canonical_name}" nor a documented alias`,
+            evidence: [`schema name: ${block.name}`, `registry canonical: ${nearest.canonical_name}; aliases: ${(nearest.aliases || []).join(', ') || 'none'}`],
+          });
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ENTITY-003', name: 'Unstable @id for same entity', namespace: 'ENTITY',
+  description: 'The same entity name appears in JSON-LD with different @id values across pages.',
+  discipline: ['geo', 'seo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { representation: 'medium' },
+  applicable_requirement: 'SEO §7 stable @id identifiers; GEO §9 required graph consistency',
+  remediation: 'Emit one stable @id per entity from shared data, referenced everywhere.',
+  verification: 'Collect @id values per entity name; each name maps to one @id.',
+  check(ctx) {
+    const byName = new Map();
+    for (const { block } of allJsonLdBlocks(ctx.site)) {
+      if (!block.name || !block['@id']) continue;
+      const key = `${[].concat(block['@type'] || []).join(',')}|${String(block.name).toLowerCase()}`;
+      if (!byName.has(key)) byName.set(key, new Set());
+      byName.get(key).add(block['@id']);
+    }
+    return [...byName.entries()]
+      .filter(([, ids]) => ids.size > 1)
+      .map(([key, ids]) => ({
+        subject: { type: 'entity', identifier: key },
+        summary: `Entity "${key.split('|')[1]}" uses ${ids.size} different @id values`,
+        evidence: [...ids].map((i) => `@id: ${i}`),
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ENTITY-004', name: 'sameAs profile not in authoritative list', namespace: 'ENTITY',
+  description: 'JSON-LD sameAs references a profile URL not recorded as an authoritative profile in the entity registry.',
+  discipline: ['geo'], severity: 'low', deterministic: true, requires: ['site', 'registries'],
+  impact: { representation: 'medium' },
+  applicable_requirement: 'AEO §6 sameAs limited to authoritative profiles; detector spec: unsupported sameAs',
+  remediation: 'Either add the profile to authoritative_profiles after verification, or remove it from sameAs.',
+  verification: 'Every sameAs URL appears in the registry authoritative_profiles.',
+  check(ctx) {
+    const entities = ctx.registries.entities?.entries || [];
+    if (entities.length === 0) return [];
+    const hits = [];
+    for (const { page, block } of allJsonLdBlocks(ctx.site)) {
+      if (!block.sameAs || !block.name) continue;
+      const entity = entities.find((e) => e.canonical_name.toLowerCase() === String(block.name).toLowerCase() || (e.aliases || []).some((a) => a.toLowerCase() === String(block.name).toLowerCase()));
+      if (!entity) continue;
+      const approved = new Set(entity.authoritative_profiles || []);
+      for (const s of [].concat(block.sameAs)) {
+        if (!approved.has(s)) {
+          hits.push({
+            subject: { type: 'schema_block', identifier: `${page.url}#sameAs`, url: page.url },
+            summary: `sameAs "${s}" for "${block.name}" is not a registered authoritative profile`,
+            evidence: [`schema sameAs: ${s}`, `registered profiles: ${[...approved].join(', ') || 'none'}`],
+          });
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ENTITY-005', name: 'Product entity without owner relationship', namespace: 'ENTITY',
+  description: 'A product/product-family entity records no owning organization.',
+  discipline: ['geo'], severity: 'medium', deterministic: true, requires: ['registries'],
+  impact: { representation: 'high' },
+  applicable_requirement: 'GEO §3 the engine must determine which products the organization owns; detector spec: product ownership ambiguous',
+  remediation: 'Set owner_entity (or a relationship) linking the product to its organization.',
+  verification: 'Product entity has owner_entity or an ownership relationship.',
+  check(ctx) {
+    return (ctx.registries.entities?.entries || [])
+      .filter((e) => ['product', 'product_family', 'service'].includes(e.entity_type) && e.status !== 'retired')
+      .filter((e) => !e.owner_entity && !(e.relationships || []).some((r) => ['owned_by', 'organization', 'publisher'].includes(r.type)))
+      .map((e) => ({
+        subject: entrySubject('entities', e.entity_id),
+        summary: `Product entity "${e.canonical_name}" has no recorded owning organization`,
+        evidence: [`entities/${e.entity_id}: owner_entity empty; no ownership relationship`],
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ENTITY-006', name: 'Unregistered name variant in page text', namespace: 'ENTITY',
+  description: 'Page text uses a variant of an entity name that is neither the canonical name nor a documented alias.',
+  discipline: ['geo', 'seo'], severity: 'low', deterministic: false, requires: ['site', 'registries'],
+  impact: { representation: 'medium' },
+  applicable_requirement: 'GEO §3 category contradictions and naming drift; SEO §6 consistent names',
+  false_positive_conditions: ['grammatical possessives and legitimate prose inflections'],
+  remediation: 'Standardize on the canonical name, or register the variant as an alias if intentional.',
+  verification: 'Page text uses only canonical names and registered aliases.',
+  check(ctx) {
+    const hits = [];
+    for (const e of (ctx.registries.entities?.entries || []).filter((e) => ['organization', 'product'].includes(e.entity_type))) {
+      const canonical = e.canonical_name;
+      const parts = canonical.split(/\s+/);
+      if (parts.length < 2) continue; // single-word names produce too many false variants
+      const known = new Set([canonical.toLowerCase(), ...(e.aliases || []).map((a) => a.toLowerCase())]);
+      // variant: same words joined/hyphenated/reordered-case
+      const variantRx = new RegExp(parts.join('[\\s-]*'), 'gi');
+      for (const p of indexTargets(ctx)) {
+        for (const m of p.text.matchAll(variantRx)) {
+          const found = m[0];
+          if (!known.has(found.toLowerCase())) {
+            hits.push({
+              subject: pageSubject(p),
+              summary: `Name variant "${found}" used for entity "${canonical}" (not a registered alias)`,
+              evidence: [`found: "${found}"`, `canonical: "${canonical}"`],
+              confidence: 'medium',
+            });
+            break; // one hit per page per entity
+          }
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'ENTITY-007', name: 'Entity verification stale', namespace: 'ENTITY',
+  description: 'An active entity has not been verified within the last 12 months (or last_verified missing).',
+  discipline: ['geo'], severity: 'low', deterministic: true, requires: ['registries'],
+  impact: { representation: 'medium', maintainability: 'medium' },
+  applicable_requirement: 'GEO §3 entity record last_verified; lifecycle premises',
+  remediation: 'Re-verify identity, category, relationships, and profiles; update last_verified.',
+  verification: 'last_verified within 12 months.',
+  check(ctx) {
+    const cutoff = new Date(ctx.refDate ?? Date.now());
+    cutoff.setMonth(cutoff.getMonth() - 12);
+    return (ctx.registries.entities?.entries || [])
+      .filter((e) => e.status === 'active' || e.status === 'verified')
+      .filter((e) => !e.last_verified || new Date(e.last_verified) < cutoff)
+      .map((e) => ({
+        subject: entrySubject('entities', e.entity_id),
+        summary: `Entity "${e.canonical_name}" not verified in the last 12 months (last: ${e.last_verified ?? 'never'})`,
+        evidence: [`last_verified: ${e.last_verified ?? 'missing'}`],
+      }));
+  },
+}));
+
+export default D;

package/src/detectors/evd.js

@@ -0,0 +1,164 @@
+import { defineDetector, entrySubject } from './framework.js';
+import { isPastDate } from '../shared/io.js';
+
+const D = [];
+
+D.push(defineDetector({
+  id: 'EVD-001', name: 'Evidence past validity date', namespace: 'EVD',
+  description: 'An evidence entry has passed valid_until but its verification_status is not stale/revoked.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: true, requires: ['registries'],
+  impact: { legal: 'medium', citation: 'medium' },
+  applicable_requirement: 'Registry §6.5 valid_until; AEO §8 source revalidation',
+  remediation: 'Re-validate the evidence or mark it stale and re-assess dependent claims.',
+  verification: 'No verified evidence past its valid_until date.',
+  check(ctx) {
+    return (ctx.registries.evidence?.entries || [])
+      .filter((e) => isPastDate(e.valid_until, ctx.refDate) && !['stale', 'revoked', 'inaccessible'].includes(e.verification_status))
+      .map((e) => ({
+        subject: entrySubject('evidence', e.evidence_id),
+        summary: `Evidence "${e.title}" passed valid_until ${e.valid_until} but is still ${e.verification_status}`,
+        evidence: [`valid_until: ${e.valid_until}; verification_status: ${e.verification_status}`],
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'EVD-002', name: 'Benchmark/test evidence missing methodology', namespace: 'EVD',
+  description: 'Benchmark, test-result, or dataset evidence records no methodology or measurement period.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: true, requires: ['registries'],
+  impact: { citation: 'medium', legal: 'medium' },
+  applicable_requirement: 'AEO §8 version evidence: methodology, test date; detector spec: missing methodology / measurement period',
+  remediation: 'Record methodology, test conditions, and measurement period, or downgrade dependent claims.',
+  verification: 'Benchmark/test evidence entries carry methodology and measurement_period.',
+  check(ctx) {
+    return (ctx.registries.evidence?.entries || [])
+      .filter((e) => ['benchmark', 'test_result', 'dataset'].includes(e.evidence_type))
+      .filter((e) => !e.methodology || !e.measurement_period)
+      .map((e) => ({
+        subject: entrySubject('evidence', e.evidence_id),
+        summary: `${e.evidence_type} evidence "${e.title}" lacks ${!e.methodology ? 'methodology' : ''}${!e.methodology && !e.measurement_period ? ' and ' : ''}${!e.measurement_period ? 'measurement period' : ''}`,
+        evidence: [`methodology: ${e.methodology ?? 'missing'}; measurement_period: ${e.measurement_period ?? 'missing'}`],
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'EVD-003', name: 'Claim references dangling or unverified evidence', namespace: 'EVD',
+  description: 'A claim references an evidence id that does not exist or has verification_status unverified.',
+  discipline: ['aeo', 'geo'], severity: 'high', deterministic: true, requires: ['registries'],
+  impact: { legal: 'medium', maintainability: 'medium' },
+  applicable_requirement: 'Referential integrity between claim and evidence registries; premise 3.5',
+  remediation: 'Register and verify the evidence, or remove the reference and re-assess the claim.',
+  verification: 'All claim evidence references resolve to reviewed/verified entries.',
+  check(ctx) {
+    const ev = new Map((ctx.registries.evidence?.entries || []).map((e) => [e.evidence_id, e]));
+    const hits = [];
+    for (const c of ctx.registries.claims?.entries || []) {
+      for (const id of c.evidence || []) {
+        const e = ev.get(id);
+        if (!e) {
+          hits.push({
+            subject: entrySubject('claims', c.claim_id),
+            summary: `Claim references unknown evidence id "${id}"`,
+            evidence: [`claims/${c.claim_id} → evidence "${id}" not found`],
+          });
+        } else if (e.verification_status === 'unverified' && ['verified', 'verified_narrowed'].includes(c.status)) {
+          hits.push({
+            subject: entrySubject('claims', c.claim_id),
+            summary: `Verified claim relies on unverified evidence "${id}"`,
+            evidence: [`evidence/${id}: verification_status=unverified`],
+          });
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'EVD-004', name: 'Secondary evidence where primary is required', namespace: 'EVD',
+  description: 'A performance or security claim is supported only by secondary evidence (e.g., third-party articles).',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: true, requires: ['registries'],
+  impact: { legal: 'medium', citation: 'medium' },
+  applicable_requirement: 'Detector spec: secondary evidence used where primary evidence is required; AEO §4 primary sources where available',
+  remediation: 'Produce primary evidence (test result, architecture spec, certification) or narrow the claim.',
+  verification: 'Performance/security claims have at least one primary evidence entry.',
+  check(ctx) {
+    const ev = new Map((ctx.registries.evidence?.entries || []).map((e) => [e.evidence_id, e]));
+    const hits = [];
+    for (const c of (ctx.registries.claims?.entries || []).filter((c) => ['performance', 'security'].includes(c.claim_type) && (c.evidence || []).length > 0)) {
+      const kinds = (c.evidence || []).map((id) => ev.get(id)).filter(Boolean);
+      if (kinds.length > 0 && kinds.every((e) => e.primary_or_secondary === 'secondary')) {
+        hits.push({
+          subject: entrySubject('claims', c.claim_id),
+          summary: `${c.claim_type} claim supported only by secondary evidence`,
+          evidence: kinds.map((e) => `${e.evidence_id}: ${e.evidence_type} (secondary)`),
+        });
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'EVD-005', name: 'Customer evidence lacks attribution', namespace: 'EVD',
+  description: 'Customer-reference or case-study evidence has no attribution recorded.',
+  discipline: ['aeo', 'geo'], severity: 'low', deterministic: true, requires: ['registries'],
+  impact: { reputational: 'medium', legal: 'medium' },
+  applicable_requirement: 'Detector spec: customer evidence lacks attribution; premise 3.6 no fabricated customers',
+  remediation: 'Record attribution (who, role, permission status) or mark the evidence anonymous-by-consent with reviewer sign-off.',
+  verification: 'Customer evidence entries carry attribution or a documented consent basis.',
+  check(ctx) {
+    return (ctx.registries.evidence?.entries || [])
+      .filter((e) => ['customer_reference', 'case_study'].includes(e.evidence_type) && !e.attribution && !e.reviewer)
+      .map((e) => ({
+        subject: entrySubject('evidence', e.evidence_id),
+        summary: `Customer evidence "${e.title}" has no attribution and no reviewer`,
+        evidence: ['attribution: missing; reviewer: missing'],
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'EVD-006', name: 'Evidence integrity hash absent', namespace: 'EVD',
+  description: 'Primary evidence (test results, benchmarks, datasets, certifications) has no integrity hash, so later tampering or drift cannot be detected.',
+  discipline: ['aeo', 'geo'], severity: 'low', deterministic: true, requires: ['registries'],
+  impact: { maintainability: 'medium', legal: 'low' },
+  applicable_requirement: 'Registry §6.5 integrity_hash; detector spec: evidence integrity hash absent where expected',
+  remediation: 'Store a sha256 of the evidence artifact at verification time.',
+  verification: 'Primary evidence entries carry integrity_hash.',
+  check(ctx) {
+    return (ctx.registries.evidence?.entries || [])
+      .filter((e) => ['test_result', 'benchmark', 'dataset', 'certification'].includes(e.evidence_type) && e.primary_or_secondary === 'primary' && !e.integrity_hash)
+      .map((e) => ({
+        subject: entrySubject('evidence', e.evidence_id),
+        summary: `Primary ${e.evidence_type} evidence "${e.title}" has no integrity hash`,
+        evidence: ['integrity_hash: missing'],
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'EVD-007', name: 'Evidence marked inaccessible still supporting claims', namespace: 'EVD',
+  description: 'Evidence with access_status inaccessible (or verification_status inaccessible) is still listed as supporting active claims.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: true, requires: ['registries'],
+  impact: { legal: 'medium', citation: 'medium' },
+  applicable_requirement: 'Detector spec: evidence source inaccessible; revoked evidence still supporting published claim',
+  remediation: 'Restore access to the source, replace the evidence, or downgrade dependent claims.',
+  verification: 'No active claim relies solely on inaccessible evidence.',
+  check(ctx) {
+    const claims = new Map((ctx.registries.claims?.entries || []).map((c) => [c.claim_id, c]));
+    return (ctx.registries.evidence?.entries || [])
+      .filter((e) => (e.access_status === 'inaccessible' || e.verification_status === 'inaccessible') && (e.supports_claims || []).some((id) => {
+        const c = claims.get(id);
+        return c && !['retired', 'expired', 'prohibited'].includes(c.status);
+      }))
+      .map((e) => ({
+        subject: entrySubject('evidence', e.evidence_id),
+        summary: `Inaccessible evidence "${e.title}" still supports active claims: ${(e.supports_claims || []).join(', ')}`,
+        evidence: [`access_status: ${e.access_status}; verification_status: ${e.verification_status}`],
+      }));
+  },
+}));
+
+export default D;

package/src/detectors/framework.js

@@ -0,0 +1,137 @@
+import { sha256 } from '../shared/io.js';
+
+const REQUIRED = ['id', 'name', 'namespace', 'description', 'discipline', 'severity', 'deterministic', 'remediation', 'verification', 'check'];
+// RENDER (browser-rendered truth / source-render divergence) is reserved for the
+// rendered-truth phase; no RENDER detectors ship until a real renderer backs them.
+const NAMESPACES = ['TECH', 'CRAWL', 'ARCH', 'PAGE', 'ANS', 'ENTITY', 'CLAIM', 'EVD', 'SCHEMA', 'LINK', 'EXT', 'GEO', 'RECO', 'LIFE', 'MEAS', 'RENDER'];
+
+/**
+ * Detector definition contract. `check(ctx)` returns raw hits:
+ *   { subject: {type, identifier, url?, source_file?, source_location?}, summary, evidence: [..],
+ *     captured?, expected?, severity?, confidence? }
+ */
+export function defineDetector(def) {
+  for (const k of REQUIRED) {
+    if (def[k] === undefined) throw new Error(`detector ${def.id ?? '?'} missing field: ${k}`);
+  }
+  if (!NAMESPACES.includes(def.namespace)) throw new Error(`detector ${def.id}: unknown namespace ${def.namespace}`);
+  if (!def.id.startsWith(def.namespace + '-')) throw new Error(`detector id ${def.id} must be prefixed with namespace`);
+  return {
+    confidence_model: def.deterministic ? 'binary condition; confirmed when observed' : 'heuristic; confidence reported per finding',
+    confidence: def.deterministic ? 'confirmed' : 'medium',
+    finding_type: def.deterministic ? 'deterministic_observation' : 'probabilistic_inference',
+    impact: {},
+    false_positive_conditions: [],
+    false_negative_conditions: [],
+    applicable_requirement: '',
+    ...def,
+  };
+}
+
+/** Run detectors over a context; returns { findings, detectorsRun, detectorsSkipped, errors }. */
+export function runDetectors(detectors, ctx) {
+  const findings = [];
+  const detectorsRun = [];
+  const detectorsSkipped = [];
+  const errors = [];
+  const ts = ctx.timestamp ?? new Date().toISOString();
+  for (const d of detectors) {
+    if (d.requires && !d.requires.every((r) => ctx[r])) {
+      detectorsSkipped.push({ detector_id: d.id, reason: `missing context: ${d.requires.filter((r) => !ctx[r]).join(', ')}` });
+      continue;
+    }
+    let hits;
+    try {
+      hits = d.check(ctx) || [];
+    } catch (err) {
+      errors.push(`${d.id}: detector error: ${err.message}`);
+      continue;
+    }
+    detectorsRun.push(d.id);
+    for (const hit of hits) {
+      const idSeed = `${d.id}|${hit.subject?.identifier ?? ''}|${hit.summary}`;
+      findings.push({
+        finding_id: `F-${sha256(idSeed).slice(0, 12)}`,
+        detector_id: d.id,
+        run_id: ctx.runId ?? 'adhoc',
+        timestamp: ts,
+        discipline: d.discipline,
+        subject: hit.subject,
+        observation: {
+          summary: hit.summary,
+          evidence: hit.evidence,
+          captured_value: hit.captured ?? null,
+          expected_value: hit.expected ?? null,
+        },
+        classification: {
+          finding_type: hit.finding_type ?? d.finding_type,
+          severity: hit.severity ?? d.severity,
+          confidence: hit.confidence ?? d.confidence,
+          deterministic: d.deterministic,
+          impact: { ...d.impact, ...(hit.impact || {}) },
+        },
+        reasoning: {
+          applicable_requirement: d.applicable_requirement,
+          explanation: d.description,
+          assumptions: hit.assumptions ?? [],
+          limitations: d.deterministic ? [] : ['heuristic detection; verify manually before acting'],
+        },
+        remediation: {
+          preferred: d.remediation,
+          alternatives: d.remediation_alternatives ?? [],
+          unsafe_shortcuts: d.unsafe_shortcuts ?? [],
+          owner: hit.owner ?? null,
+          review_required: d.review_required ?? !d.deterministic,
+        },
+        verification: {
+          method: d.verification,
+          expected_result: 'detector no longer reports this subject',
+          detector_to_rerun: d.id,
+        },
+        status: { state: 'open', first_seen: ts, last_seen: ts, resolved_at: null },
+      });
+    }
+  }
+  return { findings, detectorsRun, detectorsSkipped, errors };
+}
+
+/* ---------- shared helpers for detector implementations ---------- */
+
+/** Pages whose declared or default intent is to be indexed. */
+export function indexTargets(ctx) {
+  return ctx.site.pages.filter((p) => {
+    const reg = registryPageFor(ctx, p);
+    if (reg?.indexing_intent === 'noindex') return false;
+    return true;
+  });
+}
+
+/** Match a live page to its registry entry by URL path. */
+export function registryPageFor(ctx, page) {
+  const entries = ctx.registries?.pages?.entries || [];
+  const pPath = safePath(page.url);
+  return entries.find((e) => safePath(e.url, ctx.site?.baseUrl) === pPath) ?? null;
+}
+
+/** Find the live site page for a registry entry. */
+export function sitePageFor(ctx, registryEntry) {
+  if (!ctx.site) return null;
+  const target = safePath(registryEntry.url, ctx.site.baseUrl);
+  return ctx.site.pages.find((p) => safePath(p.url) === target) ?? null;
+}
+
+export function safePath(url, base = 'https://example.test') {
+  try {
+    return new URL(url, base).pathname.replace(/\/$/, '') || '/';
+  } catch {
+    return url;
+  }
+}
+
+export function pageSubject(page) {
+  return { type: 'page', identifier: page.url, url: page.url, ...(page.sourceFile ? { source_file: page.sourceFile } : {}) };
+}
+
+export function entrySubject(type, id) {
+  return { type: 'registry_entry', identifier: `${type}/${id}` };
+}