@citeark/agent 0.3.20

package/src/gcp/storage.mjs

@@ -0,0 +1,220 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, stat } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import path from "node:path";
+
+import { googleApiError } from "./rest.mjs";
+import { CiteArkError } from "../util.mjs";
+import { executeObservedExternalRequest } from "../observability/event-contract.mjs";
+
+export class GcsStagingClient {
+  constructor({ auth, fetchImpl = fetch, observe, correlation } = {}) {
+    this.auth = auth;
+    this.fetchImpl = fetchImpl;
+    this.observe = observe;
+    this.correlation = correlation;
+  }
+
+  async uploadFile({ bucket, object, filePath, contentType = "application/gzip" }) {
+    const file = await stat(filePath);
+    const url = new URL(`https://storage.googleapis.com/upload/storage/v1/b/${encodeURIComponent(bucket)}/o`);
+    url.searchParams.set("uploadType", "resumable");
+    url.searchParams.set("name", object);
+    const authorization = await this.auth.headers();
+    const session = await this.#request(url, {
+      method: "POST",
+      headers: {
+        ...authorization,
+        "Content-Type": "application/json; charset=UTF-8",
+        "X-Upload-Content-Type": contentType,
+        "X-Upload-Content-Length": String(file.size),
+      },
+      body: JSON.stringify({ name: object }),
+    }, "gcs_upload_session", { bucket, object });
+    if (!session.ok) throw await googleApiError(session, "POST", url);
+    const sessionUrl = session.headers.get("location");
+    if (!sessionUrl) throw new CiteArkError("Cloud Storage resumable upload 没有返回 session URL");
+    const response = await this.#request(sessionUrl, {
+      method: "PUT",
+      headers: {
+        ...authorization,
+        "Content-Type": contentType,
+        "Content-Length": String(file.size),
+      },
+      body: createReadStream(filePath),
+      duplex: "half",
+    }, "gcs_upload_object", { bucket, object });
+    if (!response.ok) throw await googleApiError(response, "PUT", sessionUrl);
+    return await response.json();
+  }
+
+  async downloadFile({ bucket, object, filePath }) {
+    const url = new URL(`https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(object)}`);
+    url.searchParams.set("alt", "media");
+    const response = await this.#request(
+      url,
+      { headers: await this.auth.headers() },
+      "gcs_download_object",
+      { bucket, object },
+    );
+    if (!response.ok) throw await googleApiError(response, "GET", url);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(filePath));
+    return filePath;
+  }
+
+  async readObjectBytes({ bucket, object, offset = 0 }) {
+    const url = new URL(`https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(object)}`);
+    url.searchParams.set('alt', 'media');
+    const response = await this.#request(url, {
+      headers: { ...await this.auth.headers(), Range: `bytes=${offset}-` },
+    }, 'gcs_read_live_trace', { bucket, object });
+    if (response.status === 404 || response.status === 416) return Buffer.alloc(0);
+    if (!response.ok) throw await googleApiError(response, 'GET', url);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    return response.status === 206 ? bytes : bytes.subarray(offset);
+  }
+
+  async readJsonObject({ bucket, object, missing = undefined }) {
+    const url = new URL(`https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(object)}`);
+    url.searchParams.set("alt", "media");
+    const response = await this.#request(
+      url,
+      { headers: await this.auth.headers() },
+      "gcs_read_json_object",
+      { bucket, object },
+    );
+    if (response.status === 404 && missing !== undefined) return missing;
+    if (!response.ok) throw await googleApiError(response, "GET", url);
+    return JSON.parse(await response.text());
+  }
+
+  async writeJsonObject({ bucket, object, value, ifGenerationMatch }) {
+    const url = new URL(`https://storage.googleapis.com/upload/storage/v1/b/${encodeURIComponent(bucket)}/o`);
+    url.searchParams.set("uploadType", "media");
+    url.searchParams.set("name", object);
+    if (ifGenerationMatch !== undefined) {
+      url.searchParams.set("ifGenerationMatch", String(ifGenerationMatch));
+    }
+    const response = await this.#request(url, {
+      method: "POST",
+      headers: {
+        ...await this.auth.headers(),
+        "Content-Type": "application/json; charset=UTF-8",
+      },
+      body: `${JSON.stringify(value, null, 2)}\n`,
+    }, "gcs_write_json_object", { bucket, object });
+    if (!response.ok) throw await googleApiError(response, "POST", url);
+    return await response.json();
+  }
+
+  async createJsonObjectIfAbsent({ bucket, object, value }) {
+    const url = new URL(`https://storage.googleapis.com/upload/storage/v1/b/${encodeURIComponent(bucket)}/o`);
+    url.searchParams.set("uploadType", "media");
+    url.searchParams.set("name", object);
+    url.searchParams.set("ifGenerationMatch", "0");
+    const response = await this.#request(url, {
+      method: "POST",
+      headers: {
+        ...await this.auth.headers(),
+        "Content-Type": "application/json; charset=UTF-8",
+      },
+      body: `${JSON.stringify(value, null, 2)}\n`,
+    }, "gcs_create_json_object", { bucket, object });
+    if (response.status === 412) return null;
+    if (!response.ok) throw await googleApiError(response, "POST", url);
+    return await response.json();
+  }
+
+  async readJsonObjectVersion({ bucket, object, missing = undefined }) {
+    const metadataUrl = new URL(`https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(object)}`);
+    const metadataResponse = await this.#request(
+      metadataUrl,
+      { headers: await this.auth.headers() },
+      "gcs_read_object_metadata",
+      { bucket, object },
+    );
+    if (metadataResponse.status === 404 && missing !== undefined) return missing;
+    if (!metadataResponse.ok) throw await googleApiError(metadataResponse, "GET", metadataUrl);
+    const metadata = await metadataResponse.json();
+    const generation = String(metadata.generation ?? "");
+    if (!/^\d+$/.test(generation)) {
+      throw new CiteArkError("Cloud Storage 对象缺少 generation，无法安全读取");
+    }
+    const mediaUrl = new URL(metadataUrl);
+    mediaUrl.searchParams.set("alt", "media");
+    mediaUrl.searchParams.set("ifGenerationMatch", generation);
+    const mediaResponse = await this.#request(
+      mediaUrl,
+      { headers: await this.auth.headers() },
+      "gcs_read_versioned_json_object",
+      { bucket, object },
+    );
+    if (!mediaResponse.ok) throw await googleApiError(mediaResponse, "GET", mediaUrl);
+    return { generation, value: JSON.parse(await mediaResponse.text()) };
+  }
+
+  async copyObject({ sourceBucket, sourceObject, destinationBucket: bucket, destinationObject: object }) {
+    if (![sourceBucket, sourceObject, bucket, object].every((value) => typeof value === "string" && value.length > 0))
+      throw new CiteArkError("Cloud copy requires source and destination bucket/object");
+    const base = `https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(sourceBucket)}/o/${encodeURIComponent(sourceObject)}/rewriteTo/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(object)}`;
+    let token;
+    do {
+      const url = new URL(base);
+      if (token) url.searchParams.set("rewriteToken", token);
+      const response = await this.#request(url, { method: "POST", headers: { ...await this.auth.headers(), "Content-Type": "application/json" }, body: "{}" }, "gcs_copy_recovery_object", { bucket, object });
+      if (!response.ok) throw await googleApiError(response, "POST", url);
+      const result = await response.json();
+      if (result.done) return result.resource;
+      token = result.rewriteToken;
+      if (!token) throw new CiteArkError("Cloud recovery copy did not provide a continuation token");
+    } while (token);
+  }
+
+  async listObjects({ bucket, prefix }) {
+    const names = [];
+    let pageToken = null;
+    do {
+      const url = new URL(`https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(bucket)}/o`);
+      url.searchParams.set("prefix", prefix);
+      if (pageToken) url.searchParams.set("pageToken", pageToken);
+      const response = await this.#request(
+        url,
+        { headers: await this.auth.headers() },
+        "gcs_list_objects",
+        { bucket, prefix },
+      );
+      if (!response.ok) throw await googleApiError(response, "GET", url);
+      const page = await response.json();
+      names.push(...(page.items ?? []).map((item) => item.name).filter(Boolean));
+      pageToken = page.nextPageToken ?? null;
+    } while (pageToken);
+    return names;
+  }
+
+  async deleteObject({ bucket, object, ifGenerationMatch }) {
+    const url = new URL(`https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(object)}`);
+    if (ifGenerationMatch !== undefined) {
+      url.searchParams.set("ifGenerationMatch", String(ifGenerationMatch));
+    }
+    const response = await this.#request(url, {
+      method: "DELETE",
+      headers: await this.auth.headers(),
+    }, "gcs_delete_object", { bucket, object });
+    if (!response.ok && response.status !== 404) throw await googleApiError(response, "DELETE", url);
+  }
+
+  async #request(url, init, operation, correlation) {
+    return executeObservedExternalRequest({
+      request: async () => await this.fetchImpl(url, init),
+      observe: this.observe,
+      component: "gcp_client",
+      service: "storage.googleapis.com",
+      operation,
+      method: init.method ?? "GET",
+      url,
+      correlation: { ...this.correlation, ...correlation },
+    });
+  }
+}

