@nebulacomponents/citable 1.19.0 → 1.20.0

package/src/artifacts/interchange.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { canonicalJson } from '../release/governance.js';
 import { nowIso, readJson, sha256, sha256File, writeJson } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { verifyRunPackage } from '../shared/runPackageVerifier.js';
 
 const PACKAGE = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
 const ENVELOPE = 'citable-artifact.json';
@@ -37,18 +38,13 @@ function validateRunPackage(runDir) {
   const checksumsFile = path.join(runDir, 'checksums.json');
   if (!fs.existsSync(manifestFile) || !fs.existsSync(checksumsFile)) throw new Error('run package requires manifest.json and checksums.json');
   const manifest = readJson(manifestFile);
-  const manifestCheck = validateAgainst('run.schema.json', manifest);
-  if (!manifestCheck.valid) throw new Error(`run manifest invalid: ${manifestCheck.errors.join('; ')}`);
   const checksums = readJson(checksumsFile);
-  if (!checksums || Array.isArray(checksums) || typeof checksums !== 'object') throw new Error('checksums.json must be an object');
+  verifyRunPackage(runDir, { requireFindings: false, requireCompleted: false, requireChecksums: true, ignoredFiles: [ENVELOPE] });
   const actualFiles = filesUnder(runDir).filter((name) => name !== ENVELOPE);
   const expectedFiles = [...Object.keys(checksums), 'checksums.json'].sort();
   if (new Set(expectedFiles).size !== expectedFiles.length) throw new Error('checksums.json contains duplicate package paths');
   for (const rel of Object.keys(checksums)) {
     if (!safeRelativePath(rel) || rel === ENVELOPE || rel === 'checksums.json') throw new Error(`unsafe checksum path: ${rel}`);
-    const file = path.join(runDir, ...rel.split('/'));
-    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`checksummed artifact is missing: ${rel}`);
-    if (!/^[a-f0-9]{64}$/.test(checksums[rel]) || sha256File(file) !== checksums[rel]) throw new Error(`artifact checksum mismatch: ${rel}`);
   }
   const extras = actualFiles.filter((name) => !expectedFiles.includes(name));
   const missing = expectedFiles.filter((name) => !actualFiles.includes(name));

package/src/cli/index.js

@@ -185,6 +185,8 @@ Commands
 
 Options
   --target <dir|url>        Built output directory or deployed URL to audit
+  --max-pages <count>       Maximum unique page URLs attempted for a URL audit (default: 500)
+  --time-budget-seconds <seconds>  Whole-run URL collection limit (default: 1800)
   --base-url <url>          Base URL for path resolution of a built output dir
   --ref-date <YYYY-MM-DD>   Reference date for expiry/staleness checks (default: today)
   --input <file>            Import evidence, remediation, or browser plan
@@ -233,7 +235,7 @@ Options
 No output of this tool guarantees crawling, indexing, ranking, citation,
 recommendation, inclusion, sentiment, or conversion outcomes.`;
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const args = { _: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -243,6 +245,8 @@ function parseArgs(argv) {
     else if (a === '--interactions') args.interactions = true;
     else if (a === '--lighthouse') args.lighthouse = true;
     else if (a === '--target') args.target = argv[++i];
+    else if (a === '--max-pages') args.maxPages = Number(argv[++i]);
+    else if (a === '--time-budget-seconds') args.timeBudgetSeconds = Number(argv[++i]);
     else if (a === '--base-url') args.baseUrl = argv[++i];
     else if (a === '--ref-date') args.refDate = argv[++i];
     else if (a === '--viewport') args.viewport = argv[++i];
@@ -411,8 +415,16 @@ ${r.findings.map((f) => `  [${f.rule_id}] (${f.severity}) ${f.summary}\n    Fix:
           break;
         }
         const scope = args._[0];
