核心概念

研究仓库快照的对象链——Paper、Claim、Experiment、Run、Evidence、Attestation，以及验证三环与 License Gate 的判定规则。

CiteArk 把每篇论文变成一个“研究仓库”。仓库在某个时刻的完整状态（快照）由一条对象链组成：论文被结构化后拆解出可验证的结论，结论关联实验方案，实验被真实执行后产生运行记录，运行留下证据对象，并由执行证明签名固化。

Paper（论文）
  └── Claim（结论）            从论文拆解出的可验证科学结论
       └── Experiment（实验）   验证结论的实验方案
            └── Run（执行）      一次真实运行记录
                 ├── Evidence（证据）      运行产生的指标、产物、日志等
                 └── Attestation（证明）   对本次执行的签名证明

研究仓库快照

GET /api/repositories?owner=<所有者>&slug=<仓库名> 返回 { "repository": … }，即仓库快照。顶层字段：

字段	说明
`id`	仓库内部 ID
`owner`	所有者（用户或组织名）
`slug`	仓库名；与 `owner` 构成页面地址 `/r/<owner>/<slug>`
`title`	标题
`description`	简介
`visibility`	可见性：`public` / `private`
`license`	仓库记录的许可标识
`licenseGate`	License Gate 判定结果，见下文 License Gate
`topics`	主题标签
`head`	当前头部 commit（含 `id`、`treeDigest`、`parentIds`、`message`、`author`、`authoredAt`）
`readme`	编译 Agent 生成的论文概览 Markdown
`sources[]`	来源对象：论文、代码仓库、数据集等（`kind`、`uri`、`digest`、`capturedAt`）
`files[]`	当前快照的文件清单（路径、类型、`digest`、大小、角色）
`claims[]`	拆解出的可验证结论，见下文 Claims
`experiments[]`	实验方案，见下文 Experiments
`runs[]`	执行记录，见下文 Runs
`evidence[]`	证据对象，见下文 Evidence 与内容寻址
`compilation`	论文结构化编译记录（状态、输入摘要、输出 commit、证明）
`starCount`	加星数
`requestCount`	社区“求复现”投票数
`forkCount`	Fork 数
`forkedFrom`	Fork 来源（源仓库与 commit）
`createdAt` / `updatedAt`	创建与最近更新时间

Claims

Claim 是从论文拆解出的一条可验证科学结论。

字段	说明
`id`	结论 ID（仓库内唯一）
`versionId`	该版本内容的 `sha256:` 摘要
`statement`	结论陈述
`sourceLocator`	在原文中的定位
`type`	`finding` / `method` / `measurement` / `limitation`
`verification`	验证状态，枚举见下
`experimentIds`	关联的实验 ID
`evidenceIds`	关联的证据 ID
`successfulIndependentRuns`	独立复现成功次数
`failedIndependentRuns`	独立复现失败次数

verification 状态枚举：unverified、review_required、queued、running、verified、failed、inconclusive、cancelled、timed_out。

Experiments

Experiment 是验证一组 claim 的实验方案。

字段	说明
`id`	实验 ID
`versionId`	该版本内容的 `sha256:` 摘要
`title`	实验标题
`claimIds`	针对的结论 ID
`command`	执行命令
`environmentDigest`	执行环境的 `sha256:` 摘要
`expectedMetrics`	期望指标数组：`name`、`comparator`（`>=` / `<=` / `~=` / `=`）、`target`、`tolerance`（可选）
`reproductionLevel`	复现级别：`directional` / `official-checkpoint` / `full-training`
`executor`	执行器，两种取值见下

executor 两种：

builtin：受控私测执行器（handler 为 ara-structure-v1，记录 sourceRepository、sourceCommit 与 requiredPaths）。生产复现队列目前只接受这种执行器的实验。
agent：Agent 执行器，availability 为 private-beta 或 unavailable。

Runs

发起复现是异步的：POST /api/runs 成功时返回 202 与一条 state=queued 的 run 记录，执行在响应返回后于后台进行。客户端轮询仓库快照中的 runs[]，直到该 run 进入终态（verified / failed 等）。

RunRecord 关键字段：

字段	说明
`id`	运行 ID
`repositoryId`	所属仓库
`commitId`	执行的仓库 commit（`sha256:` 摘要）
`experimentVersionId`	执行的实验版本（`sha256:` 摘要）
`claimIds`	针对的结论 ID
`state`	运行状态，与 claim 的 `verification` 同一枚举（`queued` / `running` / `verified` / `failed` 等）
`queuedAt` / `startedAt` / `finishedAt`	排队、开始与结束时间
`agent`	执行 Agent 信息（provider、model、prompt 与工具策略摘要等）
`environment`	执行环境（容器镜像与摘要、runner、云与区域、CPU/内存/GPU）
`inputDigests` / `outputDigests`	输入与输出的 `sha256:` 摘要清单
`metrics`	实测指标
`outputs`	类型化科学产物（`table`、`figure`、`dataset`、`model`、`checkpoint`、`text`、`archive`、`audio`、`video` 或 `other`），包含角色、摘要、媒体类型、存储方式和关联证据 ID
`log`	执行日志流（`system` / `stdout` / `stderr` / `tool`）
`attestation`	执行证明，见下文 Attestation

