@citeark/agent 0.3.20

package/src/cap/v2/research-map-records.mjs

@@ -0,0 +1,46 @@
+import { CAP_RECORD_TYPE } from './core.mjs';
+import { capRecordId } from './research-records.mjs';
+
+export function researchReferenceResolver(research, objectGraph, sourceWorkId) {
+  const map = new Map([
+    ...[...objectGraph.objectIds].map(([id, ref]) => [`object:${id}`, ref]),
+    ...[...objectGraph.sourceIds].map(([id, ref]) => [`source:${id}`, ref]),
+    ...(research.claims ?? []).map(n => [`claim:${n.id}`, capRecordId('claim', `${research.work.id}:${n.id}`)]),
+    ...(research.hypotheses ?? []).map(n => [`hypothesis:${n.id}`, capRecordId('hypothesis', `${research.work.id}:${n.id}`)]),
+  ]);
+  return id => {
+    const resolved = map.get(id);
+    if (!resolved) throw Error(`Unknown research map reference: ${id}`);
+    return { ref: resolved };
+  };
+}
+
+export function researchMapRecords({ research, objectGraph, sourceWorkId, actorId }) {
+  const resolve = researchReferenceResolver(research, objectGraph, sourceWorkId);
+  return (research.researchRelations ?? []).map(relation => ({
+    $schema: 'https://citeark.com/schemas/cap/v2/relation.schema.json',
+    id: capRecordId('source-relation', `${research.work.id}:${relation.id}`),
+    type: CAP_RECORD_TYPE.relation, role: 'provenance', predicate: relation.predicate,
+    subject: resolve(relation.from), object: resolve(relation.to),
+    attributedTo: { ref: actorId }, basis: relation.basis,
+    sources: relation.sourceLocators.map(s => resolve(`source:${s.sourceId}`)),
+    qualifiers: { sourceLocators: structuredClone(relation.sourceLocators), ...(relation.note ? { note: relation.note } : {}) },
+  }));
+}
+
+// Keep editorial organization separate from scientific edges. The assembler binds node
+// identities; consumers resolve their exact versions inside this immutable snapshot.
+export function bindResearchReading(research, objectGraph, sourceWorkId) {
+  if (!research.reading) return undefined;
+  const resolve = researchReferenceResolver(research, objectGraph, sourceWorkId), view = research.reading;
+  return { schemaVersion: '1.0', overview: view.overview,
+    mainline: view.mainline.map(resolve),
+    branches: view.branches.map(b => ({ parent: resolve(b.parent), children: b.children.map(resolve) })),
+    labels: (view.labels ?? []).map(({target,...label}) => ({ ...label, ...resolve(target) })),
+  };
+}
+export function bindResearchIntent(experiment, research, objectGraph, sourceWorkId) {
+  if (!experiment.researchIntent) return undefined;
+  const resolve = researchReferenceResolver(research, objectGraph, sourceWorkId), value = experiment.researchIntent;
+  return { ...value, from: resolve(value.from), to: resolve(value.to), context: (value.context ?? []).map(resolve) };
+}

package/src/cap/v2/research-object-records.mjs

