paper-atlas/docs/operations.md

运行维护与数据核验

PostgreSQL 迁移

共享实例的容器名为 foundry-postgres，底层镜像为 postgres:17-alpine；Compose 服务名仍为 postgres。数据库和 schema 是可配置的逻辑边界，表按研究数据域组织，不按调用项目复制。其他项目可获授 research 的 USAGE 及必要表权限，复用相同论文 ID 和表。未来换库只更新 libpq service；换 schema 可更新角色 search_path 或查询的 --pg-schema。

复用已确认的现有实例，在共享 foundry_data 数据库按数据域使用 research schema 和专用角色，不修改其他业务库。安装、测试和构建在已批准的 ces-control:host 执行环境运行。libpq service 文件由服务器提供，权限必须为 0600，不得放进仓库或带密码的命令行参数。

冻结 SQLite 写入，确认维护进程实际结束、WAL 已清空；采集到独立文件不修改索引。迁移持有源维护锁和目标 advisory lock，还须确保没有绕过协调器的旧版手工写入。

export PGSERVICEFILE=/etc/paper-atlas/pg_service.conf
paper-atlas maintain postgres \
  --db /data/paper-index/papers.sqlite --pg-service foundry-research \
  --storage-path /var/lib/docker/volumes/endoleap-dev_postgres/_data \
  --min-free-gib 8 --out /data/paper-index/collected/postgres-migration.json

全部 21 张业务表保留原 ID、原始 JSON 文本、NULL、来源、投稿、决定、标签出处和合并记录。sqlite_sequence 用于重设 PostgreSQL identity 序列，并考虑已合并的历史 ID，避免复用；SQLite FTS5 shadow 表根据完整标题/摘要重建为原生 GIN 索引，不逐字复制引擎文件。

SQLite 允许文本包含 U+0000（NUL），PostgreSQL text 不允许。迁移使用 nul-soh-v1 可逆编码：NUL 存为 U+0001 U+0001，原有 U+0001 存为 U+0001 U+0002，其他字符不变；包括字串前缀在内的二进制排序保持一致，主键、唯一约束和外键可继续验证。编码版本保存在 <schema>_migration.run.text_codec，发布时同时写入 schema 注释 paper-atlas:text-codec=nul-soh-v1，其他项目只需研究表的权限即可读取格式信息，无须访问迁移控制表。CLI 的只读连接自动还原结果并编码筛选参数；直接 SQL/ETL 调用者应使用 paper_atlas.postgres.text.encode/decode，不能删除或直接替换控制字符。全文检索把这些控制字符当作分隔符，不承担逐字节匹配。

先 COPY 到独立暂存 schema，每张表提交和记录哈希。中断后以同一命令、同一报告路径恢复，必须仍是完全相同的未变更快照。不同输入、已发布目标、未清空 WAL、新的未知业务表都会拒绝覆盖；恢复只会清空本次运行尚未完成且尚未发布的暂存表。保留错误现场，不盲目从头复制。

恢复旧版本未发布的暂存数据时，在一个事务中转义已提交表里原有的 U+0001，然后记录新编码版本；失败回滚，重复恢复不会二次编码。已经提交的表无需从 SQLite 重新复制。报告中的 source_sha256、target_sha256 比较完整还原后的原始值；target_storage_sha256 另记实际存储值的哈希，包含转义的表两种哈希可以不同。

发布前逐表按主键完整回读，比较数量及逐行 SHA-256；建立并验证所有主键、唯一约束、CHECK 和外键，重设序列、建立 GIN 并 ANALYZE。全部通过后原子重命名为 research schema，报告才为 complete。copying、prepared、部分表通过或 CI 通过均不代表生产迁移完成，也不替代原任务最后的实体去重和会议覆盖审计。

发布后核对 PostgreSQL 的统计、全文检索、论文详情，以及 reject 后另会 accept 的历史。确认后保留 SQLite 只读备份，并在旁保存 <SQLite路径>.postgresql-cutover.json，记录报告路径、源哈希、目标 service/schema；新版本旧写入入口见此标记会拒绝写入。标记不含密码。后续导入适配属于下一阶段，不可继续更新 SQLite 后声称 PostgreSQL 已同步。

