@citeark/agent 0.3.20

package/src/cap/v2/read.mjs

@@ -0,0 +1,41 @@
+import { scientificProjections } from '../../graph/model.mjs';
+import { mkdir, readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { verifyCapArchive } from './archive.mjs';
+import { CAP_PROFILE, CAP_RECORD_TYPE } from './core.mjs';
+import { captureProcess } from '../../process.mjs';
+
+/** Read authenticated scientific bytes without imposing a registry's admission policy. */
+export async function readCapArchive(archivePath, directory, options = {}) {
+  const verification = await verifyCapArchive(archivePath, options);
+  if (!verification.valid) throw Error(verification.issues.join('; '));
+  const attestation = verification.attestations.find(item => item.signatureValid && item.subjectValid);
+  if (!attestation) throw Error('CAP 缺少有效签名');
+  await mkdir(directory, { recursive: true });
+  if ((await readdir(directory)).length) throw Error('CAP 读取目录必须为空');
+  const extracted = await captureProcess('tar', ['-xzf', path.resolve(archivePath), '-C', directory]);
+  if (extracted.code) throw Error('无法解包已验证的 CAP');
+  const graphRecords = [];
+  // Large plans can contain tens of thousands of records. Keep descriptors and
+  // parsed records in manifest order without opening every file at once.
+  for (let offset = 0; offset < verification.manifest.records.length; offset += 32) {
+    const batch = verification.manifest.records.slice(offset, offset + 32);
+    const loaded = await Promise.allSettled(batch.map(descriptor =>
+      readFile(path.join(directory, descriptor.path), 'utf8').then(JSON.parse)));
+    const failed = loaded.find(result => result.status === 'rejected');
+    if (failed) throw failed.reason;
+    graphRecords.push(...loaded.map(result => result.value));
+  }
+  const records = scientificProjections(graphRecords);
+  const profiles = verification.manifest.profiles;
+  const kind = profiles.includes(CAP_PROFILE.reproduction) ? 'reproduction'
+    : profiles.includes(CAP_PROFILE.researchPlan) ? 'research-plan'
+      : profiles.includes(CAP_PROFILE.researchCompilation) ? 'research-compilation' : profiles.includes(CAP_PROFILE.computationalRun) ? 'computational-run' : 'research-graph';
+  return { ...verification, kind, records, graphRecords, signerDigest: attestation.publicKeyDigest,
+    directory, attestation };
+}
+
+export async function readCapBlob(artifact, role) {
+  const descriptor = artifact.manifest.blobs.find(blob => blob.roles.includes(role) && blob.availability === 'embedded');
+  return descriptor ? JSON.parse(await readFile(path.join(artifact.directory, descriptor.path), 'utf8')) : null;
+}

package/src/cap/v2/reassessment-artifact.mjs

@@ -0,0 +1,383 @@
+import { measurementAssessmentRecords } from './measurement-assessment-records.mjs';
+import { CAP_RECORD_ROLE } from '../../graph/model.mjs';
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { sha256Value } from "../../util.mjs";
+import {
+  attachCapAttestation,
+  signCapArtifact,
+} from "./attestation.mjs";
+import {
+  CAP_PROFILE,
+  CAP_RECORD_TYPE,
+  assembleCapDirectory,
+} from "./core.mjs";
+import { canonicalJsonBytes } from "./canonical-json.mjs";
+import {
+  capActorRecord,
+  capRecordId,
+} from "./research-records.mjs";
+import { verifyCapDirectory } from "./verify.mjs";
+
+/**
+ * Create a new signed Assessment over an existing immutable Execution and its
+ * Evidence. No experiment command is rerun and no Evidence bytes are changed.
+ */
+export async function assembleReassessmentCap({
+  sourceDirectory,
+  directory,
+  scientificAssessor,
+  recoverEvidenceContext,
+  signingKeyPath,
+  processingBinding,
+  assessedAt = new Date().toISOString(),
+  assessmentId: selectedAssessmentId,
+}) {
+  if (typeof scientificAssessor !== "function") {
+    throw new Error("CAP reassessment requires an independent scientific assessor");
+  }
+  const sourceVerification = await verifyCapDirectory(sourceDirectory);
+  if (!sourceVerification.valid) {
+    throw new Error(`Source CAP failed verification:\n- ${sourceVerification.issues.join("\n- ")}`);
+  }
+  const sourceManifest = sourceVerification.manifest;
+  const descriptors = sourceManifest.records;
+  const bodies = await Promise.all(descriptors.map(async (descriptor) => ({
+    descriptor,
+    value: JSON.parse(await readFile(path.join(sourceDirectory, descriptor.path), "utf8")),
+  })));
+  const primaryIds = sourceManifest.roots.filter(root => root.role === 'primaryAssessment').map(root => root.ref);
+  const selectedId = selectedAssessmentId ?? (primaryIds.length === 1 ? primaryIds[0] : null);
+  const oldAssessmentEntry = bodies.find(entry => entry.value.id === selectedId && entry.value.role === 'assessment');
+  if (!oldAssessmentEntry) throw Error('Select an exact assessmentId when the source has multiple assessment roots');
+  const bound = (reference, role) => {
+    const entry = bodies.find(entry => entry.value.id === reference?.ref && entry.value.role === role);
+    if (!entry) throw Error(`Reassessment requires a locally materialized ${role}`);
+    return entry;
+  };
+  const claimEntry = bound(oldAssessmentEntry.value.claim, 'claim');
+  const experimentEntry = bound(oldAssessmentEntry.value.experiment, 'procedure');
+  const executionEntry = bound(oldAssessmentEntry.value.execution, 'execution');
+  const oldAssessment = oldAssessmentEntry.value;
+  const oldComparisons = Array.isArray(oldAssessment.method?.comparisons)
+    ? oldAssessment.method.comparisons
+    : [];
+  if (!oldComparisons.length) throw new Error("Source Assessment has no protocol-bound measurement comparisons");
+
+  const runnerAudit = await retainedRunnerAudit(sourceDirectory, sourceManifest, executionEntry.value);
+  const previousContext = await retainedEvidenceContext(sourceDirectory, sourceManifest, oldAssessment);
+  const evidenceContext = recoverEvidenceContext
+    ? await recoverEvidenceContext({ claim: claimEntry.value, experiment: experimentEntry.value,
+        execution: executionEntry.value, runnerAudit, previousContext }) ?? previousContext
+    : previousContext;
+  // Supplement immutable evidence; never replace a previously bound byte identity.
+  if (evidenceContext && previousContext && evidenceContext !== previousContext) {
+    for (const old of previousContext.files ?? []) {
+      const next = evidenceContext.files?.find(f => f.path === old.path);
+      if (next && next.digest !== old.digest) throw new Error(`Recovered evidence changed: ${old.path}`);
+    }
+  }
+  const contextBytes = evidenceContext ? canonicalJsonBytes(evidenceContext) : null;
+  const contextDigest = contextBytes ? `sha256:${sha256Bytes(contextBytes)}` : null;
+  const modelResult = await scientificAssessor({
+    claim: {
+      statement: claimEntry.value.statement?.value ?? "",
+      reportedMeasurements: claimEntry.value.citeark?.reportedMeasurements ?? [],
+    },
+    contract: reassessmentContract(claimEntry.value, experimentEntry.value, oldAssessment),
+    comparisons: oldComparisons.map(modelComparison),
+    runnerAudit,
+    evidenceContext,
+    result: {
+      execution: {
+        status: executionEntry.value.citeark?.outcome?.status ?? executionEntry.value.status,
+      },
+      limitations: stringArray(executionEntry.value.citeark?.limitations),
+      workloadCompletion: executionEntry.value.citeark?.workloadCompletion ?? null,
+    },
+  });
+  if (modelResult?.status !== "completed") {
+    throw new Error([
+      modelResult?.error?.message ?? "Independent scientific reassessment did not complete",
+      modelResult?.error?.detail,
+    ].filter(Boolean).join("："));
+  }
+
+  const assessment = reassessmentBody({
+    modelResult,
+    oldAssessment,
+    oldComparisons,
+    assessedAt,
+  });
+  const assessorId = capRecordId(
+    "actor",
+    `${assessment.assessor.kind}:${assessment.assessor.provider}:${assessment.assessor.name}:${assessment.assessor.rubricVersion}`,
+  );
+  const assessmentId = capRecordId(
+    "assessment",
+    `${executionEntry.value.id}:${assessment.assessmentDigest}`,
+  );
+  // The same assessor identity must retain its already materialized bytes; otherwise
+  // copied exact provenance edges would point at a rewritten participant.
+  const assessorRecord = bodies.find(({ value }) => value.id === assessorId && value.role === 'agent')?.value ?? capActorRecord(
+    assessorId,
+    assessment.assessor.name,
+    "model",
+    assessment.assessor.model ?? assessment.assessor.rubricVersion,
+  );
+  const newAssessmentRecord = {
+    ...oldAssessment,
+    id: assessmentId,
+    method: {
+      ...oldAssessment.method,
+      type: "QualitativeReview",
+      comparisons: assessment.measurementAssessments.map((item) => ({
+        measurementId: item.measurementId,
+        verdict: item.verdict,
+        verificationStatus: item.verificationStatus,
+        reason: item.reason,
+        ...(oldComparisons.find(
+          (candidate) => candidate.measurementId === item.measurementId,
+        )?.comparison
+          ? {
+              comparison: oldComparisons.find(
+                (candidate) => candidate.measurementId === item.measurementId,
+              ).comparison,
+            }
+          : {}),
+      })),
+    },
+    conclusion: assessment.verdict,
+    limitations: assessment.limitations,
+    performedBy: { ref: assessorId },
+    createdAt: assessedAt,
+    citeark: {
+      verificationStatus: assessment.verificationStatus,
+      integrityStatus: oldAssessment.citeark?.integrityStatus ?? "passed",
+      reason: assessment.reason,
+      confidence: assessment.confidence,
+      protocolComparability: assessment.protocolComparability,
+      ...(assessment.executionEvidence ? { executionEvidence: assessment.executionEvidence } : {}),
+      claimCoverage: oldAssessment.citeark?.claimCoverage ?? "complete",
+      uncoveredMeasurementIds: oldAssessment.citeark?.uncoveredMeasurementIds ?? [],
+      assessor: assessment.assessor,
+      ...(contextDigest ? { evidenceContextBlobDigest: contextDigest } : {}),
+      evidenceReads: modelResult.evidenceReads ?? [],
+      assessmentUsage: assessment.usage,
+      measurementAssessments: assessment.measurementAssessments,
+      outputAssessments: oldAssessment.citeark?.outputAssessments ?? [],
+      diagnosis: null,
+    },
+  };
+  const evidenceByMeasurement = new Map(bodies.filter(({ value }) => value.role === 'observation'
+    && value.basis === 'observed' && value.measurement?.measurementId).map(({ value }) => [value.measurement.measurementId, value.id]));
+  const componentAssessments = measurementAssessmentRecords({ assessment, parent: newAssessmentRecord,
+    identity: `${executionEntry.value.id}:${assessment.assessmentDigest}`, evidenceByMeasurement });
+  newAssessmentRecord.componentAssessments = componentAssessments.map(item => ({ ref: item.id }));
+  const records = [
+    ...bodies
+      .filter(({value}) => value.id !== oldAssessment.id && value.id !== assessorId
+        && (value.type !== CAP_RECORD_TYPE.relation || ![value.subject, value.object, ...(value.sources ?? [])].some(reference => reference?.ref === oldAssessment.id)))
+      .map((entry) => entry.value),
+    assessorRecord,
+    newAssessmentRecord,
+    ...componentAssessments,
+    { $schema: 'https://citeark.com/schemas/cap/v2/relation.schema.json',
+      id: capRecordId('relation', `${assessmentId}:supersedes:${oldAssessment.id}`), type: CAP_RECORD_TYPE.relation, role: 'provenance',
+      predicate: 'supersedes', subject: {ref: assessmentId},
+      object: {ref: oldAssessment.id, digest: oldAssessmentEntry.descriptor.digest, recordType: CAP_RECORD_TYPE.assertion, artifactDigest: sourceVerification.artifactDigest},
+      attributedTo: {ref: assessorId}, basis: 'declared', sources: [],
+    },
+  ];
+  for (const component of componentAssessments) {
+    const previous = bodies.find(({ value }) => oldAssessment.componentAssessments?.some(ref => ref.ref === value.id)
+      && value.citeark?.measurementId === component.citeark.measurementId);
+    if (previous) records.push({ $schema: 'https://citeark.com/schemas/cap/v2/relation.schema.json',
+      id: capRecordId('relation', `${component.id}:supersedes:${previous.value.id}`), type: CAP_RECORD_TYPE.relation, role: 'provenance',
+      predicate: 'supersedes', subject: { ref: component.id }, object: { ref: previous.value.id },
+      attributedTo: { ref: assessorId }, basis: 'declared', sources: [] });
+  }
+  const blobs = await Promise.all(sourceManifest.blobs.map(async (blob) => ({
+    id: blob.id,
+    roles: blob.roles,
+    mediaType: blob.mediaType,
+    availability: blob.availability,
+    digest: blob.digest,
+    size: blob.size,
+    ...(blob.availability === "embedded"
+      ? { bytes: await readFile(path.join(sourceDirectory, blob.path)) }
+      : {}),
+    ...(blob.rights ? { rights: blob.rights } : {}),
+    ...(blob.accessPolicy ? { accessPolicy: blob.accessPolicy } : {}),
+  })));
+  if (contextBytes && !blobs.some(b => b.digest === contextDigest)) blobs.push({
+    id: capRecordId("blob", `${executionEntry.value.id}:assessment-context:${contextDigest}`),
+    roles: ["assessment-evidence-context"], mediaType: "application/json", bytes: contextBytes,
+    rights: { statement: "Recovered original execution evidence; original source rights remain unchanged." },
+  });
+  const roots = sourceManifest.roots.map((root) => ({
+    role: root.role,
+    ref: root.ref === oldAssessment.id ? assessmentId : root.ref,
+  }));
+  const built = await assembleCapDirectory({
+    directory,
+    artifact: {
+      id: capRecordId("artifact", `${sourceVerification.artifactDigest}:${assessment.assessmentDigest}`),
+      createdAt: assessedAt,
+      createdBy: sourceManifest.artifact.createdBy.ref,
+    },
+    profiles: sourceManifest.profiles.filter((profile) => profile !== CAP_PROFILE.core),
+    roots,
+    records,
+    blobs,
+    relations: [
+      ...sourceManifest.relations.filter((relation) => relation.relationship !== "supersedes"),
+      {
+        relationship: "supersedes",
+        artifactDigest: sourceVerification.artifactDigest,
+        recordDigest: oldAssessmentEntry.descriptor.digest,
+        summary: "Reassesses the same immutable Execution and Evidence with the current scientific assessment rubric.",
+      },
+    ],
+  });
+  await mkdir(path.join(directory, "projections", "citeark"), { recursive: true });
+  await writeFile(
+    path.join(directory, "projections", "citeark", "assessment.json"),
+    canonicalJsonBytes(newAssessmentRecord),
+  );
+  if (sourceManifest.profiles.includes(CAP_PROFILE.publicBundle)) {
+    await writeFile(
+      path.join(directory, "ro-crate-metadata.json"),
+      `${JSON.stringify({
+        "@context": "https://w3id.org/ro/crate/1.3/context",
+        "@graph": [
+          { "@id": "ro-crate-metadata.json", "@type": "CreativeWork", about: { "@id": "./" } },
+          {
+            "@id": "./",
+            "@type": "Dataset",
+            identifier: built.artifactDigest,
+            hasPart: built.manifest.records.map((record) => ({ "@id": record.path })),
+          },
+        ],
+      }, null, 2)}\n`,
+    );
+  }
+  const attestation = await signCapArtifact({
+    artifactDigest: built.artifactDigest,
+    actor: { ref: sourceManifest.artifact.createdBy.ref },
+    role: "artifactAssembler",
+    createdAt: assessedAt,
+    signingKeyPath,
+    processingBinding,
+  });
+  const attachedAttestation = await attachCapAttestation({ directory, attestation });
+  const verification = await verifyCapDirectory(directory);
+  if (!verification.valid) {
+    throw new Error(`Reassessment CAP failed self-verification:\n- ${verification.issues.join("\n- ")}`);
+  }
+  return {
+    ...built,
+    verification,
+    attestation: attachedAttestation,
+    assessment,
+    supersedes: {
+      artifactDigest: sourceVerification.artifactDigest,
+      assessmentDigest: oldAssessmentEntry.descriptor.digest,
+    },
+  };
+}
+
+function reassessmentContract(claim, experiment, oldAssessment) {
+  const executionPlan = experiment.citeark?.executionPlan;
+  return {
+    ...(executionPlan ? { executionPlan } : {}),
+    claim: { text: claim.statement?.value ?? "", source: claim.source ?? null },
+    ...(experiment.citeark?.reproductionScope ? { reproductionScope: experiment.citeark.reproductionScope, requiredReproductionScope: experiment.citeark.requiredReproductionScope } : {}),
+    reproductionLevel: experiment.evaluationPlan?.reproductionLevel
+      ?? experiment.citeark?.reproductionLevel
+      ?? null,
+    reconstructionFidelity: experiment.evaluationPlan?.reconstructionFidelity
+      ?? experiment.citeark?.reconstructionFidelity
+      ?? "faithful",
+    repository: {
+      implementationOrigin: experiment.citeark?.implementationOrigin ?? "official",
+    },
+    protocol: executionPlan?.plan.protocol ?? experiment.citeark?.protocol ?? experiment.publicContract ?? {},
+    measurements: (executionPlan?.plan.measurements ?? experiment.citeark?.measurements ?? experiment.publicContract?.measurements ?? []).map((measurement) => ({
+      ...measurement,
+      measurementId: measurement.measurementId ?? measurement.reportedMeasurementId ?? measurement.id,
+    })),
+    research: {
+      claimCoverage: oldAssessment.citeark?.claimCoverage ?? "complete",
+      measurementIds: (oldAssessment.method?.comparisons ?? []).map((item) => item.measurementId),
+      uncoveredMeasurementIds: oldAssessment.citeark?.uncoveredMeasurementIds ?? [],
+    },
+  };
+}
+
+async function retainedRunnerAudit(directory, manifest, execution) {
+  const digest = execution.citeark?.commandRecordsBlobDigest;
+  const blob = manifest.blobs.find((item) => item.digest === digest && item.availability === "embedded");
+  if (!blob) return null;
+  // The source CAP verifier already checked the content-addressed blob.
+  const commandRecords = (await readFile(path.join(directory, blob.path), "utf8"))
+    .split(/\r?\n/).filter((line) => line.trim()).map((line) => JSON.parse(line));
+  return { audit: execution.citeark?.audit ?? null, commandRecords };
+}
+
+async function retainedEvidenceContext(directory, manifest, assessment) {
+  const digest = assessment.citeark?.evidenceContextBlobDigest;
+  const blob = manifest.blobs.find((item) => item.digest === digest && item.availability === "embedded");
+  if (!blob) return undefined;
+  // Source CAP verification binds these exact bytes; legacy CAPs may lack it.
+  return JSON.parse(await readFile(path.join(directory, blob.path), "utf8"));
+}
+
+function modelComparison(item) {
+  return {
+    measurementId: item.measurementId,
+    comparison: Object.fromEntries(Object.entries(item.comparison ?? {}).map(([key, value]) => [
+      key,
+      value && typeof value === "object" && !Array.isArray(value) && "decimal" in value
+        ? Number(value.decimal)
+        : value,
+    ])),
+  };
+}
+
+function reassessmentBody({ modelResult, oldAssessment, oldComparisons, assessedAt }) {
+  const byMeasurementId = new Map(
+    modelResult.assessment.measurementAssessments.map((item) => [item.measurementId, item]),
+  );
+  const measurementAssessments = oldComparisons.map((comparison) => ({
+    ...byMeasurementId.get(comparison.measurementId),
+    comparison: modelComparison(comparison).comparison,
+  }));
+  const body = {
+    schemaVersion: "1.0",
+    kind: "citeark.claim-reassessment",
+    verdict: modelResult.assessment.conclusion,
+    verificationStatus: modelResult.assessment.verificationStatus,
+    confidence: modelResult.assessment.confidence,
+    protocolComparability: modelResult.assessment.protocolComparability,
+    ...(modelResult.assessment.executionEvidence ? { executionEvidence: modelResult.assessment.executionEvidence } : {}),
+    reason: modelResult.assessment.reason,
+    limitations: modelResult.assessment.limitations,
+    measurementAssessments,
+    integrityStatus: oldAssessment.citeark?.integrityStatus ?? "passed",
+    assessedAt,
+    assessor: modelResult.assessor,
+    usage: modelResult.usage,
+  };
+  return { ...body, assessmentDigest: `sha256:${sha256Value(body)}` };
+}
+
+function stringArray(value) {
+  return Array.isArray(value)
+    ? value.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim())
+    : [];
+}
+
+function sha256Bytes(bytes) { return createHash("sha256").update(bytes).digest("hex"); }

