@nebulacomponents/citable 1.19.0 → 1.21.0

package/src/commands/reviews.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import { loadRegistries, saveRegistry } from '../registries/index.js';
 import { readJson, readYaml, sha256, nowIso } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
@@ -23,7 +24,7 @@ export function queueReviews(root, { runId, policyId, write = false }) {
   if (!runId || !policyId) throw new Error('reviews queue requires <run-id> <policy-id>');
   const file = path.join(root,'.citable','runs',runId,'findings.json');
   if (!fs.existsSync(file)) throw new Error(`source findings not found for run ${runId}`);
-  const findings = readJson(file);
+  const findings = loadVerifiedRun(path.dirname(file), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings;
   const { registries, problems } = loadRegistries(root);
   if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
   if (!registries.review_policies.entries.some((p) => p.policy_id === policyId && p.status === 'active')) throw new Error(`active review policy not found: ${policyId}`);
@@ -40,7 +41,7 @@ export function queueReviews(root, { runId, policyId, write = false }) {
 export function prioritizeReviews(root, { write = false } = {}) {
   const { registries, problems } = loadRegistries(root); if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
   const cache = new Map();
-  const entries = registries.review_items.entries.map((item) => { const file=path.join(root,'.citable','runs',item.source_run_id,'findings.json'); if(!cache.has(file)) cache.set(file,fs.existsSync(file)?new Map(readJson(file).map(f=>[f.finding_id,f])):new Map()); const ranked=priority(item,cache.get(file).get(item.finding_id)); return {...item,priority_score:ranked.score,priority_tier:ranked.tier,missing_inputs:ranked.missing}; });
+  const entries = registries.review_items.entries.map((item) => { const file=path.join(root,'.citable','runs',item.source_run_id,'findings.json'); if(!cache.has(file)) cache.set(file,fs.existsSync(file)?new Map(loadVerifiedRun(path.dirname(file), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings.map(f=>[f.finding_id,f])):new Map()); const ranked=priority(item,cache.get(file).get(item.finding_id)); return {...item,priority_score:ranked.score,priority_tier:ranked.tier,missing_inputs:ranked.missing}; });
   if(write) saveRegistry(root,'review_items',{...registries.review_items,entries});
   return { items:entries.sort((a,b)=>b.priority_score-a.priority_score), written:write };
 }
@@ -67,7 +68,32 @@ export function selectSample(root,{planId,write=false}) {
 }
 
 export function evaluateReviews(root) {
-  const {registries,problems}=loadRegistries(root); const reviewers=new Map(registries.reviewers.entries.map(r=>[r.reviewer_id,r])); const results=[];
-  for(const item of registries.review_items.entries){const issues=[];const binding=reviewBindingHash(item);const source=path.join(root,'.citable','runs',item.source_run_id,'findings.json');const finding=fs.existsSync(source)?readJson(source).find(f=>f.finding_id===item.finding_id):null;if(!finding||sha256(JSON.stringify(finding))!==item.finding_hash)issues.push('source finding is unavailable or changed');for(const d of item.decisions){const r=reviewers.get(d.reviewer_id);const reviewRole=r?.roles.some(role=>['technical_reviewer','subject_matter_reviewer','independent_reviewer'].includes(role));if(!r||r.status!=='active'||!reviewRole||!item.assigned_reviewer_ids.includes(d.reviewer_id))issues.push(`${d.reviewer_id} is not an active assigned semantic reviewer`);if(d.review_item_hash!==binding)issues.push(`${d.reviewer_id} decision is stale`);}const verdicts=[...new Set(item.decisions.map(d=>d.verdict))];let state=item.decisions.length?'completed':'review_required';if(verdicts.length>1){state='adjudication_required';const a=reviewers.get(item.adjudication?.reviewer_id);if(item.adjudication&&a?.status==='active'&&a.roles.includes('independent_reviewer')&&item.adjudication.review_item_hash===binding)state='completed';else issues.push('reviewer disagreement requires a current decision from an active independent adjudicator');}results.push({review_item_id:item.review_item_id,state,verdict:state==='completed'&&!issues.length?(item.adjudication?.verdict||verdicts[0]):null,issues});}
-  return {ok:problems.length===0&&results.every(r=>!r.issues.length),problems,results};
+  const { registries, problems } = loadRegistries(root);
+  const reviewers = new Map(registries.reviewers.entries.map((r) => [r.reviewer_id, r]));
+  const results = [];
+  for (const item of registries.review_items.entries) {
+    const issues = [];
+    const binding = reviewBindingHash(item);
+    const source = path.join(root, '.citable', 'runs', item.source_run_id, 'findings.json');
+    const finding = fs.existsSync(source)
+      ? loadVerifiedRun(path.dirname(source), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings.find((f) => f.finding_id === item.finding_id)
+      : null;
+    if (!finding || sha256(JSON.stringify(finding)) !== item.finding_hash) issues.push('source finding is unavailable or changed');
+    for (const decision of item.decisions) {
+      const reviewer = reviewers.get(decision.reviewer_id);
+      const reviewRole = reviewer?.roles.some((role) => ['technical_reviewer', 'subject_matter_reviewer', 'independent_reviewer'].includes(role));
+      if (!reviewer || reviewer.status !== 'active' || !reviewRole || !item.assigned_reviewer_ids.includes(decision.reviewer_id)) issues.push(`${decision.reviewer_id} is not an active assigned semantic reviewer`);
+      if (decision.review_item_hash !== binding) issues.push(`${decision.reviewer_id} decision is stale`);
+    }
+    const verdicts = [...new Set(item.decisions.map((d) => d.verdict))];
+    let state = item.decisions.length ? 'completed' : 'review_required';
+    if (verdicts.length > 1) {
+      state = 'adjudication_required';
+      const adjudicator = reviewers.get(item.adjudication?.reviewer_id);
+      if (item.adjudication && adjudicator?.status === 'active' && adjudicator.roles.includes('independent_reviewer') && item.adjudication.review_item_hash === binding) state = 'completed';
+      else issues.push('reviewer disagreement requires a current decision from an active independent adjudicator');
+    }
+    results.push({ review_item_id: item.review_item_id, state, verdict: state === 'completed' && !issues.length ? (item.adjudication?.verdict || verdicts[0]) : null, issues });
+  }
+  return { ok: problems.length === 0 && results.every((r) => !r.issues.length), problems, results };
 }

package/src/commands/roadmapCmd.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { contextDir, loadRegistryFile } from '../registries/index.js';
-import { readJson, writeJson } from '../shared/io.js';
+import { writeJson } from '../shared/io.js';
 import { buildStrategicRoadmap, formatRoadmapMarkdown } from '../analysis/strategicRoadmap.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 /**
  * `citable roadmap [generate|show]` — generate or view the 30/90/180-day strategic roadmap.
@@ -10,6 +11,7 @@ import { buildStrategicRoadmap, formatRoadmapMarkdown } from '../analysis/strate
 export async function roadmapCommand(root, { runId, target, write = true } = {}) {
   let findings = [];
   let initiatives = [];
+  let verifiedRun = null;
 
   // 1. Load findings from specified or latest run
   const runsDir = path.join(root, '.citable', 'runs');
@@ -20,10 +22,8 @@ export async function roadmapCommand(root, { runId, target, write = true } = {})
   }
 
   if (sourceRun) {
-    const findingsFile = path.join(runsDir, sourceRun, 'findings.json');
-    if (fs.existsSync(findingsFile)) {
-      findings = JSON.parse(fs.readFileSync(findingsFile, 'utf8'));
-    }
+    verifiedRun = loadVerifiedRun(path.join(runsDir, sourceRun), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+    findings = verifiedRun.findings;
   }
 
   // 2. Load initiatives if present
@@ -39,14 +39,8 @@ export async function roadmapCommand(root, { runId, target, write = true } = {})
 
   // Target domain resolution
   let domain = target || 'nebulacomponents.com';
-  if (sourceRun) {
-    const manifestFile = path.join(runsDir, sourceRun, 'manifest.json');
-    if (fs.existsSync(manifestFile)) {
-      try {
-        const manifest = readJson(manifestFile);
-        if (manifest.target?.location) domain = manifest.target.location;
-      } catch {}
-    }
+  if (verifiedRun?.manifest?.target?.location) {
+    domain = verifiedRun.manifest.target.location;
   }
 
   const roadmap = buildStrategicRoadmap({ findings, initiatives, targetDomain: domain });

package/src/commands/sweep.js

@@ -4,6 +4,7 @@ import { parse as parseHtml } from 'node-html-parser';
 import { buildContext } from './context.js';
 import { selectDetectors } from '../detectors/index.js';
 import { runDetectors, indexTargets, pageSubject, safePath } from '../detectors/framework.js';
+import { downstreamEnvelope, scoreFromCoverage, completeLocalCoverage } from '../evidence/downstream.js';
 
 /**
  * CWV standard thresholds per Google / web.dev guidance
@@ -223,6 +224,9 @@ export async function sweepTechnical(root, { target, baseUrl, refDate, page: pag
     if (!pages.length) throw new Error(`page not found in audited output: ${pageFilter}`);
   }
 
+  const coverage = ctx.coverage || (pages.length > 0 ? completeLocalCoverage(pages, ctx.site.baseUrl) : null);
+  const evidence = downstreamEnvelope(coverage);
+
   // 3. Aggregate Core Web Vitals across audited pages
   const pageVitals = [];
   let totalLcpBlockers = 0;
@@ -269,6 +273,8 @@ export async function sweepTechnical(root, { target, baseUrl, refDate, page: pag
   } else if (highFindings.length > 0 || totalLcpBlockers > 3 || totalClsRisks > 5) {
     overallHealth = 'needs_attention';
   }
+  if (evidence.determination_status === 'indeterminate') overallHealth = 'not_established';
+  else if (evidence.determination_status === 'qualified' && overallHealth === 'optimal') overallHealth = 'qualified';
 
   const result = {
     target: ctx.site.baseUrl || target,
@@ -291,7 +297,9 @@ export async function sweepTechnical(root, { target, baseUrl, refDate, page: pag
         total_inp_risks: totalInpRisks,
         unsized_images: totalUnsizedImages,
         total_images: totalImagesCount,
-        image_dimension_coverage_pct: totalImagesCount > 0 ? Math.round(((totalImagesCount - totalUnsizedImages) / totalImagesCount) * 100) : 100,
+        image_dimension_coverage_pct: evidence.determination_status === 'supported' && totalImagesCount > 0
+          ? scoreFromCoverage(totalImagesCount - totalUnsizedImages, { ...coverage, populations: { ...coverage.populations, evaluated: totalImagesCount } })
+          : null,
       },
       pages: pageVitals,
     },
@@ -310,6 +318,10 @@ export async function sweepTechnical(root, { target, baseUrl, refDate, page: pag
       summary: f.observation.summary,
       remediation: f.remediation?.preferred,
     })),
+    coverage_status: evidence.coverage_status,
+    determination_status: evidence.determination_status,
+    evidence_scope: evidence.evidence_scope,
+    limitations: evidence.limitations,
   };
 
   return result;
@@ -325,6 +337,7 @@ export function formatSweepOutput(r) {
     `Target: ${r.target}`,
     `Pages Audited: ${r.total_pages_audited}`,
     `Overall Health: ${r.overall_health.toUpperCase()}`,
+    `Evidence Determination: ${(r.determination_status || 'not_established').toUpperCase()} (coverage: ${r.coverage_status || 'unknown'})`,
     ``,
     `CRAWL & INDEXABILITY:`,
     `  HTTP 200 OK: ${r.crawl_and_indexability.status_200_count}/${r.total_pages_audited}`,
@@ -335,7 +348,7 @@ export function formatSweepOutput(r) {
     `CORE WEB VITALS READINESS (Deterministic Static Audit):`,
     `  LCP Readiness: ${r.core_web_vitals.summary.lcp_readiness.toUpperCase()} (${r.core_web_vitals.summary.total_lcp_blockers} potential render blocker(s))`,
     `  INP Readiness: ${r.core_web_vitals.summary.inp_readiness.toUpperCase()} (${r.core_web_vitals.summary.total_inp_risks} DOM complexity risk(s))`,
-    `  CLS Readiness: ${r.core_web_vitals.summary.cls_readiness.toUpperCase()} (${r.core_web_vitals.summary.unsized_images}/${r.core_web_vitals.summary.total_images} images lack dimensions; ${r.core_web_vitals.summary.image_dimension_coverage_pct}% coverage)`,
+    `  CLS Readiness: ${r.core_web_vitals.summary.cls_readiness.toUpperCase()} (${r.core_web_vitals.summary.unsized_images}/${r.core_web_vitals.summary.total_images} images lack dimensions; ${r.core_web_vitals.summary.image_dimension_coverage_pct == null ? 'not evidenced' : `${r.core_web_vitals.summary.image_dimension_coverage_pct}%`} coverage)`,
     ``,
     `CWV Threshold Standards:`,
     `  - LCP: <= ${CWV_THRESHOLDS.lcp.good}s (Good), <= ${CWV_THRESHOLDS.lcp.needs_improvement}s (Needs Improvement)`,

package/src/commands/verifyRemediation.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import crypto from 'node:crypto';
 import { readJson, writeJson, nowIso } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
@@ -7,6 +8,7 @@ import { buildContext } from './context.js';
 import { runDetectors } from '../detectors/framework.js';
 import { selectDetectors } from '../detectors/index.js';
 import { remediateCommand } from './remediate.js';
+import { assessReobservation, resourceIdentityFor, sameResourceIdentity } from './compareSnapshots.js';
 
 const PKG_VERSION = JSON.parse(
   fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
@@ -20,14 +22,49 @@ function sha256(content) {
   return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
 }
 
-function subjectKey(subject) {
-  return subject?.identifier || subject?.url || JSON.stringify(subject) || 'unknown';
+function findingIdentityKey(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 newVerificationId() {
   return `VR-${nowIso().replace(/\D/g, '')}-${Math.random().toString(36).slice(2, 6)}`;
 }
 
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function recheckComparability(manifest, sourceFinding, afterFinding, ctx, detector) {
+  const sourceKind = manifest?.target?.kind || null;
+  const recheckKind = ctx.site?.mode || null;
+  const sourceDetectorVersion = sourceFinding?.provenance?.detector_version ?? 1;
+  const recheckDetectorVersion = afterFinding?.provenance?.detector_version ?? detector?.version ?? 1;
+  const sourceViewport = sourceFinding?.provenance?.viewport ?? null;
+  const recheckViewport = ctx.viewport ?? null;
+  const sourceConfig = manifest?.configuration_hash || null;
+  const recheckConfig = sha256(JSON.stringify(ctx.config));
+  const dimensions = {
+    tool_changed: (manifest?.tool_version || null) !== PKG_VERSION,
+    evaluator_changed: sourceDetectorVersion !== recheckDetectorVersion,
+    observation_method_changed: sourceKind !== recheckKind
+      || canonicalJson(sourceViewport) !== canonicalJson(recheckViewport),
+    configuration_changed: sourceConfig !== recheckConfig,
+  };
+  return {
+    comparable: !Object.values(dimensions).some(Boolean),
+    dimensions,
+    source: { tool_version: manifest?.tool_version || null, evaluator_version: sourceDetectorVersion, target_kind: sourceKind, configuration_hash: sourceConfig },
+    recheck: { tool_version: PKG_VERSION, evaluator_version: recheckDetectorVersion, target_kind: recheckKind, configuration_hash: recheckConfig },
+  };
+}
+
 /**
  * `citable verify remediation` — closed loop: source-run finding -> patch ->
  * detector re-run -> before/after evidence bundle.
@@ -37,7 +74,7 @@ function newVerificationId() {
  * never a silent `verified`.
  */
 export async function verifyRemediation(root, options = {}) {
-  const { run: runId, finding, target, apply = false, subject = null } = options;
+  const { run: runId, finding, target, apply = false, subject = null, viewport = null } = options;
   const runDir = path.join(root, '.citable', 'runs', runId || '');
   const limitations = [
     RESOLUTION_DEFINITION,
@@ -55,7 +92,7 @@ export async function verifyRemediation(root, options = {}) {
     recheck_run_id: null,
     detector_id: finding ? String(finding).toUpperCase() : null,
     subject: null,
-    verdict: { resolved: false, before_finding_ids: [], after_finding_ids: [], new_regressions: [], resolution_definition: RESOLUTION_DEFINITION },
+    verdict: { resolved: false, comparison_state: 'indeterminate', before_finding_ids: [], after_finding_ids: [], new_regressions: [], resolution_definition: RESOLUTION_DEFINITION },
     patch: null,
     provenance: { command: 'verify remediation', recheck_target: target || null, detectors_run: [], detectors_skipped: [], recheck_errors: [], recheck_warnings: [] },
     limitations,
@@ -73,23 +110,23 @@ export async function verifyRemediation(root, options = {}) {
     return finalizeResult(result);
   }
 
-  const beforeFindings = readJson(path.join(runDir, 'findings.json'));
-  const manifest = fs.existsSync(path.join(runDir, 'manifest.json'))
-    ? readJson(path.join(runDir, 'manifest.json'))
-    : null;
+  const source = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const beforeFindings = source.findings;
+  const manifest = source.manifest;
   result.tool_version = manifest?.tool_version || PKG_VERSION;
   result.repository_commit = manifest?.repository_commit ?? null;
 
+  const requestedSubject = subject ? { subject: { identifier: subject } } : null;
   const matches = beforeFindings.filter((f) =>
     (f.detector_id || '').toUpperCase() === result.detector_id
-    && (!subject || subjectKey(f.subject) === subject));
+    && (!requestedSubject || sameResourceIdentity(f, requestedSubject)));
   if (matches.length === 0) {
     result.provenance.recheck_errors.push(`finding ${result.detector_id} not present in source run ${runId}`);
     result.status = 'blocked';
     return finalizeResult(result);
   }
   result.verdict.before_finding_ids = matches.map((f) => f.finding_id);
-  result.subject = { type: matches[0].subject?.type || 'unknown', identifier: subject || subjectKey(matches[0].subject) };
+  result.subject = { type: matches[0].subject?.type || 'unknown', identifier: subject || matches[0].subject?.identifier || matches[0].subject?.url || 'unknown' };
 
   // Optional gated patch application (production-safe pipeline from remediate.js)
   if (target && apply) {
@@ -133,7 +170,7 @@ export async function verifyRemediation(root, options = {}) {
   const namespace = result.detector_id.split('-')[0];
   let ctx;
   try {
-    ctx = await buildContext(root, { target: recheckTarget, baseUrl: options.baseUrl, refDate: options.refDate });
+    ctx = await buildContext(root, { target: recheckTarget, baseUrl: options.baseUrl, refDate: options.refDate, viewport });
   } catch (err) {
     result.provenance.recheck_errors.push(`re-check context failed: ${err.message}`);
     result.limitations.push('required_input: a readable target directory or URL for the detector re-run.');
@@ -155,24 +192,62 @@ export async function verifyRemediation(root, options = {}) {
 
   const afterMatches = afterFindings.filter((f) =>
     (f.detector_id || '').toUpperCase() === result.detector_id
-    && subjectKey(f.subject) === subjectKey(matches[0].subject));
+    && sameResourceIdentity(f, matches[0]));
   result.verdict.after_finding_ids = afterMatches.map((f) => f.finding_id);
 
-  const beforeKeys = new Set(beforeFindings.map((f) => `${f.detector_id}|${subjectKey(f.subject)}|${f.observation?.summary}`));
-  const afterKeys = new Set(afterFindings.map((f) => `${f.detector_id}|${subjectKey(f.subject)}|${f.observation?.summary}`));
+  const beforeKeys = new Set(beforeFindings.map((f) => `${findingIdentityKey(f)}|${f.observation?.summary}`));
+  const afterKeys = new Set(afterFindings.map((f) => `${findingIdentityKey(f)}|${f.observation?.summary}`));
   result.verdict.new_regressions = afterFindings
     .filter((f) => ['critical', 'high'].includes(f.classification?.severity))
-    .filter((f) => !beforeKeys.has(`${f.detector_id}|${subjectKey(f.subject)}|${f.observation?.summary}`))
+    .filter((f) => !beforeKeys.has(`${findingIdentityKey(f)}|${f.observation?.summary}`))
     .map((f) => ({ finding_id: f.finding_id, detector_id: f.detector_id, severity: f.classification.severity, summary: f.observation?.summary }));
 
+  const detectorDefinition = selectDetectors({ namespaces: [namespace] })
+    .find((candidate) => candidate.id === result.detector_id);
+  const comparability = recheckComparability(manifest, matches[0], afterMatches[0], ctx, detectorDefinition);
+
+  // Finalize the same collection envelope used by audit so detector absence
+  // is only resolution when the responsible resource was actually observed.
+  let recheckCoverage = null;
+  if (ctx.site?.finalizeCoverage) {
+    try { recheckCoverage = ctx.site.finalizeCoverage({ evaluated: true }); }
+    catch (error) { result.provenance.recheck_errors.push(`coverage finalization failed: ${error.message}`); }
+  }
+  let reobservation = assessReobservation(matches[0], recheckCoverage);
+  // Directory re-checks predate the coverage ledger and intentionally do not
+  // manufacture a package artifact. Their concrete page model is still a
+  // sufficient page-local observation when the subject is present.
+  if (!recheckCoverage && ctx.site?.pages?.some((page) => sameResourceIdentity(matches[0], page))) {
+    reobservation = { state: 'resolved', reason: 'page_present_in_recheck_model', resource: null };
+  }
+  result.comparison = {
+    state: comparability.comparable ? reobservation.state : 'not_comparable',
+    reason: reobservation.reason,
+    coverage_status: recheckCoverage?.coverage_status || 'not_available',
+    resource: reobservation.resource?.normalized_url || null,
+    comparability,
+  };
+  result.verdict.comparison_state = comparability.comparable ? reobservation.state : 'not_comparable';
+
   const errorsDuringRecheck = result.provenance.recheck_errors.length > 0;
   if (errorsDuringRecheck) {
-    result.status = 'blocked';
+    result.status = 'indeterminate';
+    result.verdict.resolved = false;
+    result.verdict.comparison_state = 'indeterminate';
+    result.limitations.push('Detector or collection errors occurred during the re-check; resolution cannot be established from a failed observation.');
+  } else if (!comparability.comparable) {
+    result.status = 'not_comparable';
     result.verdict.resolved = false;
-    result.limitations.push('Detector errors occurred during the re-check; resolution cannot be established from a failed observation.');
+    result.limitations.push('The source and re-check evaluator/tool/method/configuration envelopes are not comparable; resolution is not established.');
   } else if (afterMatches.length === 0) {
-    result.status = 'verified';
-    result.verdict.resolved = true;
+    if (reobservation.state === 'resolved') {
+      result.status = 'verified';
+      result.verdict.resolved = true;
+    } else {
+      result.status = reobservation.state === 'indeterminate' ? 'indeterminate' : 'not_reobserved';
+      result.verdict.resolved = false;
+      result.limitations.push(`The source subject was not sufficiently reobserved: ${reobservation.reason}.`);
+    }
   } else {
     result.status = 'not_resolved';
     result.verdict.resolved = false;

package/src/connectors/collectionResult.js

@@ -0,0 +1,80 @@
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+export const COLLECTION_SCHEMA_VERSION = 1;
+export const COLLECTION_COVERAGE_STATUSES = new Set([
+  'complete',
+  'truncated',
+  'indeterminate',
+  'provider_bounded',
+]);
+
+function nonNegativeInteger(value, name) {
+  if (!Number.isInteger(value) || value < 0) throw new TypeError(`${name} must be a non-negative integer`);
+  return value;
+}
+
+function stringList(value, name) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) throw new TypeError(`${name} must be an array of strings`);
+  return [...new Set(value)];
+}
+
+/**
+ * Build the provider-neutral collection envelope. `items` are the items
+ * actually observed, never a provider-reported total or an inferred census.
+ */
+export function collectionResult({
+  items = [],
+  paginationState = {},
+  providerReportedTotal = null,
+  continuationState = null,
+  limitations = [],
+  errors = [],
+  providerCompleteness = 'declared',
+} = {}) {
+  if (!Array.isArray(items)) throw new TypeError('items must be an array');
+  if (!paginationState || typeof paginationState !== 'object' || Array.isArray(paginationState)) throw new TypeError('paginationState must be an object');
+  if (providerReportedTotal !== null) nonNegativeInteger(providerReportedTotal, 'providerReportedTotal');
+  stringList(limitations, 'limitations');
+  stringList(errors, 'errors');
+  if (continuationState !== null && (typeof continuationState !== 'object' || Array.isArray(continuationState))) throw new TypeError('continuationState must be an object or null');
+  if (!['declared', 'unknown'].includes(providerCompleteness)) throw new TypeError('providerCompleteness must be declared or unknown');
+
+  const totalErrors = providerReportedTotal !== null && providerReportedTotal < items.length
+    ? [`provider reported total ${providerReportedTotal}, below retrieved item count ${items.length}`]
+    : [];
+  const cleanErrors = [...new Set([...errors, ...totalErrors])];
+  const contradictoryTotal = providerReportedTotal !== null && providerReportedTotal < items.length;
+  const unresolvedTotal = providerReportedTotal !== null && providerReportedTotal > items.length && !continuationState;
+  const status = (cleanErrors.length || contradictoryTotal)
+    ? 'indeterminate'
+    : continuationState
+      ? 'truncated'
+      : (unresolvedTotal || providerCompleteness === 'unknown')
+        ? 'provider_bounded'
+        : 'complete';
+  const result = {
+    schema_version: COLLECTION_SCHEMA_VERSION,
+    items,
+    pagination_state: paginationState,
+    provider_reported_total: providerReportedTotal,
+    retrieved_total: items.length,
+    coverage_status: status,
+    continuation_state: continuationState,
+    limitations: [...new Set(limitations)],
+    errors: cleanErrors,
+  };
+  const check = validateAgainst('collection-result.schema.json', result);
+  if (!check.valid) throw new TypeError(`invalid collection result: ${check.errors.join('; ')}`);
+  return result;
+}
+
+export function paginationBoundary(context = {}) {
+  const value = context.collectionMaxPages ?? context.maxPages ?? 1000;
+  if (!Number.isInteger(value) || value < 1 || value > 10000) throw new RangeError('collection max pages must be an integer from 1 to 10000');
+  return value;
+}
+
+export function errorMessage(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/Bearer\s+\S+/gi, 'Bearer [redacted]').slice(0, 300);
+}

package/src/connectors/ga4.js

@@ -1,4 +1,5 @@
 import { providerRequest } from './http.js';
+import { collectionResult, errorMessage, paginationBoundary } from './collectionResult.js';
 
 const DATA = 'https://analyticsdata.googleapis.com/v1beta';
 const ADMIN = 'https://analyticsadmin.googleapis.com/v1beta';
@@ -36,24 +37,58 @@ export const ga4Connector = {
     if (!dimensions.includes('landingPagePlusQueryString')) dimensions.push('landingPagePlusQueryString');
     const rows = [];
     const limitations = [];
+    const errors = [];
+    const items = [];
+    const maxPages = paginationBoundary(context);
+    let pagesRequested = 0;
+    let pagesRetrieved = 0;
+    let continuationState = null;
+    let providerTotal = null;
+    let connectorError = null;
     let offset = 0;
     do {
-      const result = await providerRequest(`${DATA}/properties/${encodeURIComponent(connection.property_id)}:runReport`, {
-        ...context, method: 'POST', body: {
-        dateRanges: [{ startDate, endDate }], dimensions: dimensions.map((name) => ({ name })),
-        metrics: metrics.map((metric) => ({ name: metric.external_name })), limit: '100000', offset: String(offset),
-        dimensionFilter: { filter: { fieldName: 'sessionDefaultChannelGroup', stringFilter: { matchType: 'EXACT', value: 'Organic Search' } } },
-        },
-      });
-      for (const row of result.rows || []) {
+      pagesRequested += 1;
+      let result;
+      try {
+        result = await providerRequest(`${DATA}/properties/${encodeURIComponent(connection.property_id)}:runReport`, {
+          ...context, method: 'POST', body: {
+          dateRanges: [{ startDate, endDate }], dimensions: dimensions.map((name) => ({ name })),
+          metrics: metrics.map((metric) => ({ name: metric.external_name })), limit: '100000', offset: String(offset),
+          dimensionFilter: { filter: { fieldName: 'sessionDefaultChannelGroup', stringFilter: { matchType: 'EXACT', value: 'Organic Search' } } },
+          },
+        });
+      } catch (error) {
+        connectorError ||= error;
+        errors.push(`offset ${offset}: ${errorMessage(error)}`);
+        continuationState = { offset };
+        break;
+      }
+      pagesRetrieved += 1;
+      const pageRows = result.rows || [];
+      items.push(...pageRows);
+      if (Number.isInteger(result.rowCount) && result.rowCount >= 0) providerTotal = result.rowCount;
+      for (const row of pageRows) {
         const values = Object.fromEntries(dimensions.map((name, index) => [name === 'landingPagePlusQueryString' ? 'url' : name, row.dimensionValues[index]?.value]));
         const date = values.date?.replace(/^(\d{4})(\d{2})(\d{2})$/, '$1-$2-$3');
         rows.push(...metrics.map((metric, index) => ({ metric, value: Number(row.metricValues[index]?.value), dimensions: values, observed_at: `${date}T00:00:00.000Z` })));
       }
       if (result.metadata?.dataLossFromOtherRow) limitations.push('Provider reports data loss from the (other) row.');
-      offset += (result.rows || []).length;
-      if (!result.rowCount || offset >= result.rowCount || !(result.rows || []).length) break;
+      offset += pageRows.length;
+      if ((result.rowCount === undefined || result.rowCount === null)
+        ? pageRows.length < 100000 || !pageRows.length
+        : offset >= result.rowCount || !pageRows.length) break;
+      if (pagesRequested >= maxPages) { continuationState = { offset }; break; }
     } while (true);
-    return { rows, cursor: endDate, limitations: [...new Set([...limitations, 'GA4 reporting identity, thresholding, attribution, and consent configuration affect results.', 'Sync is filtered to Organic Search sessions.'])] };
+    const providerCompleteness = limitations.some((item) => /data loss/i.test(item)) || providerTotal === null ? 'unknown' : 'declared';
+    const collection = collectionResult({
+      items,
+      paginationState: { pages_requested: pagesRequested, pages_retrieved: pagesRetrieved, boundary: { max_pages: maxPages } },
+      providerReportedTotal: providerTotal,
+      continuationState,
+      providerCompleteness,
+      limitations: [...new Set([...limitations, 'GA4 reporting identity, thresholding, attribution, and consent configuration affect results.', 'Sync is filtered to Organic Search sessions.'])],
+      errors,
+    });
+    return { rows, cursor: endDate, limitations: collection.limitations, collection, ...(connectorError ? { connectorError } : {}) };
   },
 };

package/src/connectors/gsc.js

@@ -1,4 +1,6 @@
 import { providerRequest } from './http.js';
+import { collectionResult, errorMessage, paginationBoundary } from './collectionResult.js';
+import { collectSearchConsoleObservations } from '../discovery/searchConsole.js';
 
 const BASE = 'https://www.googleapis.com/webmasters/v3';
 const METRICS = {
@@ -25,17 +27,54 @@ export const gscConnector = {
     if (!dimensions.includes('date')) dimensions.unshift('date');
     const rows = [];
     let startRow = 0;
+    const items = [];
+    const errors = [];
+    const maxPages = paginationBoundary(context);
+    let pagesRequested = 0;
+    let pagesRetrieved = 0;
+    let continuationState = null;
+    let providerTotal = null;
+    let connectorError = null;
     do {
-      const result = await providerRequest(`${BASE}/sites/${encodeURIComponent(connection.property_id)}/searchAnalytics/query`, {
-        ...context, method: 'POST', body: { startDate, endDate, dimensions, rowLimit: 25000, startRow, dataState: 'final' },
-      });
-      for (const row of result.rows || []) {
+      pagesRequested += 1;
+      let result;
+      try {
+        result = await providerRequest(`${BASE}/sites/${encodeURIComponent(connection.property_id)}/searchAnalytics/query`, {
+          ...context, method: 'POST', body: { startDate, endDate, dimensions, rowLimit: 25000, startRow, dataState: 'final' },
+        });
+      } catch (error) {
+        connectorError ||= error;
+        errors.push(`start row ${startRow}: ${errorMessage(error)}`);
+        continuationState = { start_row: startRow };
+        break;
+      }
+      pagesRetrieved += 1;
+      const pageRows = result.rows || [];
+      items.push(...pageRows);
+      if (Number.isInteger(result.rowCount) && result.rowCount >= 0) providerTotal = result.rowCount;
+      for (const row of pageRows) {
         const values = Object.fromEntries(dimensions.map((name, index) => [name === 'page' ? 'url' : name, row.keys[index]]));
         for (const metric of metrics) rows.push({ metric, value: row[metric.external_name], dimensions: values, observed_at: `${values.date}T00:00:00.000Z` });
       }
-      if ((result.rows || []).length < 25000) break;
+      if (pageRows.length < 25000) break;
       startRow += 25000;
+      if (pagesRequested >= maxPages) {
+        continuationState = { start_row: startRow };
+        break;
+      }
     } while (true);
-    return { rows, cursor: endDate, limitations: ['Search Console privacy filtering and aggregation apply.', 'Search Analytics does not guarantee every data row; the API can return top rows only.', 'Final data can still be revised by the provider.'] };
+    const collection = collectionResult({
+      items,
+      paginationState: { pages_requested: pagesRequested, pages_retrieved: pagesRetrieved, boundary: { max_pages: maxPages } },
+      providerReportedTotal: providerTotal,
+      continuationState,
+      providerCompleteness: 'unknown',
+      limitations: ['Search Console privacy filtering and aggregation apply.', 'Search Analytics does not guarantee every data row; the API can return top rows only.', 'Final data can still be revised by the provider.'],
+      errors,
+    });
+    return { rows, cursor: endDate, limitations: collection.limitations, collection, ...(connectorError ? { connectorError } : {}) };
+  },
+  async collectObservations(connection, request, context = {}) {
+    return collectSearchConsoleObservations({ connection, request, ...context });
   },
 };

package/src/connectors/index.js

@@ -4,6 +4,7 @@ import { wordpressConnector } from './wordpress.js';
 import { webflowConnector } from './webflow.js';
 import { indexnowConnector } from './indexnow.js';
 import { mcpConnector } from './mcp/pilot.js';
+export { collectionResult, paginationBoundary, errorMessage } from './collectionResult.js';
 
 const CONNECTORS = new Map([gscConnector, ga4Connector, wordpressConnector, webflowConnector, indexnowConnector, mcpConnector].map((connector) => [connector.provider, connector]));
 
@@ -18,4 +19,3 @@ export function listConnectors() {
 }
 
 export { McpClient, McpStdioTransport, McpHttpTransport, ALLOWED_MCP_SERVERS, isServerAllowlisted, isToolAllowlisted, assertToolAllowed, collectMcpEvidence, mcpConnector, diagnoseMcpTransports } from './mcp/index.js';
-