@citeark/agent 0.3.20

package/src/graph/query.mjs

@@ -0,0 +1,159 @@
+import { CAP_RECORD_TYPE, referenceKey, primitiveOf } from './model.mjs';
+
+export const ARKGRAPH_QUERY_VERSION = 'arkgraph/1';
+const routePredicates = new Set(['requires', 'partOf', 'used', 'generated', 'follows', 'derivedFrom', 'plannedFor', 'evidenceFor', 'assesses', 'basedOn']);
+
+/** Callers MUST supply only artifacts readable by the current principal.
+ * A content digest is identity, never an authorization credential.
+ */
+export function createArkGraph(artifacts) {
+  const records = new Map();
+  const artifactIds = new Set(artifacts.map(item => item.artifactDigest));
+  for (const artifact of artifacts) {
+    const descriptors = new Map(artifact.manifest.records.map(d => [d.id, d]));
+    for (const record of artifact.graphRecords) {
+      const descriptor = descriptors.get(record.id);
+      if (!descriptor) throw Error(`Missing authenticated descriptor for ${record.id}`);
+      const key = referenceKey({ ref: record.id, digest: descriptor.digest });
+      const existing = records.get(key);
+      if (existing) { if (!existing.artifacts.includes(artifact.artifactDigest)) existing.artifacts.push(artifact.artifactDigest); continue; }
+      records.set(key, { key, ref: record.id, digest: descriptor.digest, recordType: record.type,
+        role: record.role, record, artifacts: [artifact.artifactDigest] });
+    }
+  }
+  const resolve = reference => {
+    const candidate = records.get(referenceKey(reference));
+    if (!candidate || (reference.artifactDigest && (!artifactIds.has(reference.artifactDigest) || !candidate.artifacts.includes(reference.artifactDigest)))) return 'unavailable';
+    return candidate.recordType === reference.recordType ? 'resolved' : 'type-mismatch';
+  };
+  const nodes = [], relations = [];
+  for (const record of records.values()) {
+    record.artifacts.sort();
+    if (record.recordType === CAP_RECORD_TYPE.relation) {
+      relations.push({ ...record, predicate: record.record.predicate,
+        subject: record.record.subject, object: record.record.object,
+        resolution: { subject: resolve(record.record.subject), object: resolve(record.record.object) } });
+    } else nodes.push(record);
+  }
+  const byKey = (a, b) => a.key.localeCompare(b.key, 'en');
+  return { queryVersion: ARKGRAPH_QUERY_VERSION, artifacts: [...artifactIds].sort(),
+    nodes: nodes.sort(byKey), relations: relations.sort(byKey),
+    attestations: artifacts.map(a => ({ artifactDigest: a.artifactDigest, attestations: a.attestations ?? [] })) };
+}
+
+export function queryArkGraph(graph, { roots = [], predicates, depth = 4, limit = 200, cursor } = {}) {
+  if (!Number.isInteger(depth) || depth < 0 || depth > 12) throw Error('depth must be between 0 and 12');
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw Error('limit must be between 1 and 500');
+  const offset = cursor == null ? 0 : Number(cursor);
+  if (!Number.isSafeInteger(offset) || offset < 0 || String(offset) !== String(cursor ?? 0)) throw Error('invalid graph cursor');
+  const validRoots = roots.filter(root => getArkGraphRecord(graph, root));
+  const rootKeys = new Set(validRoots.map(referenceKey));
+  const edges = graph.relations.filter(edge => !predicates || predicates.includes(edge.predicate));
+  const reachable = new Set(rootKeys);
+  let frontier = new Set(rootKeys);
+  for (let i = 0; i < depth && frontier.size; i++) {
+    const next = new Set();
+    for (const edge of edges) {
+      const subject = referenceKey(edge.subject), object = referenceKey(edge.object);
+      if (edge.resolution.subject !== 'resolved' || edge.resolution.object !== 'resolved') continue;
+      if (frontier.has(subject) && !reachable.has(object)) next.add(object);
+      if (frontier.has(object) && !reachable.has(subject)) next.add(subject);
+    }
+    for (const key of next) reachable.add(key);
+    frontier = next;
+  }
+  const selected = graph.nodes.filter(node => !roots.length || reachable.has(node.key));
+  const nodes = selected.slice(offset, offset + limit);
+  const visible = new Set(nodes.map(node => node.key));
+  const relations = edges.filter(edge => visible.has(referenceKey(edge.subject)) || visible.has(referenceKey(edge.object)))
+    .map(edge => ({ ...edge, selection: { subject: visible.has(referenceKey(edge.subject)), object: visible.has(referenceKey(edge.object)) } }));
+  const boundary = rootKeys.size && edges.some(edge => reachable.has(referenceKey(edge.subject)) !== reachable.has(referenceKey(edge.object)));
+  return { queryVersion: graph.queryVersion, artifacts: graph.artifacts, nodes, relations,
+    scope: { roots, predicates: predicates ?? null, depth },
+    missingRoots: roots.filter(root => !getArkGraphRecord(graph, root)),
+    truncated: Boolean(graph.truncated || boundary || offset > 0 || offset + limit < selected.length),
+    nextCursor: offset + limit < selected.length ? String(offset + limit) : null,
+    totalSelected: selected.length, attestations: graph.attestations };
+}
+
+export function getArkGraphRecord(graph, reference) {
+  const key = referenceKey(reference);
+  const item = [...graph.nodes, ...graph.relations].find(record => record.key === key);
+  if (!item || (reference.recordType && item.recordType !== reference.recordType) || (reference.artifactDigest && !item.artifacts.includes(reference.artifactDigest))) return null;
+  return { ...item, relations: graph.relations.filter(edge => edge.key === key || referenceKey(edge.subject) === key || referenceKey(edge.object) === key) };
+}
+
+export function traceArkGraphProvenance(graph, reference, options = {}) {
+  const record = getArkGraphRecord(graph, reference);
+  if (!record) return null;
+  const roots = record.recordType === CAP_RECORD_TYPE.relation
+    ? [record.record.subject, record.record.object, record.record.attributedTo, ...(record.record.sources ?? [])]
+    : [reference];
+  return { record, ...queryArkGraph(graph, { ...options, roots,
+    predicates: ['derivedFrom', 'assertedIn', 'attributedTo', 'generated', 'used', 'basedOn', 'revises', 'supersedes'] }) };
+}
+
+export function deriveArkRoute(graph, { target, activities = [], artifactDigests, limit = 300, depth = 8 } = {}) {
+  if (artifactDigests?.length) {
+    const selected = new Set(artifactDigests);
+    const nodes = graph.nodes.filter(node => node.artifacts.some(id => selected.has(id)));
+    const visible = new Map(nodes.map(node => [node.key, node]));
+    const relations = graph.relations.filter(edge => edge.artifacts.some(id => selected.has(id))).map(edge => ({ ...edge,
+      resolution: Object.fromEntries(['subject', 'object'].map(field => {
+        const ref = edge[field], node = visible.get(referenceKey(ref));
+        return [field, node && (!ref.artifactDigest || selected.has(ref.artifactDigest) && node.artifacts.includes(ref.artifactDigest)) ? node.recordType === ref.recordType ? 'resolved' : 'type-mismatch' : 'unavailable'];
+      })),
+    }));
+    graph = { ...graph, nodes, relations, artifacts: graph.artifacts.filter(id => selected.has(id)),
+      attestations: graph.attestations.filter(item => selected.has(item.artifactDigest)) };
+  }
+  if (!target?.ref || !target.digest) throw Error('route requires an exact target reference');
+  const targetNode = getArkGraphRecord(graph, target);
+  if (!targetNode) return null;
+  const selectedActivities = new Set(activities.map(referenceKey));
+  const selectedGraph = selectedActivities.size ? { ...graph, relations: graph.relations.filter(edge => {
+    for (const endpoint of [edge.subject, edge.object]) {
+      if (endpoint.recordType === CAP_RECORD_TYPE.activity && !selectedActivities.has(referenceKey(endpoint))) return false;
+    }
+    return true;
+  }) } : graph;
+  const route = queryArkGraph(selectedGraph, { roots: [target], predicates: [...routePredicates], depth, limit });
+  const chosen = new Set(route.nodes.map(node => node.key));
+  // Include immediate provenance, but do not let a shared author or paper merge all routes.
+  const origins = selectedGraph.relations.filter(edge => !routePredicates.has(edge.predicate) && chosen.has(referenceKey(edge.subject)));
+  const originKeys = new Set(origins.map(edge => referenceKey(edge.object)));
+  const allNodes = [...route.nodes, ...graph.nodes.filter(node => originKeys.has(node.key) && !chosen.has(node.key))];
+  const nodes = allNodes.slice(0, limit);
+  const relations = [...route.relations, ...origins];
+  const unresolved = relations.flatMap(edge => ['subject', 'object'].filter(field => edge.resolution[field] !== 'resolved').map(field => ({ relation: edge.key, reference: edge[field], reason: 'dependency-unavailable-in-authorized-scope' })));
+  const assessments = nodes.filter(node => node.role === 'assessment').map(node => ({ reference: { ref: node.ref, digest: node.digest }, conclusion: node.record.conclusion, scope: node.record.scope, limitations: node.record.limitations, performedBy: node.record.performedBy }));
+  return { ...route, truncated: route.truncated || allNodes.length > limit, nodes, relations, target, activities,
+    groups: { reference: nodes.filter(n => n.record.basis === 'declared' || n.role === 'source-work').map(n => n.key),
+      planned: nodes.filter(n => n.role === 'procedure').map(n => n.key),
+      actual: nodes.filter(n => primitiveOf(n.record) === 'activity').map(n => n.key) },
+    assessments, unknowns: unresolved,
+    independence: { status: 'unknown', reason: 'Distinct record or artifact digests do not establish independent execution.' } };
+}
+
+/** Compare exact identities against one explicit target set; never align by metric label or text. */
+export function compareArkRoutes(left, right, { targets = [] } = {}) {
+  if (!left || !right) throw Error('both routes must be available');
+  const leftKeys = new Set(left.nodes.map(n => n.key)), rightKeys = new Set(right.nodes.map(n => n.key));
+  const versions = new Map();
+  for (const node of [...left.nodes, ...right.nodes]) {
+    const ds = versions.get(node.ref) ?? new Set(); ds.add(node.digest); versions.set(node.ref, ds);
+  }
+  const coverage = route => targets.map(target => {
+    const targetKey = referenceKey(target);
+    const assessmentKeys = new Set(route.relations.filter(edge => edge.predicate === 'assesses' && referenceKey(edge.object) === targetKey && edge.resolution.object === 'resolved').map(edge => referenceKey(edge.subject)));
+    const assessments = route.nodes.filter(n => n.role === 'assessment' && assessmentKeys.has(n.key)).map(n => ({ ref: n.ref, digest: n.digest, conclusion: n.record.conclusion, limitations: n.record.limitations }));
+    return { target, status: assessments.length ? 'assessed' : route.truncated || route.unknowns.length ? 'unknown' : 'unassessed', assessments };
+  });
+  return { queryVersion: ARKGRAPH_QUERY_VERSION,
+    inputs: { left: { target: left.target, artifacts: left.artifacts, activities: left.activities }, right: { target: right.target, artifacts: right.artifacts, activities: right.activities }, targets },
+    shared: [...leftKeys].filter(k => rightKeys.has(k)), onlyLeft: [...leftKeys].filter(k => !rightKeys.has(k)), onlyRight: [...rightKeys].filter(k => !leftKeys.has(k)),
+    changedVersions: [...versions].filter(([, digests]) => digests.size > 1).map(([ref, digests]) => ({ ref, digests: [...digests].sort() })),
+    coverage: { left: coverage(left), right: coverage(right) },
+    incomplete: left.truncated || right.truncated || left.unknowns.length > 0 || right.unknowns.length > 0,
+    independence: { status: 'unknown', reason: 'Shared inputs and different digests alone do not establish independence.' } };
+}