Evidence 是运行产生的证据对象：kind 为 metric / artifact / log / checkpoint / figure，另有 digest、uri、generatedByRunId 与 summary。Evidence 用于支持验证，runs[].outputs 则记录执行实际产生了什么科研产物；同一内容寻址文件可以同时承担两种角色。

所有二进制对象都按内容寻址：digest 即内容的 sha256。下载走 GET /api/objects/{64 位 hex}（digest 去掉 sha256: 前缀），响应头 x-content-sha256 给出完整的 sha256:<hex>，调用方可重新计算下载内容的 sha256 与之比对，校验完整性。服务端在返回前也会校验存储对象的摘要与字节数，不一致则返回 502。

Attestation

每个 run 都带一条执行证明（AttestationRecord）：statementDigest、nodeId、keyId、algorithm（ed25519 / ecdsa-p256 / pending）、signature、signedAt，以及 transparencyLog（透明日志的 index、entryDigest、previousEntryDigest）。刚进入队列的 run 证明为 pending，执行完成后才签名。

按 statementDigest 查询证明：GET /api/attestations/{64 位 hex}，返回：

{
  "attestation": { "statementDigest": "sha256:…", "signature": "…", "transparencyLog": { "index": 1, "entryDigest": "sha256:…" } },
  "verified": true,
  "verificationMethod": "ECDSA P-256 over CiteArk canonical JSON"
}

verified 不是存储的标记，而是服务端在响应时用证明中的公钥对签名现场验签的结果。

验证三环 Run · Match · Repeat

Run · Match · Repeat 是 CiteArk 的统一信任语言，判定逻辑在 src/domain/rings.ts 的 deriveVerificationRings：

Run：runs[] 中存在 state=verified 的运行——代码真的跑起来过。
Match：某个 verified run 的 claimIds 与 verification=verified 的 claim 集合有交集——运行结果支撑论文报告值。
Repeat：任一 claim 的 successfulIndependentRuns > 0——已有独立 Agent / runner / 环境复现成功。

三环严格递进：successfulIndependentRuns 只在独立复现验证通过时增加，因此 Repeat 亮起时 Match 与 Run 必然已亮（Repeat ⇒ Match ⇒ Run）。三个环只能由真实执行证据点亮，不允许只凭文字判断。

实心圆点与外圈含义不同：●●● 表示 Repeat；只有达到 L5，即论文作者或可信机构对当前 Artifact root 完成可验证签名确认后，才显示为 ◉◉◉。普通 runner attestation、社区复现或 Agent 文字结论都不得产生外圈。

徽章等级与三环同源（src/domain/badge.ts）：L2 reproduced = Match，L1 executed = Run，L0 indexed = compilation.state === verified。

License Gate

快照中的 licenseGate 字段记录许可判定结果：

字段	说明
`status`	`green` / `yellow` / `red`
`paperLicense`	论文许可
`codeLicense`	代码许可（可无）
`sourceUrl`	原始来源 URL
`discoverable`	CiteArk 是否可以发现并固定公开研究来源
`executable`	CiteArk 是否可以在隔离沙箱中执行研究
`redistributable`	CiteArk 是否可以再分发第三方源材料
`artifactPublishable`	CiteArk 是否可以发布派生执行记录
`submitterAttested`	提交者是否已声明其有权提交并处理这些材料
`reason`	判定理由
`assessedAt`	判定时间

判定规则（src/domain/license.ts 的 assessLicense，按顺序匹配）：

提交者未声明权属（submitterAttested=false）→ red；
论文许可属于开放集合（CC0-1.0、CC-BY-4.0、CC-BY-SA-4.0、MIT、Apache-2.0）且代码许可可执行（未提供、no-code，或 MIT、Apache-2.0、BSD-2-Clause、BSD-3-Clause、ISC、MPL-2.0、GPL-3.0-only 之一）→ green；
论文许可为 publisher-restricted → red；
其余 → yellow。

派生字段：

discoverable 与 executable 跟随提交者声明，不受源材料再分发权影响；
redistributable 在提交者已声明且论文许可本身开放时为 true，不依赖单独的代码许可判定；
artifactPublishable 覆盖 CiteArk 自行生成的指标、日志、轨迹、类型化科学产物、签名与验证记录。CAP 不包含第三方论文、代码仓库、数据集或 checkpoint 源负载；由本次执行真正生成的数据集或 checkpoint，在许可允许时可以作为派生产物发布。

因此，许可状态是源材料处理与风险标记，不再是入库或执行闸门。黄区和红区仓库仍可发现与执行；除非存在明确再分发授权，第三方源材料仍只保留链接。

许可不允许重新分发的论文 PDF 经 /api/objects 下载会返回 451（“论文许可不允许 CiteArk 重新分发，请访问原始来源”），页面只回链原始来源。

公开投影

仓库快照是内部读模型，非 owner 读取公开仓库时，快照会先经过公开投影（src/server/public-projection.ts）再序列化：

sources[]、evidence[] 与 runs[].outputs[] 中的内部存储 URI（r2:// 等）被改写为 /api/objects/<hex>；外部 URL 会被去掉用户名密码与敏感查询参数；
runs[] 的 requestedBy 被抹除；
run.log 只保留 system / stdout 流，每条消息截断到 4000 字符，并脱敏 Bearer token 与 api_key / token / secret / password / authorization 等赋值。

本页目录