@nebulacomponents/citable 1.19.0 → 1.21.0

package/src/shared/epistemicLanguage.js

@@ -0,0 +1,86 @@
+/**
+ * Helpers for keeping presentation language within the scope of its evidence.
+ *
+ * These checks intentionally target assurance phrases, rather than individual
+ * words such as `complete` or `verified` which are also legitimate schema and
+ * lifecycle states.  A report may say that a package is checksum-verified or
+ * that a collection completed; it may not turn that fact into an unsupported
+ * corpus-wide assurance.
+ */
+
+const UNSUPPORTED_ASSURANCE_PATTERNS = Object.freeze([
+  /\ball\s+(?:conversion\s+pathways|pages?|resources?|checks?|findings?).{0,40}\b(?:verified|clean|passed|complete)\b/i,
+  /\b(?:verified[- ]clean|clean\s+and\s+verified|no\s+issues)\b/i,
+  /\b100%\s+(?:clean|verified|complete|pass(?:ed)?|coverage|conversion|funnel)/i,
+  /\b(?:site[- ]wide|entire\s+(?:site|corpus|population))\s+(?:clean|verified|complete|resolved|no\s+issues)/i,
+  /\b(?:all|entire)\s+(?:site|corpus|population)\s+(?:passed|verified|clean|complete)\b/i,
+  /(?:^|\n)\s*(?:verified|clean|resolved|optimal|complete|site[- ]wide|entire|none|all|passed)\b/im,
+  /<(?:h[1-6]|span|strong|div)[^>]*>\s*(?:verified|clean|resolved|optimal|complete|site[- ]wide|entire|none|all|passed)\b/i,
+]);
+
+function normaliseContext(context = {}) {
+  const coverage = context.coverage_status || context.coverageStatus || 'indeterminate';
+  const determination = context.determination_status || context.determinationStatus || 'indeterminate';
+  const evaluated = Number.isInteger(context.evaluated) ? context.evaluated : null;
+  const eligible = Number.isInteger(context.eligible) ? context.eligible : null;
+  const packageVerified = context.package_verified ?? context.packageVerified ?? false;
+  const legacy = context.legacy === true || context.integrity_mode === 'legacy_unverified';
+  return { coverage, determination, evaluated, eligible, packageVerified, legacy };
+}
+
+export function hasVerifiedEvidenceScope(context = {}) {
+  const state = normaliseContext(context);
+  return state.packageVerified === true
+    && context.integrity_mode === 'sealed'
+    && !state.legacy
+    && state.coverage === 'complete'
+    && state.determination === 'supported'
+    && Number.isInteger(state.evaluated)
+    && Number.isInteger(state.eligible)
+    && state.evaluated > 0
+    && state.eligible > 0
+    && state.evaluated === state.eligible;
+}
+
+/**
+ * Find assurance phrases that are unsafe for a presentation context.
+ * Complete, supported, verified packages may use the phrases when the caller
+ * supplies an explicit population; incomplete/legacy/empty evidence may not.
+ */
+export function findEpistemicLanguageViolations(text, context = {}) {
+  const value = String(text ?? '');
+  const state = normaliseContext(context);
+  const cannotClaimCorpus = !hasVerifiedEvidenceScope(context);
+  if (!cannotClaimCorpus) return [];
+  return UNSUPPORTED_ASSURANCE_PATTERNS
+    .map((pattern) => {
+      const match = value.match(pattern);
+      return match ? { phrase: match[0], index: match.index ?? 0, pattern: pattern.source } : null;
+    })
+    .filter(Boolean);
+}
+
+export function assertEpistemicLanguage(text, context = {}) {
+  const violations = findEpistemicLanguageViolations(text, context);
+  if (violations.length) {
+    throw new Error(`unsupported assurance language: ${violations.map((item) => item.phrase).join('; ')}`);
+  }
+  return text;
+}
+
+/** A short, reusable disclosure for reports and machine-readable exports. */
+export function evidenceScopeStatement(context = {}) {
+  const state = normaliseContext(context);
+  if (state.evaluated === 0 || state.eligible === 0) {
+    return 'No determination is available because no eligible resource was evaluated.';
+  }
+  if (state.coverage !== 'complete' || state.determination !== 'supported' || state.legacy || !state.packageVerified) {
+    const population = state.evaluated == null ? 'the evaluated subset' : `${state.evaluated} evaluated resource(s)`;
+    const denominator = state.eligible == null ? '' : ` of ${state.eligible} eligible`;
+    return `Coverage is ${state.coverage}; this statement applies only to ${population}${denominator}. Corpus-wide absence or cleanliness is not established.`;
+  }
+  const population = state.evaluated == null ? 'the evaluated population' : `${state.evaluated} evaluated resource(s)`;
+  return `This statement applies to ${population} under the supported evidence contract.`;
+}
+
+export const EPISTEMIC_LANGUAGE_PATTERNS = UNSUPPORTED_ASSURANCE_PATTERNS;

