@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/shared-kernel/evidence-adapters.js

@@ -0,0 +1,251 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function createMemoryEvidenceAdapter({ maxBytes = Number.MAX_SAFE_INTEGER, fault = null } = {}) {
+  const records = new Map();
+  let sequence = 0;
+  const adapter = {
+    record(envelope) {
+      if (fault === 'throw') {
+        throw new Error('writer_crash');
+      }
+      if (fault === 'enospc') {
+        const error = new Error('ENOSPC');
+        error.code = 'ENOSPC';
+        return { ok: false, error: 'ENOSPC' };
+      }
+      if (fault === 'hang') {
+        return new Promise(() => {});
+      }
+      const bytes = Buffer.byteLength(JSON.stringify(envelope));
+      if (bytes > maxBytes) {
+        return { ok: false, error: 'payload_too_large', bytes, maxBytes };
+      }
+      sequence += 1;
+      const stored = fault === 'corrupt_manifest'
+        ? { ...envelope, checksum: '0'.repeat(64) }
+        : { ...envelope };
+      records.set(stored.evidenceId, stored);
+      return { ok: true, stored: true, globalSeq: sequence, evidenceId: stored.evidenceId };
+    },
+    offer(envelope) {
+      return { accepted: true, completion: Promise.resolve().then(() => adapter.record(envelope)) };
+    },
+    readById(evidenceId) {
+      return records.get(evidenceId) || null;
+    },
+    list({ namespace, operationId } = {}) {
+      return [...records.values()].filter((item) => (
+        (!namespace || item.namespace === namespace)
+        && (!operationId || item.operationId === operationId)
+      ));
+    },
+    status() {
+      if (fault === 'corrupt_manifest') {
+        return { ok: false, error: 'corrupt_manifest', count: records.size };
+      }
+      return { ok: true, adapter: 'memory', count: records.size, degraded: false };
+    },
+    close() {
+      records.clear();
+    },
+  };
+  return adapter;
+}
+
+function createSegmentedEvidenceAdapter(factStore, { ownsStore = false } = {}) {
+  if (!factStore || typeof factStore.record !== 'function' || typeof factStore.read !== 'function') {
+    throw new TypeError('segmented evidence adapter requires a FactStore');
+  }
+  function factFor(envelope) {
+    return {
+      partition: partitionFor(envelope.kind),
+      targetKey: `evidence:${envelope.namespace}:${envelope.operationId}`,
+      app: { platform: 'host', packageName: envelope.namespace },
+      runtimeEpoch: String(envelope.operationId),
+      actionId: envelope.evidenceId,
+      timestamps: {
+        occurredAtMs: envelope.committedAtMs,
+        observedAtMs: envelope.committedAtMs,
+      },
+      payload: envelope,
+    };
+  }
+  const adapter = {
+    record(envelope) {
+      try {
+        const result = factStore.record(factFor(envelope), { durability: 'sync' });
+        const receipt = result.receipt || result.receipts?.[0] || result;
+        if (receipt?.ok === false || result.ok === false) {
+          return { ok: false, error: receipt?.error || result.error || 'persist_failed' };
+        }
+        return { ok: true, stored: true, evidenceId: envelope.evidenceId, globalSeq: receipt.globalSeq };
+      } catch (error) {
+        return {
+          ok: false,
+          error: error.code || 'persist_failed',
+          detail: error.message || String(error),
+        };
+      }
+    },
+    offer(envelope) {
+      if (typeof factStore.offer !== 'function') {
+        return { accepted: false, reason: 'async_offer_unsupported' };
+      }
+      const offered = factStore.offer(factFor(envelope), { durability: 'sync' });
+      if (!offered.accepted) return offered;
+      return {
+        ...offered,
+        completion: offered.completion.then((result) => {
+          const receipt = result.receipt || result.receipts?.[0] || result;
+          if (receipt?.ok === false || result.ok === false) {
+            return { ok: false, stored: false, error: receipt?.error || result.error || 'persist_failed' };
+          }
+          return {
+            ok: true,
+            stored: true,
+            evidenceId: envelope.evidenceId,
+            globalSeq: receipt.globalSeq,
+          };
+        }),
+      };
+    },
+    readById(evidenceId) {
+      const page = factStore.read({ actionId: evidenceId, limit: 1 });
+      if (!page.ok) throw Object.assign(new Error(page.error || 'Evidence store read failed.'), { code: 'evidence_read_failed' });
+      const item = page.items?.[0];
+      return item?.payload || null;
+    },
+    list({ namespace, operationId } = {}) {
+      const items = [];
+      let cursor;
+      do {
+        const page = factStore.read({
+          targetKey: operationId ? `evidence:${namespace}:${operationId}` : undefined,
+          cursor,
+          limit: 1_000,
+        });
+        if (!page.ok) throw Object.assign(new Error(page.error || 'Evidence store read failed.'), { code: 'evidence_read_failed' });
+        items.push(...(page.items || []));
+        cursor = page.hasMore ? page.cursor : null;
+      } while (cursor);
+      return items
+        .map((item) => item.payload)
+        .filter((payload) => payload
+          && (!namespace || payload.namespace === namespace)
+          && (!operationId || payload.operationId === operationId));
+    },
+    status() {
+      return factStore.status();
+    },
+    close() {
+      if (ownsStore) factStore.close?.();
+    },
+  };
+  return adapter;
+}
+
+function createLegacyFactStoreAdapter(factStore) {
+  if (
+    !factStore
+    || typeof factStore.record !== 'function'
+    || typeof factStore.read !== 'function'
+    || typeof factStore.status !== 'function'
+  ) {
+    throw new TypeError('legacy fact adapter requires a FactStore');
+  }
+  return {
+    append(partitionOrFact, maybeFact) {
+      const fact = maybeFact === undefined
+        ? partitionOrFact
+        : { ...maybeFact, partition: String(partitionOrFact) };
+      const result = factStore.record(fact, { durability: 'sync' });
+      return result.receipt || result.receipts?.[0] || result;
+    },
+    query(query = {}) {
+      return factStore.read({
+        partitions: query.partitions || (query.partition ? [query.partition] : undefined),
+        targetKey: query.targetKey ?? query.target,
+        runtimeEpoch: query.runtimeEpoch,
+        cursor: query.cursor,
+        limit: query.limit,
+        ...(Object.prototype.hasOwnProperty.call(query, 'actionId')
+          ? { actionId: query.actionId }
+          : {}),
+      });
+    },
+    status() {
+      return factStore.status();
+    },
+    close() {},
+  };
+}
+
+function partitionFor(kind) {
+  if (kind === 'observation' || kind === 'summary') return 'ui';
+  return 'action';
+}
+
+function createFileEvidenceAdapter({ dir } = {}) {
+  if (!dir) throw new TypeError('dir is required');
+  fs.mkdirSync(dir, { recursive: true });
+  const indexPath = path.join(dir, 'index.json');
+
+  function loadIndex() {
+    if (!fs.existsSync(indexPath)) return [];
+    return JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  }
+
+  function writeAtomic(file, data) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, file);
+  }
+
+  function saveIndex(ids) {
+    writeAtomic(indexPath, JSON.stringify(ids));
+  }
+
+  function fileFor(evidenceId) {
+    return path.join(dir, `${encodeURIComponent(evidenceId)}.json`);
+  }
+
+  const adapter = {
+    record(envelope) {
+      writeAtomic(fileFor(envelope.evidenceId), JSON.stringify(envelope));
+      const ids = loadIndex();
+      ids.push(envelope.evidenceId);
+      saveIndex(ids);
+      return { ok: true, stored: true, evidenceId: envelope.evidenceId, globalSeq: ids.length };
+    },
+    offer(envelope) {
+      return { accepted: true, completion: Promise.resolve().then(() => adapter.record(envelope)) };
+    },
+    readById(evidenceId) {
+      const file = fileFor(evidenceId);
+      if (!fs.existsSync(file)) return null;
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    },
+    list({ namespace, operationId } = {}) {
+      return loadIndex()
+        .map((id) => this.readById(id))
+        .filter((item) => item
+          && (!namespace || item.namespace === namespace)
+          && (!operationId || item.operationId === operationId));
+    },
+    status() {
+      return { ok: true, adapter: 'file', dir, count: loadIndex().length };
+    },
+    close() {},
+  };
+  return adapter;
+}
+
+module.exports = {
+  createLegacyFactStoreAdapter,
+  createMemoryEvidenceAdapter,
+  createSegmentedEvidenceAdapter,
+  createFileEvidenceAdapter,
+};