-        const r = await audit(root, { target: args.target, scope, baseUrl: args.baseUrl, refDate: args.refDate, viewport: args.viewport });
-        out(args, `Audit ${r.runId}: ${r.summary.total} finding(s) [${Object.entries(r.summary.by_severity).map(([k, v]) => `${k}:${v}`).join(' ')}]\nEvidence package: ${r.dir}\nReport: ${path.join(r.dir, 'report.md')}\nStatus: ${r.manifest.status}${r.manifest.incomplete_checks.length ? `\nIncomplete: ${r.manifest.incomplete_checks.join('; ')}` : ''}`, { runId: r.runId, dir: r.dir, summary: r.summary, status: r.manifest.status });
+        const r = await audit(root, {
+          target: args.target,
+          scope,
+          baseUrl: args.baseUrl,
+          refDate: args.refDate,
+          viewport: args.viewport,
+          maxPages: args.maxPages,
+          timeBudgetSeconds: args.timeBudgetSeconds,
+        });
+        out(args, `Audit ${r.runId}: ${r.summary.total} finding(s) [${Object.entries(r.summary.by_severity).map(([k, v]) => `${k}:${v}`).join(' ')}]\nEvidence package: ${r.dir}\nReport: ${path.join(r.dir, 'report.md')}\nStatus: ${r.manifest.status}\nExecution: ${r.manifest.execution_status}\nCoverage: ${r.manifest.coverage_status}\nDetermination: ${r.manifest.determination_status}${r.manifest.incomplete_checks.length ? `\nIncomplete: ${r.manifest.incomplete_checks.join('; ')}` : ''}`, { runId: r.runId, dir: r.dir, summary: r.summary, status: r.manifest.status, execution_status: r.manifest.execution_status, coverage_status: r.manifest.coverage_status, determination_status: r.manifest.determination_status });
         break;
       }
       case 'plan-audit': {

package/src/commands/actionPlan.js

@@ -2,7 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readJson, writeJson, sha256, nowIso } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { downstreamEnvelope } from '../evidence/downstream.js';
+import { REQUIREMENTS, evaluateRequirement } from '../evidence/determination.js';
 import { checklistItem, toStringArray } from '../shared/checklist.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 const SEVERITY = { critical: 0, high: 1, medium: 2, low: 3, informational: 3, experimental: 3 };
 const PHASE = { unblock: 0, governance: 1, content: 2, optimization: 3 };