package/src/graph/research-relations.mjs

@@ -0,0 +1,69 @@
+import { CAP_RECORD_TYPE } from './model.mjs';
+import { canonicalJsonBytes, sha256Bytes } from '../cap/v2/canonical-json.mjs';
+
+/** Project explicitly recorded scientific bindings into independently addressable edges.
+ * This never infers a missing scientific step from a command or final measurement.
+ */
+export function researchRelations(records, creator) {
+  const edges = [];
+  const add = (owner, predicate, subject, object, pointer, basis = 'declared', qualifiers = {}) => {
+    if (!subject?.ref || !object?.ref) return;
+    const identity = { owner: owner.id, predicate, subject: subject.ref, object: object.ref, pointer };
+    edges.push({
+      $schema: 'https://citeark.com/schemas/cap/v2/relation.schema.json',
+      id: `urn:citeark:relation:${sha256Bytes(canonicalJsonBytes(identity)).slice(7)}`,
+      type: CAP_RECORD_TYPE.relation, role: 'provenance', predicate, subject, object,
+      basis, attributedTo: { ref: creator },
+      sources: [{ ref: owner.id }], qualifiers: { field: pointer, ...qualifiers },
+    });
+  };
+  for (const record of records) {
+    const self = { ref: record.id };
+    if (record.type === CAP_RECORD_TYPE.relation) continue;
+    if (record.source?.work) add(record, 'assertedIn', self, record.source.work, '/source', record.origin?.basis ?? 'declared', { selector: record.source.selector ?? null });
+    if (record.origin?.actor) add(record, 'attributedTo', self, record.origin.actor, '/origin', record.origin.basis ?? 'declared');
+    // Array bindings are separate source occurrences, even when endpoints match.
+    // Their exact pointer preserves distinct selectors, roles and declarations.
+    for (const [index, context] of (record.sourceContext ?? []).entries()) add(record, 'describes', context.source, self, `/sourceContext/${index}`, record.basis ?? 'declared', { selector: context.selector ?? null });
+    const objectsField = record.objects != null ? 'objects' : 'contextObjects';
+    for (const [index, object] of (record[objectsField] ?? []).entries()) add(record, 'about', self, object, `/${objectsField}/${index}`, record.contextBasis ?? record.origin?.basis ?? record.basis ?? 'declared');
+    if (record.type === CAP_RECORD_TYPE.entity && ['procedure', 'procedure-step'].includes(record.role)) {
+      for (const [index, input] of (record.inputs ?? []).entries()) if (input.record) add(record, 'requires', self, input.record, `/inputs/${index}`, input.basis ?? 'declared', { role: input.role, required: input.required !== false });
+      for (const [index, output] of (record.expectedOutputs ?? []).entries()) add(record, 'expects', self, output, `/expectedOutputs/${index}`, 'inferred', { prospective: true });
+      for (const [index, step] of (record.steps ?? []).entries()) add(record, 'hasStep', self, step, `/steps/${index}`, 'inferred');
+      for (const [index, step] of (record.dependencies ?? []).entries()) add(record, 'requires', self, step, `/dependencies/${index}`, 'inferred', { role: 'procedure-dependency' });
+    }
+    for (const [index, target] of (record.tests ?? []).entries()) add(record, 'plannedFor', self, target, `/tests/${index}`);
+    if (record.type === CAP_RECORD_TYPE.activity) {
+      if (record.experiment) add(record, 'follows', self, record.experiment, '/experiment');
+      for (const [index, item] of (record.actors ?? []).entries()) add(record, 'associatedWith', self, item.actor, `/actors/${index}`, 'declared', { role: item.role });
+      for (const [index, item] of (record.inputs ?? []).entries()) if (item.record) add(record, 'used', self, item.record, `/inputs/${index}`, item.basis ?? 'declared', { role: item.role });
+      for (const [index, item] of (record.outputs ?? []).entries()) if (item.record) add(record, 'generated', self, item.record, `/outputs/${index}`, 'declared', { role: item.role });
+    }
+    if (record.generatedBy) add(record, 'generated', record.generatedBy, self, '/generatedBy', record.basis ?? 'declared');
+    for (const [index, source] of (record.derivedFrom ?? []).entries()) add(record, 'derivedFrom', self, source, `/derivedFrom/${index}`, record.basis ?? 'declared');
+    for (const [index, evidence] of (record.reportedEvidence ?? []).entries()) add(record, 'evidenceFor', evidence, self, `/reportedEvidence/${index}`, 'declared');
+    if (record.role === 'assessment' || record.role === 'measurement-assessment') {
+      add(record, 'assesses', self, record.subject ?? record.claim, '/subject', 'inferred');
+      for (const [index, evidence] of (record.evidence ?? []).entries()) add(record, 'basedOn', self, evidence, `/evidence/${index}`, 'inferred');
+      for (const [index, component] of (record.componentAssessments ?? []).entries()) add(record, 'basedOn', self, component, `/componentAssessments/${index}`, 'inferred');
+      if (record.execution) add(record, 'basedOn', self, record.execution, '/execution', 'inferred');
+      if (record.performedBy) add(record, 'attributedTo', self, record.performedBy, '/performedBy', 'declared');
+    }
+  }
+  return edges;
+}
+
+/** Resolve only local bindings. Cross-artifact references stay explicit and unresolved. */
+export function bindRelation(record, descriptors) {
+  const bind = reference => {
+    if (!reference?.ref || reference.artifactDigest) return reference;
+    const target = descriptors.get(reference.ref);
+    if (!target) return reference; // The verifier reports the missing dependency.
+    if (reference.digest && reference.digest !== target.digest) return { ...reference, recordType: reference.recordType ?? target.recordType };
+    if (reference.recordType && reference.recordType !== target.recordType) return { ...reference, digest: reference.digest ?? target.digest };
+    return { ...reference, digest: target.digest, recordType: target.recordType };
+  };
+  return { ...record, subject: bind(record.subject), object: bind(record.object),
+    attributedTo: bind(record.attributedTo), sources: (record.sources ?? []).map(bind) };
+}

