@citeark/agent 0.3.20

package/src/cap/v2/verify.mjs

@@ -0,0 +1,642 @@
+import { validateGraphRecords } from '../../graph/validate.mjs';
+import { CAP_RECORD_ROLE } from '../../graph/model.mjs';
+import { publicContractPolicyIssues } from "../../contracts/public-contract.mjs";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  assertSha256Digest,
+  parseCanonicalJson,
+  sha256Bytes,
+} from "./canonical-json.mjs";
+import {
+  CAP_MANIFEST,
+  CAP_MANIFEST_MEDIA_TYPE,
+  CAP_PROFILE,
+  CAP_RECORD_TYPE,
+  CAP_SPEC_VERSION,
+  CAP_READABLE_SPEC_VERSIONS,
+  capPolicyCommitment,
+  safeCapPath,
+} from "./core.mjs";
+import { verifyCapAttestation } from "./attestation.mjs";
+
+const KNOWN_PROFILES = new Set(Object.values(CAP_PROFILE));
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+export async function verifyCapDirectory(directory, options = {}) {
+  const root = path.resolve(directory);
+  const issues = [];
+  const warnings = [];
+  const entries = await listRegularEntries(root, issues);
+  const manifestPath = path.join(root, CAP_MANIFEST);
+  let manifest;
+  let manifestBytes;
+  try {
+    manifestBytes = await readFile(manifestPath);
+    manifest = parseCanonicalJson(manifestBytes, CAP_MANIFEST);
+  } catch (error) {
+    issues.push(error instanceof Error ? error.message : String(error));
+    return emptyReport();
+  }
+  const artifactDigest = sha256Bytes(manifestBytes);
+  validateManifestEnvelope(manifest, issues, warnings);
+
+  const recordBodies = new Map();
+  const recordDescriptors = validateRecordDescriptors(manifest.records, issues);
+  const blobDescriptors = validateBlobDescriptors(manifest.blobs, issues);
+  const declaredArtifactPaths = new Set([CAP_MANIFEST]);
+
+  for (const descriptor of recordDescriptors.values()) {
+    declaredArtifactPaths.add(descriptor.path);
+    const target = path.join(root, descriptor.path);
+    try {
+      const bytes = await readFile(target);
+      if (bytes.byteLength !== descriptor.size) issues.push(`Record size mismatch: ${descriptor.id}`);
+      if (sha256Bytes(bytes) !== descriptor.digest) issues.push(`Record digest mismatch: ${descriptor.id}`);
+      const body = parseCanonicalJson(bytes, `Record ${descriptor.id}`);
+      if (body?.id !== descriptor.id) issues.push(`Record body id does not match descriptor: ${descriptor.id}`);
+      if (body?.type !== descriptor.recordType) issues.push(`Record body type does not match descriptor: ${descriptor.id}`);
+      validateRecordBody(body, descriptor, issues);
+      recordBodies.set(descriptor.id, body);
+    } catch (error) {
+      issues.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  let embedded = 0;
+  let external = 0;
+  let withheld = 0;
+  for (const descriptor of blobDescriptors.values()) {
+    if (descriptor.availability === "embedded") {
+      embedded += 1;
+      declaredArtifactPaths.add(descriptor.path);
+      try {
+        const bytes = await readFile(path.join(root, descriptor.path));
+        if (bytes.byteLength !== descriptor.size) issues.push(`Blob size mismatch: ${descriptor.id}`);
+        if (sha256Bytes(bytes) !== descriptor.digest) issues.push(`Blob digest mismatch: ${descriptor.id}`);
+      } catch (error) {
+        issues.push(`Cannot read embedded Blob ${descriptor.id}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    } else if (descriptor.availability === "external") {
+      external += 1;
+    } else if (descriptor.availability === "withheld") {
+      withheld += 1;
+    }
+  }
+
+  validateDeclaredPaths(entries, declaredArtifactPaths, issues);
+  validateRootsAndCreator(manifest, recordDescriptors, recordBodies, issues);
+  validateRecordReferences(recordBodies, recordDescriptors, artifactDigest, issues);
+  validateGraphRecords(recordBodies, recordDescriptors, issues);
+  for (const body of recordBodies.values()) {
+    if (body.blobs != null && !Array.isArray(body.blobs)) issues.push(`Record ${body.id}: blobs must be an array`);
+    for (const digest of Array.isArray(body.blobs) ? body.blobs : []) {
+      if (!blobDescriptors.has(digest)) issues.push(`Record ${body.id} references an unknown Blob digest: ${digest}`);
+    }
+  }
+  validateScientificBindings(recordBodies, blobDescriptors, issues, manifest.profiles ?? []);
+  await validateLocations(root, entries, blobDescriptors, issues, warnings);
+
+  const attestations = await verifyAttestations(root, entries, artifactDigest, options, warnings);
+  for (const attestation of attestations) issues.push(...attestation.issues.map((item) => `Attestation: ${item}`));
+  await validateProfiles({
+    root,
+    manifest,
+    entries,
+    recordBodies,
+    blobDescriptors,
+    attestations,
+    issues,
+    warnings,
+  });
+
+  return {
+    valid: issues.length === 0,
+    protocolVersion: CAP_SPEC_VERSION,
+    artifactDigest,
+    manifest,
+    issues,
+    warnings,
+    materialization: { embedded, external, withheld },
+    attestations,
+  };
+
+  function emptyReport() {
+    return {
+      valid: false,
+      protocolVersion: CAP_SPEC_VERSION,
+      artifactDigest: null,
+      manifest: manifest ?? null,
+      issues,
+      warnings,
+      materialization: { embedded: 0, external: 0, withheld: 0 },
+      attestations: [],
+    };
+  }
+}
+
+function validateManifestEnvelope(manifest, issues, warnings) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    issues.push("CAP manifest must be a JSON object");
+    return;
+  }
+  if (!CAP_READABLE_SPEC_VERSIONS.has(manifest.specVersion)) issues.push(`Unsupported CAP specVersion: ${manifest.specVersion ?? "<missing>"}`);
+  if (manifest.mediaType !== CAP_MANIFEST_MEDIA_TYPE) issues.push("CAP manifest mediaType is invalid");
+  if (!manifest.artifact || typeof manifest.artifact !== "object") issues.push("CAP manifest requires artifact metadata");
+  if (!Array.isArray(manifest.profiles) || !manifest.profiles.includes(CAP_PROFILE.core)) {
+    issues.push("CAP manifest must declare the Core Profile");
+  } else {
+    for (const profile of manifest.profiles) {
+      if (!KNOWN_PROFILES.has(profile)) warnings.push(`Unknown optional CAP Profile: ${profile}`);
+    }
+  }
+  if (!Array.isArray(manifest.roots) || manifest.roots.length === 0) issues.push("CAP manifest requires at least one root Record");
+  if (!Array.isArray(manifest.records) || manifest.records.length === 0) issues.push("CAP manifest requires Record descriptors");
+  if (!Array.isArray(manifest.blobs)) issues.push("CAP manifest blobs must be an array");
+  if (!Array.isArray(manifest.relations)) issues.push("CAP manifest relations must be an array");
+  for (const [index, relation] of (manifest.relations ?? []).entries()) {
+    if (typeof relation?.relationship !== "string" || !relation.relationship) issues.push(`relations[${index}] requires relationship`);
+    if (!DIGEST_PATTERN.test(relation?.artifactDigest)) issues.push(`relations[${index}] requires artifactDigest`);
+    if (relation?.recordDigest != null && !DIGEST_PATTERN.test(relation.recordDigest)) issues.push(`relations[${index}] recordDigest is invalid`);
+  }
+}
+
+function validateRecordDescriptors(value, issues) {
+  const output = new Map();
+  const paths = new Set();
+  const digests = new Set();
+  for (const [index, descriptor] of (Array.isArray(value) ? value : []).entries()) {
+    if (!descriptor || typeof descriptor !== "object") {
+      issues.push(`records[${index}] must be an object`);
+      continue;
+    }
+    if (typeof descriptor.id !== "string" || !descriptor.id) issues.push(`records[${index}] requires id`);
+    if (typeof descriptor.role !== "string" || !descriptor.role) issues.push(`records[${index}] requires role`);
+    if (typeof descriptor.recordType !== "string" || !descriptor.recordType) issues.push(`records[${index}] requires recordType`);
+    if (typeof descriptor.mediaType !== "string" || !descriptor.mediaType) issues.push(`records[${index}] requires mediaType`);
+    if (typeof descriptor.schema !== "string" || !descriptor.schema) issues.push(`records[${index}] requires schema`);
+    if (!DIGEST_PATTERN.test(descriptor.digest)) issues.push(`records[${index}] digest is invalid`);
+    if (!Number.isSafeInteger(descriptor.size) || descriptor.size < 0) issues.push(`records[${index}] size is invalid`);
+    if (!safeCapPath(descriptor.path) || !descriptor.path.startsWith("records/")) { issues.push(`records[${index}] path is invalid`); continue; }
+    if (output.has(descriptor.id)) issues.push(`Duplicate Record id: ${descriptor.id}`);
+    if (paths.has(descriptor.path)) issues.push(`Duplicate Record path: ${descriptor.path}`);
+    if (digests.has(descriptor.digest)) issues.push(`Duplicate Record digest: ${descriptor.digest}`);
+    output.set(descriptor.id, descriptor);
+    paths.add(descriptor.path);
+    digests.add(descriptor.digest);
+  }
+  return output;
+}
+
+function validateBlobDescriptors(value, issues) {
+  const output = new Map();
+  const ids = new Set();
+  const paths = new Set();
+  for (const [index, descriptor] of (Array.isArray(value) ? value : []).entries()) {
+    if (!descriptor || typeof descriptor !== "object") {
+      issues.push(`blobs[${index}] must be an object`);
+      continue;
+    }
+    if (typeof descriptor.id !== "string" || !descriptor.id) issues.push(`blobs[${index}] requires id`);
+    if (!Array.isArray(descriptor.roles)) issues.push(`blobs[${index}] roles must be an array`);
+    if (typeof descriptor.mediaType !== "string" || !descriptor.mediaType) issues.push(`blobs[${index}] requires mediaType`);
+    if (!DIGEST_PATTERN.test(descriptor.digest)) issues.push(`blobs[${index}] digest is invalid`);
+    if (!Number.isSafeInteger(descriptor.size) || descriptor.size < 0) issues.push(`blobs[${index}] size is invalid`);
+    if (!new Set(["embedded", "external", "withheld"]).has(descriptor.availability)) issues.push(`blobs[${index}] availability is invalid`);
+    if (descriptor.availability === "embedded") {
+      if (!safeCapPath(descriptor.path) || !descriptor.path.startsWith("blobs/")) { issues.push(`blobs[${index}] embedded path is invalid`); continue; }
+      const expected = casBlobPath(descriptor.digest);
+      if (descriptor.path !== expected) issues.push(`Embedded Blob path is not content-addressed: ${descriptor.id}`);
+      if (paths.has(descriptor.path)) issues.push(`Duplicate Blob path: ${descriptor.path}`);
+      paths.add(descriptor.path);
+    } else if (descriptor.path != null) {
+      issues.push(`${descriptor.availability} Blob must not have a bundle path: ${descriptor.id}`);
+    }
+    if (ids.has(descriptor.id)) issues.push(`Duplicate Blob id: ${descriptor.id}`);
+    if (output.has(descriptor.digest)) issues.push(`Duplicate Blob digest: ${descriptor.digest}`);
+    ids.add(descriptor.id);
+    output.set(descriptor.digest, descriptor);
+  }
+  return output;
+}
+
+function validateRecordBody(body, descriptor, issues) {
+  const requireText = (value, field) => {
+    if (typeof value !== "string" || !value) issues.push(`Record ${descriptor.id} requires ${field}`);
+  };
+  if (!body || typeof body !== "object" || Array.isArray(body)) return;
+  if (body.$schema != null && body.$schema !== descriptor.schema) issues.push(`Record ${descriptor.id} $schema does not match its descriptor`);
+  switch (body.role) {
+    case CAP_RECORD_ROLE.actor:
+      requireText(body.kind, "kind");
+      requireText(body.name, "name");
+      break;
+    case CAP_RECORD_ROLE.sourceWork:
+      requireText(body.title, "title");
+      if (!Array.isArray(body.sources) || body.sources.length === 0) issues.push(`SourceWork ${body.id} requires sources`);
+      break;
+    case CAP_RECORD_ROLE.claim:
+      if (typeof body.statement?.value !== "string" || !body.statement.value) issues.push(`Claim ${body.id} requires statement.value`);
+      
+      break;
+    case CAP_RECORD_ROLE.experiment:
+      
+      
+      break;
+    case CAP_RECORD_ROLE.execution:
+      
+      requireText(body.status, "status");
+      
+      break;
+    case CAP_RECORD_ROLE.evidence:
+      requireText(body.kind, "kind");
+      if (!new Set(["observed", "declared", "inferred", "attested"]).has(body.basis)) issues.push(`Evidence ${body.id} basis is invalid`);
+
+      break;
+    case CAP_RECORD_ROLE.assessment:
+      
+      if (!Array.isArray(body.evidence)) issues.push(`Assessment ${body.id} evidence must be an array`);
+      if (!new Set(["supports", "challenges", "contradicts", "inconclusive"]).has(body.conclusion)) issues.push(`Assessment ${body.id} conclusion is invalid`);
+      if (!body.method || typeof body.method !== "object") issues.push(`Assessment ${body.id} requires method`);
+      break;
+    default:
+      break;
+  }
+}
+
+function validateDeclaredPaths(entries, declared, issues) {
+  for (const expected of declared) {
+    if (!entries.files.has(expected)) issues.push(`Declared Artifact file is missing: ${expected}`);
+  }
+  for (const filename of entries.files) {
+    if (declared.has(filename) || allowedBundleAttachment(filename)) continue;
+    issues.push(`Bundle contains an undeclared Artifact file: ${filename}`);
+  }
+}
+
+function validateRootsAndCreator(manifest, records, bodies, issues) {
+  validateReference(manifest.artifact?.createdBy, records, "artifact.createdBy", issues);
+  const creator = records.get(manifest.artifact?.createdBy?.ref);
+  if (creator && creator.recordType !== CAP_RECORD_TYPE.agent) issues.push("artifact.createdBy must reference an Actor Record");
+  for (const [index, root] of (manifest.roots ?? []).entries()) {
+    if (typeof root?.role !== "string" || !root.role) issues.push(`roots[${index}] requires role`);
+    validateReference(root, records, `roots[${index}]`, issues);
+  }
+  if (manifest.artifact?.createdAt && !Number.isFinite(Date.parse(manifest.artifact.createdAt))) issues.push("artifact.createdAt is not a date-time");
+  if (bodies.size !== records.size) issues.push("Not every Record descriptor resolved to a valid Record body");
+}
+
+function validateRecordReferences(bodies, descriptors, currentArtifactDigest, issues) {
+  for (const [recordId, body] of bodies) walk(body, `$record:${recordId}`);
+
+  function walk(value, pointer) {
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(item, `${pointer}/${index}`));
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (typeof value.ref === "string") {
+      if (value.artifactDigest) {
+        if (!DIGEST_PATTERN.test(value.artifactDigest)) issues.push(`${pointer}.artifactDigest is invalid`);
+        if (!DIGEST_PATTERN.test(value.digest)) issues.push(`${pointer}.digest is required for an external Record reference`);
+        if (typeof value.recordType !== "string" || !value.recordType) issues.push(`${pointer}.recordType is required for an external Record reference`);
+        if (value.artifactDigest === currentArtifactDigest) validateReference(value, descriptors, pointer, issues);
+      } else {
+        validateReference(value, descriptors, pointer, issues, false);
+      }
+      return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+      if (key === "$schema") continue;
+      walk(child, `${pointer}/${key}`);
+    }
+  }
+}
+
+function validateScientificBindings(bodies, blobs, issues, profiles) {
+  const reproduction = profiles.includes(CAP_PROFILE.reproduction);
+  const typeOf = (reference) => reference?.artifactDigest
+    ? reference.role
+    : bodies.get(reference?.ref)?.role;
+  const domainProfile = profiles.some(profile => [CAP_PROFILE.reproduction, CAP_PROFILE.researchCompilation, CAP_PROFILE.researchPlan, CAP_PROFILE.computationalRun].includes(profile));
+  for (const body of bodies.values()) {
+    // Core also accepts relation-only and paper-free scientific records.
+    if (!domainProfile) continue;
+    if (body.role === "claim") {
+      if (body.source?.work && typeOf(body.source?.work) !== CAP_RECORD_ROLE.sourceWork) issues.push(`Claim ${body.id} source.work must reference a SourceWork Record`);
+      if (body.origin?.actor && typeOf(body.origin?.actor) !== CAP_RECORD_ROLE.actor) issues.push(`Claim ${body.id} origin.actor must reference an Actor Record`);
+    } else if (body.role === "procedure") {
+      for (const reference of body.tests ?? []) {
+        if (typeOf(reference) !== CAP_RECORD_ROLE.claim) issues.push(`Experiment ${body.id} tests must reference Claim Records`);
+      }
+      for (const issue of publicContractPolicyIssues(body.publicContract ?? {})) {
+        issues.push(`Experiment ${body.id} publicContract: ${issue}`);
+      }
+    } else if (body.role === "execution") {
+      if (body.experiment && typeOf(body.experiment) !== CAP_RECORD_ROLE.experiment) issues.push(`Execution ${body.id} experiment must reference an Experiment Record`);
+      for (const item of body.actors ?? []) {
+        if (typeOf(item.actor) !== CAP_RECORD_ROLE.actor) issues.push(`Execution ${body.id} actors must reference Actor Records`);
+      }
+      if (body.reproduced != null || body.verificationStatus != null) {
+        issues.push(`Execution ${body.id} must not contain a scientific reproduction verdict`);
+      }
+      if (body.trace?.blobDigest) {
+        const trace = blobs.get(body.trace.blobDigest);
+        if (!trace || !trace.roles.includes("execution-trace")) issues.push(`Execution ${body.id} trace must reference an execution-trace Blob`);
+      }
+    } else if (body.role === "observation") {
+      if (body.generatedBy && typeOf(body.generatedBy) !== CAP_RECORD_ROLE.execution) issues.push(`Evidence ${body.id} generatedBy must reference an Execution Record`);
+      for (const digest of [...(body.parser?.inputs ?? []), ...(body.blobs ?? [])]) {
+        if (!blobs.has(digest)) issues.push(`Evidence ${body.id} references an unknown Blob digest: ${digest}`);
+      }
+    } else if (body.role === "assessment") {
+      if (body.claim && typeOf(body.claim) !== CAP_RECORD_ROLE.claim) issues.push(`Assessment ${body.id} claim must reference a Claim Record`);
+      if (body.experiment && typeOf(body.experiment) !== CAP_RECORD_ROLE.experiment) issues.push(`Assessment ${body.id} experiment must reference an Experiment Record`);
+      if ((reproduction || body.execution) && typeOf(body.execution) !== CAP_RECORD_ROLE.execution) issues.push(`Assessment ${body.id} execution must reference an Execution Record`);
+      if (typeOf(body.performedBy) !== CAP_RECORD_ROLE.actor) issues.push(`Assessment ${body.id} performedBy must reference an Actor Record`);
+      for (const reference of body.evidence ?? []) {
+        if (typeOf(reference) !== CAP_RECORD_ROLE.evidence) issues.push(`Assessment ${body.id} evidence must reference Evidence Records`);
+      }
+      const experiment = bodies.get(body.experiment?.ref);
+      const execution = bodies.get(body.execution?.ref);
+      if (experiment && !(experiment.tests ?? []).some((item) => sameReference(item, body.claim))) issues.push(`Assessment ${body.id} Claim is not tested by its Experiment`);
+      if (reproduction && experiment && !DIGEST_PATTERN.test(experiment.publicContract?.verificationPolicyCommitment)) {
+        issues.push(`Assessment ${body.id} requires its Experiment to bind a verification policy commitment`);
+      }
+      if (execution?.experiment && !sameReference(execution.experiment, body.experiment)) issues.push(`Assessment ${body.id} Execution does not instantiate its Experiment`);
+      for (const reference of body.evidence ?? []) {
+        const evidence = bodies.get(reference.ref);
+        if (evidence?.generatedBy && !sameReference(evidence.generatedBy, body.execution)) issues.push(`Assessment ${body.id} Evidence was generated by a different Execution`);
+      }
+      const reveal = body.method?.policyReveal;
+      if (reproduction && !reveal) {
+        issues.push(`Assessment ${body.id} requires a verification policy reveal`);
+      } else if (reveal) {
+        try {
+          const actual = capPolicyCommitment({ nonce: reveal.nonce, policy: reveal.policy });
+          if (reveal.algorithm !== "citeark-policy-commitment-v1") issues.push(`Assessment ${body.id} policy commitment algorithm is unsupported`);
+          if (actual !== body.method?.policyCommitment) issues.push(`Assessment ${body.id} policy reveal does not match method.policyCommitment`);
+          if (experiment && actual !== experiment.publicContract?.verificationPolicyCommitment) issues.push(`Assessment ${body.id} policy reveal does not match the Experiment pre-execution commitment`);
+        } catch (error) {
+          issues.push(`Assessment ${body.id} policy reveal is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+    }
+  }
+}
+
+function validateReference(reference, records, label, issues, requireDigest = true) {
+  if (!reference || typeof reference.ref !== "string" || !reference.ref) {
+    issues.push(`${label} is not a CAP Record reference`);
+    return;
+  }
+  const descriptor = records.get(reference.ref);
+  if (!descriptor) {
+    issues.push(`${label} references an unknown Record: ${reference.ref}`);
+    return;
+  }
+  if (requireDigest && reference.digest !== descriptor.digest) issues.push(`${label} does not bind the current Record digest`);
+  if (!requireDigest && reference.digest != null && reference.digest !== descriptor.digest) issues.push(`${label} Record digest is inconsistent`);
+}
+
+async function validateLocations(root, entries, blobs, issues, warnings) {
+  if (!entries.files.has("cap-locations.json")) return;
+  try {
+    const locations = JSON.parse(await readFile(path.join(root, "cap-locations.json"), "utf8"));
+    if (!Array.isArray(locations?.objects)) throw new Error("cap-locations.json requires objects[]");
+    for (const [index, object] of locations.objects.entries()) {
+      if (!DIGEST_PATTERN.test(object?.digest)) issues.push(`cap-locations objects[${index}] digest is invalid`);
+      else if (!blobs.has(object.digest)) warnings.push(`cap-locations references an unknown Blob digest: ${object.digest}`);
+      if (!Array.isArray(object?.locations)) issues.push(`cap-locations objects[${index}] locations must be an array`);
+    }
+  } catch (error) {
+    issues.push(`Invalid cap-locations.json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function verifyAttestations(root, entries, artifactDigest, options, warnings) {
+  const output = [];
+  for (const filename of [...entries.files].filter((item) => item.startsWith("attestations/") && item.endsWith(".json")).sort()) {
+    try {
+      const value = JSON.parse(await readFile(path.join(root, filename), "utf8"));
+      const report = verifyCapAttestation(value, {
+        artifactDigest,
+        trustedKeyDigests: options.trustedKeyDigests ?? [],
+      });
+      if (!report.recognized) {
+        warnings.push(`Unsupported attestation attachment ignored: ${filename}`);
+        continue;
+      }
+      output.push({ path: filename, ...report });
+      warnings.push(...report.warnings.map((item) => `${filename}: ${item}`));
+    } catch (error) {
+      output.push({
+        path: filename,
+        recognized: true,
+        signatureValid: false,
+        subjectValid: false,
+        trusted: false,
+        issues: [error instanceof Error ? error.message : String(error)],
+        warnings: [],
+      });
+    }
+  }
+  return output;
+}
+
+async function validateProfiles({ root, manifest, entries, recordBodies, blobDescriptors, attestations, issues }) {
+  const types = new Set([...recordBodies.values()].map((item) => item.role));
+  const requireTypes = (profile, required) => {
+    if (!manifest.profiles.includes(profile)) return;
+    for (const type of required) {
+      if (!types.has(type)) issues.push(`Profile ${profile} requires Record type ${type}`);
+    }
+  };
+  requireTypes(CAP_PROFILE.computationalRun, [
+    CAP_RECORD_ROLE.actor,
+    CAP_RECORD_ROLE.experiment,
+    CAP_RECORD_ROLE.execution,
+    CAP_RECORD_ROLE.evidence,
+  ]);
+  requireTypes(CAP_PROFILE.researchCompilation, [
+    CAP_RECORD_ROLE.actor,
+    CAP_RECORD_ROLE.sourceWork,
+  ]);
+  if (manifest.profiles.includes(CAP_PROFILE.researchCompilation)) {
+    if (!(manifest.roots ?? []).some((root) => root.role === "primarySourceWork")) {
+      issues.push("Research Compilation Profile requires root role primarySourceWork");
+    }
+    const claimIds = new Set(
+      [...recordBodies.values()]
+        .filter((record) => record.role === "claim")
+        .map((record) => record.id),
+    );
+    const compiledClaimIds = new Set(
+      (manifest.roots ?? [])
+        .filter((root) => root.role === "compiledClaim")
+        .map((root) => root.ref),
+    );
+    if (
+      claimIds.size !== compiledClaimIds.size
+      || [...claimIds].some((id) => !compiledClaimIds.has(id))
+    ) {
+      issues.push("Research Compilation Profile must root every Claim as compiledClaim");
+    }
+    const compilerOutput = [...blobDescriptors.values()].find((item) =>
+      item.roles.includes("compiler-output"),
+    );
+    if (!compilerOutput) {
+      issues.push("Research Compilation Profile requires a compiler-output Blob");
+    }
+    const researchInventory = [...blobDescriptors.values()].find((item) =>
+      item.roles.includes("research-inventory"),
+    );
+    if (!researchInventory) {
+      issues.push("Research Compilation Profile requires a research-inventory Blob");
+    } else if (
+      researchInventory.availability !== "embedded"
+      || researchInventory.mediaType !== "application/json"
+    ) {
+      issues.push("Research Compilation research-inventory must be embedded JSON");
+    }
+    if ([...recordBodies.values()].some(body => (body.type === CAP_RECORD_TYPE.activity && !(body.role === 'research-activity'
+        && body.basis === 'declared' && body.origin?.basis === 'declared' && body.status === 'unknown'
+        && body.prospective !== true && body.sourceContext?.length > 0))
+      || ['procedure', 'procedure-step', 'assessment', 'measurement-assessment'].includes(body.role)
+      || (body.role === 'observation' && (body.basis !== 'declared' || body.generatedBy)))) {
+      issues.push("Research Compilation Profile permits only source-declared observations, never planned experiments, actual executions or assessments");
+    }
+  }
+  requireTypes(CAP_PROFILE.researchPlan, [
+    CAP_RECORD_ROLE.actor,
+    CAP_RECORD_ROLE.sourceWork,
+    CAP_RECORD_ROLE.claim,
+  ]);
+  if (manifest.profiles.includes(CAP_PROFILE.researchPlan)) {
+    for (const role of ["primarySourceWork", "plannedClaim"]) {
+      if (!(manifest.roots ?? []).some((root) => root.role === role)) {
+        issues.push(`Research Plan Profile requires root role ${role}`);
+      }
+    }
+    if (types.has(CAP_RECORD_ROLE.execution) || types.has(CAP_RECORD_ROLE.assessment)) {
+      issues.push("Research Plan Profile must not contain Execution or Assessment Records");
+    }
+  }
+  requireTypes(CAP_PROFILE.reproduction, [
+    CAP_RECORD_ROLE.sourceWork,
+    CAP_RECORD_ROLE.claim,
+    CAP_RECORD_ROLE.experiment,
+    CAP_RECORD_ROLE.execution,
+    CAP_RECORD_ROLE.evidence,
+    CAP_RECORD_ROLE.assessment,
+  ]);
+  if (manifest.profiles.includes(CAP_PROFILE.reproduction)) {
+    for (const role of ["primaryClaim", "primaryExecution", "primaryAssessment"]) {
+      if (!(manifest.roots ?? []).some((root) => root.role === role)) issues.push(`Reproduction Profile requires root role ${role}`);
+    }
+  }
+  if (manifest.profiles.includes(CAP_PROFILE.agentTrace)) {
+    const trace = [...blobDescriptors.values()].find((item) => item.roles.includes("execution-trace"));
+    if (!trace) issues.push("Agent Trace Profile requires an execution-trace Blob");
+    else if (trace.availability === "embedded") await validateTrace(path.join(root, trace.path), issues);
+  }
+  if (manifest.profiles.includes(CAP_PROFILE.restrictedEvidence)) {
+    const restricted = [...blobDescriptors.values()].filter((item) => item.availability !== "embedded");
+    if (restricted.length === 0) issues.push("Restricted Evidence Profile requires an external or withheld Blob");
+    for (const blob of restricted) {
+      if (!blob.accessPolicy || typeof blob.accessPolicy !== "object") issues.push(`Restricted Blob requires accessPolicy: ${blob.id}`);
+    }
+  }
+  if (manifest.profiles.includes(CAP_PROFILE.publicBundle)) {
+    if (!entries.files.has("ro-crate-metadata.json")) issues.push("Public Bundle Profile requires ro-crate-metadata.json");
+    else {
+      try {
+        const crate = JSON.parse(await readFile(path.join(root, "ro-crate-metadata.json"), "utf8"));
+        if (!crate?.["@context"] || !Array.isArray(crate?.["@graph"])) issues.push("ro-crate-metadata.json is not a usable RO-Crate projection");
+      } catch (error) {
+        issues.push(`ro-crate-metadata.json is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    for (const blob of blobDescriptors.values()) {
+      if (!blob.rights || typeof blob.rights !== "object") issues.push(`Public Blob requires resource-specific rights: ${blob.id}`);
+    }
+    for (const sourceWork of [...recordBodies.values()].filter((item) => item.role === "source-work")) {
+      for (const [index, source] of (sourceWork.sources ?? []).entries()) {
+        if (!source.rights || typeof source.rights !== "object") issues.push(`Public SourceWork ${sourceWork.id} source[${index}] requires rights`);
+      }
+    }
+    const validSignature = attestations.some((item) => item.signatureValid && item.subjectValid);
+    if (!validSignature) issues.push("Public Bundle Profile requires a valid root Artifact attestation");
+  }
+}
+
+function sameReference(left, right) {
+  if (!left || !right || left.ref !== right.ref) return false;
+  if (left.artifactDigest || right.artifactDigest) return left.artifactDigest === right.artifactDigest && left.digest === right.digest;
+  return true;
+}
+
+async function validateTrace(filename, issues) {
+  try {
+    const text = await readFile(filename, "utf8");
+    let previous = 0;
+    for (const [index, line] of text.split(/\r?\n/).filter(Boolean).entries()) {
+      const event = JSON.parse(line);
+      if (!Number.isSafeInteger(event.sequence) || event.sequence <= previous) issues.push(`Trace line ${index + 1} has a non-monotonic sequence`);
+      if (typeof event.eventType !== "string" || !event.eventType) issues.push(`Trace line ${index + 1} requires eventType`);
+      if (typeof event.occurredAt !== "string" || !Number.isFinite(Date.parse(event.occurredAt))) issues.push(`Trace line ${index + 1} requires occurredAt`);
+      if (typeof event.observedAt !== "string" || !Number.isFinite(Date.parse(event.observedAt))) issues.push(`Trace line ${index + 1} requires observedAt`);
+      previous = event.sequence;
+    }
+  } catch (error) {
+    issues.push(`Execution trace is invalid: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function listRegularEntries(root, issues) {
+  const files = new Set();
+  async function visit(directory, prefix = "") {
+    let children;
+    try {
+      children = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      issues.push(`Cannot read CAP directory: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    for (const child of children) {
+      const relative = prefix ? `${prefix}/${child.name}` : child.name;
+      if (!safeCapPath(relative)) {
+        issues.push(`Unsafe CAP path: ${relative}`);
+        continue;
+      }
+      const target = path.join(directory, child.name);
+      const stat = await lstat(target);
+      if (stat.isSymbolicLink()) {
+        issues.push(`CAP contains a symbolic link: ${relative}`);
+      } else if (stat.isDirectory()) {
+        await visit(target, relative);
+      } else if (stat.isFile()) {
+        files.add(relative);
+      } else {
+        issues.push(`CAP contains a non-regular entry: ${relative}`);
+      }
+    }
+  }
+  await visit(root);
+  return { files };
+}
+
+function allowedBundleAttachment(filename) {
+  return filename === "cap-locations.json"
+    || filename === "ro-crate-metadata.json"
+    || filename.startsWith("attestations/")
+    || filename.startsWith("preview/")
+    || filename.startsWith("projections/");
+}
+
+function casBlobPath(digest) {
+  if (!DIGEST_PATTERN.test(digest)) return "<invalid>";
+  const hex = digest.slice(7);
+  return `blobs/sha256/${hex.slice(0, 2)}/${hex}`;
+}