远程集成测试通过 PAPER_ATLAS_TEST_PG_SERVICE 显式指定，使用随机前缀 schema 并仅清理自己的 fixture；没有该配置时会跳过，应另外报告“未运行”，不能用 SQLite 测试代替 PostgreSQL 验证。

PostgreSQL 增量写入

import records、import arxiv、maintain backfill 使用 --pg-service 选择主库，--pg-schema 可覆盖配置的 search_path。写入只接受已经发布、拥有完整业务表和受支持编码标记的 schema，不自动建库或引导空表。SQLite 样本仍使用 --db，已切换备份继续禁止写入。

写入连接按数据库/schema 获取会话级 advisory lock，文件提交、回滚以及 arXiv 分批提交均不释放；关闭连接才释放，其他写入者立即得到明确的占用错误。只读查询继续使用独立一致性快照。锁是所有调用方必须遵守的协议，其他项目不要绕过接口并发修改同一论文和投稿；PostgreSQL 会话锁说明解释了其事务边界。

论文身份匹配、跨来源合并、投稿/决定来源和标签维护复用同一套领域逻辑。PostgreSQL 使用原生 RETURNING 和 identity 序列分配 ID，继承迁移时设定的历史 ID 高水位；失败和冲突尝试可以留下序列空洞，不能把最大 ID 当作行数。绑定文本按 nul-soh-v1 编码，结果解码，GIN 随论文写入自动更新。

会议文件的数据变化在同一事务内完成，manifest 数量不符等错误会回滚整份文件，ingest_runs 另保留 failed、已处理数和零写入数；身份回填整个队列一次提交。arXiv 每 500 行提交数据和 checkpoint，异常只回滚尚未提交部分，重试必须仍为同一压缩包。大批次开始前核对独立审计清单、当前主库冲突和磁盘空间；完成后对数量、实际来源/决定关联及检索做数据验收，代码测试成功不代表生产导入成功。

audit public-openreview --pg-service ... 在只读快照中核验两个受支持公开负面决定来源的固定 revision、逐文件哈希、manifest、原始出处标记和既有同届投稿。最新决定排序与查询端一致：观察时间、决定日期（为空时回退观察时间）、ID。实际导入持有写锁后再次复核该投稿的最新状态，阻止过期预检或弱来源标签覆盖冲突决定；冲突文件整体回滚并等待进一步证据核查，其他会议录用不构成同一次投稿的冲突。

会议导入按原始字节流计算 SHA-256，在提交前与 manifest 提供的 file_sha256 比较；不符则回滚整份文件。成功批次的 checkpoint 会记录实际读取内容的哈希，便于复核导入时使用的文件版本。

代码以固定 commit 部署，已经启动的任务继续使用其原版本。目录重构不要求迁移数据库，也不更改已有 JSONL 和 manifest 格式。

arXiv 原始编号与类别证据

原始行数、唯一 arXiv 编号数和合并后的论文实体数分别核验。以下只读原始压缩包，流式处理到 ZIP EOF/CRC 检查完成；输出审计 JSON 与编号 SQLite 索引，不修改论文主库：

paper-atlas audit arxiv --archive /data/paper-index/raw/arxiv-metadata.zip \
  --out /data/paper-index/collected/arxiv-source-audit.json

同编号的重复行会记录出现位置、次数和内容哈希版本，不直接视作不同论文；同篇论文的多个 arXiv 编号则保留各自来源及类别证据。旧导入器使用共享类别证据键，可能在论文实体合并时丢失某个编号的相同类别出处。新导入使用逐记录证据键；已有数据须在没有其他主库写入任务时按保留的来源 metadata 修复：

paper-atlas maintain arxiv-tags --db /data/paper-index/papers.sqlite \
  --out /data/paper-index/collected/arxiv-tag-repair.json

修复使用同一维护锁，分批提交并保存断点，保留 custom:* 和其他来源证据；失败后确认原因已解决，再增加 --resume 从上次提交位置继续。完成报告不能作为重新扫描的断点，重新核验应指定新报告。源审计和标签修复均保留 8 GiB 空闲空间，不能代替所有来源入库后的实体、投稿去重与完整性检查。