package/src/graph/command.mjs

@@ -0,0 +1,41 @@
+import { buildArkGraphPresentation } from './presentation.mjs';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { readCapArchive } from '../cap/v2/read.mjs';
+import { createArkGraph, queryArkGraph, getArkGraphRecord, deriveArkRoute, compareArkRoutes, traceArkGraphProvenance } from './query.mjs';
+
+export async function graphCommand(args, parseOptions) {
+  const options = parseOptions(args, { '--cap': { type: 'string' }, '--server': { type: 'string' },
+    '--query': { type: 'string' }, '--operation': { type: 'string', default: 'subgraph' } });
+  const query = options['--query'] ? JSON.parse(await readFile(path.resolve(options['--query']), 'utf8')) : {};
+  const operation = options['--operation'];
+  if (options['--server']) {
+    if (operation === 'presentation') throw Error('presentation 当前使用本地 --cap；网站读模型尚未切换');
+    const base = new URL(options['--server']);
+    if (base.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(base.hostname)) throw Error('远程查询必须使用 HTTPS');
+    const token = process.env.CITEARK_API_KEY;
+    const response = await fetch(new URL('/api/v1/graph', base), { method: 'POST',
+      headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify({ ...query, operation }) });
+    const value = await response.json();
+    if (!response.ok) throw Error(value.error ?? `查询失败：${response.status}`);
+    console.log(JSON.stringify(value, null, 2)); return;
+  }
+  if (!options['--cap']) throw Error('graph 需要 --cap（多个文件用逗号分隔）或 --server');
+  const temporary = await mkdtemp(path.join(os.tmpdir(), 'citeark-graph-'));
+  try {
+    const artifacts = [];
+    for (const [index, filename] of options['--cap'].split(',').entries()) artifacts.push(await readCapArchive(path.resolve(filename), path.join(temporary, String(index))));
+    const graph = createArkGraph(artifacts);
+    let value;
+    if (operation === 'subgraph') value = queryArkGraph(graph, query);
+    else if (operation === 'presentation') value = buildArkGraphPresentation(graph, query);
+    else if (operation === 'record') value = getArkGraphRecord(graph, query.reference);
+    else if (operation === 'route') value = deriveArkRoute(graph, query);
+    else if (operation === 'provenance') value = traceArkGraphProvenance(graph, query.reference, query);
+    else if (operation === 'compare') value = compareArkRoutes(deriveArkRoute(graph, query.left), deriveArkRoute(graph, query.right), { targets: query.targets });
+    else throw Error('未知 graph 操作');
+    console.log(JSON.stringify(value, null, 2));
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}

package/src/graph/execution.mjs

@@ -0,0 +1,97 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CAP_RECORD_TYPE as T } from './model.mjs';
+import { canonicalJsonBytes, sha256Bytes } from '../cap/v2/canonical-json.mjs';
+import { redactSensitive, redactString } from '../cap/redaction.mjs';
+
+const id = (kind, identity) => `urn:citeark:${kind}:${sha256Bytes(Buffer.from(identity)).slice(7)}`;
+const ref = id => ({ ref: id });
+const entity = (id, role, content) => ({ $schema: 'https://citeark.com/schemas/cap/v2/entity.schema.json', id, type: T.entity, role, ...content });
+
+/** Materialize captured inputs, process steps and trace provenance. No model calls or experiments. */
+export async function enrichExecutionGraph({ runDirectory, physicalRunId, ids, actualContract,
+  executionRecord, experimentRecord, assessmentRecord, runnerAudit, evidenceContext, rawEvidenceRecords,
+  blobByDigest, addBytesBlob, objectGraph }) {
+  const records = [];
+  const edge = (predicate, subject, object, basis = 'declared', qualifiers = {}, sources = []) => {
+    records.push({ $schema: 'https://citeark.com/schemas/cap/v2/relation.schema.json',
+      id: id('relation', JSON.stringify([predicate, subject, object, qualifiers])), type: T.relation, role: 'provenance',
+      predicate, subject: ref(subject), object: ref(object), basis, attributedTo: ref(ids.assembler),
+      sources: sources.map(ref), qualifiers });
+  };
+  edge('follows', ids.execution, ids.experiment, 'declared', {}, [ids.experiment]);
+  const repository = actualContract.repository ?? {};
+  const observedRevision = executionRecord.codeState.observedRevision;
+  const codeId = id('code', `${repository.url}@${observedRevision ?? repository.commit}`);
+  const code = objectGraph?.records.find(record => record.id === codeId);
+  if (!code) records.push(entity(codeId, 'code', { title: repository.url, identity: { uri: repository.url, revision: observedRevision ?? repository.commit }, basis: observedRevision ? 'observed' : 'declared' }));
+  if (code) { code.observedRevision = executionRecord.codeState.observedRevision; code.basis = executionRecord.codeState.observedRevision ? 'observed' : 'declared'; }
+  edge('used', ids.execution, codeId, executionRecord.codeState.observedRevision ? 'observed' : 'declared');
+  // These small retained files describe externally observable inputs and changes.
+  for (const [filename, role, relationship] of [
+    ['input/agent-instructions.md', 'prompt', 'used'],
+    ['execution/workspace-changes.json', 'code-patch', 'generated'],
+  ]) {
+    const bytes = await readFile(path.join(runDirectory, filename)).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (!bytes) continue;
+    const cleaned = role === 'code-patch' ? canonicalJsonBytes(redactSensitive(JSON.parse(bytes.toString('utf8')))) : Buffer.from(redactString(bytes.toString('utf8')));
+    const blob = addBytesBlob({ id: id('blob', `${physicalRunId}:${role}`), roles: [role], mediaType: role === 'prompt' ? 'text/markdown' : 'application/json', bytes: cleaned });
+    const materialId = id(role, `${physicalRunId}:${filename}`);
+    records.push(entity(materialId, role, { title: filename, blobs: [blob.digest], basis: 'observed',
+      disclosure: { redacted: !bytes.equals(cleaned), originalDigest: sha256Bytes(bytes), captured: true } }));
+    edge(relationship, ids.execution, materialId, 'observed');
+  }
+  for (const blob of blobByDigest.values()) {
+    if (!blob.roles.some(role => ['execution-trace', 'runner-command-records', 'assessment-evidence-context'].includes(role))) continue;
+    const materialId = id('trace-material', blob.digest);
+    records.push(entity(materialId, blob.roles.includes('assessment-evidence-context') ? 'context' : 'trace', {
+      title: blob.roles.join(', '), blobs: [blob.digest], basis: 'observed',
+      disclosure: { level: blob.roles.includes('execution-trace') ? 'minimal' : 'audit', hiddenReasoning: false, availability: blob.availability },
+    }));
+    edge('describes', materialId, ids.execution, 'observed');
+    if (blob.roles.includes('assessment-evidence-context')) edge('basedOn', assessmentRecord.id, materialId, 'declared', { role: 'assessment-context' });
+  }
+  const assessor = assessmentRecord.citeark?.assessor;
+  if (assessor?.promptDigest) {
+    const promptId = id('prompt', assessor.promptDigest);
+    records.push(entity(promptId, 'prompt', { title: 'Assessment prompt and tool context', identity: { digest: assessor.promptDigest },
+      basis: 'declared', disclosure: { availability: 'digest-only', templateVersion: assessor.rubricVersion ?? null },
+    }));
+    edge('basedOn', assessmentRecord.id, promptId, 'declared', { role: 'prompt-context' });
+  }
+  // The helper records real invocations and plan snapshots, but its workspace is Agent-writable.
+  // Preserve that weaker basis instead of upgrading it to independent runner observation.
+  const eventText = await readFile(path.join(runDirectory, 'output/experiment-records.jsonl'), 'utf8').catch(error => { if (error.code === 'ENOENT') return ''; throw error; });
+  const events = new Map();
+  for (const line of eventText.split(/\r?\n/).filter(Boolean)) {
+    let event; try { event = JSON.parse(line); } catch { continue; }
+    if (!event.executionId || !event.startedAt || !Array.isArray(event.command)) continue;
+    events.set(event.executionId, { ...events.get(event.executionId), ...event });
+  }
+  const evidenceByPath = new Map(rawEvidenceRecords.map(record => [record.citeark.sourcePath, record.id]));
+  for (const event of events.values()) {
+    const stepId = id('activity', `${physicalRunId}:${event.executionId}`);
+    records.push({ $schema: 'https://citeark.com/schemas/cap/v2/activity.schema.json', id: stepId, type: T.activity, role: 'execution-step',
+      status: event.event === 'experiment_finished' ? event.exitCode === 0 ? 'succeeded' : 'failed' : 'unknown',
+      startedAt: event.startedAt, ...(event.finishedAt ? { endedAt: event.finishedAt } : {}),
+      ...(event.scientificStepId ? { scientificStepId: event.scientificStepId } : {}),
+      command: redactSensitive(event.command), planDigest: event.planDigest ?? null, basis: 'declared',
+      capture: { source: 'experiment-records.jsonl', boundary: 'agent-writable-helper-log' },
+    });
+    edge('partOf', stepId, ids.execution, 'declared');
+    const plannedStep = actualContract.researchGraph?.steps?.find(step => step.id === event.scientificStepId);
+    if (plannedStep) {
+      const procedureId = id('research-step', `${actualContract.research.workId}:${plannedStep.id}`);
+      if (objectGraph?.records.some(record => record.id === procedureId)) edge('follows', stepId, procedureId, 'declared', { capture: 'agent-writable-helper-log' });
+      for (const input of plannedStep.inputIds ?? []) {
+        const inputId = objectGraph?.objectIds.get(input);
+        if (inputId) edge('used', stepId, inputId, 'declared', { binding: 'agent-declared-scientific-step' });
+      }
+    }
+    for (const filename of [event.stdoutPath, event.stderrPath]) if (evidenceByPath.has(filename)) edge('generated', stepId, evidenceByPath.get(filename), 'declared');
+  }
+  // Missing detail is retained explicitly; commands are never classified into guessed training phases.
+  executionRecord.citeark.capture = { granularity: 'runner-process', stepLogAvailable: events.size > 0,
+    fineGrainedScientificPhases: 'not-classified', commandRecordCount: runnerAudit?.commandRecords?.length ?? 0 };
+  return records;
+}