@@ -0,0 +1,163 @@
+import { CONTEXT_ROLES } from '../../research/research-map.mjs';
+import { CAP_RECORD_TYPE } from './core.mjs';
+import { canonicalJsonBytes, sha256Bytes } from './canonical-json.mjs';
+import { CAP_SCHEMA, capRecordId, capSourceRights, capDecimal } from './research-records.mjs';
+import { reportedObservationCollections } from '../../research/source-observations.mjs';
+
+const ref = id => ({ ref: id });
+const objectId = (research, localId) => capRecordId('research-object', `${research.work.id}:${localId}`);
+const sourceId = (research, source, workId) => source.kind === 'paper' ? workId
+  : source.kind === 'repository' && source.version ? capRecordId('code', `${source.uri}@${source.version}`)
+    : capRecordId('source', `${research.work.id}:${source.id}`);
+const role = kind => ({ repository: 'code', supplement: 'material' })[kind] ?? kind;
+
+/** Materialize only named objects and explicitly recorded inputs. Never extract identities from prose. */
+export function researchObjectRecords({ research, sourceWorkId, actorId }) {
+  const records = [], inputIdsByExperiment = new Map(), stepIdsByExperiment = new Map();
+  const collections = reportedObservationCollections(research);
+  const sourceIds = new Map((research.sources ?? []).map(source => [source.id, sourceId(research, source, sourceWorkId)]));
+  const objectIds = new Map((research.researchObjects ?? []).map(object => [object.id, object.sourceId ? sourceIds.get(object.sourceId) : objectId(research, object.id)]));
+  for (const source of research.sources ?? []) {
+    if (source.kind === 'paper') continue;
+    records.push({ $schema: CAP_SCHEMA.sourceWork, id: sourceIds.get(source.id), type: CAP_RECORD_TYPE.entity,
+      role: role(source.kind), title: source.title ?? source.uri,
+      basis: 'declared', identity: { uri: source.uri, ...(source.version ? { version: source.version } : {}), ...(source.digest ? { digest: source.digest } : {}) },
+      rights: capSourceRights(source.kind, research.license),
+      origin: { basis: 'declared', actor: ref(actorId) }, citeark: { sourceId: source.id },
+    });
+  }
+  for (const object of research.researchObjects ?? []) {
+    const sourceIndex = records.findIndex(record => record.id === objectIds.get(object.id));
+    const sourceRecord = sourceIndex >= 0 ? records.splice(sourceIndex, 1)[0] : {};
+    const primitive = CONTEXT_ROLES[object.role]?.[0] ?? 'entity';
+    records.push({ ...sourceRecord, $schema: `https://citeark.com/schemas/cap/v2/${primitive}.schema.json`, id: objectIds.get(object.id), type: CAP_RECORD_TYPE[primitive],
+      ...(primitive === 'activity' ? { status: 'unknown', reportingBasis: 'declared' } : {}),
+      ...(primitive === 'assertion' ? { statement: { value: object.description ?? object.title, language: 'und' } } : {}),
+      ...(primitive === 'agent' ? { name: object.title, kind: object.role === 'person' ? 'human' : object.role } : {}),
+      role: object.role, title: object.title, basis: object.basis ?? 'declared',
+      ...(object.role === 'observation' ? { kind: object.prospective ? 'observation-specification'
+        : object.observationKind && object.observationKind !== 'scalar' ? 'source-observation-collection' : 'source-observation',
+        ...(object.observationKind ? { observationKind: object.observationKind } : {}) } : {}),
+      ...(collections.has(object.id) ? { kind: 'source-observation-collection',
+        measurements: collections.get(object.id).map(({ claim, measurement }) => ({
+          measurementId: measurement.id, metric: measurement.metric,
+          value: { decimal: capDecimal(measurement.value) }, unit: measurement.unit,
+          ...(measurement.dimensions ? { scope: structuredClone(measurement.dimensions) } : {}),
+          conditions: structuredClone(measurement.conditions ?? claim.conditions ?? {}),
+          sourceLocator: structuredClone(measurement.sourceLocator ?? claim.sourceLocator),
+          contextObjects: (measurement.objectIds ?? claim.objectIds ?? []).map(id => ref(objectIds.get(id))),
+          ...(measurement.aggregation ? { aggregation: measurement.aggregation } : {}),
+          ...(measurement.evidenceBasis ? { evidenceBasis: measurement.evidenceBasis } : {}),
+          ...(measurement.extractionUncertainty !== undefined ? { uncertainty: { absolute: capDecimal(measurement.extractionUncertainty) } } : {}),
+        })),
+        contextObjects: [...new Set(collections.get(object.id).flatMap(({ claim, measurement }) => measurement.objectIds ?? claim.objectIds ?? []))]
+          .map(id => ref(objectIds.get(id))),
+      } : {}),
+      ...(object.description ? { description: object.description } : {}),
+      ...((sourceRecord.identity || object.identity) ? { identity: { ...sourceRecord.identity, ...structuredClone(object.identity ?? {}) } } : {}),
+      ...(object.conditions !== undefined ? { conditions: structuredClone(object.conditions) } : {}),
+      prospective: object.prospective === true,
+      ...(object.prospective ? { availability: 'not-yet-generated' } : {}),
+      sourceContext: (object.sourceLocators ?? []).map(locator => ({ source: ref(sourceIds.get(locator.sourceId)), selector: { label: locator.locator } })),
+      derivedFrom: (object.derivedFromIds ?? []).map(id => ref(objectIds.get(id))),
+      origin: { basis: object.basis ?? 'declared', actor: ref(actorId) },
+      citeark: { ...sourceRecord.citeark, objectId: object.id, sourceLocators: object.sourceLocators ?? [], limitations: object.limitations ?? [] },
+    });
+  }
+  // Older compiler inputs already carry source-grounded asset declarations. Keep each exact recipe
+  // once; availability labels and matching names never establish observed bytes or shared identity.
+  const materialIds = new Set(records.map(record => record.id));
+  for (const experiment of research.experiments ?? []) {
+    const inputs = new Set((experiment.inputIds ?? []).map(id => objectIds.get(id)));
+    const repository = experiment.repository;
+    if (repository?.url && repository?.commit) {
+      const codeId = capRecordId('code', `${repository.url}@${repository.commit}`);
+      if (!materialIds.has(codeId)) {
+        records.push({ $schema: CAP_SCHEMA.sourceWork, id: codeId, type: CAP_RECORD_TYPE.entity, role: 'code',
+          title: repository.url, identity: { uri: repository.url, revision: repository.commit }, basis: 'declared',
+          origin: { basis: 'declared', actor: ref(actorId) } });
+        materialIds.add(codeId);
+      }
+      inputs.add(codeId);
+    }
+    for (const asset of experiment.protocol?.preflight?.assets ?? []) {
+      const identity = { kind: asset.kind, identity: asset.identity, acquisition: asset.acquisition ?? null,
+        sourceUrls: [...(asset.sourceUrls ?? [])].sort(), registryDatasetId: asset.registryDatasetId ?? null,
+        scientificRole: asset.scientificRole ?? null };
+      const assetId = capRecordId('material', sha256Bytes(canonicalJsonBytes(identity)));
+      if (!materialIds.has(assetId)) {
+        records.push({ $schema: CAP_SCHEMA.sourceWork, id: assetId, type: CAP_RECORD_TYPE.entity, role: role(asset.kind ?? 'material'),
+          title: asset.identity ?? asset.id, identity, basis: 'declared', availability: asset.availability ?? 'unknown',
+          origin: { basis: 'declared', actor: ref(actorId) }, citeark: { assetId: asset.id, verification: asset.verification ?? null } });
+        materialIds.add(assetId);
+      }
+      inputs.add(assetId);
+    }
+    inputIdsByExperiment.set(experiment.id, [...inputs]);
+  }
+  const steps = new Map();
+  for (const experiment of research.experiments ?? []) {
+    const ids = [];
+    const internalOutputs = new Set((experiment.steps ?? []).flatMap(step => step.outputIds ?? []));
+    const packageInputs = new Set(inputIdsByExperiment.get(experiment.id));
+    for (const step of experiment.steps ?? []) {
+      const id = capRecordId('research-step', `${research.work.id}:${step.id}`);
+      ids.push(id);
+      for (const input of step.inputIds ?? []) if (!internalOutputs.has(input)) packageInputs.add(objectIds.get(input));
+      if (!steps.has(step.id)) steps.set(step.id, { id, step, claimIds: new Set(), experimentIds: new Set() });
+      const entry = steps.get(step.id);
+      entry.experimentIds.add(experiment.id);
+      for (const claimId of step.claimIds ?? []) if (research.claims.some(claim => claim.id === claimId)) entry.claimIds.add(claimId);
+    }
+    stepIdsByExperiment.set(experiment.id, ids);
+    inputIdsByExperiment.set(experiment.id, [...packageInputs]);
+  }
+  for (const entry of steps.values()) {
+    const step = entry.step;
+    records.push({ $schema: CAP_SCHEMA.experiment, id: entry.id, type: CAP_RECORD_TYPE.entity, role: 'procedure-step',
+      title: step.title, kind: step.kind, prospective: true,
+      inputs: (step.inputIds ?? []).map(id => ({ record: ref(objectIds.get(id)), role: 'scientific-input', basis: 'declared' })),
+      expectedOutputs: (step.outputIds ?? []).map(id => ref(objectIds.get(id))),
+      dependencies: (step.dependsOn ?? []).map(id => ref(capRecordId('research-step', `${research.work.id}:${id}`))),
+      tests: [...entry.claimIds].map(id => ref(capRecordId('claim', `${research.work.id}:${id}`))),
+      origin: { basis: 'inferred', actor: ref(actorId) },
+      evaluationPlan: { title: step.title, state: 'planned', ...(step.description ? { instructions: step.description } : {}) },
+      citeark: { stepId: step.id, experimentIds: [...entry.experimentIds], workloadIds: step.workloadIds ?? [] },
+    });
+  }
+  return { records, objectIds, sourceIds, inputIdsByExperiment, stepIdsByExperiment };
+}
+
+/** Source measurements remain declared observations, including during compilation. */
+export function reportedObservationRecords({ research, sourceWorkId, objectIds = new Map() }) {
+  const records = [], idsByClaim = new Map();
+  for (const claim of research.claims ?? []) {
+    const ids = [];
+    for (const measurement of claim.reportedMeasurements ?? []) {
+      if (measurement.observationId !== undefined) {
+        const object = (research.researchObjects ?? []).find(object => object.id === measurement.observationId);
+        const id = objectIds.get(measurement.observationId);
+        if (!id || object?.role !== 'observation' || object.prospective || object.basis === 'inferred') throw Error('Invalid source observation collection');
+        if (!ids.includes(id)) ids.push(id);
+        continue;
+      }
+      const id = capRecordId('evidence', `${research.work.id}:${claim.id}:reported:${measurement.id}`);
+      ids.push(id);
+      records.push({ $schema: CAP_SCHEMA.evidence, id, type: CAP_RECORD_TYPE.entity, role: 'observation',
+        title: `${measurement.metric}: ${measurement.value} ${measurement.unit}`, kind: 'measurement', basis: 'declared',
+        derivedFrom: [{ ref: sourceWorkId }],
+        measurement: { measurementId: measurement.id, metric: measurement.metric,
+          value: { decimal: capDecimal(measurement.value) }, unit: measurement.unit,
+          ...(measurement.dimensions ? { scope: measurement.dimensions } : {}) },
+        contextObjects: (measurement.objectIds ?? claim.objectIds ?? []).map(id => ref(objectIds.get(id))),
+        limitations: ['Declared by the fixed source work; not independently observed.',
+          ...(measurement.evidenceBasis === 'digitized_figure' ? [`Digitized with absolute extraction uncertainty ${measurement.extractionUncertainty} ${measurement.unit}.`] : [])],
+        citeark: { claimId: claim.id, sourceLocator: measurement.sourceLocator, conditions: measurement.conditions ?? claim.conditions ?? null,
+          aggregation: measurement.aggregation ?? null, evidenceBasis: measurement.evidenceBasis ?? 'reported_numeric',
+          extractionUncertainty: measurement.extractionUncertainty ?? null },
+      });
+    }
+    idsByClaim.set(claim.id, ids);
+  }
+  return { records, idsByClaim };
+}

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