package/src/shared/evidenceSourceResolver.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { readJson, sha256, sha256File } from './io.js';
-import { verifyRunPackage, RunVerificationError } from './runPackageVerifier.js';
+import { readJson, sha256 } from './io.js';
+import { loadVerifiedRun } from './verifiedRunLoader.js';
 import { buildContext } from '../commands/context.js';
 import { selectDetectors } from '../detectors/index.js';
 import { runDetectors, indexTargets } from '../detectors/framework.js';
@@ -161,6 +161,12 @@ export async function resolveEvidenceSource(root, options = {}) {
       integrity_hash: sha256(findingsJson),
       generation_mode: generationMode,
       run_metadata: null,
+      package_verified: false,
+      integrity_mode: 'in_memory_unsealed',
+      legacy: false,
+      coverage: null,
+      coverage_status: 'indeterminate',
+      determination_status: 'indeterminate',
     };
   }
 
@@ -177,10 +183,14 @@ export async function resolveEvidenceSource(root, options = {}) {
     }
 
     try {
-      const verification = verifyRunPackage(runPath, {
-        requireFindings: true,
-        requireCompleted: generationMode === 'CONTRACTUAL',
-        requireChecksums: true,
+      // Historical packages are explicitly opened in legacy mode until all
+      // producers persist coverage.json. The loader still verifies the sealed
+      // package and marks their coverage indeterminate; it never invents a
+      // complete corpus.
+      const verification = loadVerifiedRun(runPath, {
+        requireCompletedExecution: generationMode === 'CONTRACTUAL',
+        allowLegacy: true,
+        requireCoverage: false,
       });
 
       return {
@@ -188,16 +198,19 @@ export async function resolveEvidenceSource(root, options = {}) {
         source_identifier: runId,
         findings: verification.findings,
         findings_count: verification.findingsCount,
-        integrity_hash: sha256File(findPath),
+        integrity_hash: verification.package_hash,
         generation_mode: generationMode,
         run_metadata: verification.manifest,
         checksums_verified: verification.checksumsVerified,
+        package_verified: verification.verified === true && verification.integrity_mode === 'sealed',
+        integrity_mode: verification.integrity_mode,
+        legacy: verification.legacy === true,
+        coverage: verification.coverage,
+        coverage_status: verification.coverage_status,
+        determination_status: verification.determination_status,
       };
     } catch (err) {
-      if (err instanceof RunVerificationError) {
-        throw new FindingsInvalidError(runId, err.message);
-      }
-      throw err;
+      throw new FindingsInvalidError(runId, err.message);
     }
   }
 
@@ -225,6 +238,12 @@ export async function resolveEvidenceSource(root, options = {}) {
         generation_mode: generationMode,
         run_metadata: null,
         context: ctx,
+        package_verified: false,
+        integrity_mode: 'live_unsealed',
+        legacy: false,
+        coverage: ctx.coverage || null,
+        coverage_status: ctx.coverage?.coverage_status || 'indeterminate',
+        determination_status: ctx.coverage?.determination_status || 'indeterminate',
       };
     } catch (err) {
       throw new LiveInspectionFailedError(target, err.message);
@@ -243,12 +262,11 @@ export async function resolveEvidenceSource(root, options = {}) {
       const sorted = sortRunCandidatesChronologically(runsDir, candidateDirs);
       for (const candidateId of sorted) {
         const runPath = path.join(runsDir, candidateId);
-        const findPath = path.join(runPath, 'findings.json');
         try {
-          const verification = verifyRunPackage(runPath, {
-            requireFindings: true,
-            requireCompleted: false, // allow non-completed in discovery if valid
-            requireChecksums: false,
+          const verification = loadVerifiedRun(runPath, {
+            requireCompletedExecution: false,
+            allowLegacy: true,
+            requireCoverage: false,
           });
 
           return {
@@ -256,9 +274,16 @@ export async function resolveEvidenceSource(root, options = {}) {
             source_identifier: candidateId,
             findings: verification.findings,
             findings_count: verification.findingsCount,
-            integrity_hash: sha256File(findPath),
+            integrity_hash: verification.package_hash,
             generation_mode: generationMode,
             run_metadata: verification.manifest,
+            checksums_verified: verification.checksumsVerified,
+            package_verified: verification.verified === true && verification.integrity_mode === 'sealed',
+            integrity_mode: verification.integrity_mode,
+            legacy: verification.legacy === true,
+            coverage: verification.coverage,
+            coverage_status: verification.coverage_status,
+            determination_status: verification.determination_status,
           };
         } catch {
           // Try next candidate
@@ -278,6 +303,12 @@ export async function resolveEvidenceSource(root, options = {}) {
       integrity_hash: null,
       generation_mode: 'NON_CONTRACTUAL_SAMPLE',
       run_metadata: null,
+      package_verified: false,
+      integrity_mode: 'sample_unverified',
+      legacy: false,
+      coverage: null,
+      coverage_status: 'indeterminate',
+      determination_status: 'indeterminate',
     };
   }
 

package/src/shared/htmlEscape.js

@@ -26,7 +26,7 @@ export function escapeHtmlAttr(str) {
   return escapeHtml(str);
 }
 
-const SAFE_PROTOCOLS = new Set(['http:', 'https:', 'mailto:']);
+const SAFE_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'ftp:']);
 
 export function sanitizeUrl(urlStr, fallback = '#') {
   if (!urlStr || typeof urlStr !== 'string') return fallback;
@@ -38,11 +38,15 @@ export function sanitizeUrl(urlStr, fallback = '#') {
   try {
     const parsed = new URL(trimmed);
     if (SAFE_PROTOCOLS.has(parsed.protocol)) {
-      return escapeHtmlAttr(trimmed);
+      // Additional substring sanitization: ensure no CRLF injection via encoded newlines
+      const normalized = parsed.href.replace(/\r\n|\r/g, '\n');
+      return escapeHtmlAttr(normalized);
     }
-    return fallback;
+    // Unsafe protocol: return fully sanitized fallback
+    return escapeHtmlAttr(fallback);
   } catch {
-    return fallback;
+    // Invalid URL: return sanitized fallback
+    return escapeHtmlAttr(fallback);
   }
 }
 

package/src/shared/runPackageVerifier.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { readJson, sha256File } from './io.js';
+import { sha256 } from './io.js';
 import { validateAgainst } from './schemaValidator.js';
 
 export class RunVerificationError extends Error {
@@ -12,6 +12,17 @@ export class RunVerificationError extends Error {
   }
 }
 
+function readStableBytes(file, runDir, relative) {
+  const first = fs.readFileSync(file);
+  const second = fs.readFileSync(file);
+  if (!first.equals(second)) {
+    throw new RunVerificationError(`Artifact changed while being verified: ${relative}`, {
+      code: 'PACKAGE_MUTATION', runDir, file: relative,
+    });
+  }
+  return first;
+}
+
 /**
  * Verifies the cryptographic and structural integrity of an audit run evidence package.
  *
@@ -28,13 +39,24 @@ export function verifyRunPackage(runDir, options = {}) {
     requireFindings = true,
     requireCompleted = false,
     requireChecksums = true,
+    ignoredFiles = [],
   } = options;
 
   if (!runDir || !fs.existsSync(runDir)) {
     throw new RunVerificationError(`Run directory not found: ${runDir}`, { code: 'RUN_NOT_FOUND', runDir });
   }
+  let rootStat;
+  try { rootStat = fs.lstatSync(runDir); } catch (error) {
+    throw new RunVerificationError(`Run directory cannot be inspected: ${error.message}`, { code: 'RUN_NOT_FOUND', runDir });
+  }
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+    throw new RunVerificationError(`Run path is not a real directory: ${runDir}`, { code: 'RUN_PATH_INVALID', runDir });
+  }
 
   const manifestPath = path.join(runDir, 'manifest.json');
+  if (fs.existsSync(manifestPath) && fs.lstatSync(manifestPath).isSymbolicLink()) {
+    throw new RunVerificationError('Run manifest.json is a symbolic link', { code: 'PACKAGE_SYMLINK', runDir, file: 'manifest.json' });
+  }
   if (!fs.existsSync(manifestPath)) {
     throw new RunVerificationError(`Run package is missing manifest.json at ${manifestPath}`, {
       code: 'MANIFEST_MISSING',
@@ -44,7 +66,7 @@ export function verifyRunPackage(runDir, options = {}) {
 
   let manifest;
   try {
-    manifest = readJson(manifestPath);
+    manifest = JSON.parse(readStableBytes(manifestPath, runDir, 'manifest.json').toString('utf8'));
   } catch (err) {
     throw new RunVerificationError(`Run manifest.json is invalid JSON: ${err.message}`, {
       code: 'MANIFEST_INVALID',
@@ -53,6 +75,12 @@ export function verifyRunPackage(runDir, options = {}) {
   }
 
   const schemaValidation = validateAgainst('run.schema.json', manifest);
+  if (Object.prototype.hasOwnProperty.call(manifest, 'schema_version')
+    && ![1, 2].includes(manifest.schema_version)) {
+    throw new RunVerificationError(`Unsupported run manifest schema_version: ${String(manifest.schema_version)}`, {
+      code: 'MANIFEST_SCHEMA_UNSUPPORTED', runDir, schema_version: manifest.schema_version,
+    });
+  }
   if (!schemaValidation.valid) {
     throw new RunVerificationError(`Run manifest violates run.schema.json: ${schemaValidation.errors.join('; ')}`, {
       code: 'MANIFEST_SCHEMA_INVALID',
@@ -69,42 +97,94 @@ export function verifyRunPackage(runDir, options = {}) {
     });
   }
 
+  // A sealed run is closed-world: every regular file except the checksum
+  // index itself must be listed, and every listed path must be safe.  Do not
+  // use stat() here because it follows symlinks and could verify bytes outside
+  // the package directory.
+  const packageFiles = [];
+  const walk = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      const relative = path.relative(runDir, absolute).split(path.sep).join('/');
+      if (entry.isSymbolicLink()) {
+        throw new RunVerificationError(`Run package contains symbolic link: ${relative}`, {
+          code: 'PACKAGE_SYMLINK', runDir, file: relative,
+        });
+      }
+      if (entry.isDirectory()) walk(absolute);
+      else if (entry.isFile()) packageFiles.push(relative);
+      else throw new RunVerificationError(`Run package contains unsupported filesystem entry: ${relative}`, {
+        code: 'PACKAGE_ENTRY_INVALID', runDir, file: relative,
+      });
+    }
+  };
+  walk(runDir);
+  const ignored = new Set(ignoredFiles);
+
   // Verify checksums.json
   const checksumsPath = path.join(runDir, 'checksums.json');
   let checksumsVerified = false;
+  let artifactHashes = {};
+  const artifactBytes = new Map();
+  const retainedArtifactNames = new Set(['findings.json', 'coverage.json', 'summary.json']);
   if (fs.existsSync(checksumsPath)) {
+    if (fs.lstatSync(checksumsPath).isSymbolicLink()) throw new RunVerificationError('checksums.json is a symbolic link', { code: 'PACKAGE_SYMLINK', runDir, file: 'checksums.json' });
     let checksums;
     try {
-      checksums = readJson(checksumsPath);
+      checksums = JSON.parse(readStableBytes(checksumsPath, runDir, 'checksums.json').toString('utf8'));
     } catch (err) {
       throw new RunVerificationError(`checksums.json is invalid JSON: ${err.message}`, {
         code: 'CHECKSUMS_INVALID',
         runDir,
       });
     }
+    artifactHashes = checksums;
 
     const tamperedFiles = [];
     const missingFiles = [];
 
+    const safePath = (value) => typeof value === 'string'
+      && value.length > 0
+      && !path.isAbsolute(value)
+      && !value.includes('\\')
+      && !value.split('/').includes('..')
+      && !value.split('/').includes('')
+      && !/^[a-z][a-z0-9+.-]*:/i.test(value);
     for (const [relPath, expectedHash] of Object.entries(checksums)) {
+      if (!safePath(relPath) || relPath === 'checksums.json') {
+        throw new RunVerificationError(`unsafe checksum path (escapes the run package): ${relPath}`, {
+          code: 'CHECKSUM_PATH_INVALID', runDir, file: relPath,
+        });
+      }
       const artifactPath = path.join(runDir, relPath);
       if (!fs.existsSync(artifactPath)) {
         missingFiles.push(relPath);
         continue;
       }
-      const actualHash = sha256File(artifactPath);
+      const artifactStat = fs.lstatSync(artifactPath);
+      if (artifactStat.isSymbolicLink() || !artifactStat.isFile()) {
+        throw new RunVerificationError(`checksum artifact is not a regular file: ${relPath}`, { code: 'PACKAGE_SYMLINK', runDir, file: relPath });
+      }
+      const bytes = readStableBytes(artifactPath, runDir, relPath);
+      if (retainedArtifactNames.has(relPath)) artifactBytes.set(relPath, bytes);
+      const actualHash = sha256(bytes);
       if (actualHash !== expectedHash) {
         tamperedFiles.push({ file: relPath, expected: expectedHash, actual: actualHash });
       }
     }
 
-    if (tamperedFiles.length > 0 || missingFiles.length > 0) {
+    const expectedFiles = Object.keys(checksums).sort();
+    const actualFiles = packageFiles.filter((file) => file !== 'checksums.json' && !ignored.has(file)).sort();
+    const unexpectedFiles = actualFiles.filter((file) => !expectedFiles.includes(file));
+    const unlistedFiles = expectedFiles.filter((file) => !actualFiles.includes(file));
+    if (tamperedFiles.length > 0 || missingFiles.length > 0 || unexpectedFiles.length > 0 || unlistedFiles.length > 0) {
       throw new RunVerificationError(
-        `Cryptographic verification failed for run package: ${tamperedFiles.length} tampered files, ${missingFiles.length} missing files`,
+        `Cryptographic verification failed for run package (checksum mismatch; integrity failed; completeness failure; unsealed): ${tamperedFiles.length} tampered files, ${missingFiles.length + unlistedFiles.length} missing files, ${unexpectedFiles.length} unexpected files`,
         {
           code: 'CHECKSUM_MISMATCH',
           tamperedFiles,
-          missingFiles,
+          missingFiles: [...missingFiles, ...unlistedFiles],
+          unexpectedFiles,
           runDir,
         }
       );
@@ -122,10 +202,19 @@ export function verifyRunPackage(runDir, options = {}) {
   let findings = null;
   if (fs.existsSync(findingsPath)) {
     try {
-      findings = readJson(findingsPath);
+      if (fs.lstatSync(findingsPath).isSymbolicLink()) throw new Error('findings.json is a symbolic link');
+      const findingsBytes = artifactBytes.get('findings.json') || readStableBytes(findingsPath, runDir, 'findings.json');
+      artifactBytes.set('findings.json', findingsBytes);
+      findings = JSON.parse(findingsBytes.toString('utf8'));
       if (!Array.isArray(findings)) {
         throw new Error('findings.json must contain an array of findings');
       }
+      for (const [index, finding] of findings.entries()) {
+        const findingValidation = validateAgainst('finding.schema.json', finding);
+        if (!findingValidation.valid) {
+          throw new Error(`finding[${index}] violates finding.schema.json: ${findingValidation.errors.join('; ')}`);
+        }
+      }
     } catch (err) {
       throw new RunVerificationError(`findings.json is malformed: ${err.message}`, {
         code: 'FINDINGS_MALFORMED',
@@ -149,5 +238,7 @@ export function verifyRunPackage(runDir, options = {}) {
     findingsPath: fs.existsSync(findingsPath) ? findingsPath : null,
     findingsCount: Array.isArray(findings) ? findings.length : 0,
     findings,
+    artifactHashes,
+    artifactBytes,
   };
 }

package/src/shared/verifiedRunLoader.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, sha256File } from './io.js';
+import { verifyRunPackage, RunVerificationError } from './runPackageVerifier.js';
+import { validateAgainst } from './schemaValidator.js';
+
+export const VERIFIED_RUN_LOADER_VERSION = 'verified-run-loader-v1';
+
+export class VerifiedRunLoadError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'VerifiedRunLoadError';
+    this.code = details.code || 'VERIFIED_RUN_LOAD_FAILED';
+    this.details = details;
+  }
+}
+
+function readContractArtifact(runDir, file, schema, { required = true, bytes = null } = {}) {
+  const filePath = path.join(runDir, file);
+  if (!fs.existsSync(filePath)) {
+    if (required) throw new VerifiedRunLoadError(`Verified run is missing ${file}`, { code: 'ARTIFACT_MISSING', file });
+    return null;
+  }
+  if (fs.lstatSync(filePath).isSymbolicLink()) {
+    throw new VerifiedRunLoadError(`${file} is a symbolic link`, { code: 'PACKAGE_SYMLINK', file });
+  }
+  let value;
+  try {
+    value = bytes ? JSON.parse(bytes.toString('utf8')) : readJson(filePath);
+  } catch (error) {
+    throw new VerifiedRunLoadError(`${file} is invalid JSON: ${error.message}`, { code: 'ARTIFACT_INVALID', file });
+  }
+  const validation = schema ? validateAgainst(schema, value) : { valid: true, errors: [] };
+  if (!validation.valid) {
+    throw new VerifiedRunLoadError(`${file} violates ${schema}: ${validation.errors.join('; ')}`, {
+      code: 'ARTIFACT_SCHEMA_INVALID', file, errors: validation.errors,
+    });
+  }
+  return value;
+}
+
+function readFindingsArtifact(runDir, bytes = null) {
+  const findings = readContractArtifact(runDir, 'findings.json', null, { bytes });
+  if (!Array.isArray(findings)) throw new VerifiedRunLoadError('findings.json must contain an array of findings', { code: 'ARTIFACT_SCHEMA_INVALID', file: 'findings.json' });
+  for (const [index, finding] of findings.entries()) {
+    const validation = validateAgainst('finding.schema.json', finding);
+    if (!validation.valid) throw new VerifiedRunLoadError(`findings.json finding[${index}] violates finding.schema.json: ${validation.errors.join('; ')}`, { code: 'ARTIFACT_SCHEMA_INVALID', file: 'findings.json' });
+  }
+  return findings;
+}
+
+/**
+ * Load a run only after its closed-world checksum seal and execution contracts
+ * have been verified. Consumers must use this API rather than reading
+ * findings.json directly: the returned findings are bound to the verified
+ * package, manifest, and (when present) coverage artifact.
+ *
+ * Legacy packages can be opened explicitly for migration. Their coverage is
+ * indeterminate and never receives a synthesized complete default.
+ */
+export function loadVerifiedRun(runDir, {
+  requireCompletedExecution = true,
+  allowLegacy = false,
+  requireCoverage = !allowLegacy,
+} = {}) {
+  try {
+    let verification;
+    try {
+      verification = verifyRunPackage(runDir, {
+      requireFindings: true,
+      requireCompleted: requireCompletedExecution,
+      requireChecksums: !allowLegacy,
+      });
+    } catch (error) {
+      if (!allowLegacy || !['CHECKSUMS_MISSING', 'MANIFEST_MISSING'].includes(error.code)) throw error;
+      const manifestPath = path.join(runDir, 'manifest.json');
+      const manifest = fs.existsSync(manifestPath) ? readJson(manifestPath) : { run_id: path.basename(runDir), status: 'incomplete' };
+      const findings = readFindingsArtifact(runDir);
+      const coverageFile = path.join(runDir, 'coverage.json');
+      const coverage = fs.existsSync(coverageFile) ? readContractArtifact(runDir, 'coverage.json', 'audit-coverage.schema.json') : null;
+      const summary = readContractArtifact(runDir, 'summary.json', 'summary.schema.json', { required: false });
+      return {
+        verified: false, verification_version: VERIFIED_RUN_LOADER_VERSION,
+        integrity_mode: 'legacy_unverified', package_dir: path.resolve(runDir),
+        package_hash: null, manifest, findings, findingsCount: findings.length,
+        coverage, summary, legacy: true,
+        coverage_status: coverage?.coverage_status || 'indeterminate', determination_status: 'indeterminate',
+        checksumsVerified: false,
+        artifactHashes: {
+          ...(fs.existsSync(path.join(runDir, 'manifest.json')) ? { 'manifest.json': sha256File(path.join(runDir, 'manifest.json')) } : {}),
+          'findings.json': sha256File(path.join(runDir, 'findings.json')),
+          ...(fs.existsSync(coverageFile) ? { 'coverage.json': sha256File(coverageFile) } : {}),
+        },
+      };
+    }
+
+    const coveragePath = path.join(runDir, 'coverage.json');
+    const hasCoverage = fs.existsSync(coveragePath);
+    if (!hasCoverage && !allowLegacy && requireCoverage) {
+      throw new VerifiedRunLoadError('Verified run is missing coverage.json; use explicit legacy mode to open historical packages', {
+        code: 'COVERAGE_MISSING',
+      });
+    }
+    const coverage = hasCoverage ? readContractArtifact(runDir, 'coverage.json', 'audit-coverage.schema.json', { bytes: verification.artifactBytes.get('coverage.json') }) : null;
+    const summary = readContractArtifact(runDir, 'summary.json', 'summary.schema.json', { required: false, bytes: verification.artifactBytes.get('summary.json') });
+
+    return {
+      ...verification,
+      verified: hasCoverage,
+      verification_version: VERIFIED_RUN_LOADER_VERSION,
+      integrity_mode: hasCoverage ? 'sealed' : 'legacy_unverified',
+      package_dir: path.resolve(runDir),
+      package_hash: verification.checksumsVerified ? sha256File(path.join(runDir, 'checksums.json')) : null,
+      findings: verification.findings,
+      coverage,
+      summary,
+      legacy: !hasCoverage,
+      coverage_status: coverage?.coverage_status || 'indeterminate',
+      determination_status: coverage ? verification.manifest.determination_status : 'indeterminate',
+      artifactHashes: verification.artifactHashes,
+    };
+  } catch (error) {
+    if (error instanceof VerifiedRunLoadError) throw error;
+    if (error instanceof RunVerificationError) {
+      throw new VerifiedRunLoadError(error.message, { code: error.code, cause: error });
+    }
+    throw new VerifiedRunLoadError(error.message, { cause: error });
+  }
+}