package/src/graph/model.mjs

@@ -0,0 +1,37 @@
+/** CAP 2 scientific primitives. Roles refine a primitive; they never replace it. */
+export const CAP_RECORD_TYPE = Object.freeze(Object.fromEntries(
+  ['entity', 'activity', 'assertion', 'agent', 'relation'].map(name =>
+    [name, `https://citeark.com/cap/record-types/${name}/2.0`]),
+));
+export const CAP_RECORD_ROLE = Object.freeze({
+  actor: 'agent', sourceWork: 'source-work', claim: 'claim', experiment: 'procedure',
+  execution: 'execution', evidence: 'observation', assessment: 'assessment',
+});
+export const CAP_ROLE_TYPE = Object.freeze({
+  agent: 'agent', 'source-work': 'entity', claim: 'assertion', hypothesis: 'assertion',
+  question: 'entity', concept: 'entity', premise: 'assertion', argument: 'entity',
+  'research-plan': 'entity', 'research-activity': 'activity', 'source-assessment': 'assertion',
+  person: 'agent', organization: 'agent', instrument: 'entity',
+  'measurement-assessment': 'assertion', 'procedure-step': 'entity', procedure: 'entity', execution: 'activity', observation: 'entity', assessment: 'assertion',
+});
+/** Direction is subject -> object. Null permits any primitive except Relation. */
+export const CAP_PREDICATES = Object.freeze({
+  expects: ['entity', 'entity'], hasStep: ['entity', 'entity'], about: [null, 'entity'],
+  requires: ['entity', 'entity'], partOf: ['activity', 'activity'], used: ['activity', 'entity'], generated: ['activity', 'entity'],
+  follows: ['activity', 'entity'], associatedWith: ['activity', 'agent'],
+  derivedFrom: ['entity', 'entity'], assertedIn: ['assertion', 'entity'],
+  attributedTo: [null, 'agent'], plannedFor: ['entity', 'assertion'],
+  evidenceFor: ['entity', 'assertion'], assesses: ['assertion', 'assertion'],
+  basedOn: ['assertion', null], describes: ['entity', null],
+  revises: [null, null], supersedes: [null, null],
+});
+export const CAP_BASES = new Set(['observed', 'declared', 'inferred', 'attested']);
+export const CAP_ACTIVITY_STATUSES = new Set(['running', 'succeeded', 'failed', 'cancelled', 'partial', 'timedOut', 'unknown']);
+export function primitiveOf(record) {
+  return Object.entries(CAP_RECORD_TYPE).find(([, type]) => type === record?.type)?.[0] ?? null;
+}
+export function scientificProjections(records) {
+  return Object.fromEntries(Object.entries(CAP_RECORD_ROLE).map(([name, role]) =>
+    [name, records.filter(record => record.role === role)]));
+}
+export function referenceKey(reference) { return `${reference?.ref ?? ''}@${reference?.digest ?? ''}`; }