package/src/graph/source-page.mjs

@@ -0,0 +1,12 @@
+export function sourcePage(locators){
+  for(const locator of locators??[]){
+    if(Number.isSafeInteger(locator.page)&&locator.page>0)return locator.page;
+    const text=String(locator.locator??'');
+    const match=text.match(/\b(?:p\.|page\s+)\s*(\d+)\b|物理页\s*(\d+)|第\s*(\d+)\s*页/i);
+    if(match&&!/^\s*(?:[-–—~]|至)\s*\d/.test(text.slice(match.index+match[0].length))){
+      const page=Number(match.slice(1).find(Boolean));
+      if(Number.isSafeInteger(page)&&page>0)return page;
+    }
+  }
+  return null;
+}

package/src/graph/source-preview.mjs

@@ -0,0 +1,34 @@
+import {readFile,mkdir,copyFile} from 'node:fs/promises';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import path from 'node:path';
+import {sha256Bytes} from '../cap/v2/canonical-json.mjs';
+const exec=promisify(execFile);
+
+import {sourcePage} from './source-page.mjs';
+export {sourcePage} from './source-page.mjs';
+/** Render a source page, never infer a figure crop or invent data from plot pixels.
+ * The optional PDF must match the signed source identity before it is displayed.
+ */
+export async function attachLocalSourcePreviews(view,pdfPath,directory){
+  const bytes=await readFile(pdfPath),digest=sha256Bytes(bytes);
+  const works=view.nodes.filter(n=>n.role==='source-work');
+  const signedDigests=works.flatMap(n=>[...(n.raw.sources??[]).filter(s=>s.kind==='paper').map(s=>s.digest),n.raw.citeark?.provenance?.sourceIdentity?.paperDigest]);
+  if(!signedDigests.includes(digest))throw Error('Preview PDF does not match a signed source digest');
+  await copyFile(pdfPath,path.join(directory,'source-paper.pdf'));
+  view.sourceDocument='source-paper.pdf';
+  const {stdout}=await exec('pdfinfo',[pdfPath],{maxBuffer:100000});
+  const pages=Number(stdout.match(/^Pages:\s*(\d+)/m)?.[1]);
+  if(!pages)throw Error('Cannot determine source PDF page count');
+  const rendered=new Set();await mkdir(path.join(directory,'source-pages'),{recursive:true});
+  for(const node of view.nodes){
+    const page=sourcePage(node.sourceLocators);if(!page||page>pages)continue;node.sourcePage=page;
+    if(node.category!=='result')continue;
+    if(!rendered.has(page)){
+      await exec('pdftoppm',['-f',String(page),'-l',String(page),'-singlefile','-scale-to','1600','-png',pdfPath,path.join(directory,'source-pages',String(page))],{maxBuffer:100000});
+      rendered.add(page);
+    }
+    node.image=`source-pages/${page}.png`;node.imageCaption=`${node.label} · 原文第 ${page} 页`;
+  }
+  return {sourceDigest:digest,pages:[...rendered]};
+}

