Archive MaleCNS research sources, provenance, bibliography and immutable data inventory

docs/10-data/data-contract.md

@@ -0,0 +1,30 @@
+# 数据契约
+
+唯一正式全脑连接组输入：`datasets/male-cns-v1.0/processed/neuron-only/`。
+
+| 项目 | 固定值 / 语义 |
+|---|---|
+| canonical neurons | 166,700；annotation 的 superclass 非空 |
+| fragments | 44,877；从 neuron-only 图排除，仍保留原数据与审计 |
+| annotation bodies | 211,577；不能全部称为 neurons |
+| directed edges | 25,582,938 |
+| anatomical synaptic-contact sum | 124,177,617 |
+| neuron_idx | 连续 int32，0…166699 |
+| body_id | 原始 uint64；不可与其他数据集 ID 混用 |
+| CSR indptr / indices / raw weights | int64 / int32 / int64 |
+| isolated neurons / self-loops | 保留 217 / 101 |
+| missing type | 保留 2,194 个 neurons |
+| nonempty raw type unique strings | 11,751；不为匹配论文数字手工合并 |
+
+上表是已经封存的项目契约，不是本次重新计算的结果；以原 Phase 3B 审计、schema 和 manifest 为权威依据。
+正式 Cell 论文神经元总数为 166,700、types 11,710；与本地 raw 字符串统计不一致时保留版本/定义差异。
+
+原始文件实际位置：
+
+- `raw/annotations/body-annotations-male-cns-v1.0-minconf-0.5.feather`
+- `raw/annotations/body-neurotransmitters-male-cns-v1.0.feather`（不是空的 raw/neurotransmitters 目录）
+- `raw/connectivity/connectome-weights-male-cns-v1.0-minconf-0.5.feather`
+- `raw/skeletons/`：本次清点 211,573 个 SWC 文件；这不是 neuron-only 的 SWC 覆盖数。
+
+不得由 SWC 文件总数推断 neuron coverage；需用 canonical body_id 做集合连接。不得改动 raw 以匹配论文。
+本项目没有下载原始 EM 图像。所有新增解释字段与原始 neurotransmitter 字段分离。

docs/10-data/provenance.md

@@ -0,0 +1,27 @@
+# 数据、外部资源与来源链
+
+## 精确定位而非重新下载
+
+完整逐文件路径、字节数、SHA-256 位于 `registry/snapshots/bootstrap-20260929/files.jsonl.gz`。
+它记录目前服务器实物，不替代上游官方校验，也不证明过去每一次实验的执行过程。
+原下载来源/校验文件保留在 `datasets/male-cns-v1.0/raw/_manifests/`，原 Phase 3B schema/audit 保留在 processed/neuron-only。
+自动引用抽取 `registry/catalog-20260929/source-citations.json` 同时保存来源文件 SHA-256；抽取到的 URL/DOI 未自动背书为有效生物学证据。
+
+## 外部资源
+
+| 资源 | 本地用途 | 不允许的推断 |
+|---|---|---|
+| MaleCNS v1.0 / Cell 2026 | canonical bodies、真实边、annotation | anatomical count ≠ 实测有效电导 |
+| reiserlab/visualpathways | pathway / receptive-field / retinotopy 参考 | 没有坐标的 neuron 不随机补坐标 |
+| Cell Type Explorer / eye maps | 视觉层级和 eye-map 参考 | 名称相似不证明跨数据集 ID 一致 |
+| FlyVis | 独立 engineering visual front-end 探索 | 不称为纯 MaleCNS phototransduction |
+| DoOR.data 2.0.1 | odor-response physiology、receptor/glomerulus 通道映射 | 不自动推断缺失 MaleCNS body 映射 |
+
+四个外部 Git 仓库的 origin、commit、dirty 状态、许可证据 SHA-256 已锁在 `external-resources.lock.json`。
+外部仓库未 pull、未更新、未被作为嵌套 Git 内容上传。
+
+## 版本与覆盖缺口
+
+论文 formal / preprint、数据 release、软件 commit 分开标记。未知许可证、缺失映射或没有原始生理参数都显式保留 unknown。
+不能因为外部数据“公开可下载”就默认可全部再分发。
+不上传大型上游数据副本，恢复时优先使用自己已校验的备份；上游重下载是显式操作，不由本仓库自动执行。

docs/10-data/schema-and-catalog.md

@@ -0,0 +1,17 @@
+# 实际 schema 与可恢复文件登记
+
+`registry/data-20260929/dataset.json` 登记实际 raw 核心文件、Phase 3B canonical 文件、大小、SHA-256、原始下载脚本中的来源基址。
+`registry/data-20260929/observed-schemas.json` 通过只读 Arrow/Parquet/NumPy header 获取列名、dtype、数组形状；不是猜测字段，也不是重新生成 Phase 3B。
+`registry/data-20260929/evidence/` 保留小型 Phase 3B audit、schema、manifest、原下载来源和校验记录的字节一致副本。
+完整 SWC 列表和所有实验大文件仍通过全量 gzip JSONL 清单引用，不在本目录重复写 20 万行。
+
+原下载脚本作为来源证据归档，**不是本轮获准重新执行的操作**。其中重下载、移走坏文件等行为本次均未运行。
+恢复时先取已校验备份；需要重下载时应在独立目的地显式审批来源和范围，不能改写当前 raw。
+
+Git 内容本身另有 `registry/repository-files.sha256`，可在无科学数据的新 clone 上独立验证：
+
+```bash
+python3 -B tools/verify_repository_files.py
+```
+
+该清单不包含它自身（避免自引用），由 Git commit 内容身份覆盖其完整性；它不等于科学大数据备份。