package/src/cap/v2/research-artifact.mjs

@@ -0,0 +1,231 @@
+import { researchMapRecords, bindResearchReading, bindResearchIntent } from './research-map-records.mjs';
+import { researchObjectRecords, reportedObservationRecords } from './research-object-records.mjs';
+import { researchPublicContract } from "../../contracts/public-contract.mjs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { attachCapAttestation, signCapArtifact } from "./attestation.mjs";
+import { canonicalJsonBytes } from "./canonical-json.mjs";
+import {
+  CAP_PROFILE,
+  CAP_RECORD_TYPE,
+  assembleCapDirectory,
+} from "./core.mjs";
+import {
+  CAP_SCHEMA,
+  capActorRecord,
+  capClaimRecord,
+  capHypothesisRecords,
+  capDecimal,
+  capRecordId,
+  capSourceWorkRecord,
+} from "./research-records.mjs";
+import { verifyCapDirectory } from "./verify.mjs";
+import { CiteArkError } from "../../util.mjs";
+
+/** Build an immutable scientific plan from one or more compiler outputs. */
+export async function assembleResearchPlanCap({
+  directory,
+  research,
+  compilerRunId,
+  planner,
+  plannerRunId = compilerRunId,
+  sourceCompilationDigests = [],
+  sourceArtifactDigests = [],
+  createdAt,
+  signingKeyPath,
+  processingBinding,
+}) {
+  if (planner && (typeof planner.id !== "string" || !planner.id || typeof planner.name !== "string" || !planner.name)) {
+    throw new CiteArkError("Research Plan planner requires id and name");
+  }
+  if (typeof plannerRunId !== "string" || !plannerRunId) {
+    throw new CiteArkError("Research Plan requires plannerRunId");
+  }
+  const timestamp = isoDate(createdAt ?? research.provenance?.compiledAt);
+  const actorId = planner
+    ? capRecordId("actor", `research-planner:${planner.id}:${planner.version ?? "unversioned"}`)
+    : capRecordId("actor", `research-compiler:${compilerRunId}`);
+  const sourceWorkId = capRecordId("work", research.work.id);
+  const claimIdByLocalId = new Map(
+    research.claims.map((claim) => [claim.id, capRecordId("claim", `${research.work.id}:${claim.id}`)]),
+  );
+  const experimentIdByLocalId = new Map(
+    research.experiments.map((experiment) => [
+      experiment.id,
+      capRecordId("experiment", `${research.work.id}:${experiment.id}`),
+    ]),
+  );
+  const objectGraph = researchObjectRecords({ research, sourceWorkId, actorId });
+  const { records: reportedEvidence, idsByClaim: reportedEvidenceIdsByClaim } = reportedObservationRecords({ research, sourceWorkId, objectIds: objectGraph.objectIds });
+
+  const sourceWork = capSourceWorkRecord({
+    research,
+    id: sourceWorkId,
+    processingBinding,
+  });
+  const reading = bindResearchReading(research, objectGraph, sourceWorkId);
+  if (reading) sourceWork.citeark.reading = reading;
+  const claims = research.claims.map((claim) => capClaimRecord({
+    claim,
+    id: claimIdByLocalId.get(claim.id),
+    sourceWorkId,
+    actorId,
+    reportedEvidenceIds: reportedEvidenceIdsByClaim.get(claim.id),
+    objectReferences: (claim.objectIds ?? []).map(id => ({ ref: objectGraph.objectIds.get(id) })),
+  }));
+  const experiments = research.experiments.map((experiment) => ({
+    $schema: CAP_SCHEMA.experiment,
+    id: experimentIdByLocalId.get(experiment.id),
+    type: CAP_RECORD_TYPE.entity, role: "procedure",
+    ...((experiment.observationTargets ?? []).length ? {
+      objects: [...new Set(experiment.observationTargets.map(target => target.observationId))]
+        .map(id => ({ ref: requiredId(objectGraph.objectIds, id, "Source observation") })),
+    } : {}),
+    inputs: (objectGraph.inputIdsByExperiment.get(experiment.id) ?? []).map(id => ({ record: { ref: id }, role: 'scientific-input', basis: 'declared' })),
+    steps: (objectGraph.stepIdsByExperiment.get(experiment.id) ?? []).map(ref => ({ ref })),
+    tests: experiment.claimIds.map((claimId) => ({ ref: requiredId(claimIdByLocalId, claimId, "Claim") })),
+    publicContract: researchPublicContract(experiment),
+    evaluationPlan: {
+      title: experiment.title,
+      reproductionLevel: experiment.reproductionLevel,
+      ...(experiment.reproductionScope ? { reproductionScope: experiment.reproductionScope, requiredReproductionScope: experiment.requiredReproductionScope } : {}),
+      reconstructionFidelity: experiment.reconstructionFidelity ?? null,
+      instructions: experiment.protocol.instructions ?? null,
+      state: "planned",
+    },
+    citeark: {
+      ...(experiment.researchIntent ? { researchIntent: bindResearchIntent(experiment, research, objectGraph, sourceWorkId) } : {}),
+      localId: experiment.id,
+      versionId: experiment.versionId,
+      title: experiment.title,
+      claimIds: experiment.claimIds,
+      reproductionLevel: experiment.reproductionLevel,
+      ...(experiment.reproductionScope ? { reproductionScope: experiment.reproductionScope, requiredReproductionScope: experiment.requiredReproductionScope } : {}),
+      implementationOrigin: experiment.implementationOrigin
+        ?? experiment.repository?.implementationOrigin
+        ?? "official",
+      reconstructionFidelity: experiment.reconstructionFidelity ?? null,
+      repository: experiment.repository,
+      protocol: experiment.protocol,
+      measurements: experiment.measurements ?? [],
+      ...(experiment.observationTargets !== undefined ? { observationTargets: experiment.observationTargets } : {}),
+      compute: experiment.compute ?? null,
+      environment: experiment.environment ?? null,
+    },
+  }));
+  const actor = {
+    ...capActorRecord(
+      actorId,
+      planner?.name ?? "CiteArk Research Compiler",
+      planner?.kind ?? "agent",
+      planner?.version ?? research.provenance?.compiler,
+    ),
+    ...(planner?.identity ? { identity: structuredClone(planner.identity) } : {}),
+    ...(planner ? { planner: { id: planner.id } } : {}),
+    citeark: planner ? { plannerRunId } : { compilerRunId },
+  };
+  const built = await assembleCapDirectory({
+    directory,
+    artifact: {
+      id: capRecordId("artifact", `research-plan:${plannerRunId}`),
+      createdAt: timestamp,
+      createdBy: actorId,
+    },
+    profiles: [CAP_PROFILE.researchPlan, CAP_PROFILE.publicBundle],
+    roots: [
+      { role: "primarySourceWork", ref: sourceWorkId },
+      ...claims.map((claim) => ({ role: "plannedClaim", ref: claim.id })),
+      ...experiments.map((experiment) => ({ role: "plannedExperiment", ref: experiment.id })),
+    ],
+    records: [...researchMapRecords({ research: research, objectGraph, sourceWorkId, actorId }), actor, sourceWork, ...objectGraph.records, ...claims, ...experiments, ...reportedEvidence,
+      ...capHypothesisRecords({ research, sourceWorkId, actorId, objectIds: objectGraph.objectIds })],
+    blobs: [{ id: capRecordId('research-plan-input', plannerRunId), roles: ['research-plan-input'],
+      mediaType: 'application/json', bytes: canonicalJsonBytes(research),
+      rights: { statement: 'Research interpretation and plan; referenced materials retain their own rights.' } }],
+    relations: [...new Set([...sourceCompilationDigests, ...sourceArtifactDigests])].map((artifactDigest) => ({
+      relationship: "derivedFrom",
+      artifactDigest,
+      summary: "Research Plan informed by prior source interpretations or research artifacts.",
+    })),
+  });
+  await writeResearchAttachments({ directory, built, research });
+  const attestation = await signCapArtifact({
+    artifactDigest: built.artifactDigest,
+    actor: { ref: actorId },
+    role: "researchPlanAssembler",
+    createdAt: timestamp,
+    signingKeyPath,
+    processingBinding,
+  });
+  const attachedAttestation = await attachCapAttestation({ directory, attestation });
+  const verification = await verifyCapDirectory(directory);
+  if (!verification.valid) {
+    throw new CiteArkError(`Research Plan CAP 2.0 failed self-verification:\n- ${verification.issues.join("\n- ")}`);
+  }
+  return {
+    ...built,
+    verification,
+    attestation: attachedAttestation,
+    recordIds: {
+      actor: actorId,
+      sourceWork: sourceWorkId,
+      claims: Object.fromEntries(claimIdByLocalId),
+      experiments: Object.fromEntries(experimentIdByLocalId),
+      researchObjects: Object.fromEntries(objectGraph.objectIds),
+    },
+  };
+}
+
+async function writeResearchAttachments({ directory, built, research }) {
+  await Promise.all([
+    mkdir(path.join(directory, "preview"), { recursive: true }),
+    mkdir(path.join(directory, "projections", "citeark"), { recursive: true }),
+  ]);
+  const crate = {
+    "@context": "https://w3id.org/ro/crate/1.3/context",
+    "@graph": [
+      { "@id": "ro-crate-metadata.json", "@type": "CreativeWork", about: { "@id": "./" } },
+      {
+        "@id": "./",
+        "@type": "Dataset",
+        name: research.work.title,
+        identifier: built.artifactDigest,
+        hasPart: built.manifest.records.map((record) => ({ "@id": record.path })),
+      },
+      ...built.manifest.records.map((record) => ({
+        "@id": record.path,
+        "@type": "CreativeWork",
+        identifier: record.digest,
+        encodingFormat: record.mediaType,
+      })),
+    ],
+  };
+  const planned = research.claims.filter((claim) => claim.reproduction?.status === "planned").length;
+  const blocked = research.claims.filter((claim) => claim.reproduction?.status === "blocked").length;
+  const contextual = research.claims.length - planned - blocked;
+  const significance = research.work.significance
+    ? `## What this means\n\n${research.work.significance}\n\n> This is an AI-generated plain-language interpretation, not reproduction evidence or a scientific Assessment.\n\n`
+    : "";
+  const readme = `# ${research.work.title}\n\n${research.work.abstract}\n\n${significance}## Research plan snapshot\n\n- Claims: ${research.claims.length}\n- Planned reproductions: ${planned}\n- Blocked claims: ${blocked}\n- Contextual claims: ${contextual}\n- Planned experiments: ${research.experiments.length}\n\nThis document is a derived preview. Canonical scientific content is stored in CAP Records.\n`;
+  await Promise.all([
+    writeFile(path.join(directory, "ro-crate-metadata.json"), `${JSON.stringify(crate, null, 2)}\n`),
+    writeFile(path.join(directory, "preview", "README.md"), readme),
+    writeFile(
+      path.join(directory, "projections", "citeark", "research-plan.json"),
+      canonicalJsonBytes(research),
+    ),
+  ]);
+}
+
+function requiredId(values, key, label) {
+  const value = values.get(key);
+  if (!value) throw new CiteArkError(`${label} reference is missing from the research plan: ${key}`);
+  return value;
+}
+
+function isoDate(value) {
+  const date = new Date(value ?? Date.now());
+  if (!Number.isFinite(date.getTime())) throw new CiteArkError(`CAP timestamp is invalid: ${String(value)}`);
+  return date.toISOString();
+}