@citeark/agent 0.3.20

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

@@ -0,0 +1,240 @@
+import { researchMapRecords, bindResearchReading, bindResearchIntent } from './research-map-records.mjs';
+import { researchObjectRecords, reportedObservationRecords } from './research-object-records.mjs';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { attachCapAttestation, signCapArtifact } from "./attestation.mjs";
+import { verifyCapArchive } from "./archive.mjs";
+import { canonicalJsonBytes, parseCanonicalJson, sha256Bytes } from "./canonical-json.mjs";
+import {
+  CAP_PROFILE,
+  assembleCapDirectory,
+} from "./core.mjs";
+import {
+  capActorRecord,
+  capClaimRecord,
+  capHypothesisRecords,
+  capRecordId,
+  capSourceWorkRecord,
+} from "./research-records.mjs";
+import { verifyCapDirectory } from "./verify.mjs";
+import { captureProcess } from "../../process.mjs";
+import { CiteArkError } from "../../util.mjs";
+
+/**
+ * Turn one compiler's source-grounded inventory into a portable CAP Artifact.
+ * The compiler identity is supplied by the caller; CiteArk is not privileged.
+ */
+export async function assembleResearchCompilationCap({
+  directory,
+  inventory,
+  compiler,
+  runId,
+  createdAt,
+  signingKeyPath,
+  processingBinding,
+  nativeOutput = inventory,
+  nativeOutputBytes,
+  nativeOutputMediaType,
+}) {
+  if (inventory?.compilationStage !== "inventory") {
+    throw new CiteArkError("Research Compilation requires a source inventory, not an execution plan");
+  }
+  if (!Array.isArray(inventory.claims)) {
+    throw new CiteArkError("Research Compilation claims must be an array");
+  }
+  if (!compiler || typeof compiler !== "object" || Array.isArray(compiler)) {
+    throw new CiteArkError("Research Compilation requires compiler identity");
+  }
+  const compilerName = requiredText(compiler.name, "compiler.name");
+  const compilerId = requiredText(compiler.id, "compiler.id");
+  const compilationRunId = requiredText(runId, "runId");
+  const timestamp = isoDate(createdAt ?? inventory.provenance?.compiledAt);
+  const actorId = capRecordId(
+    "actor",
+    `research-compiler:${compilerId}:${compiler.version ?? "unversioned"}`,
+  );
+  const sourceWorkId = capRecordId("work", inventory.work.id);
+  const actor = {
+    ...capActorRecord(actorId, compilerName, compiler.kind ?? "agent", compiler.version),
+    ...(compiler.identity ? { identity: structuredClone(compiler.identity) } : {}),
+    compiler: {
+      id: compilerId,
+      ...(Array.isArray(compiler.capabilities)
+        ? { capabilities: [...new Set(compiler.capabilities)].sort() }
+        : {}),
+    },
+    citeark: { runId: compilationRunId },
+  };
+  const sourceWork = capSourceWorkRecord({
+    research: inventory,
+    id: sourceWorkId,
+    processingBinding,
+  });
+  const objectGraph = researchObjectRecords({ research: inventory, sourceWorkId, actorId });
+  const observations = reportedObservationRecords({ research: inventory, sourceWorkId, objectIds: objectGraph.objectIds });
+  const reading = bindResearchReading(inventory, objectGraph, sourceWorkId);
+  if (reading) sourceWork.citeark.reading = reading;
+  const claims = inventory.claims.map((claim) => capClaimRecord({
+    claim,
+    id: capRecordId("claim", `${inventory.work.id}:${claim.id}`),
+    sourceWorkId,
+    actorId,
+    reportedEvidenceIds: observations.idsByClaim.get(claim.id),
+    objectReferences: (claim.objectIds ?? []).map(id => ({ ref: objectGraph.objectIds.get(id) })),
+  }));
+  const inventoryBytes = canonicalJsonBytes(inventory);
+  const nativeBytes = nativeOutputBytes == null
+    ? canonicalJsonBytes(nativeOutput)
+    : Buffer.from(nativeOutputBytes);
+  const nativeMediaType = nativeOutputBytes == null
+    ? "application/json"
+    : requiredText(nativeOutputMediaType, "nativeOutputMediaType");
+  const sharedOutput = nativeMediaType === "application/json" && inventoryBytes.equals(nativeBytes);
+  const outputRights = {
+    statement: "Compiler-produced output; source materials retain their own rights.",
+  };
+  const built = await assembleCapDirectory({
+    directory,
+    artifact: {
+      id: capRecordId("artifact", `research-compilation:${compilerId}:${compilationRunId}`),
+      createdAt: timestamp,
+      createdBy: actorId,
+    },
+    profiles: [CAP_PROFILE.researchCompilation, CAP_PROFILE.publicBundle],
+    roots: [
+      { role: "primarySourceWork", ref: sourceWorkId },
+      ...claims.map((claim) => ({ role: "compiledClaim", ref: claim.id })),
+    ],
+    records: [...researchMapRecords({ research: inventory, objectGraph, sourceWorkId, actorId }), actor, sourceWork, ...objectGraph.records, ...claims, ...observations.records,
+      ...capHypothesisRecords({ research: inventory, sourceWorkId, actorId, objectIds: objectGraph.objectIds })],
+    blobs: sharedOutput
+      ? [{
+          id: capRecordId("compiler-output", `${compilerId}:${compilationRunId}`),
+          roles: ["compiler-output", "research-inventory"],
+          mediaType: nativeMediaType,
+          bytes: nativeBytes,
+          rights: outputRights,
+        }]
+      : [
+          {
+            id: capRecordId("compiler-output", `${compilerId}:${compilationRunId}`),
+            roles: ["compiler-output"],
+            mediaType: nativeMediaType,
+            bytes: nativeBytes,
+            rights: outputRights,
+          },
+          {
+            id: capRecordId("research-inventory", `${compilerId}:${compilationRunId}`),
+            roles: ["research-inventory"],
+            mediaType: "application/json",
+            bytes: inventoryBytes,
+            rights: outputRights,
+          },
+        ],
+  });
+  await writeAttachments({ directory, built, inventory, compilerName });
+  const attestation = await signCapArtifact({
+    artifactDigest: built.artifactDigest,
+    actor: { ref: actorId },
+    role: "researchCompiler",
+    createdAt: timestamp,
+    signingKeyPath,
+    processingBinding,
+  });
+  const attachedAttestation = await attachCapAttestation({ directory, attestation });
+  const verification = await verifyCapDirectory(directory);
+  if (!verification.valid) {
+    throw new CiteArkError(`Research Compilation CAP 2.0 failed self-verification:\n- ${verification.issues.join("\n- ")}`);
+  }
+  return {
+    ...built,
+    verification,
+    attestation: attachedAttestation,
+    recordIds: {
+      actor: actorId,
+      sourceWork: sourceWorkId,
+      claims: claims.map((claim) => claim.id),
+      researchObjects: Object.fromEntries(objectGraph.objectIds),
+    },
+  };
+}
+
+/** Read the normalized planner handoff from a verified Compilation CAP file. */
+export async function loadResearchCompilationCap(archivePath) {
+  const source = path.resolve(archivePath);
+  const verification = await verifyCapArchive(source);
+  if (!verification.valid) {
+    throw new CiteArkError(`Research Compilation CAP verification failed:\n- ${verification.issues.join("\n- ")}`);
+  }
+  if (!verification.manifest.profiles.includes(CAP_PROFILE.researchCompilation)) {
+    throw new CiteArkError("CAP file does not declare the Research Compilation Profile");
+  }
+  const descriptor = verification.manifest.blobs.find((blob) =>
+    blob.roles.includes("research-inventory"),
+  );
+  if (!descriptor || descriptor.availability !== "embedded" || descriptor.mediaType !== "application/json") {
+    throw new CiteArkError("Research Compilation CAP requires an embedded JSON research-inventory Blob");
+  }
+  const temporary = await mkdtemp(path.join(os.tmpdir(), "citeark-compilation-input-"));
+  try {
+    const extraction = await captureProcess("tar", ["-xzf", source, "-C", temporary]);
+    if (extraction.code !== 0) throw new CiteArkError("Cannot extract verified Research Compilation CAP");
+    const bytes = await readFile(path.join(temporary, descriptor.path));
+    if (bytes.byteLength !== descriptor.size || sha256Bytes(bytes) !== descriptor.digest) {
+      throw new CiteArkError("Research Compilation inventory does not match its verified descriptor");
+    }
+    const inventory = parseCanonicalJson(bytes, "research-inventory Blob");
+    if (inventory?.compilationStage !== "inventory") {
+      throw new CiteArkError("Research Compilation inventory is not an inventory-stage handoff");
+    }
+    return {
+      inventory,
+      artifactDigest: verification.artifactDigest,
+      verification,
+    };
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+
+async function writeAttachments({ directory, built, inventory, compilerName }) {
+  await mkdir(path.join(directory, "preview"), { 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: inventory.work.title,
+        identifier: built.artifactDigest,
+        hasPart: [
+          ...built.manifest.records.map((record) => ({ "@id": record.path })),
+          ...built.manifest.blobs.filter((blob) => blob.path).map((blob) => ({ "@id": blob.path })),
+        ],
+      },
+    ],
+  };
+  const readme = `# ${inventory.work.title}\n\nCompiled by ${compilerName}.\n\n- Compiled claims: ${inventory.claims.length}\n- Artifact: ${built.artifactDigest}\n\nThis is a compiler interpretation of fixed sources. It is not execution evidence or a scientific assessment.\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),
+  ]);
+}
+
+function requiredText(value, label) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new CiteArkError(`${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+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();
+}

package/src/cap/v2/core.mjs

@@ -0,0 +1,282 @@
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  assertSha256Digest,
+  canonicalJson,
+  canonicalJsonBytes,
+  sha256Bytes,
+} from "./canonical-json.mjs";
+
+export const CAP_SPEC_VERSION = "2.0.0-alpha.2";
+export const CAP_READABLE_SPEC_VERSIONS = new Set(["2.0.0-alpha.1", CAP_SPEC_VERSION]);
+export const CAP_MANIFEST = "cap-manifest.json";
+export const CAP_MANIFEST_MEDIA_TYPE = "application/vnd.citeark.cap.manifest.v2+json";
+export const CAP_ARCHIVE_MEDIA_TYPE = "application/vnd.citeark.cap+tar+gzip;version=2";
+
+export const CAP_PROFILE = Object.freeze({
+  core: "https://citeark.com/cap/profiles/core/2.0",
+  researchCompilation: "https://citeark.com/cap/profiles/research-compilation/2.0",
+  researchPlan: "https://citeark.com/cap/profiles/research-plan/2.0",
+  computationalRun: "https://citeark.com/cap/profiles/computational-run/2.0",
+  reproduction: "https://citeark.com/cap/profiles/reproduction/2.0",
+  agentTrace: "https://citeark.com/cap/profiles/agent-trace/2.0",
+  publicBundle: "https://citeark.com/cap/profiles/public-bundle/2.0",
+  restrictedEvidence: "https://citeark.com/cap/profiles/restricted-evidence/2.0",
+});
+
+export { CAP_RECORD_TYPE, CAP_RECORD_ROLE } from '../../graph/model.mjs';
+import { CAP_RECORD_TYPE } from '../../graph/model.mjs';
+import { researchRelations, bindRelation } from '../../graph/research-relations.mjs';
+
+const CAP_RELATION = new Set([
+  "derivedFrom",
+  "revises",
+  "reproduces",
+  "extends",
+  "supersedes",
+  "refersTo",
+]);
+
+export async function assembleCapDirectory({
+  directory,
+  artifact,
+  profiles = [],
+  roots,
+  records,
+  blobs = [],
+  relations = [],
+}) {
+  await requireEmptyDirectory(directory);
+  const nodes = records.filter(entry => (entry.value ?? entry).type !== CAP_RECORD_TYPE.relation);
+  const normalizedRecords = await stageRecords(directory, nodes);
+  const recordById = new Map(normalizedRecords.map(item => [item.id, item]));
+  const creator = typeof artifact.createdBy === 'string' ? artifact.createdBy : artifact.createdBy?.ref;
+  const explicit = records.filter(entry => (entry.value ?? entry).type === CAP_RECORD_TYPE.relation).map(entry => entry.value ?? entry);
+  const generated = researchRelations(nodes.map(entry => entry.value ?? entry), creator);
+  const explicitIds = new Set(explicit.map(record => record.id));
+  const edges = [...explicit, ...generated.filter(record => !explicitIds.has(record.id))];
+  if (edges.length) {
+    const staged = await stageRecords(directory, edges.map(record => bindRelation(record, recordById)));
+    for (const edge of staged) {
+      if (recordById.has(edge.id)) throw Error(`Duplicate CAP Record id: ${edge.id}`);
+      recordById.set(edge.id, edge);
+    }
+    normalizedRecords.push(...staged);
+    normalizedRecords.sort((a, b) => compareText(a.id, b.id));
+  }
+  const normalizedBlobs = await stageBlobs(directory, blobs);
+  const allProfiles = [...new Set([CAP_PROFILE.core, ...profiles])].sort();
+  const manifest = {
+    $schema: "https://citeark.com/schemas/cap/v2/manifest.schema.json",
+    mediaType: CAP_MANIFEST_MEDIA_TYPE,
+    specVersion: CAP_SPEC_VERSION,
+    artifact: normalizeArtifact(artifact, recordById),
+    profiles: allProfiles,
+    roots: normalizeRoots(roots, recordById),
+    records: normalizedRecords,
+    blobs: normalizedBlobs,
+    relations: normalizeRelations(relations),
+  };
+  const manifestBytes = canonicalJsonBytes(manifest);
+  await writeFile(path.join(directory, CAP_MANIFEST), manifestBytes);
+  return {
+    directory,
+    manifest,
+    artifactDigest: sha256Bytes(manifestBytes),
+  };
+}
+
+export function capRecordReference(descriptor) {
+  return { ref: descriptor.id, digest: descriptor.digest };
+}
+
+export function capPolicyCommitment({ nonce, policy }) {
+  if (typeof nonce !== "string" || nonce.length < 22) {
+    throw new Error("CAP verification policy commitment requires a high-entropy nonce");
+  }
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new Error("CAP verification policy must be a JSON object");
+  }
+  return sha256Bytes(canonicalJsonBytes({
+    algorithm: "citeark-policy-commitment-v1",
+    nonce,
+    policy,
+  }));
+}
+
+export function safeCapPath(value) {
+  if (typeof value !== "string" || !value || value.includes("\\") || value.includes("\0")) return false;
+  if (value.startsWith("/") || value.endsWith("/") || value.includes("//")) return false;
+  const segments = value.split("/");
+  return segments.every((segment) => segment && segment !== "." && segment !== "..");
+}
+
+async function stageRecords(directory, records) {
+  if (!Array.isArray(records) || records.length === 0) {
+    throw new Error("CAP 2.0 requires at least one Record");
+  }
+  const descriptors = [];
+  const ids = new Set();
+  for (const entry of records) {
+    const value = entry?.value ?? entry;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("Each CAP Record must be a JSON object");
+    }
+    if (typeof value.id !== "string" || !value.id) throw new Error("Each CAP Record requires an id");
+    if (typeof value.type !== "string" || !value.type) throw new Error(`Record ${value.id} requires a type`);
+    if (ids.has(value.id)) throw new Error(`Duplicate CAP Record id: ${value.id}`);
+    ids.add(value.id);
+    const bytes = canonicalJsonBytes(value);
+    const digest = sha256Bytes(bytes);
+    const hex = digest.slice(7);
+    const recordPath = entry?.path ?? `records/sha256/${hex.slice(0, 2)}/${hex}.json`;
+    if (!safeCapPath(recordPath) || !recordPath.startsWith("records/")) {
+      throw new Error(`Unsafe CAP Record path: ${recordPath}`);
+    }
+    await mkdir(path.dirname(path.join(directory, recordPath)), { recursive: true });
+    await writeFile(path.join(directory, recordPath), bytes);
+    descriptors.push({
+      id: value.id,
+      recordType: value.type,
+      role: value.role,
+      mediaType: entry?.mediaType ?? "application/vnd.citeark.cap.record+json",
+      schema: entry?.schema ?? value.$schema ?? schemaForRecordType(value.type),
+      digest,
+      size: bytes.byteLength,
+      path: recordPath,
+    });
+  }
+  return descriptors.sort((left, right) => compareText(left.id, right.id));
+}
+
+async function stageBlobs(directory, blobs) {
+  const descriptors = [];
+  const ids = new Set();
+  const digests = new Set();
+  for (const entry of blobs) {
+    if (typeof entry?.id !== "string" || !entry.id) throw new Error("Each CAP Blob requires an id");
+    if (ids.has(entry.id)) throw new Error(`Duplicate CAP Blob id: ${entry.id}`);
+    ids.add(entry.id);
+    const availability = entry.availability ?? "embedded";
+    if (!new Set(["embedded", "external", "withheld"]).has(availability)) {
+      throw new Error(`Unsupported Blob availability: ${availability}`);
+    }
+    let digest;
+    let size;
+    let blobPath;
+    if (availability === "embedded") {
+      if (entry.bytes == null) throw new Error(`Embedded Blob ${entry.id} requires bytes`);
+      const bytes = Buffer.isBuffer(entry.bytes) ? entry.bytes : Buffer.from(entry.bytes);
+      digest = sha256Bytes(bytes);
+      size = bytes.byteLength;
+      if (entry.digest && entry.digest !== digest) throw new Error(`Blob ${entry.id} digest does not match its bytes`);
+      if (entry.size != null && entry.size !== size) throw new Error(`Blob ${entry.id} size does not match its bytes`);
+      const hex = digest.slice(7);
+      blobPath = entry.path ?? `blobs/sha256/${hex.slice(0, 2)}/${hex}`;
+      if (!safeCapPath(blobPath) || !blobPath.startsWith("blobs/")) {
+        throw new Error(`Unsafe CAP Blob path: ${blobPath}`);
+      }
+      await mkdir(path.dirname(path.join(directory, blobPath)), { recursive: true });
+      await writeFile(path.join(directory, blobPath), bytes);
+    } else {
+      digest = assertSha256Digest(entry.digest, `Blob ${entry.id} digest`);
+      if (!Number.isSafeInteger(entry.size) || entry.size < 0) {
+        throw new Error(`Blob ${entry.id} requires a non-negative integer size`);
+      }
+      size = entry.size;
+      if (entry.path != null) throw new Error(`${availability} Blob ${entry.id} must not declare a bundle path`);
+    }
+    if (digests.has(digest)) throw new Error(`Duplicate CAP Blob digest: ${digest}`);
+    digests.add(digest);
+    descriptors.push({
+      id: entry.id,
+      roles: [...new Set(entry.roles ?? [])].sort(),
+      mediaType: entry.mediaType ?? "application/octet-stream",
+      digest,
+      size,
+      availability,
+      ...(blobPath ? { path: blobPath } : {}),
+      ...(entry.rights ? { rights: entry.rights } : {}),
+      ...(entry.accessPolicy ? { accessPolicy: entry.accessPolicy } : {}),
+    });
+  }
+  return descriptors.sort((left, right) => compareText(left.digest, right.digest));
+}
+
+function normalizeArtifact(artifact, records) {
+  if (!artifact || typeof artifact !== "object") throw new Error("CAP Artifact metadata is required");
+  if (typeof artifact.createdAt !== "string" || !Number.isFinite(Date.parse(artifact.createdAt))) {
+    throw new Error("CAP Artifact createdAt must be an ISO date-time");
+  }
+  return {
+    ...(artifact.id ? { id: artifact.id } : {}),
+    createdAt: artifact.createdAt,
+    createdBy: resolveRecordReference(artifact.createdBy, records, "artifact.createdBy"),
+  };
+}
+
+function normalizeRoots(roots, records) {
+  if (!Array.isArray(roots) || roots.length === 0) throw new Error("CAP Artifact requires at least one root Record");
+  const output = roots.map((root, index) => ({
+    role: requiredText(root?.role, `roots[${index}].role`),
+    ...resolveRecordReference(root?.ref ?? root, records, `roots[${index}]`),
+  }));
+  return output.sort((left, right) => compareText(canonicalJson(left), canonicalJson(right)));
+}
+
+function normalizeRelations(relations) {
+  if (!Array.isArray(relations)) throw new Error("CAP Artifact relations must be an array");
+  return relations
+    .map((relation, index) => {
+      const artifactDigest = assertSha256Digest(
+        relation?.artifactDigest,
+        `relations[${index}].artifactDigest`,
+      );
+      const relationship = requiredText(relation.relationship, `relations[${index}].relationship`);
+      if (!CAP_RELATION.has(relationship)) throw new Error(`relations[${index}].relationship is unsupported`);
+      return {
+        relationship,
+        artifactDigest,
+        ...(relation.recordDigest
+          ? { recordDigest: assertSha256Digest(relation.recordDigest, `relations[${index}].recordDigest`) }
+          : {}),
+        ...(relation.summary ? { summary: relation.summary } : {}),
+      };
+    })
+    .sort((left, right) => compareText(canonicalJson(left), canonicalJson(right)));
+}
+
+function resolveRecordReference(input, records, label) {
+  const id = typeof input === "string" ? input : input?.ref;
+  if (typeof id !== "string" || !id) throw new Error(`${label} must reference a Record id`);
+  const descriptor = records.get(id);
+  if (!descriptor) throw new Error(`${label} references an unknown Record: ${id}`);
+  if (input?.digest && input.digest !== descriptor.digest) {
+    throw new Error(`${label} digest does not match Record ${id}`);
+  }
+  return capRecordReference(descriptor);
+}
+
+function schemaForRecordType(type) {
+  const name = Object.entries(CAP_RECORD_TYPE).find(([, value]) => value === type)?.[0];
+  if (!name) return "https://citeark.com/schemas/cap/v2/descriptor.schema.json";
+  const filename = name.replace(/[A-Z]/g, (character) => `-${character.toLowerCase()}`);
+  return `https://citeark.com/schemas/cap/v2/${filename}.schema.json`;
+}
+
+async function requireEmptyDirectory(directory) {
+  await mkdir(directory, { recursive: true });
+  if ((await readdir(directory)).length > 0) throw new Error(`CAP output directory is not empty: ${directory}`);
+}
+
+function requiredText(value, label) {
+  if (typeof value !== "string" || !value) throw new Error(`${label} must be a non-empty string`);
+  return value;
+}
+
+function compareText(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

package/src/cap/v2/measurement-assessment-records.mjs

@@ -0,0 +1,23 @@
+import { CAP_RECORD_TYPE } from './core.mjs';
+import { capRecordId, CAP_SCHEMA } from './research-records.mjs';
+
+/** Narrow judgments never replace the compound claim's verdict. */
+export function measurementAssessmentRecords({ assessment, parent, identity, evidenceByMeasurement }) {
+  return (assessment.measurementAssessments ?? []).map(item => {
+    const evidence = evidenceByMeasurement.get(item.measurementId);
+    const comparison = parent.method.comparisons?.find(value => value.measurementId === item.measurementId)?.comparison;
+    return { $schema: CAP_SCHEMA.assessment,
+      id: capRecordId('measurement-assessment', `${identity}:${item.measurementId}`),
+      type: CAP_RECORD_TYPE.assertion, role: 'measurement-assessment',
+      title: `Assessment: ${item.measurementId}`, statement: { value: item.reason ?? 'No assessment explanation provided.', language: 'en' },
+      subject: parent.claim ?? parent.subject, execution: parent.execution,
+      evidence: evidence ? [{ ref: evidence }] : [],
+      method: { type: parent.method.type, measurementId: item.measurementId, ...(comparison ? { comparison } : {}) },
+      conclusion: ['supports', 'challenges', 'contradicts'].includes(item.verdict) ? item.verdict : 'inconclusive',
+      scope: { ...parent.scope, measurementIds: [item.measurementId] },
+      limitations: [...(parent.limitations ?? []), ...(!evidence ? ['No available measurement observation is attached.'] : [])],
+      performedBy: parent.performedBy, createdAt: parent.createdAt,
+      citeark: { measurementId: item.measurementId, reason: item.reason ?? null, verificationStatus: item.verificationStatus ?? null },
+    };
+  });
+}