@@ -0,0 +1,187 @@
+import { CAP_RECORD_TYPE } from "./core.mjs";
+import { sha256Bytes } from "./canonical-json.mjs";
+
+export const CAP_SCHEMA = Object.freeze({
+  actor: "https://citeark.com/schemas/cap/v2/agent.schema.json",
+  sourceWork: "https://citeark.com/schemas/cap/v2/entity.schema.json",
+  claim: "https://citeark.com/schemas/cap/v2/assertion.schema.json",
+  experiment: "https://citeark.com/schemas/cap/v2/entity.schema.json",
+  execution: "https://citeark.com/schemas/cap/v2/activity.schema.json",
+  evidence: "https://citeark.com/schemas/cap/v2/entity.schema.json",
+  assessment: "https://citeark.com/schemas/cap/v2/assertion.schema.json",
+});
+
+export function capRecordId(kind, value) {
+  return `urn:citeark:${kind}:${sha256Bytes(Buffer.from(String(value), "utf8")).slice(7)}`;
+}
+
+export function capActorRecord(id, name, kind, version) {
+  return {
+    $schema: CAP_SCHEMA.actor,
+    id,
+    type: CAP_RECORD_TYPE.agent, role: "agent",
+    kind,
+    name,
+    ...(version ? { version: String(version) } : {}),
+  };
+}
+
+export function capSourceWorkRecord({
+  research,
+  id,
+  processingBinding,
+}) {
+  return {
+    $schema: CAP_SCHEMA.sourceWork,
+    id,
+    type: CAP_RECORD_TYPE.entity, role: "source-work",
+    title: research.work.title,
+    abstract: research.work.abstract,
+    sources: research.sources.map((source) => capSourceDescriptor({
+      source,
+      research,
+      processingBinding,
+    })),
+    citeark: {
+      workId: research.work.id,
+      ...(research.compilationStage ? { compilationStage: research.compilationStage } : {}),
+      ...(research.sourceInventory ? { sourceInventory: structuredClone(research.sourceInventory) } : {}),
+      ...(research.reproductionScope ? { reproductionScope: research.reproductionScope } : {}),
+      ...(research.work.significance ? { significance: research.work.significance } : {}),
+      authorNames: research.work.authors ?? [],
+      subjects: research.work.subjects ?? [],
+      license: research.license ?? {},
+      provenance: research.provenance ?? {},
+      coverage: research.coverage ?? { items: [] },
+      lineage: research.lineage ?? [],
+    },
+  };
+}
+
+export function capClaimRecord({
+  claim,
+  id,
+  sourceWorkId,
+  actorId,
+  reportedEvidenceIds = [],
+  objectReferences = [],
+}) {
+  const ref = (value) => ({ ref: value });
+  return {
+    $schema: CAP_SCHEMA.claim,
+    id,
+    type: CAP_RECORD_TYPE.assertion, role: "claim",
+    statement: { value: claim.statement, language: "en" },
+    kind: capClaimKind(claim.type),
+    ...(objectReferences.length ? { objects: objectReferences } : {}),
+    scope: {
+      reportedMeasurements: (claim.reportedMeasurements ?? []).map((item) => ({
+        id: item.id,
+        metric: item.metric,
+        value: capDecimal(item.value),
+        unit: item.unit,
+        evidenceBasis: item.evidenceBasis ?? "reported_numeric",
+        ...(item.extractionUncertainty !== undefined
+          ? { extractionUncertainty: capDecimal(item.extractionUncertainty) }
+          : {}),
+      })),
+      reproduction: claim.reproduction ?? {},
+    },
+    source: {
+      work: ref(sourceWorkId),
+      selector: {
+        type: "TextQuoteSelector",
+        exact: claim.statement,
+        label: `${claim.sourceLocator.sourceId}:${claim.sourceLocator.locator}`,
+      },
+      selectedTextDigest: sha256Bytes(Buffer.from(claim.statement, "utf8")),
+    },
+    origin: {
+      basis: "inferred",
+      actor: ref(actorId),
+    },
+    ...(reportedEvidenceIds.length
+      ? { reportedEvidence: reportedEvidenceIds.map(ref) }
+      : {}),
+    citeark: {
+      localId: claim.id,
+      versionId: claim.versionId,
+      type: claim.type,
+      sourceLocator: claim.sourceLocator,
+      ...Object.fromEntries(["description", "sourceLocators", "conditions", "relations", "ambiguities", "verificationHint"]
+        .filter((key) => claim[key] !== undefined).map((key) => [key, structuredClone(claim[key])])),
+      reportedMeasurements: claim.reportedMeasurements ?? [],
+      reproduction: claim.reproduction ?? {},
+    },
+  };
+}
+
+export function capSourceDescriptor({ source, research, processingBinding }) {
+  const paperDigest = source.kind === "paper" && capDigest(processingBinding?.sourceDigest)
+    ? processingBinding.sourceDigest
+    : capDigest(source.digest) ? source.digest : null;
+  return {
+    kind: capSourceKind(source.kind),
+    uri: source.uri,
+    ...(source.version ? { version: String(source.version) } : {}),
+    integrity: paperDigest ? "verified" : "unverified",
+    ...(paperDigest ? { digest: paperDigest } : {}),
+    rights: capSourceRights(source.kind, research.license),
+  };
+}
+
+export function capSourceRights(kind, license = {}) {
+  const key = kind === "repository"
+    ? "code"
+    : kind === "paper"
+      ? "paper"
+      : kind === "dataset"
+        ? "dataset"
+        : kind === "checkpoint" ? "checkpoint" : null;
+  return {
+    statement: key && license?.[key]
+      ? String(license[key])
+      : "Source-specific rights; CAP records identity and provenance but grants no redistribution permission.",
+  };
+}
+
+export function capClaimKind(value) {
+  return ({
+    finding: "descriptive",
+    method: "methodological",
+    measurement: "descriptive",
+    limitation: "limitation",
+  })[value] ?? "descriptive";
+}
+
+/** A source's proposed mechanism is an Assertion, without a reproduction disposition or verdict. */
+export function capHypothesisRecords({ research, sourceWorkId, actorId, objectIds }) {
+  return (research.hypotheses ?? []).map(hypothesis => ({
+    $schema: CAP_SCHEMA.claim, id: capRecordId('hypothesis', `${research.work.id}:${hypothesis.id}`),
+    type: CAP_RECORD_TYPE.assertion, role: 'hypothesis',
+    statement: { value: hypothesis.statement, language: 'en' },
+    source: { work: { ref: sourceWorkId }, selector: { label: `${hypothesis.sourceLocator.sourceId}:${hypothesis.sourceLocator.locator}` } },
+    origin: { basis: 'inferred', actor: { ref: actorId } },
+    objects: (hypothesis.objectIds ?? []).map(id => ({ ref: objectIds.get(id) })),
+    ...(hypothesis.conditions !== undefined ? { scope: structuredClone(hypothesis.conditions) } : {}),
+    citeark: { localId: hypothesis.id, sourceLocator: hypothesis.sourceLocator,
+      limitations: hypothesis.limitations ?? [], status: 'proposed' },
+  }));
+}
+
+export function capSourceKind(value) {
+  if (value === "checkpoint") return "model";
+  return new Set(["paper", "repository", "dataset", "model", "supplement", "other"]).has(value)
+    ? value
+    : "other";
+}
+
+export function capDecimal(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (typeof value === "string" && /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$/.test(value)) return value;
+  throw new Error(`CAP scientific number cannot be represented as a decimal string: ${String(value)}`);
+}
+
+export function capDigest(value) {
+  return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
+}