package/bin/shared-kernel/evidence-archive.js

@@ -0,0 +1,329 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { checksumOf, canonicalJson, validateArchivedRecord, verifyChecksum } = require('./evidence-schema');
+const { analyzeRecordedPayloads } = require('./recorded-payload-archive');
+const { readRegularFile: readRecordedFile } = require('./evidence-recording');
+
+const SCHEMA = 'aab.evidence-archive/v1';
+const PAYLOAD_ARCHIVE_SCHEMA = 'aab.evidence-archive/v2';
+const MAX_RECORDS = 10_000;
+const MAX_BYTES = 128 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = 2 * 1024 * 1024;
+const sha256 = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+
+function requireValue(condition, code, detail) {
+  if (!condition) throw Object.assign(new Error(code), { code, detail });
+}
+
+function textArgument(value, field) {
+  requireValue(typeof value === 'string' && value.trim().length > 0, 'invalid_argument', field);
+}
+
+function namespaceArgument(namespace) {
+  requireValue(namespace === 'intent' || namespace === 'script', 'invalid_argument', 'namespace');
+}
+
+async function handle(args = {}, { getFactStore } = {}) {
+  try {
+    if (args.operation === 'verify') return verifyArchive(args);
+    if (args.operation === 'export') {
+      namespaceArgument(args.namespace);
+      textArgument(args.operationId, 'operationId');
+      textArgument(args.outputDir, 'outputDir');
+      requireValue(args.includeRecordedPayloads === undefined || typeof args.includeRecordedPayloads === 'boolean',
+        'invalid_argument', 'includeRecordedPayloads');
+      requireValue(!fs.existsSync(path.resolve(args.outputDir)), 'output_exists');
+      const store = getFactStore();
+      await store.drain();
+      return exportArchive(args, store);
+    }
+    return { ok: false, error: 'invalid_operation' };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error.code || 'archive_failed',
+      ...(error.detail === undefined ? {} : { detail: error.detail }),
+      ...(error.code === 'invalid_argument' ? { field: error.detail } : {}),
+    };
+  }
+}
+
+// There is no await between the watermark, page reads and final status: the
+// owning Host writer cannot interleave another command with this snapshot.
+function exportArchive({ namespace, operationId, outputDir, includeRecordedPayloads = false }, store) {
+  const status = store.status();
+  requireValue(status.ok === true && status.authoritative === true && status.persistence === true,
+    'fact_store_unavailable');
+  requireValue(Number.isSafeInteger(status.sequences?.nextGlobalSeq), 'invalid_store_snapshot');
+  const throughGlobalSeq = status.sequences.nextGlobalSeq - 1;
+  requireValue(typeof status.storeId === 'string' && status.storeId.length > 0 && Number.isSafeInteger(throughGlobalSeq)
+    && throughGlobalSeq >= 0, 'invalid_store_snapshot');
+  const targetKey = `evidence:${namespace}:${operationId}`;
+  const facts = [];
+  const cursors = new Set();
+  let cursor;
+  let byteCount = 2;
+  do {
+    const page = store.read({ targetKey, limit: 1000, ...(cursor === undefined ? {} : { cursor }) });
+    requireValue(page.ok === true, 'fact_store_read_failed', page.error);
+    requireValue(page.gap === false && page.cursorExpired === false, 'evidence_gap');
+    requireValue(Array.isArray(page.items) && typeof page.hasMore === 'boolean', 'invalid_store_page');
+    for (const fact of page.items) {
+      byteCount += Buffer.byteLength(JSON.stringify(fact)) + 1;
+      requireValue(facts.length < MAX_RECORDS && byteCount <= MAX_BYTES, 'archive_limit_exceeded');
+      facts.push(fact);
+    }
+    if (!page.hasMore) break;
+    requireValue(page.items.length > 0 && typeof page.cursor === 'string' && page.cursor.length > 0 && !cursors.has(page.cursor),
+      'invalid_store_cursor');
+    cursors.add(page.cursor);
+    cursor = page.cursor;
+  } while (true);
+  requireValue(facts.length > 0, 'operation_not_found');
+  const after = store.status();
+  requireValue(after.ok === true && after.storeId === status.storeId
+    && after.sequences?.nextGlobalSeq === throughGlobalSeq + 1, 'store_changed_during_export');
+  const analysis = analyzeFacts(facts, { namespace, operationId, throughGlobalSeq });
+  const payloadFiles = new Map();
+  if (includeRecordedPayloads) {
+    includePayloadAnalysis(analysis, analyzeRecordedPayloads(facts, (record, file, name) => {
+      const bytes = readRecordedFile(record.directory, file.name);
+      payloadFiles.set(name, bytes);
+      return bytes;
+    }));
+  }
+  const recordsBytes = Buffer.from(JSON.stringify(facts) + '\n');
+  requireValue(recordsBytes.length <= MAX_BYTES, 'archive_limit_exceeded');
+  const manifest = {
+    schemaVersion: includeRecordedPayloads ? PAYLOAD_ARCHIVE_SCHEMA : SCHEMA,
+    namespace,
+    operationId,
+    exportedAtMs: Date.now(),
+    source: {
+      kind: 'host-fact-store',
+      storeId: status.storeId,
+      targetKey,
+      throughGlobalSeq,
+      // These describe retention for whole partitions, not just this operation.
+      retention: { ui: status.quota?.partitions?.ui ?? null, action: status.quota?.partitions?.action ?? null },
+    },
+    records: { path: 'records.json', bytes: recordsBytes.length, sha256: sha256(recordsBytes) },
+    ...analysis,
+  };
+  const manifestBytes = Buffer.from(JSON.stringify(manifest, null, 2) + '\n');
+  requireValue(manifestBytes.length <= MAX_MANIFEST_BYTES, 'archive_limit_exceeded');
+  const directory = path.resolve(outputDir);
+  // An output directory is created exclusively. Interrupted writes have no
+  // manifest, and existing user files are never replaced or removed.
+  try { fs.mkdirSync(directory); }
+  catch (error) { if (error.code === 'EEXIST') error.code = 'output_exists'; throw error; }
+  fs.writeFileSync(path.join(directory, 'records.json'), recordsBytes, { flag: 'wx' });
+  for (const [name, bytes] of payloadFiles) fs.writeFileSync(path.join(directory, name), bytes, { flag: 'wx', mode: 0o600 });
+  fs.writeFileSync(path.join(directory, 'manifest.json'), manifestBytes, { flag: 'wx' });
+  return resultOf(manifest, directory, sha256(manifestBytes));
+}
+
+function analyzeFacts(facts, { namespace, operationId, throughGlobalSeq }) {
+  requireValue(Array.isArray(facts) && facts.length > 0 && facts.length <= MAX_RECORDS, 'invalid_records');
+  const ids = new Map();
+  const positions = new Map();
+  const counts = {};
+  const targets = new Map();
+  let previousSequence = 0;
+  function target(role, value) {
+    if (value === undefined) return;
+    requireValue((value === null && namespace === 'script')
+      || (value !== null && typeof value === 'object' && !Array.isArray(value)), 'invalid_record_target');
+    const item = { role, value };
+    targets.set(canonicalJson(item), item);
+  }
+  for (const fact of facts) {
+    requireValue(fact && Number.isSafeInteger(fact.globalSeq) && fact.globalSeq > previousSequence
+      && fact.globalSeq <= throughGlobalSeq, 'invalid_record_sequence');
+    previousSequence = fact.globalSeq;
+    const record = fact.payload;
+    requireValue(record?.namespace === namespace && record.operationId === operationId, 'record_scope_mismatch');
+    requireValue(fact.targetKey === `evidence:${namespace}:${operationId}`
+      && fact.runtimeEpoch === operationId && fact.actionId === record.evidenceId, 'fact_binding_mismatch');
+    requireValue(record.persisted === true && typeof record.evidenceId === 'string' && record.evidenceId.length > 0,
+      'invalid_evidence_record');
+    requireValue(!ids.has(record.evidenceId), 'duplicate_evidence_id');
+    requireValue(validateArchivedRecord(namespace, record.kind, record).ok, 'invalid_evidence_record');
+    requireValue(verifyChecksum(record).ok, 'record_checksum_mismatch', record.evidenceId);
+    ids.set(record.evidenceId, record);
+    positions.set(record.evidenceId, fact.globalSeq);
+    counts[record.kind] = (counts[record.kind] || 0) + 1;
+    target(namespace === 'script' && record.kind === 'dispatch-marker' ? 'dispatch' : 'owner', record.target);
+    target('owner', record.requestedTarget);
+    target('foreground', record.foreground);
+    if (record.kind === 'observation') {
+      if (record.schemaVersion === undefined) target('observed', { serial: record.serial, packageName: record.packageName });
+      else target('observed', record.observedTarget);
+    }
+  }
+  const missingReferences = [];
+  const externalReferences = [];
+  function uniqueIndex(kind, field) {
+    const index = new Map();
+    for (const { payload: record } of facts) {
+      if (record.kind !== kind || record[field] === undefined) continue;
+      requireValue(!index.has(record[field]), 'ambiguous_evidence_reference', field);
+      index.set(record[field], record);
+    }
+    return index;
+  }
+  const observations = uniqueIndex('observation', 'rawTreeId');
+  const summaries = new Set(facts.filter(f => f.payload.kind === 'summary').map(f => f.payload.rawTreeId));
+  const markers = uniqueIndex('dispatch-marker', 'actionId');
+  const decisions = uniqueIndex('decision', 'decisionId');
+  const missing = (record, field, value) => missingReferences.push({ evidenceId: record.evidenceId, field, value });
+  const precedes = (reference, record) => requireValue(
+    positions.get(reference.evidenceId) < positions.get(record.evidenceId), 'invalid_reference_binding', record.evidenceId);
+  for (const { payload: record } of facts) {
+    if (record.kind === 'observation' && record.rawTree == null) missing(record, 'rawTree', null);
+    if (record.kind === 'observation' && !summaries.has(record.rawTreeId)) missing(record, 'summary', record.rawTreeId ?? null);
+    if (record.basedOnEvidenceIds !== undefined) {
+      requireValue(Array.isArray(record.basedOnEvidenceIds), 'invalid_evidence_references');
+      for (const id of record.basedOnEvidenceIds) {
+        if (!ids.has(id)) missing(record, 'basedOnEvidenceIds', id);
+        else precedes(ids.get(id), record);
+      }
+    }
+    if (record.parentFactId) {
+      if (!ids.has(record.parentFactId)) missing(record, 'parentFactId', record.parentFactId);
+      else precedes(ids.get(record.parentFactId), record);
+    }
+    if (record.kind !== 'observation' && record.rawTreeId !== undefined) {
+      const observation = observations.get(record.rawTreeId);
+      if (!observation) missing(record, 'rawTreeId', record.rawTreeId);
+      else {
+        precedes(observation, record);
+        requireValue(observation.revision === record.revision, 'invalid_reference_binding', record.evidenceId);
+      }
+    }
+    if (record.kind === 'dispatch-marker' && record.decisionId) {
+      const decision = decisions.get(record.decisionId);
+      if (!decision) missing(record, 'decisionId', record.decisionId);
+      else {
+        precedes(decision, record);
+        requireValue(decision.revision === record.revision && decision.actionSpecHash === record.actionSpecHash,
+          'invalid_reference_binding', record.evidenceId);
+      }
+    }
+    if (record.kind === 'checkpoint' && record.resultRef) {
+      const ref = record.resultRef, result = ids.get(ref.evidenceId);
+      if (!result) missing(record, 'resultRef', ref.evidenceId);
+      else {
+        precedes(result, record);
+        requireValue(result.kind === 'result' && result.revision === record.revision
+          && result.bytes === ref.bytes && result.sha256 === ref.sha256 && checksumOf(result.result) === ref.sha256
+          && Buffer.byteLength(canonicalJson(result.result)) === ref.bytes
+          && result.originalSha256 === ref.originalSha256 && result.representation === ref.representation,
+          'invalid_reference_binding', record.evidenceId);
+      }
+    }
+    if (record.kind === 'action-receipt') {
+      const marker = markers.get(record.actionId);
+      if (!marker) missing(record, 'actionId', record.actionId);
+      else {
+        precedes(marker, record);
+        requireValue(record.target === undefined || canonicalJson(record.target) === canonicalJson(marker.target),
+          'invalid_reference_binding', record.evidenceId);
+      }
+    }
+    for (const field of ['captureRefs', 'evidenceRefs']) {
+      if (record[field] === undefined) continue;
+      requireValue(Array.isArray(record[field]), 'invalid_evidence_references');
+      for (const ref of record[field]) {
+        if (typeof ref !== 'string' || !ids.has(ref)) externalReferences.push({ evidenceId: record.evidenceId, field, ref });
+      }
+    }
+    if (record.kind === 'attachment') externalReferences.push({ evidenceId: record.evidenceId,
+      field: 'recordedPayload', ref: { recordingId: record.recordingId, sequence: record.sequence, file: record.file } });
+  }
+  return {
+    recordCount: facts.length,
+    firstGlobalSeq: facts[0].globalSeq,
+    lastGlobalSeq: facts.at(-1).globalSeq,
+    counts,
+    targets: [...targets.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, value]) => value),
+    coverage: {
+      scope: 'retained-host-records',
+      priorHistoryComplete: 'unknown',
+      referenceClosure: missingReferences.length === 0 ? 'complete' : 'partial',
+      missingReferences,
+      externalPayloads: 'not-included',
+      externalReferences,
+      executionStatus: 'not-inferred',
+      businessVerdict: 'not-evaluated',
+      exclusions: ['external-screenshots', 'mobile-capture-items', 'intermediate-script-call-results-and-assertions', 'in-memory-events'],
+    },
+  };
+}
+
+function readRegularFile(directory, name, maxBytes) {
+  const file = path.join(directory, name);
+  const stat = fs.lstatSync(file);
+  requireValue(stat.isFile() && !stat.isSymbolicLink(), 'invalid_archive_file', name);
+  requireValue(stat.size <= maxBytes, 'archive_limit_exceeded');
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const opened = fs.fstatSync(descriptor);
+    requireValue(opened.isFile() && opened.size <= maxBytes, 'invalid_archive_file', name);
+    const bytes = fs.readFileSync(descriptor);
+    requireValue(bytes.length <= maxBytes, 'archive_limit_exceeded');
+    return bytes;
+  } finally { fs.closeSync(descriptor); }
+}
+
+function verifyArchive({ archiveDir, manifestSha256 }) {
+  textArgument(archiveDir, 'archiveDir');
+  requireValue(typeof manifestSha256 === 'string' && /^[a-f0-9]{64}$/.test(manifestSha256),
+    'invalid_argument', 'manifestSha256');
+  const directory = path.resolve(archiveDir);
+  requireValue(fs.lstatSync(directory).isDirectory() && !fs.lstatSync(directory).isSymbolicLink(), 'invalid_archive_directory');
+  const manifestBytes = readRegularFile(directory, 'manifest.json', MAX_MANIFEST_BYTES);
+  requireValue(sha256(manifestBytes) === manifestSha256, 'manifest_checksum_mismatch');
+  const manifest = JSON.parse(manifestBytes);
+  requireValue([SCHEMA, PAYLOAD_ARCHIVE_SCHEMA].includes(manifest.schemaVersion), 'unsupported_archive_schema');
+  namespaceArgument(manifest.namespace);
+  textArgument(manifest.operationId, 'operationId');
+  requireValue(manifest.records?.path === 'records.json', 'invalid_archive_path');
+  requireValue(manifest.source?.kind === 'host-fact-store' && typeof manifest.source.storeId === 'string'
+    && manifest.source.targetKey === `evidence:${manifest.namespace}:${manifest.operationId}`
+    && Number.isSafeInteger(manifest.source.throughGlobalSeq) && manifest.source.throughGlobalSeq >= 0,
+  'invalid_archive_source');
+  const recordsBytes = readRegularFile(directory, 'records.json', MAX_BYTES);
+  requireValue(recordsBytes.length === manifest.records.bytes && sha256(recordsBytes) === manifest.records.sha256,
+    'records_checksum_mismatch');
+  const facts = JSON.parse(recordsBytes);
+  const analysis = analyzeFacts(facts, { namespace: manifest.namespace,
+    operationId: manifest.operationId, throughGlobalSeq: manifest.source.throughGlobalSeq });
+  if (manifest.schemaVersion === PAYLOAD_ARCHIVE_SCHEMA) {
+    includePayloadAnalysis(analysis, analyzeRecordedPayloads(facts, (_record, _file, name) => readRecordedFile(directory, name)));
+  } else requireValue(manifest.recordedPayloads === undefined, 'manifest_analysis_mismatch', 'recordedPayloads');
+  for (const [field, expected] of Object.entries(analysis)) {
+    requireValue(canonicalJson(manifest[field]) === canonicalJson(expected), 'manifest_analysis_mismatch', field);
+  }
+  return { ...resultOf(manifest, directory, manifestSha256), integrity: 'verified' };
+}
+
+function includePayloadAnalysis(analysis, payloads) {
+  analysis.recordedPayloads = payloads;
+  analysis.coverage.externalPayloads = 'included-retained-recordings';
+  analysis.coverage.exclusions = payloads.exclusions;
+  analysis.coverage.missingReferences.push(...payloads.missingReferences);
+  analysis.coverage.referenceClosure = analysis.coverage.missingReferences.length ? 'partial' : 'complete';
+}
+
+function resultOf(manifest, directory, manifestSha256) {
+  return { ok: true, archiveDir: directory, manifestPath: path.join(directory, 'manifest.json'), manifestSha256,
+    namespace: manifest.namespace, operationId: manifest.operationId, recordCount: manifest.recordCount,
+    targets: manifest.targets, coverage: manifest.coverage,
+    ...(manifest.recordedPayloads ? { recordedPayloads: manifest.recordedPayloads } : {}) };
+}
+
+module.exports = { handle, analyzeFacts };