@citeark/agent 0.3.20

package/src/research/planning-policy.mjs

@@ -0,0 +1,88 @@
+import { REPRODUCTION_SCOPES } from "./reproduction-scope.mjs";
+
+export const SCIENTIFIC_OPERATION_SCOPES = {
+  evaluate_existing_state: "low",
+  regenerate_selected_state: "medium",
+  rebuild_research_workflow: "high",
+};
+
+const LEGACY_SCIENTIFIC_OPERATION_SCOPES = {
+  observe_existing: "low",
+  generate_inputs: "medium",
+  rebuild_workflow: "high",
+};
+
+export function scientificOperationScope(kind) {
+  return SCIENTIFIC_OPERATION_SCOPES[kind]
+    ?? LEGACY_SCIENTIFIC_OPERATION_SCOPES[kind]
+    ?? null;
+}
+
+// One task definition for the compiler and the independent plan reviewer.
+// The three user-facing values are recommendation presets, while operation
+// scope remains descriptive metadata for each experiment.
+export const SCIENTIFIC_PLANNING_POLICY = {
+  version: "scientific-planning-v8",
+  resourceDiscovery: "Read the task's timestamped resource discovery before planning. Distinguish provider inventory, quota and permissions, supported runtime adapters, exact prices and unknown live capacity. Derive CPU/RAM/VRAM minima from scientific workload and cited or explicitly assumed evidence, never by copying the selected machine's size. Explain compatible alternatives without weakening source-bound measurement hardware. Only charge preparation dependencies needed by each experiment; unknown or failed discovery is not proof of resource absence.",
+  objective: "Produce a source-grounded catalog of independently selectable experiment packages for the paper's reported questions. Planning is not execution or scientific support.",
+  compilationBoundary: {
+    responsibility: "Define the reported empirical questions, necessary comparisons and conditions, allowed verification routes, and evidence needed by execution and independent assessment. Preserve the complete empirical result inventory, including negative results and local gaps. Organize independently meaningful assertions separately from source observation collections, methods, conditions and proposed hypotheses; never create a claim per cell or point.",
+    context: "Theory, proofs, architecture descriptions and implementation exposition explain the empirical questions; they do not each require a separate claim or experiment. Include a distinct testable result when it is needed to interpret or verify the paper's empirical conclusions. Numerical examples do not prove a theorem.",
+    handoff: "Execution resolves commands, loaders, asset locations, environment details and operational probes. Assessment judges comparability and scientific support from actual evidence. Compilation does not certify either runtime success or the paper's truth.",
+    review: "Block changes to scientific meaning, material empirical omissions, invalid comparisons or verification routes, and fabricated evidence. Do not reject the whole catalog because one package is unavailable; preserve its requirements and surface the reason to the user. Keep editorial details, redundant coverage, optional theoretical extensions and resolvable operational uncertainty as non-blocking advice.",
+  },
+  scopes: {
+    low: "Descriptive operation class: evaluate existing scientific state and produce fresh measurements without regenerating upstream scientific state.",
+    medium: "Descriptive operation class: regenerate selected scientific state for one or a few key experiments with matched controls, required seeds and analysis.",
+    high: "Descriptive operation class: rebuild a major research workflow from preparation and scientific-state generation through experiments, controls and analysis.",
+  },
+  stateBoundary: {
+    scientificState: "Research outputs whose generation is itself part of the scientific question, such as trained weights, collected datasets, simulation trajectories, generated samples, attack traces, or state produced by an experimental system.",
+    operationalScaffolding: "Means needed to evaluate the question without recreating its upstream science, such as dependencies, compiled binaries, deterministic fixed-workload construction, temporary runtime tensors, caches, evaluators, analysis code, and logs.",
+  },
+  decisions: {
+    planned: "An allowed, source-grounded verification route exists. Unverified operational details can be resolved by bounded execution probes.",
+    blocked: "A specific necessary scientific input, decision rule, access or resource is demonstrably unavailable. Name the missing requirement and affected measurements; uncertainty alone does not establish impossibility.",
+    notSelected: "The experiment remains in the catalog but is not in the current default checkbox recommendation. This is not a blocker or scientific verdict.",
+  },
+  operationScopes: SCIENTIFIC_OPERATION_SCOPES,
+  planGranularity: {
+    steps: "Describe method stages, not Cartesian-product execution instances. Keep checkpoints, datasets, seeds, layers and metrics as complete parameter axes inside a stage and its expected collection; split only for materially different operations, scientific state, decision rules or reusable consumer scope. Preserve all explicit source object and measurement identities. No graph-size cap or scope reduction is allowed.",
+    products: "Prospective objects specify coherent result tables, matrices, curve families or trained-state families with their complete dimensions and row/member identity rules. Do not create a future object per loop coordinate or scalar. Source identities remain separate and actual produced states retain their own identities during execution. Declare direct inputs and derivation, not repeated transitive ancestry.",
+    observationTargets: "Retain qualitative methods as explicit source observation comparisons with claimId, observationId, comparison and an unresolved decision_rule limitation. Never fabricate scalar IDs or parsers for collections. Observation-only proposals remain in the catalog but are not automatically executable or verifiable. Mixed proposals preserve valid numeric bindings separately.",
+    accounting: "A compute workload can be an exact recipe/seed/parameter batch. Reuse identical batches across consumers. Partition partially shared batches into exact shared subsets and disjoint remainders only where independently selectable consumers require it. Accounting partitions do not force separate steps or output objects. Count every member in duration arithmetic; different complete batch definitions cannot share an ID.",
+  },
+  sharedExecution: "All selected experiments share one machine sized to the maximum resource requirements and one Agent workspace. Declare compute.workloads for each experiment, separating reusable scientific-state generation and setup from incremental measurements. Compare the whole catalog before submitting: shared prerequisites must have identical IDs and definitions across consumers, never be buried in differently named experiment-sized bundles. Preserve independent seeds and different recipes within explicitly scoped batch identities; do not enumerate one work item per seed by default. Execution chooses order, batching and safe parallelism; workload items are not separate jobs or a forced serial schedule. Every selectable experiment and workload item must have a finite positive time estimate for its eligible execution path. Explicit conservative runtime assumptions are acceptable and must report their basis; unknown or null quotes are not acceptable, and hard limits remain separate.",
+  principles: [
+    "Preserve all reported empirical questions, their conditions, controls and source locations, including findings without a reliable numeric reference. Do not replace an unresolved source value with an invented target.",
+    "For each question identify the necessary inputs, verification operation, observable, aggregation and decision rule. A relation can be encoded numerically only when that computation and comparison are defined.",
+    "Classify the necessary operations, not the table, topic, runtime cost, accelerator count or artifact's production history. Ask whether matching existing scientific state would let an independent observation or analysis answer the question.",
+    "Fresh measurements do not make a task medium scope. Measuring released software on a fixed workload, including compilation and deterministic construction of temporary runtime inputs, is low scope when it does not regenerate upstream scientific state.",
+    "If evaluating matching pretrained artifacts would answer a result question, missing those artifacts is an input gap, not a higher-scope question merely because training could replace them. Distinguish an unverified locator from demonstrated unavailability; preserve an allowed discovery probe when plausible.",
+    "Apply planned or blocked decisions to the exact measurements concerned. Preserve feasible work and localize uncertainty; one missing input does not block unrelated measurements.",
+    "Treat default selection, operation complexity, monetary budget, available resources and fidelity as separate dimensions. Preserve source ambiguity explicitly and distinguish a qualified verification question from an unsupported claim of exact reproduction.",
+    "Use low, medium and high only to recommend initial checkboxes. Never remove a valid experiment, fabricate a blocker, or reject a package because its operation scope is above the requested preset.",
+    "Execution owns operational refinement; source identity, the scientific question and its evidence requirements remain fixed. A bounded probe is a way to investigate uncertainty, not proof that a workload is feasible.",
+  ],
+};
+
+export function scientificPlanningPolicy(requestedScope, stage = "inventory") {
+  if (requestedScope !== undefined && !REPRODUCTION_SCOPES.includes(requestedScope)) {
+    throw new Error("Invalid task-owned reproduction scope");
+  }
+  const policy = stage === "execution_plan" ? SCIENTIFIC_PLANNING_POLICY : {
+    version: "research-inventory-v2",
+    objective: "Record the paper faithfully for the reproduction Agent. Recorded inventory is neither an executable plan nor scientific support.",
+    compilationBoundary: {
+      responsibility: "Preserve empirical results including negative findings, reported numbers, comparison objects, necessary source conditions, locations, relationships and ambiguities. Optional verification hints are provisional. Preserve scientifically meaningful propositions as claims, coherent matrices/tables/curve families as observation collections with observationId-linked measurements, and proposed mechanisms as hypotheses. Completeness does not require one claim per value; there is no claim-count cap.",
+      context: "Theory and implementation exposition supply context; do not expand each passage into a separate verification obligation.",
+      handoff: "Reproduction reads the inventory and original materials, investigates inputs, defines comparisons and decision rules, estimates each package, and recommends initial selections. Execution refines interpretations with source-grounded reasons and retained history. Assessment judges actual evidence. Original source statements and reported values remain preserved.",
+      review: "Check material empirical omissions, incorrect numbers or comparison objects, lost necessary reported conditions and inferences presented as source facts. Do not demand executable routes, asset availability checks, decision rules, scope decisions or cost estimates from the inventory. Preserve ambiguity rather than rejecting already disclosed uncertainty.",
+    },
+    scopes: SCIENTIFIC_PLANNING_POLICY.scopes,
+    principles: ["Keep the complete empirical result inventory, including qualitative and negative findings without numeric targets.", "Distinguish reported facts, unknown source conditions and investigator interpretations. Never invent reference values.", "Source ambiguity and unresolved verification methods are handoff context, not proof of impossibility."],
+  };
+  return { ...structuredClone(policy), requestedPreset: requestedScope ?? null,
+    requestedScope: requestedScope ?? null,
+    legacyScope: requestedScope === undefined ? "Preserve the existing task's scientific objectives; do not invent a scope restriction." : null };
+}