修复结束后还须核对每条 arXiv 来源记录的类别集合，不能只看旧证据键是否清零。下面的只读审计比较来源 metadata 中的类别、所属论文实体和逐记录证据键，同时检查没有合法 arXiv 来源的类别行：

paper-atlas audit arxiv-tags --db /data/paper-index/papers.sqlite \
  --repair-report /data/paper-index/collected/arxiv-tag-repair.json \
  --out /data/paper-index/collected/arxiv-tag-coverage-audit.json

审计持有共享维护锁；修复或其他协调写入尚未结束时会拒绝运行。提供修复报告时，还会核对其已完成状态、数据库路径和固定来源范围。审计以一致的只读快照分批读取，记录完整扫描数量、缺失/多余证据、错误论文归属、残留旧键及少量异常样例，不修改主库。

来源记录按整数主键区间读取，避免 SQLite 误选按 external_id 排列的来源索引、每批重新排序整个来源；其他来源交错在编号区间内时仍按 source_id 过滤。类别证据继续使用 source_record_id 索引批量读取。完整核验范围不因查询优化缩小。

只有全量记录核对完毕且无差异时才标记 passed；存在差异为 failed 并返回非零退出码，解析或执行中断为 error。运行中的报告不能作为完成证明。重新核验须使用新输出路径，不能覆盖已有报告；该检查不替代最后的实体去重、外键、SQLite 与全文索引核验。

长期维护与更新

1. 每次采集先核对来源、许可、可访问性、空闲空间和现有运行批次。保持低并发，遵守来源限流、重试与人机验证要求。
2. 下载先写 .part，确认完整 HTTP 响应和 ZIP 目录，再记录 SHA-256 与时间后切换为正式文件。正式导入会读至 EOF，从而验证成员 CRC。
3. 每次导入保留来源证据和批次，按会议/年份/track 报告覆盖状态。缺失摘要留空，不编造文本；缺失决定保留未知。
4. 核验行数、唯一标识、外键、全文查询和 SQLite 完整性后，再将批次视为交付。样本通过不能证明全量正确。
5. 数据库备份使用 SQLite backup API 或一致性快照，不能在写入过程中只复制 .sqlite 主文件而遗漏 WAL。按明确保留策略轮换备份，避免无上限积累。
6. 不为每次数据更新生成新 Docker 镜像；不常驻下载器；不自动创建定时任务。本项目的更新任务应按需或经用户授权调度。
7. 代码通过工作分支和 PR 交付；构建或 CI 只能使用用户确认的远程 runner，不在本机触发构建。

当前访问限制

2026-11-06 从目标服务器测试：Kaggle 元数据 GET 可下载；OpenReview 会议 group 接口可读，但 notes 接口返回 ChallengeRequiredError。这限制了直接补全；已使用来源可追溯的公开历史快照补充近期投稿与明确决定。仍不能用录用名单替代全部投稿，也不能声称覆盖了全部拒稿。

查询批次与入库状态

采集文件、已入库的来源记录和去重论文实体是不同的计数。来源可能覆盖同一篇论文，同一篇论文也可能有多次投稿；不能把各批文件数量相加作为独立论文总数。实时统计与覆盖报告使用：

PGSERVICEFILE=/etc/paper-atlas/pg_service.conf paper-atlas query --pg-service foundry-research --pg-schema research --stats
PGSERVICEFILE=/etc/paper-atlas/pg_service.conf paper-atlas coverage \
  --pg-service foundry-research --pg-schema research \
  --out /data/paper-index/collected/venue-coverage-current.json

manifest 和采集器状态清单用于确认文件是否齐全及是否缺摘要；ingest_runs 和协调器日志用于确认主库导入是否成功。官方程序、书目目录和公开投稿快照分别保留，未出现在某份清单不等于被拒稿；第三方快照也不能代表平台当前全量状态。代码测试成功不能代替最终全库去重、完整性和逐届覆盖核验。

coverage 的所有计数来自同一个只读快照。latest_observed_status_counts 按每次投稿的最新观察决定统计，decision_observation_counts 保留所有历史观察；重复来源不增加投稿数，缺少决定的投稿计入最新状态 unknown，但不凭空制造 unknown 决定。source_record_counts 统计来源在该届次的实际记录与缺摘要数，和 sources 中逐清单的预期/导入数量分开；身份补充清单与原始论文集清单可以描述同一条记录。来源缺摘要与论文实体从其他来源获得摘要也分别报告。报告仍将历史覆盖标为待独立审计，不能用某个清单 complete 或没有拒稿记录推断全会议覆盖。