package/src/graph/presentation.mjs

@@ -0,0 +1,110 @@
+import { CAP_RECORD_TYPE, referenceKey } from './model.mjs';
+import {sourcePage} from './source-page.mjs';
+
+export const RESEARCH_READING_TYPES = Object.freeze({
+  question: '研究问题', concept: '概念与定义', hypothesis: '假说与前提', claim: '主张',
+  method: '方法', plan: '研究方案', activity: '研究活动', result: '观测与结果',
+  argument: '论证与证明', assessment: '评估', resource: '对象与资源', agent: '责任主体',
+});
+export function readingCategory(node) {
+  const role = node.role;
+  if (node.recordType === CAP_RECORD_TYPE.agent) return 'agent';
+  if (node.recordType === CAP_RECORD_TYPE.activity) return 'activity';
+  return ({question:'question', concept:'concept', hypothesis:'hypothesis', premise:'hypothesis',
+    claim:'claim', method:'method', procedure:'plan', 'procedure-step':'plan', 'research-plan':'plan',
+    observation:'result', argument:'argument', assessment:'assessment', 'measurement-assessment':'assessment',
+    'source-assessment':'assessment'})[role] ?? 'resource';
+}
+const titleOf = n => n.record.title ?? n.record.statement?.value ?? n.record.name ?? n.record.evaluationPlan?.title ?? n.role;
+
+/** A complete presentation of one authorized, verified snapshot. Never infer science
+ * from labels, discard hidden objects, or claim that a visual edge authorizes execution.
+ */
+export function buildArkGraphPresentation(graph, { artifactDigest } = {}) {
+  if (graph.truncated) throw Error('ArkGraph presentation requires a complete snapshot');
+  const digest = artifactDigest ?? (graph.artifacts.length === 1 ? graph.artifacts[0] : null);
+  if (!digest || !graph.artifacts.includes(digest)) throw Error('Choose one exact ArkGraph snapshot');
+  const records = graph.nodes.filter(n => n.artifacts.includes(digest));
+  const byRef = new Map(records.map(n => [n.ref, n])), byKey = new Map(records.map(n => [n.key, n]));
+  const source = records.find(n => n.role === 'source-work' && n.record.citeark?.reading)
+    ?? records.find(n => n.role === 'source-work');
+  const view = source?.record.citeark?.reading;
+  const resolve = reference => {
+    const node = reference?.digest ? byKey.get(referenceKey(reference)) : byRef.get(reference?.ref);
+    if (!node) throw Error(`Reading reference missing from snapshot: ${reference?.ref}`);
+    return node.key;
+  };
+  const labels = new Map((view?.labels ?? []).map(n => [resolve(n), n]));
+  const nodes = records.map(n => {
+    const r = n.record, category = readingCategory(n), label = labels.get(n.key);
+    const locations = r.citeark?.sourceLocators ?? r.sourceContext?.map(s => ({locator:s.selector?.label}))
+      ?? (r.citeark?.sourceLocator ? [r.citeark.sourceLocator] : []);
+    const measurements = (r.measurements ?? r.citeark?.reportedMeasurements ?? (r.measurement ? [r.measurement] : [])).map(m => ({
+      ...m, id: m.measurementId ?? m.id, value: m.value?.decimal ?? m.value,
+      dimensions: m.scope ?? m.dimensions ?? {}, conditions: m.conditions ?? {},
+    }));
+    return { key:n.key, local:r.citeark?.objectId ?? r.citeark?.localId ?? n.ref, ref:n.ref,
+      digest:n.digest, recordType:n.recordType, role:n.role, category,
+      subtype:label?.subtype ?? RESEARCH_READING_TYPES[category], label:label?.title ?? titleOf(n), brief:r.description ?? r.statement?.value ?? r.evaluationPlan?.instructions ?? r.abstract ?? '',
+      source:locations.map(s => s.locator).filter(Boolean).join(' · '),
+      sourceLocators: locations, sourcePage:sourcePage(locations) ?? undefined, measurements, conditions:r.conditions ?? r.citeark?.conditions ?? r.scope ?? {},
+      limitations:[...(r.citeark?.limitations ?? r.limitations ?? []), ...(r.citeark?.ambiguities ?? [])],
+      prospective:r.prospective === true || n.role === 'procedure' || n.role === 'procedure-step',
+      basis:r.basis ?? r.origin?.basis ?? null, raw:r,
+    };
+  });
+  const edges = graph.relations.filter(e => e.artifacts.includes(digest)).map(e => ({
+    id:e.key, ref:e.ref, digest:e.digest, from:referenceKey(e.subject), to:referenceKey(e.object),
+    predicate:e.predicate, basis:e.record.basis, raw:e.record,
+    available:byKey.has(referenceKey(e.subject)) && byKey.has(referenceKey(e.object)),
+    source:(e.record.qualifiers?.sourceLocators ?? []).map(s => s.locator).join(' · '),
+    qualification:e.record.qualifiers?.note ?? '',
+  }));
+  const spine = view?.mainline.map(resolve) ?? records.filter(n => n.role === 'claim').map(n => n.key);
+  if (!spine.length && nodes.length) spine.push(nodes[0].key);
+  const parentMap = new Map((view?.branches ?? []).flatMap(b => b.children.map(c => [resolve(c), resolve(b.parent)])));
+  const rootOf = key => { const seen = new Set(); while (parentMap.has(key)) { if (seen.has(key)) throw Error('Cyclic reading branches'); seen.add(key); key = parentMap.get(key); } return key; };
+  const groups = spine.map(parent => ({parent, label:labels.get(parent)?.title ?? titleOf(byKey.get(parent)),
+    members:nodes.filter(n => parentMap.get(n.key) === parent
+      && !['result', 'agent'].includes(n.category) && n.role !== 'source-work').map(n => n.key)}));
+  const primary = [...new Set([...spine, ...groups.flatMap(g => g.members)])];
+  const exact = node => ({ref:node.ref,digest:node.digest,recordType:node.recordType});
+  const experiments = records.filter(n => n.role === 'procedure').map((n, index) => {
+    const outgoing = (key, predicate) => edges.filter(e => e.available && e.from === key && e.predicate === predicate).map(e => e.to);
+    const targets = outgoing(n.key, 'plannedFor'), inputs = outgoing(n.key, 'requires');
+    const stepKeys = new Set(), visiting = new Set(), visit = key => { if (stepKeys.has(key)) return; if(visiting.has(key))throw Error('Cyclic scientific step dependencies'); visiting.add(key); for (const dependency of outgoing(key,'requires')) if (byKey.get(dependency)?.role === 'procedure-step') visit(dependency); visiting.delete(key); stepKeys.add(key); };
+    const declaredSteps = outgoing(n.key,'hasStep');
+    for (const reference of n.record.steps ?? []) { const key=resolve(reference); if(declaredSteps.includes(key))visit(key); }
+    for (const step of declaredSteps) visit(step);
+    const intent = n.record.citeark?.researchIntent, from = intent ? resolve(intent.from) : inputs.find(k => byKey.get(k).role === 'method') ?? inputs[0] ?? n.key;
+    const to = intent ? resolve(intent.to) : targets[0];
+    if (!to || !targets.includes(to)) throw Error(`Experiment ${n.ref} lacks its declared target`);
+    const context = [...new Set([from,to,...targets,...inputs,...(intent?.context ?? []).map(resolve)])];
+    return { id:n.key, experimentId:n.record.citeark?.localId, procedure:exact(n), index,
+      source:from, target:to, question:intent?.question ?? titleOf(n), title:titleOf(n),
+      summary:intent?.comparison ?? n.record.citeark?.protocol?.objective ?? '',
+      criterion:intent?.criterion ?? '',
+      limitations:[...new Set([...(n.record.citeark?.observationTargets ?? []).map(t=>t.limitation?.evidence),...targets.map(k=>byKey.get(k).record.citeark?.reproduction).filter(r=>r?.status==='blocked').map(r=>r.reason)].filter(Boolean))],
+      contextNodeIds:context, targetKeys:targets, inputKeys:inputs,
+      stepKeys:[...stepKeys], requiredProcedureKeys:inputs.filter(k => byKey.get(k).role === 'procedure'),
+      unresolvedInputs:edges.filter(e => e.from === n.key && e.predicate === 'requires' && !e.available).map(e => e.raw.object),
+    };
+  });
+  experiments.sort((a,b)=>spine.indexOf(rootOf(a.target))-spine.indexOf(rootOf(b.target)));
+  experiments.forEach((experiment,index)=>{experiment.index=index;});
+  // Visible candidate anchors are existing scientific objects; they are never new procedures.
+  for (const e of experiments) for (const id of [e.source,e.target]) if (!primary.includes(id)) {
+    primary.push(id); const group=groups.find(g => g.parent === rootOf(id)) ?? groups.find(g => g.parent === e.target) ?? groups[0];
+    if (group && id !== group.parent && !spine.includes(id) && !group.members.includes(id)) group.members.push(id);
+  }
+  const paperUri=source?.record.sources?.find(s=>s.kind==='paper')?.uri;
+  const sourceDocument=typeof paperUri==='string'&&/^https?:\/\//i.test(paperUri)?paperUri:undefined;
+  return { schemaVersion:'arkgraph-presentation/1', digest, sourceDocument, paperTitle:source?.record.title ?? 'ArkGraph',
+    titleZh:source?.record.title ?? 'ArkGraph', question:view?.overview ?? source?.record.abstract ?? '',
+    provenance:'Agent 生成 · 来源声明', nodes, edges, experiments,
+    presentation:{spine,primary,groups,contextGroups:[...new Set(parentMap.values())].map(parent=>({parent,children:nodes.filter(n=>parentMap.get(n.key)===parent&&!primary.includes(n.key)).map(n=>n.key)})),shortLabels:Object.fromEntries(nodes.map(n => [n.key,n.label]))},
+    classification:{assignments:Object.fromEntries(nodes.map(n => [n.key,{category:n.category,
+      subtype:labels.get(n.key)?.subtype ?? RESEARCH_READING_TYPES[n.category], reason:'', contextualRoles:[]}]))},
+    completeness:{nodes:records.length,relations:edges.length,unavailableRelations:edges.filter(e=>!e.available).length},
+  };
+}