package/src/research/reference-materials.mjs

@@ -0,0 +1,11 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { writeJson } from '../util.mjs';
+import { validateCodeFiles } from '../deployment/handoff.mjs';
+
+export async function stageReferenceMaterials(filename, directory) {
+  if (!filename) return;
+  const materials = JSON.parse(await readFile(filename, 'utf8'));
+  validateCodeFiles(materials.files);
+  await writeJson(path.join(directory, 'reference-materials.json'), materials);
+}

package/src/research/reproduction-scope.mjs

@@ -0,0 +1,30 @@
+/** Task-owned scope. Old artifacts without this field retain their original contract. */
+export const REPRODUCTION_SCOPES = ["low", "medium", "high"];
+export const REPRODUCTION_ROUTES = ["directional", "official-checkpoint", "full-training", "artifact-evaluation", "experiment-rerun", "workflow-rebuild"];
+export const isReproductionScope = (value) => REPRODUCTION_SCOPES.includes(value);
+export const exceedsReproductionScope = (required, requested) =>
+  isReproductionScope(required) && isReproductionScope(requested)
+  && REPRODUCTION_SCOPES.indexOf(required) > REPRODUCTION_SCOPES.indexOf(requested);
+
+export function scopeExclusionFor(claim, measurementId, requested) {
+  void claim;
+  void measurementId;
+  void requested;
+  return undefined;
+}
+
+export function reproductionScopeIssues(research, requested = research?.reproductionScope) {
+  if (requested === undefined) return [];
+  if (!isReproductionScope(requested)) return ["Invalid requested reproduction scope"];
+  const issues = [];
+  if (research.reproductionScope !== requested) issues.push("Research Plan must preserve the task-owned reproductionScope");
+  for (const experiment of Array.isArray(research.experiments) ? research.experiments : []) {
+    if (!experiment || typeof experiment !== "object") continue;
+    if (experiment.reproductionScope !== requested) issues.push(`Experiment ${experiment.id} must retain the requested scope identity`);
+    if (experiment.requiredReproductionScope !== undefined
+      && !isReproductionScope(experiment.requiredReproductionScope)) {
+      issues.push(`Experiment ${experiment.id} has an invalid requiredReproductionScope annotation`);
+    }
+  }
+  return issues;
+}