当前代码与合并状态以 Pull Requests 为准；CI 结果以对应提交的 Actions 检查为准。工作分支交付后等待用户手动合并。合并代码不自动部署、不自动启动采集，也不代表数据批次已完成。

修正已有 PMLR 投稿的轨道

先用采集器 v3 把 ICML 多轨道卷采集到新目录，保留旧文件。以下命令默认只读生成迁移计划；--inventory 可重复指定，以完整卷为单位核对，不能只提供 Position 子集：

paper-atlas maintain pmlr-tracks --db /data/paper-index/papers.sqlite \
  --inventory /data/paper-index/collected/pmlr-tracks-v3/pmlr-v235.inventory.json \
  --inventory /data/paper-index/collected/pmlr-tracks-v3/pmlr-v267.inventory.json \
  --inventory /data/paper-index/collected/pmlr-tracks-v3/pmlr-v306.inventory.json \
  --out /data/paper-index/collected/pmlr-track-plan.json

检查报告后，在同一命令添加 --apply 并使用新的 --out 路径执行迁移。计划使用共享维护锁，实际迁移使用独占锁；已有 arXiv 类别修复或其他写入运行时会拒绝启动，不会停止或重启它们。一次事务内核对整个来源集合、原始题目/摘要/作者、forum 身份、已有事件及目标冲突，更新原投稿的 edition 和身份归属，回填官方轨道出处及逐轨道覆盖数，最后复查轨道与外键后提交。论文、来源、投稿、决定的 ID 及决定观察均保留，不重新创建事件、不做实体合并、不改论文正文元数据或标签。

报告记录每个迁移事件的旧 edition、原身份、完整决定观察及新轨道证据。planned 是未执行的计划；complete 才表示事务已提交；error 表示执行失败。若进程在提交前后中断而报告停在 prepared，先对照主库和报告核查，不根据日志缺失自行重启任务。新路径重跑会重新核对当前数据库，已正确的轨道不会再次迁移。共享多个来源、重复目标事件或冲突决定会停止迁移，需另行核对，不能直接删掉其中一条。

追加同一目录的部分记录

默认 import records 把 manifest 当成一份来源快照，覆盖统计使用该文件的数量。 若目录已有2条，之后仅补入1条，不能把这一小批当成完整快照，否则会把目录计数改成1。 为已核验的部分补充批次，在 manifest 显式声明：

{
  "coverage_mode": "incremental",
  "coverage_previous_count": 2,
  "coverage_previous_expected_count": 2,
  "coverage_expected_count": 4,
  "status": "partial",
  "count": 1
}

这只是新增字段示例，manifest仍须保留source、venue、year、track、list_url、文件哈希等来源证据。 count是本文件行数，coverage_previous_count是导入前该来源/届次的实际记录数， coverage_previous_expected_count是旧覆盖行的expected_count（未知时用null）， coverage_expected_count是独立目录证据支持的整份来源预期数，不能小于已知旧预期数。 这个例子成功后覆盖统计为预期4、已导入3；文件checkpoint的records_written仍为1。 刷新相同记录不重复累加。初次导入部分来源可声明previous_count为0、previous_expected_count为null。

只支持当前最多一个规范目录URL且旧覆盖状态为partial的来源/届次；多目录、旧状态complete、 旧计数与实际来源记录不符，或前置计数已变化，都会中止，先核对来源范围或重新取得完整快照。 该模式在写入前检查父状态，并在同一文件事务中按实际来源记录重新计数、检查总量界限和乐观更新覆盖行。 失败会回滚本文件的论文、来源、决定、标签和覆盖变化，保留失败运行记录；更早已提交文件不重放。 增量模式始终保留partial，不能靠一个小批次推断完整论文集、摘要或公开拒稿覆盖。

仍需先独立核对新增记录身份与决定，按原生单写入保护串行导入，再独立核验数据与原有历史。 这些计数检查不证明外部目录完整，也不代替最终全库去重。