@@ -46,6 +49,7 @@ function renderPlan(plan) {
     '# Citable action plan', '',
     `- Source audit: \`${plan.source_run_id}\``,
     `- Actions: ${plan.summary.total_actions}; ready: ${plan.summary.ready}; blocked: ${plan.summary.blocked}`,
+    `- Evidence coverage: ${plan.source_coverage.coverage_status}; determination: ${plan.source_coverage.determination_status}`,
     '',
     '> This plan prioritizes observed findings. It does not guarantee ranking, citation, recommendation, or conversion outcomes.',
     '',
@@ -61,6 +65,7 @@ function renderPlan(plan) {
       lines.push(`- Decision owner: ${action.decision_owner ?? 'unassigned'}`);
       lines.push(`- Dependencies: ${action.depends_on_action_ids.length ? action.depends_on_action_ids.join(', ') : 'none established'}`);
       if (action.required_input.length) lines.push(`- Required input: ${action.required_input.join(', ')}`);
+      if (action.limitations.length) lines.push(`- Evidence limitations: ${action.limitations.join('; ')}`);
       if (action.semantic_gates.length) lines.push(`- Semantic gates: ${action.semantic_gates.join(', ')}`);
       lines.push(`- Failure condition: ${action.failure_condition}`);
       lines.push(`- Leading indicators: ${action.leading_indicators.length ? action.leading_indicators.join(', ') : 'none established'}`);
@@ -78,13 +83,37 @@ export function actionPlan(root, { runId } = {}) {
   const sourceDir = path.join(runsDir, sourceRunId);
   const findingsFile = path.join(sourceDir, 'findings.json');
   if (!fs.existsSync(findingsFile)) throw new Error(`run ${sourceRunId} has no findings.json`);
-  const rawFindings = fs.readFileSync(findingsFile, 'utf8');
-  const findings = JSON.parse(rawFindings);
-  const manifest = readJson(path.join(sourceDir, 'manifest.json'));
+  const loaded = loadVerifiedRun(sourceDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const findings = loaded.findings;
+  const rawFindings = JSON.stringify(findings);
+  const manifest = loaded.manifest;
+  const coverage = loaded.coverage;
+  const sourceCoverage = downstreamEnvelope(coverage, {
+    artifact: coverage ? 'coverage.json' : null,
+  });
   const target = manifest.target?.location;
   const actions = findings.map((finding) => {
     const owner = finding.remediation.owner ?? null;
-    const blocked = finding.remediation.review_required && !owner;
+    const findingScope = finding.evidence_scope || {
+      requirement: 'evaluated_subset',
+      satisfaction: sourceCoverage.determination_status,
+      coverage_ref: coverage ? 'coverage.json' : null,
+      resource_ids: [],
+    };
+    const requirement = findingScope.requirement || REQUIREMENTS.EVALUATED_SUBSET;
+    let requirementResult;
+    try {
+      requirementResult = evaluateRequirement(requirement, coverage, finding.subject);
+    } catch (error) {
+      requirementResult = { status: 'indeterminate', reason: `invalid_evidence_requirement: ${error.message}` };
+    }
+    const scopeSatisfied = ['supported', 'qualified'].includes(requirementResult.status);
+    const effectiveDetermination = sourceCoverage.determination_status === 'indeterminate'
+      || sourceCoverage.determination_status === 'not_applicable'
+      || !scopeSatisfied
+      ? 'indeterminate'
+      : (sourceCoverage.determination_status === 'qualified' || requirementResult.status === 'qualified' ? 'qualified' : 'supported');
+    const blocked = (finding.remediation.review_required && !owner) || !scopeSatisfied || effectiveDetermination === 'indeterminate';
     const scope = finding.discipline.length === 1 && ['aeo', 'geo', 'seo'].includes(finding.discipline[0]) ? ` ${finding.discipline[0]}` : '';
     return {
       action_id: `ACT-${finding.finding_id.replace(/^F-/, '')}`,
@@ -97,7 +126,18 @@ export function actionPlan(root, { runId } = {}) {
       owner,
       decision_owner: owner,
       status: blocked ? 'blocked' : 'ready',
-      required_input: blocked ? toStringArray([checklistItem('owner', 'accountable owner')]) : [],
+      evidence_scope: { ...findingScope, satisfaction: effectiveDetermination },
+      coverage_status: sourceCoverage.coverage_status,
+      determination_status: effectiveDetermination,
+      limitations: [
+        ...sourceCoverage.limitations,
+        ...(finding.reasoning?.limitations || []),
+        ...(requirementResult.reason ? [`evidence requirement: ${requirementResult.reason}`] : []),
+      ].filter((item, index, all) => all.indexOf(item) === index),
+      required_input: blocked ? toStringArray([
+        ...(finding.remediation.review_required && !owner ? [checklistItem('owner', 'accountable owner')] : []),
+        ...(!scopeSatisfied || effectiveDetermination === 'indeterminate' ? ['sufficient comparable evidence for the declared scope'] : []),
+      ]) : [],
       semantic_gates: semanticGates(finding),
       unsafe_shortcuts: finding.remediation.unsafe_shortcuts || [],
       failure_condition: `${finding.verification.detector_to_rerun} still reports the exact subject, or verification cannot complete with sufficient evidence`,
@@ -120,6 +160,7 @@ export function actionPlan(root, { runId } = {}) {
       ready: actions.filter((action) => action.status === 'ready').length,
       blocked: actions.filter((action) => action.status === 'blocked').length,
     },
+    source_coverage: sourceCoverage,
     actions,
   };
   const validation = validateAgainst('action-plan.schema.json', plan);

package/src/commands/applyRemediation.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createRun } from '../evidence/run.js';
 import { readJson, sha256 } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 function inside(root, candidate) {
   const base = path.resolve(root) + path.sep;
@@ -19,11 +20,10 @@ export function applyRemediation(root, { input, write = false } = {}) {
   const spec = readJson(input);
   const valid = validateAgainst('remediation-spec.schema.json', spec);
   if (!valid.valid) throw new Error(`remediation spec invalid: ${valid.errors.join('; ')}`);
-  const manifestFile = path.join(root, '.citable', 'runs', spec.source_run_id, 'manifest.json');
-  if (!fs.existsSync(manifestFile)) throw new Error(`source run not found: ${spec.source_run_id}`);
-  const findingsFile = path.join(root, '.citable', 'runs', spec.source_run_id, 'findings.json');
-  if (!fs.existsSync(findingsFile)) throw new Error(`source run has no findings: ${spec.source_run_id}`);
-  const sourceFindingIds = new Set(readJson(findingsFile).map((finding) => finding.finding_id));
+  const sourceDir = path.join(root, '.citable', 'runs', spec.source_run_id);
+  if (!fs.existsSync(sourceDir)) throw new Error(`source run not found: ${spec.source_run_id}`);
+  const source = loadVerifiedRun(sourceDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const sourceFindingIds = new Set(source.findings.map((finding) => finding.finding_id));
   const results = [];
   const pending = [];
   for (const operation of spec.operations) {

package/src/commands/audit.js

@@ -10,10 +10,16 @@ import { writeJson, sha256 } from '../shared/io.js';
 import { extractModified } from '../detectors/lifeMeas.js';
 import { buildEntityGraph } from '../observations/entityGraph.js';
 import { buildSourceIdentityChain } from '../observations/sourceIdentity.js';
+import { pageArtifactRecord } from '../evidence/hashes.js';
 
 /** `citable audit [scope]` — run detectors and produce an evidence package. */
-export async function audit(root, { target, scope, baseUrl, refDate, viewport = null } = {}) {
-  const ctx = await buildContext(root, { target, baseUrl, refDate, viewport });
+export async function audit(root, {
+  target, scope, baseUrl, refDate, viewport = null,
+  maxPages, timeBudgetSeconds, fetcher, concurrency = 1,
+} = {}) {
+  const ctx = await buildContext(root, {
+    target, baseUrl, refDate, viewport, maxPages, timeBudgetSeconds, fetcher, concurrency,
+  });
   const detectors = selectDetectors({ scope });
 
   const run = createRun(root, {
@@ -36,10 +42,32 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
   if (ctx.site?.fetchErrors?.length) {
     run.manifest.errors.push(...ctx.site.fetchErrors);
   }
-  if (ctx.site?.crawl?.truncated) {
+  if (ctx.site?.crawl?.stopReason === 'page_budget_exhausted') {
     run.manifest.incomplete_checks.push(
       `URL collection reached the ${ctx.site.crawl.maxPages}-page limit with ${ctx.site.crawl.pendingUrlCount} discovered URL(s) pending; sitemap absence checks are incomplete.`
     );
+  } else if (ctx.site?.crawl?.stopReason === 'time_budget_exhausted') {
+    run.manifest.incomplete_checks.push(
+      `URL collection reached the ${ctx.site.crawl.timeBudgetSeconds}-second time budget; sitemap absence checks are incomplete.`
+    );
+  }
+
+  // Establish and persist the collection contract before detectors execute.
+  // Detectors receive this exact provisional evidence envelope through ctx so
+  // they cannot infer completeness from page-array length or legacy crawl data.
+  let coverage = null;
+  if (ctx.site?.previewCoverage) {
+    try {
+      coverage = ctx.site.previewCoverage();
+      run.manifest.coverage_status = coverage.coverage_status;
+      run.writeArtifact('coverage.json', coverage);
+      ctx.coverage = coverage;
+    } catch (error) {
+      run.manifest.execution_status = 'failed';
+      run.manifest.errors.push(`coverage: ${error.message}`);
+      run.finalize('failed');
+      throw error;
+    }
   }
 
   const { findings, detectorsRun, detectorsSkipped, errors } = runDetectors(detectors, ctx);
@@ -47,6 +75,27 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
   run.manifest.detectors_skipped = detectorsSkipped;
   run.manifest.errors.push(...errors);
 
+  // Seal the ledger after detector evaluation so the same artifact records
+  // evaluated resources while retaining the pre-detector persistence proof.
+  if (ctx.site?.finalizeCoverage) {
+    try {
+      coverage = ctx.site.finalizeCoverage({ evaluated: true });
+      run.manifest.coverage_status = coverage.coverage_status;
+      run.manifest.determination_status = coverage.coverage_status === 'complete' ? 'supported' : 'qualified';
+      run.writeArtifact('coverage.json', coverage);
+      if (coverage.coverage_status !== 'complete') {
+        run.manifest.incomplete_checks.push(
+          `Coverage is ${coverage.coverage_status}; conclusions are limited to the successfully observed corpus.`,
+        );
+      }
+    } catch (error) {
+      run.manifest.execution_status = 'failed';
+      run.manifest.errors.push(`coverage: ${error.message}`);
+      run.finalize('failed');
+      throw error;
+    }
+  }
+
   // Validate every finding against the data contract; a contract breach fails the run.
   const invalid = [];
   for (const f of findings) {
@@ -66,6 +115,7 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
     detectorsSkipped,
     promptResults: ctx.promptResults || [],
     targetOrigin: ctx.site?.baseUrl ? new URL(ctx.site.baseUrl).origin : null,
+    coverage,
   });
   run.writeArtifact('summary.json', summary);
   run.writeArtifact('inputs.json', {
@@ -73,6 +123,8 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
     registry_counts: Object.fromEntries(Object.entries(ctx.registries).map(([k, v]) => [k, v.entries.length])),
     pages_audited: ctx.site?.pages.length ?? 0,
     crawl_coverage: ctx.site?.crawl ?? null,
+    coverage_status: coverage?.coverage_status ?? 'not_applicable',
+    coverage_populations: coverage?.populations ?? null,
   });
   run.writeArtifact('environment.json', {
     node: process.version, platform: process.platform, cwd: root,
@@ -80,9 +132,8 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
   });
   if (ctx.site) {
     run.writeArtifact('pages/index.json', ctx.site.pages.map((p) => ({
-      url: p.url, status: p.status, title: p.title, canonicals: p.canonicals,
-      noindex: p.noindex, wordCount: p.wordCount, sourceFile: p.sourceFile,
-      contentHash: ctx.hashPage(p),
+      ...pageArtifactRecord(p),
+      artifact_hash: p.artifact_hash ?? null,
     })));
     if (ctx.site.robotsText != null) run.writeArtifact('robots/robots.txt', ctx.site.robotsText);
     for (const sm of ctx.site.sitemaps) {
@@ -102,14 +153,26 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
     }
   }
 
-  const report = renderMarkdownReport({ findings, manifest: run.manifest, summary, detectorsSkipped });
+  const report = renderMarkdownReport({ findings, manifest: run.manifest, summary, detectorsSkipped, coverage });
   run.writeArtifact('report.md', report);
 
   // Update the latest page snapshot for regression/freshness comparison
   if (ctx.site) {
     const snap = { taken_at: run.manifest.timestamp, run_id: run.runId, pages: {} };
     for (const p of ctx.site.pages) {
-      snap.pages[p.url] = { contentHash: ctx.hashPage(p), dateModified: extractModified(p), status: p.status };
+      snap.pages[p.url] = {
+        contentHash: p.extracted_text_hash ?? ctx.hashPage(p),
+        hash_semantics: 'extracted_text_v1',
+        extracted_text_hash: p.extracted_text_hash ?? ctx.hashPage(p),
+        response_body_hash: p.response_body_hash ?? null,
+        structured_data_hash: p.structured_data_hash ?? null,
+        evidence_hash: p.evidence_hash ?? null,
+        artifact_hash: p.artifact_hash ?? null,
+        resource_id: p.urlIdentity?.resource_id ?? null,
+        url_identity: p.urlIdentity ?? null,
+        dateModified: extractModified(p),
+        status: p.status,
+      };
     }
     const snapDir = path.join(root, '.citable', 'snapshots');
     fs.mkdirSync(snapDir, { recursive: true });
@@ -121,6 +184,10 @@ export async function audit(root, { target, scope, baseUrl, refDate, viewport =
 
   const status = run.manifest.errors.length ? 'completed_with_warnings'
     : run.manifest.incomplete_checks.length ? 'incomplete' : 'completed';
+  // Successful persistence/execution is independent from collection coverage
+  // and legacy warning status. A run with fetch warnings can still complete as
+  // an execution while its coverage remains indeterminate or truncated.
+  run.manifest.execution_status = 'completed';
   const dir = run.finalize(status);
   return { runId: run.runId, dir, findings, summary, manifest: run.manifest, report };
 }

package/src/commands/ciWorkflow.js

@@ -33,9 +33,14 @@ jobs:
 `;
 }
 
-export function formatPrReviewComment(findings = []) {
+export function formatPrReviewComment(findings = [], determination = null) {
   if (findings.length === 0) {
-    return '### ✅ Citable CRO Sentinel: All conversion funnels and components verified clean with zero detected friction.';
+    const status = determination?.determination_status || 'indeterminate';
+    if (status !== 'supported') {
+      const coverage = determination?.coverage_status ? ` (coverage: ${determination.coverage_status})` : '';
+      return `### ⚠️ Citable CRO Sentinel: No determination can be made from the available evidence${coverage}; insufficient evidence for a clean determination. No finding was observed in the evaluated subset; this is not a verified result.`;
+    }
+    return '### ✅ Citable CRO Sentinel: No findings were observed over the supported evidence scope.';
   }
 
   const lines = [

package/src/commands/compareSnapshots.js

@@ -1,63 +1,171 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJson } from '../shared/io.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
+import { normalizeUrlIdentity } from '../crawler/urlIdentity.js';
 
-/**
- * `citable compare-snapshots [runA runB]` — regression comparison between two audit runs.
- * Defaults to the two most recent runs containing findings.json.
- */
-export function compareSnapshots(root, { runA, runB } = {}) {
-  const runsDir = path.join(root, '.citable', 'runs');
-  if (!fs.existsSync(runsDir)) throw new Error('no runs recorded yet');
-  const runs = fs.readdirSync(runsDir)
-    .filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json')))
-    .sort();
-  if (!runA || !runB) {
-    if (runs.length < 2) throw new Error(`need two runs with findings to compare; found ${runs.length}`);
-    runB = runB ?? runs[runs.length - 1];
-    runA = runA ?? runs[runs.length - 2];
+export const COMPARISON_STATES = Object.freeze([
+  'persisted', 'resolved', 'new', 'changed', 'not_comparable', 'not_reobserved', 'indeterminate',
+]);
+
+function normalizeCandidate(value) {
+  if (!value) return null;
+  try { return normalizeUrlIdentity(String(value)); } catch { return String(value); }
+}
+
+/** Keep effective/requested identity distinct; canonical is never fetch identity. */
+export function resourceIdentityFor(findingOrPage) {
+  const subject = findingOrPage?.subject || findingOrPage || {};
+  const identity = subject.urlIdentity || subject.url_identity || {};
+  const ids = new Set([
+    subject.resource_id, identity.resource_id,
+    subject.classification?.resource_id, subject.evaluation?.resource_id,
+    ...(findingOrPage?.evidence_scope?.resource_ids || []),
+  ].filter(Boolean).map(String));
+  const requested = normalizeCandidate(identity.requested?.normalized_url || identity.requested?.url || subject.requested_url);
+  const effective = normalizeCandidate(identity.effective?.normalized_url || identity.effective?.url
+    || subject.effective_url || subject.normalized_url || subject.url || subject.identifier);
+  const canonical = normalizeCandidate(identity.canonical?.normalized_url || identity.canonical?.url || subject.canonical_url);
+  const fallback = new Set([requested, effective, normalizeCandidate(subject.url || subject.identifier)].filter(Boolean));
+  return { resourceIds: ids, requested, effective, canonical, fallbackUrls: fallback };
+}
+
+export function sameResourceIdentity(left, right) {
+  const a = resourceIdentityFor(left); const b = resourceIdentityFor(right);
+  if (a.resourceIds.size && b.resourceIds.size) {
+    return [...a.resourceIds].some((id) => b.resourceIds.has(id));
   }
-  const load = (r) => {
-    const dir = path.join(runsDir, r);
-    if (!fs.existsSync(path.join(dir, 'findings.json'))) throw new Error(`run ${r} has no findings.json`);
-    return {
-      findings: readJson(path.join(dir, 'findings.json')),
-      manifest: readJson(path.join(dir, 'manifest.json')),
-    };
-  };
-  const a = load(runA);
-  const b = load(runB);
-  const changedKeys = (left = {}, right = {}) => [...new Set([...Object.keys(left), ...Object.keys(right)])].filter((key) => left[key] !== right[key]);
+  if (a.effective && b.effective) return a.effective === b.effective;
+  if (a.requested && b.requested) return a.requested === b.requested;
+  // URL fallback is allowed only when each side has exactly one candidate.
+  return a.fallbackUrls.size === 1 && b.fallbackUrls.size === 1
+    && [...a.fallbackUrls][0] === [...b.fallbackUrls][0];
+}
+
+function findingKey(finding) {
+  const identity = resourceIdentityFor(finding);
+  const id = identity.resourceIds.size ? [...identity.resourceIds].sort().join(',')
+    : identity.effective || identity.requested || (identity.fallbackUrls.size === 1 ? [...identity.fallbackUrls][0] : JSON.stringify(finding?.subject || {}));
+  return `${finding?.detector_id || ''}|${id}`;
+}
+
+function loadCoverage(dir) {
+  const file = path.join(dir, 'coverage.json');
+  return fs.existsSync(file) ? readJson(file) : null;
+}
+
+function coverageResource(coverage, finding) {
+  if (!Array.isArray(coverage?.resources)) return null;
+  const target = resourceIdentityFor(finding);
+  const byId = coverage.resources.filter((resource) => {
+    const ids = resourceIdentityFor(resource).resourceIds;
+    return [...target.resourceIds].some((id) => ids.has(id));
+  });
+  if (target.resourceIds.size) return byId.length === 1 ? byId[0] : null;
+  const byUrl = coverage.resources.filter((resource) => sameResourceIdentity(finding, resource));
+  return byUrl.length === 1 ? byUrl[0] : null;
+}
+
+export function assessReobservation(finding, coverage) {
+  if (!coverage) return { state: 'not_reobserved', reason: 'comparison_run_has_no_coverage_artifact' };
+  const resource = coverageResource(coverage, finding);
+  if (!resource) return { state: 'not_reobserved', reason: 'resource_not_reobserved_in_comparison_run' };
+  if (['failed', 'indeterminate', 'unvisited', 'valid_but_unevaluated'].includes(resource.state)) {
+    return { state: resource.state === 'indeterminate' ? 'indeterminate' : 'not_reobserved', reason: `resource_state_${resource.state}`, resource };
+  }
+  if (resource.state !== 'evaluated') return { state: 'not_reobserved', reason: `resource_state_${resource.state || 'unknown'}`, resource };
+  if (finding?.evidence_scope?.requirement === 'exhaustive_requested_scope' && coverage.coverage_status !== 'complete') {
+    return { state: 'indeterminate', reason: 'exhaustive_scope_coverage_incomplete', resource };
+  }
+  return { state: 'resolved', reason: 'resource_reobserved_with_sufficient_coverage', resource };
+}
+
+function changedKeys(left = {}, right = {}) {
+  return [...new Set([...Object.keys(left), ...Object.keys(right)])].filter((key) => left[key] !== right[key]);
+}
+
+function comparabilityFor(a, b) {
   const changeDimensions = {
     resource_changed: changedKeys(a.manifest.input_hashes, b.manifest.input_hashes),
     evidence_artifacts_changed: changedKeys(a.manifest.output_hashes, b.manifest.output_hashes),
     detector_set_changed: JSON.stringify(a.manifest.detectors_run) !== JSON.stringify(b.manifest.detectors_run),
     configuration_changed: a.manifest.configuration_hash !== b.manifest.configuration_hash,
-    observation_method_changed: a.manifest.command !== b.manifest.command || JSON.stringify(a.manifest.argv) !== JSON.stringify(b.manifest.argv) || a.manifest.target?.kind !== b.manifest.target?.kind,
+    observation_method_changed: a.manifest.command !== b.manifest.command
+      || JSON.stringify(a.manifest.argv) !== JSON.stringify(b.manifest.argv)
+      || a.manifest.target?.kind !== b.manifest.target?.kind,
     tool_changed: a.manifest.tool_version !== b.manifest.tool_version,
     external_system_may_have_changed: a.manifest.target?.kind === 'url' || b.manifest.target?.kind === 'url',
   };
-  const key = (f) => `${f.detector_id}|${f.subject.identifier}|${f.observation.summary}`;
-  const aKeys = new Map(a.findings.map((f) => [key(f), f]));
-  const bKeys = new Map(b.findings.map((f) => [key(f), f]));
-  const regressions = [...bKeys.entries()].filter(([k]) => !aKeys.has(k)).map(([, f]) => f);
-  const resolved = [...aKeys.entries()].filter(([k]) => !bKeys.has(k)).map(([, f]) => f);
-  const persisting = [...bKeys.entries()].filter(([k]) => aKeys.has(k)).map(([, f]) => f);
   return {
-    runA, runB,
-    baseline_timestamp: a.manifest.timestamp,
-    comparison_timestamp: b.manifest.timestamp,
-    regressions, resolved, persisting,
-    comparability: {
-      comparable: !changeDimensions.detector_set_changed && !changeDimensions.configuration_changed && !changeDimensions.observation_method_changed && !changeDimensions.tool_changed,
-      change_dimensions: changeDimensions,
-      limitation: 'These dimensions identify observed differences between run envelopes; they do not establish what caused a finding change.',
-    },
-    summary: {
-      new_findings: regressions.length,
-      resolved_findings: resolved.length,
-      persisting_findings: persisting.length,
-      regression_critical_or_high: regressions.filter((f) => ['critical', 'high'].includes(f.classification.severity)).length,
-    },
+    comparable: !changeDimensions.detector_set_changed
+      && !changeDimensions.configuration_changed
+      && !changeDimensions.observation_method_changed
+      && !changeDimensions.tool_changed,
+    change_dimensions: changeDimensions,
+    limitation: 'These dimensions identify observed differences between run envelopes; they do not establish what caused a finding change.',
+  };
+}
+
+function withState(finding, state, reason, extra = {}) {
+  return { ...finding, comparison_state: state, comparison_provenance: { reason, ...extra } };
+}
+
+/** Compare findings only after checking that their responsible resource was reobserved. */
+export function compareSnapshots(root, { runA, runB } = {}) {
+  const runsDir = path.join(root, '.citable', 'runs');
+  if (!fs.existsSync(runsDir)) throw new Error('no runs recorded yet');
+  const runs = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json'))).sort();
+  if (!runA || !runB) {
+    if (runs.length < 2) throw new Error(`need two runs with findings to compare; found ${runs.length}`);
+    runB = runB ?? runs[runs.length - 1];
+    runA = runA ?? runs[runs.length - 2];
+  }
+  const load = (runId) => {
+    const dir = path.join(runsDir, runId);
+    if (!fs.existsSync(path.join(dir, 'findings.json'))) throw new Error(`run ${runId} has no findings.json`);
+    const loaded = loadVerifiedRun(dir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+    return { findings: loaded.findings, manifest: loaded.manifest, coverage: loaded.coverage };
+  };
+  const a = load(runA); const b = load(runB);
+  const comparability = comparabilityFor(a, b);
+  const aFindings = a.findings;
+  const bFindings = b.findings;
+  const matchedA = new Set();
+  const result = {
+    runA, runB, baseline_timestamp: a.manifest.timestamp, comparison_timestamp: b.manifest.timestamp,
+    regressions: [], resolved: [], persisting: [], new: [], changed: [], not_comparable: [], not_reobserved: [], indeterminate: [],
+    comparability,
+  };
+  for (const finding of bFindings) {
+    const priorIndex = aFindings.findIndex((candidate, index) => !matchedA.has(index)
+      && candidate.detector_id === finding.detector_id && sameResourceIdentity(candidate, finding));
+    const prior = priorIndex >= 0 ? aFindings[priorIndex] : null;
+    if (priorIndex >= 0) matchedA.add(priorIndex);
+    if (!prior) {
+      const item = withState(finding, 'new', 'finding_not_present_in_baseline');
+      result.new.push(item); result.regressions.push(item); continue;
+    }
+    if (!comparability.comparable) result.not_comparable.push(withState(finding, 'not_comparable', 'run_envelopes_not_comparable'));
+    else if (JSON.stringify(prior.observation) !== JSON.stringify(finding.observation)) result.changed.push(withState(finding, 'changed', 'finding_observation_changed'));
+    else result.persisting.push(withState(finding, 'persisted', 'finding_observation_persisted'));
+  }
+  for (let index = 0; index < aFindings.length; index += 1) {
+    const finding = aFindings[index];
+    if (matchedA.has(index)) continue;
+    if (!comparability.comparable) { result.not_comparable.push(withState(finding, 'not_comparable', 'run_envelopes_not_comparable')); continue; }
+    const state = assessReobservation(finding, b.coverage);
+    const item = withState(finding, state.state, state.reason, {
+      resource: state.resource?.normalized_url || null, comparison_coverage_status: b.coverage?.coverage_status || 'not_available',
+    });
+    if (state.state === 'resolved') result.resolved.push(item);
+    else if (state.state === 'indeterminate') result.indeterminate.push(item);
+    else result.not_reobserved.push(item);
+  }
+  result.summary = {
+    new_findings: result.new.length, changed_findings: result.changed.length, resolved_findings: result.resolved.length,
+    persisting_findings: result.persisting.length, not_comparable_findings: result.not_comparable.length,
+    not_reobserved_findings: result.not_reobserved.length, indeterminate_findings: result.indeterminate.length,
+    regression_critical_or_high: result.regressions.filter((f) => ['critical', 'high'].includes(f.classification?.severity)).length,
   };
+  return result;
 }

package/src/commands/connect.js

@@ -79,16 +79,37 @@ export async function syncConnection(root, { connectionId, startDate, endDate, a
     }
     throw error;
   }
+  // Connector collection may preserve a partial result even when the provider
+  // reports an authorization/quota state. Keep the result available to direct
+  // connector callers, while retaining the command's legacy state transition.
+  if (result.connectorError?.connectorState) {
+    const error = result.connectorError;
+    const failed = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: error.connectorState, limitations: [...(result.collection?.errors || []), 'Connector synchronization did not complete; inspect collection errors.'] } : item) };
+    saveRegistry(root, 'connections', failed);
+    throw error;
+  }
+  const collection = result.collection || {
+    schema_version: 1,
+    items: result.rows,
+    pagination_state: { pages_requested: 1, pages_retrieved: 1 },
+    provider_reported_total: null,
+    retrieved_total: result.rows.length,
+    coverage_status: 'indeterminate',
+    continuation_state: null,
+    limitations: ['Connector did not provide a collection contract.'],
+    errors: [],
+  };
+  const collectionLimitations = [...collection.limitations, ...collection.errors];
   const observations = result.rows.map((row) => envelope('metric', {
     metric_id: row.metric.metric_id, provider: connector.provider, external_name: row.metric.external_name,
     value: Number(row.value), unit: row.metric.unit === 'custom' ? row.metric.custom_unit : row.metric.unit,
     aggregation: row.metric.aggregation, observed_at: row.observed_at, period_start: row.observed_at,
     period_end: row.observed_at, dimensions: row.dimensions,
-  }, { method: 'live_api', source: connector.provider, limitations: [...row.metric.limitations, ...result.limitations] }));
+  }, { method: 'live_api', source: connector.provider, limitations: [...row.metric.limitations, ...collectionLimitations] }));
   const run = observationRun(root, 'connect sync', loaded.connection.property_id, observations);
-  const updated = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: 'synchronized', last_synchronized_at: new Date().toISOString(), cursor: result.cursor, limitations: result.limitations } : item) };
+  const updated = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: ['truncated', 'indeterminate'].includes(collection.coverage_status) ? 'partial' : 'synchronized', last_synchronized_at: new Date().toISOString(), cursor: result.cursor, limitations: collectionLimitations } : item) };
   saveRegistry(root, 'connections', updated);
-  return { ...run, connection_id: connectionId, provider: connector.provider };
+  return { ...run, connection_id: connectionId, provider: connector.provider, collection };
 }
 
 export async function readCmsContent(root, { connectionId, targetId, accessToken, env, fetchImpl } = {}) {
@@ -119,4 +140,3 @@ export async function applyCmsRemediation(root, { connectionId, input, write = f
 
 export { submitIndexNow, verifyHostKey, buildIndexNowPayload, normalizeHost, parseUrlsInput } from '../connectors/indexnow.js';
 export { collectMcpEvidence } from '../connectors/mcp/pilot.js';
-