package/src/research/research-map.mjs

@@ -0,0 +1,94 @@
+import { CAP_PREDICATES } from '../graph/model.mjs';
+
+// Editorial references are typed local identities, never a match on a display title.
+export const CONTEXT_ROLES = Object.freeze({
+  question: ['entity', 'question'], concept: ['entity', 'concept'],
+  premise: ['assertion', 'hypothesis'], argument: ['entity', 'argument'],
+  'research-plan': ['entity', 'plan'], 'research-activity': ['activity', 'activity'],
+  'source-assessment': ['assertion', 'assessment'],
+  person: ['agent', 'agent'], organization: ['agent', 'agent'], instrument: ['entity', 'resource'],
+});
+export function inventoryReferences(research) {
+  return new Map([
+    ...(research.sources ?? []).map(n => [`source:${n.id}`, { value: n, primitive: 'entity' }]),
+    ...(research.researchObjects ?? []).map(n => [`object:${n.id}`, { value: n, primitive: CONTEXT_ROLES[n.role]?.[0] ?? 'entity' }]),
+    ...(research.claims ?? []).map(n => [`claim:${n.id}`, { value: n, primitive: 'assertion' }]),
+    ...(research.hypotheses ?? []).map(n => [`hypothesis:${n.id}`, { value: n, primitive: 'assertion' }]),
+  ]);
+}
+export function validateResearchMap(research, issues) {
+  const refs = inventoryReferences(research), sources = new Set((research.sources ?? []).map(n => n.id));
+  const nonempty = value => typeof value === 'string' && value.trim().length > 0;
+  const reference = (value, label) => { if (!refs.has(value)) issues.push(`${label}: unknown research reference ${String(value)}`); };
+  const list = (value, label) => { if (!Array.isArray(value)) { issues.push(`${label} must be an array`); return []; } return value; };
+  const locators = (value, label) => {
+    const entries = list(value, label);
+    if (!entries.length) issues.push(`${label} requires a source locator`);
+    for (const entry of entries) if (!sources.has(entry?.sourceId) || !nonempty(entry?.locator)) issues.push(`${label} requires a fixed source and location`);
+  };
+  for (const object of research.researchObjects ?? []) if (CONTEXT_ROLES[object.role]) {
+    locators(object.sourceLocators, `object ${object.id}.sourceLocators`);
+    if (['research-activity', 'person', 'organization'].includes(object.role) && object.prospective === true)
+      issues.push(`object ${object.id}: prospective work must use research-plan, not an actual activity or participant`);
+  }
+  const entityInputs=(ids,label)=>{for(const id of Array.isArray(ids)?ids:[])if(refs.has(`object:${id}`)&&refs.get(`object:${id}`).primitive!=='entity')issues.push(`${label}: ${id} must be an Entity; use an explicit researchRelations predicate for assertions, activities or participants`);};
+  for(const item of [...(research.claims??[]),...(research.hypotheses??[])]){
+    entityInputs(item.objectIds,`${item.id}.objectIds`);
+    for(const row of item.reportedMeasurements??[])entityInputs(row.objectIds,`${row.id}.objectIds`);
+  }
+  for(const object of research.researchObjects??[]){entityInputs(object.derivedFromIds,`${object.id}.derivedFromIds`);if(object.derivedFromIds?.length&&refs.get(`object:${object.id}`)?.primitive!=='entity')issues.push(`${object.id}: derivedFromIds requires an Entity subject`);}
+  for(const experiment of research.experiments??[]){entityInputs(experiment.inputIds,`${experiment.id}.inputIds`);for(const step of experiment.steps??[]){entityInputs(step.inputIds,`${step.id}.inputIds`);entityInputs(step.outputIds,`${step.id}.outputIds`);}}
+  if (research.researchRelations !== undefined) {
+    const ids = new Set();
+    for (const relation of list(research.researchRelations, 'researchRelations')) {
+      if (!relation || !nonempty(relation.id) || ids.has(relation.id)) { issues.push('researchRelations requires unique nonempty ids'); continue; }
+      ids.add(relation.id);
+      reference(relation.from, `relation ${relation.id}.from`); reference(relation.to, `relation ${relation.id}.to`);
+      const types = CAP_PREDICATES[relation.predicate];
+      if (!types || ['revises', 'supersedes', 'hasStep', 'expects'].includes(relation.predicate)) issues.push(`relation ${relation.id}: unsupported source predicate`);
+      else for (const [i, endpoint] of [relation.from, relation.to].entries())
+        if (types[i] && refs.has(endpoint) && refs.get(endpoint).primitive !== types[i]) issues.push(`relation ${relation.id}: ${endpoint} must be ${types[i]}`);
+      if (!['declared', 'inferred'].includes(relation.basis)) issues.push(`relation ${relation.id}: source basis must be declared or inferred`);
+      locators(relation.sourceLocators, `relation ${relation.id}.sourceLocators`);
+    }
+  }
+  const view = research.reading;
+  if (view !== undefined) {
+    if (!view || view.schemaVersion !== '1.0') { issues.push('reading.schemaVersion must be 1.0'); return; }
+    if (!nonempty(view.overview)) issues.push('reading.overview must be nonempty');
+    const main = list(view.mainline, 'reading.mainline');
+    if (!main.length) issues.push('reading.mainline must contain source-grounded objects');
+    const seen = new Set();
+    for (const id of main) { reference(id, 'reading.mainline'); if (seen.has(id)) issues.push('reading.mainline contains duplicates'); seen.add(id); }
+    const parents = new Map();
+    for (const branch of list(view.branches, 'reading.branches')) {
+      reference(branch?.parent, 'reading.branch.parent');
+      for (const child of list(branch?.children, 'reading.branch.children')) {
+        reference(child, 'reading.branch.child');
+        if (main.includes(child) || parents.has(child) || child === branch.parent) issues.push(`reading branch ${child} has duplicate or cyclic placement`);
+        parents.set(child, branch.parent);
+      }
+    }
+    for (const start of parents.keys()) {
+      let id = start; const visited = new Set();
+      while (parents.has(id)) { if (visited.has(id)) { issues.push(`reading branch cycle at ${start}`); break; } visited.add(id); id = parents.get(id); }
+      if (!main.includes(id)) issues.push(`reading branch ${start} must connect to a mainline object`);
+    }
+    const labelled = new Set();
+    for (const entry of list(view.labels ?? [], 'reading.labels')) {
+      reference(entry?.target, 'reading.label');
+      if(entry?.ref !== undefined) issues.push('reading.labels uses target for local identity; ref is reserved for bound CAP references');
+      if (!nonempty(entry?.title) || labelled.has(entry?.target)) issues.push('reading.labels needs unique references and nonempty titles');
+      labelled.add(entry?.target);
+    }
+  }
+  for (const experiment of research.experiments ?? []) {
+    const intent = experiment.researchIntent;
+    if (intent === undefined) continue;
+    for (const field of ['question', 'comparison', 'criterion']) if (!nonempty(intent?.[field])) issues.push(`experiment ${experiment.id}.researchIntent.${field} must be nonempty`);
+    reference(intent?.from, `experiment ${experiment.id}.researchIntent.from`);
+    reference(intent?.to, `experiment ${experiment.id}.researchIntent.to`);
+    if (!experiment.claimIds?.some(id => intent?.to === `claim:${id}`)) issues.push(`experiment ${experiment.id}: researchIntent.to must be an explicitly targeted claim`);
+    for (const id of list(intent?.context ?? [], `experiment ${experiment.id}.researchIntent.context`)) reference(id, `experiment ${experiment.id}.researchIntent.context`);
+  }
+}