package/src/graph/validate.mjs

@@ -0,0 +1,76 @@
+import { CAP_RECORD_TYPE, CAP_ROLE_TYPE, CAP_PREDICATES, CAP_BASES, CAP_ACTIVITY_STATUSES, primitiveOf } from './model.mjs';
+const digestPattern = /^sha256:[0-9a-f]{64}$/;
+const conclusions = new Set(['supports', 'challenges', 'contradicts', 'inconclusive']);
+
+export function validateGraphRecords(bodies, descriptors, issues) {
+  for (const body of bodies.values()) {
+    const fail = message => issues.push(`Record ${body.id}: ${message}`);
+    const primitive = primitiveOf(body);
+    if (!primitive) { fail('unsupported scientific primitive'); continue; }
+    if (typeof body.id !== 'string' || !/^(urn:|https?:\/\/)/.test(body.id)) fail('id must have a producer namespace (URN or URL)');
+    if (typeof body.role !== 'string' || !body.role) fail('role is required');
+    if (descriptors.get(body.id)?.role !== body.role) fail('role does not match descriptor');
+    if (CAP_ROLE_TYPE[body.role] && CAP_ROLE_TYPE[body.role] !== primitive) fail('role is incompatible with primitive');
+    if (primitive === 'agent' && (typeof body.name !== 'string' || !body.name)) fail('agent requires name');
+    if (primitive === 'activity') {
+      if (!CAP_ACTIVITY_STATUSES.has(body.status)) fail('activity status must describe actual execution');
+      if (body.reproduced != null || body.verificationStatus != null) fail('activity must not contain a scientific reproduction verdict');
+      for (const key of ['startedAt', 'endedAt']) if (body[key] != null && !Number.isFinite(Date.parse(body[key]))) fail(`invalid ${key}`);
+      if (body.startedAt && body.endedAt && Date.parse(body.startedAt) > Date.parse(body.endedAt)) fail('activity ends before it starts');
+    }
+    if (primitive === 'assertion') {
+      if (['assessment', 'measurement-assessment'].includes(body.role)) {
+        if (!(body.subject ?? body.claim)?.ref) fail('assessment requires a subject');
+        if (!conclusions.has(body.conclusion)) fail('assessment conclusion is invalid');
+        if (!Array.isArray(body.evidence)) fail('assessment requires evidence array (empty is allowed)');
+        if (!body.method || typeof body.method !== 'object') fail('assessment requires method');
+        if (!body.scope || typeof body.scope !== 'object') fail('assessment requires scope');
+        if (!Array.isArray(body.limitations)) fail('assessment requires limitations');
+        if (!body.performedBy?.ref) fail('assessment requires performedBy');
+      } else if (!body.statement?.value) fail('assertion requires statement.value');
+    }
+    if (body.measurement) {
+      if (primitive !== 'entity') fail('measurement belongs to an Entity');
+      const m = body.measurement;
+      if (typeof m.metric !== 'string' || !m.metric) fail('measurement requires metric');
+      if (typeof m.value?.decimal !== 'string' || !/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$/.test(m.value.decimal)) fail('measurement requires an exact decimal string');
+      if (typeof m.unit !== 'string') fail('measurement requires unit (empty means dimensionless)');
+      if (!CAP_BASES.has(body.basis)) fail('measurement requires explicit basis');
+    }
+    if (primitive !== 'relation') continue;
+    if (!CAP_BASES.has(body.basis)) fail('relation requires explicit basis');
+    const signature = CAP_PREDICATES[body.predicate];
+    if (!signature) { fail('unsupported relation predicate'); continue; }
+    for (const [index, field] of ['subject', 'object'].entries()) {
+      const endpoint = body[field];
+      validateExactReference(endpoint, descriptors, fail, field);
+      const actual = endpoint?.artifactDigest ? endpoint.recordType : descriptors.get(endpoint?.ref)?.recordType;
+      if (signature[index] && actual !== CAP_RECORD_TYPE[signature[index]]) fail(`${field} has wrong primitive for ${body.predicate}`);
+      if (actual === CAP_RECORD_TYPE.relation) fail('relation endpoints must be scientific objects');
+    }
+    if (['expects', 'hasStep'].includes(body.predicate)) {
+      const subject = bodies.get(body.subject?.ref), object = bodies.get(body.object?.ref);
+      if (subject && !['procedure', 'procedure-step'].includes(subject.role)) fail(`${body.predicate} subject must be a prospective procedure`);
+      if (body.predicate === 'expects' && object && object.prospective !== true) fail('expects must reference a prospective specification, never an actual generated object');
+      if (body.predicate === 'hasStep' && object && object.role !== 'procedure-step') fail('hasStep must reference a scientific procedure step');
+    }
+    if (['revises', 'supersedes'].includes(body.predicate) && body.subject?.recordType !== body.object?.recordType) fail('revision endpoints must have the same primitive');
+    validateExactReference(body.attributedTo, descriptors, fail, 'attributedTo');
+    const authorType = body.attributedTo?.artifactDigest ? body.attributedTo.recordType : descriptors.get(body.attributedTo?.ref)?.recordType;
+    if (authorType !== CAP_RECORD_TYPE.agent) fail('relation attributedTo must reference an Agent');
+    if (!Array.isArray(body.sources)) fail('relation requires provenance sources array');
+    for (const source of body.sources ?? []) validateExactReference(source, descriptors, fail, 'source');
+  }
+}
+
+function validateExactReference(reference, descriptors, fail, label) {
+  if (!reference?.ref || !digestPattern.test(reference?.digest) || !Object.values(CAP_RECORD_TYPE).includes(reference?.recordType)) {
+    fail(`${label} requires exact ref, digest and recordType`); return;
+  }
+  if (reference.artifactDigest) {
+    if (!digestPattern.test(reference.artifactDigest)) fail(`${label} has invalid artifactDigest`);
+    return; // Dependency authenticity is unknown until separately resolved.
+  }
+  const local = descriptors.get(reference.ref);
+  if (!local || local.digest !== reference.digest || local.recordType !== reference.recordType) fail(`${label} does not bind a local record version`);
+}