package/src/research/research-objects.mjs

@@ -0,0 +1,88 @@
+import { CONTEXT_ROLES } from './research-map.mjs';
+import { isRecord, sha256Value } from '../util.mjs';
+import { validateSourceObservations } from './source-observations.mjs';
+
+export const RESEARCH_OBJECT_ROLES = new Set(['dataset', 'sample', 'model', 'checkpoint', 'code', 'method', 'observation', 'material', ...Object.keys(CONTEXT_ROLES)]);
+export const RESEARCH_STEP_KINDS = new Set(['preparation', 'collection', 'preprocessing', 'training', 'evaluation', 'analysis']);
+
+/** IDs are explicit scientific identities. Names never merge objects or steps. */
+export function validateResearchObjects(research, issues) {
+  const objects = research.researchObjects ?? [];
+  if (!Array.isArray(objects)) { issues.push('researchObjects must be an array'); return []; }
+  const boundSources = new Set();
+  const ids = new Set(), sourceIds = new Set((research.sources ?? []).map(item => item.id));
+  const claimIds = new Set((research.claims ?? []).map(item => item.id));
+  const steps = new Map();
+  const checkIds = (values, allowed, label) => {
+    if (values === undefined) return;
+    if (!Array.isArray(values)) { issues.push(`${label} must be an array`); return; }
+    for (const value of values) if (typeof value !== 'string' || !allowed.has(value)) issues.push(`${label} references an unknown identity: ${String(value)}`);
+    if (new Set(values).size !== values.length) issues.push(`${label} contains duplicate identities`);
+  };
+  for (const [index, object] of objects.entries()) {
+    const label = `researchObjects[${index}]`;
+    if (!isRecord(object)) { issues.push(`${label} must be an object`); continue; }
+    for (const field of ['id', 'title']) if (typeof object[field] !== 'string' || !object[field].trim()) issues.push(`${label}.${field} must be nonempty`);
+    if (ids.has(object.id)) issues.push(`Duplicate research object id: ${object.id}`);
+    ids.add(object.id);
+    if (!RESEARCH_OBJECT_ROLES.has(object.role)) issues.push(`${label}.role is unsupported`);
+    if (object.observationKind !== undefined && (object.role !== 'observation'
+      || !['scalar', 'table', 'matrix', 'series', 'collection'].includes(object.observationKind))) issues.push(`${label}.observationKind must describe an observation`);
+    if (object.basis !== undefined && !['declared', 'inferred'].includes(object.basis)) issues.push(`${label}.basis cannot claim actual observation during planning`);
+    if (object.prospective !== undefined && typeof object.prospective !== 'boolean') issues.push(`${label}.prospective must be boolean`);
+    if (object.sourceId !== undefined) {
+      const source = research.sources.find(source => source.id === object.sourceId);
+      if (!source || source.kind === 'paper') issues.push(`${label}.sourceId must identify an existing scientific material, not a paper mention`);
+      if (boundSources.has(object.sourceId)) issues.push(`${label}.sourceId is already represented by another object`);
+      boundSources.add(object.sourceId);
+      if (object.prospective === true) issues.push(`${label} cannot replace an existing source with a prospective object`);
+      for (const [key, expected] of [['uri', source?.uri], ['version', source?.version], ['revision', source?.kind === 'repository' ? source.version : undefined], ['digest', source?.digest]]) {
+        if (expected && object.identity?.[key] !== undefined && object.identity[key] !== expected) issues.push(`${label}.identity.${key} conflicts with its fixed source`);
+      }
+    }
+    if (object.sourceLocators !== undefined && !Array.isArray(object.sourceLocators)) { issues.push(`${label}.sourceLocators must be an array`); continue; }
+    for (const locator of object.sourceLocators ?? []) if (!sourceIds.has(locator?.sourceId) || typeof locator?.locator !== 'string' || !locator.locator.trim()) issues.push(`${label}.sourceLocators requires fixed source identities and locations`);
+    if (object.identity !== undefined && !isRecord(object.identity)) issues.push(`${label}.identity must be an object`);
+  }
+  for (const [index, object] of objects.entries()) if (isRecord(object)) checkIds(object.derivedFromIds, ids, `researchObjects[${index}].derivedFromIds`);
+  for (const claim of research.claims ?? []) {
+    checkIds(claim.objectIds, ids, `claim ${claim.id}.objectIds`);
+    for (const measurement of claim.reportedMeasurements ?? []) checkIds(measurement.objectIds, ids, `measurement ${measurement.id}.objectIds`);
+  }
+  const prospective = new Set(objects.filter(object => object?.prospective === true).map(object => object.id));
+  for (const experiment of research.experiments ?? []) {
+    checkIds(experiment.inputIds, ids, `experiment ${experiment.id}.inputIds`);
+    if (experiment.steps !== undefined && !Array.isArray(experiment.steps)) { issues.push(`experiment ${experiment.id}.steps must be an array`); continue; }
+    for (const step of experiment.steps ?? []) {
+      const label = `experiment ${experiment.id}.step ${step?.id}`;
+      if (!isRecord(step)) { issues.push(`${label} must be an object`); continue; }
+      for (const field of ['id', 'title']) if (typeof step[field] !== 'string' || !step[field].trim()) issues.push(`${label}.${field} must be nonempty`);
+      if (!RESEARCH_STEP_KINDS.has(step.kind)) issues.push(`${label}.kind is unsupported`);
+      checkIds(step.inputIds, ids, `${label}.inputIds`);
+      checkIds(step.outputIds, prospective, `${label}.outputIds (prospective objects only)`);
+      checkIds(step.claimIds, claimIds, `${label}.claimIds`);
+      const content = { ...step }; delete content.claimIds;
+      const prior = steps.get(step.id);
+      if (prior && sha256Value(prior) !== sha256Value(content)) issues.push(`Shared scientific step ${step.id} has conflicting definitions`);
+      steps.set(step.id, content);
+    }
+  }
+  for (const [id, step] of steps) {
+    checkIds(step.dependsOn, new Set(steps.keys()), `step ${id}.dependsOn`);
+    if (step.dependsOn?.includes(id)) issues.push(`step ${id} cannot depend on itself`);
+  }
+  validateSourceObservations(research, issues);
+  return structuredClone(objects);
+}
+
+/** Preserve source objects; preparation adds new specifications without rewriting source identity. */
+export function mergeResearchObjects(source = [], additions = []) {
+  const merged = new Map(source.map(object => [object.id, structuredClone(object)]));
+  if (!Array.isArray(additions)) throw Error('Preparation researchObjects must be an array');
+  for (const object of additions) {
+    const original = merged.get(object?.id);
+    if (original && sha256Value(original) !== sha256Value(object)) throw Error(`Preparation cannot overwrite source research object ${object.id}; create a distinct derived object`);
+    merged.set(object.id, structuredClone(object));
+  }
+  return [...merged.values()];
+}