24-EFT.WP.Particle.TopologyAtlas v1.0 | 附录C 清单模板与样例（topo manifest）

目录 ／ 文档-技术白皮书 ／ 24-EFT.WP.Particle.TopologyAtlas v1.0

附录C 清单模板与样例（topo manifest）

一句话目标：给出拓扑图谱产物在工程链路中的标准清单 manifest.topo.* 的最小键集、字段规范、模板与样例，确保结果可复现、可审计、可对比与可回放。

I. 范围与对象

1. 覆盖清单类型
   • manifest.topo.atlas：全局图谱发布（第9–11章）。
   • manifest.topo.case：用例级发布（第15章）。
   • manifest.topo.search：检索/对比结果（第13章）。
   • manifest.topo.runtime：流式运行态快照（第14章）。
   • manifest.topo.patch：增量补丁/合并记录（第11章）。
2. 产物引用：允许以内容寻址 hash:// 与外部 uri 混合；二进制产物（如 D, Atlas）只存元信息与 data_hash。

II. 命名、版本与跨卷引用

• 命名：清单键一律以 manifest.topo.* 起首；模式与版本字段为 schema, ver。
• 版本：schema = "topo-manifest"；ver = "1.0.x" 语义化管理（主版本升级可能破坏兼容）。
• 跨卷引用：时间/时序字段 tau_mono/ts 与契约格式参照 配套白皮书《能量丝》 第2章与本卷附录B C90-*。

III. 最小键集（统一必填）

• 身份与追溯：TraceID, producer, ts, code.ver, deps, seed。
• 数据来源：data.uri, data_hash, RefCond。
• 方法策略：policy（含 τ_policy, norm, window, thresholds）。
• 产物索引：artifacts（引用 D, Atlas, Γ, Inv, charts, T_ab 等的 hash/uri）。
• 指标与契约：metrics, contracts（执行结果与证据）。
• 签名：signature = { alg, digest, signer, key_id }。

任何进入方程的字段必须声明 unit(field) 与 dim(field) 并通过 check_dim( y - f(x) ) 校核；整数不变量须记录取整前后值与 u(x)。

IV. 字段规范与单位

• 时间：ts 为 ISO8601；运行态再给 window = [t0, t1]。
• 单位/量纲：在 units 节点统一声明，如 {"Q":"[1]", "d_B":"[τ]", "Lk":"[1]"}；dim 用 SI 量纲符号。
• 两口径：forms = {formA, formB}，并记录 delta_form 与评价区间 p95/p99。
• 不确定度：uncertainty = { u(x), U = k * u_c, nu_eff }；覆盖概率入 coverage。

V. 模板（可拷贝起草）

• 图谱发布 manifest.topo.atlas

{

"schema": "topo-manifest",

"ver": "1.0.0",

"kind": "atlas",

"TraceID": "ta-2025-09-02-0001",

"producer": "EFT.TopologyAtlas/atlas-publisher",

"ts": "2025-09-02T10:15:00Z",

"code": { "ver": "1.3.2", "git": "hash://e3b0c442", "runtime": "py310" },

"deps": ["gudhi@3.9", "giotto-tda@0.6", "numba@0.59"],

"seed": 172001,

"data": { "uri": "s3://bucket/dataset-A", "data_hash": "hash://ab12cd..." },

"RefCond": {

"domain": "S2-orientation",

"grid": [1024, 1024],

"spacing": [1.0, 1.0],

"tau_mono": "UTC",

"norm": "L2",

"window": null

},

"policy": {

"τ_policy": "Alpha",

"persistence": { "min_lifespan": 0.02, "scale_τ": 1.0 },

"transition": { "model": "affine", "reg": 1e-3 },

"blend": { "Σψ≡1": true }

},

"artifacts": {

"Atlas": "hash://atlas-7f..",

"charts": ["hash://chart-a..", "hash://chart-b.."],

"T_ab": ["hash://tab-a-b..", "hash://tab-b-c.."],

"ψ_stats": { "sup|Σψ-1|": 7.2e-7 },

"D": "hash://pd-H0H1..",

"Inv": { "Q": 12, "Lk": 0, "Wr": 0.3 }

},

"forms": {

"formA": "clean→build→measure",

"formB": "build→simplify→measure",

"delta_form": { "d_B": 0.008, "p95": 0.011, "tol": 0.02 }

},

"units": { "Q": "[1]", "Lk": "[1]", "d_B": "[τ]" },

"metrics": {

"Δ_cyc": 8.5e-4,

"κ_cover": 0.72,

"cond_max(∂φ)": 12.4,

"coverage": 0.95

},

"contracts": [

{ "id": "C90-091", "status": "pass", "evidence": "hash://psi-check" },

{ "id": "C90-092", "status": "pass", "value": 0.00085, "tol": 0.001 },

{ "id": "C90-004", "status": "pass", "value": 0.011, "tol": 0.02 }

],

"signature": { "alg": "SHA256-RSA", "digest": "hash://sig-..", "signer": "ops@eft", "key_id": "k-2025-07" }

}

• 用例发布 manifest.topo.case

{

"schema": "topo-manifest",

"ver": "1.0.0",

"kind": "case",

"TraceID": "case-skyrmion-001",

"producer": "EFT.Case.Pipeline",

"ts": "2025-09-02T10:20:00Z",

"code": { "ver": "0.9.5", "git": "hash://acbd18.." },

"seed": 7,

"data": { "uri": "file://skx/scan-42.tiff", "data_hash": "hash://ff00aa.." },

"RefCond": { "domain": "S2-orientation", "grid": [512, 512], "spacing": [2, 2] },

"policy": { "τ_policy": "cubical", "thresholds": { "τ_pers_min": 0.03 } },

"artifacts": {

"q_map": "hash://qmap-..",

"D": "hash://pd-..",

"evidence": ["hash://slice-1..", "hash://pair-14.."],

"Inv": {

"Q": { "raw": 9.82, "rounded": 10, "u": 0.09, "U": 0.18, "coverage": 0.95 }

}

},

"forms": { "formA": "exact", "formB": "approx", "delta_form": { "Q": 0.18, "tol": 0.5 } },

"units": { "Q": "[1]" },

"metrics": { "lifespan_p50": 0.11, "lifespan_p95": 0.27 },

"contracts": [

{ "id": "C90-101", "status": "pass" },

{ "id": "C90-151", "status": "pass", "value": 0.18, "tol": 0.5 }

],

"signature": { "alg": "SHA256-Ed25519", "digest": "hash://sig-..", "signer": "lab@eft" }

}

• 检索结果 manifest.topo.search

{

"schema": "topo-manifest",

"ver": "1.0.0",

"kind": "search",

"TraceID": "srch-2025-09-02-01",

"producer": "EFT.TopologySearch",

"ts": "2025-09-02T10:30:00Z",

"query": { "Z_Q": "hash://embed-q..", "norm": "cosine", "K": 50 },

"candidates": [

{ "id": "atlas#A1", "score": 0.91, "uri": "hash://atlas-A1", "d_exact": 0.12 },

{ "id": "atlas#B9", "score": 0.87, "uri": "hash://atlas-B9", "d_exact": 0.15 }

],

"metrics": { "Recall@10": 0.94, "delta_form_retr_p95": 0.02 },

"contracts": [

{ "id": "C90-131", "status": "pass", "value": 0.94, "tol": 0.9 },

{ "id": "C90-132", "status": "pass" }

],

"signature": { "alg": "SHA256-RSA", "digest": "hash://sig-.." }

}

• 运行态快照 manifest.topo.runtime

{

"schema": "topo-manifest",

"ver": "1.0.0",

"kind": "runtime",

"TraceID": "rt-2025w36-03",

"producer": "EFT.Stream.Worker",

"ts": "2025-09-02T10:45:00Z",

"window": ["2025-09-02T10:00:00Z", "2025-09-02T10:45:00Z"],

"state": { "ω(t)": "hash://wm-..", "lag_ms_p95": 820 },

"artifacts": { "K_t": "hash://complx-..", "D_t": "hash://pd-..", "Atlas_t": "hash://atlas-t.." },

"forms": { "offline_ref": "hash://pd-off..", "delta_form_rt": { "d_B": 0.026, "tol": 0.03 } },

"metrics": { "β": 0.78, "H_cache": 0.86, "drop_late": 0.0 },

"contracts": [

{ "id": "C90-141", "status": "pass", "value": 820, "tol": 1800 },

{ "id": "C90-142", "status": "pass", "value": 0.026, "tol": 0.03 }

],

"panel": { "uri": "dashboard://topo/runtime/stream-03" },

"signature": { "alg": "SHA256-Ed25519", "digest": "hash://sig-.." }

}

• 增量补丁 manifest.topo.patch

{

"schema": "topo-manifest",

"ver": "1.0.0",

"kind": "patch",

"TraceID": "patch-AT-0007",

"producer": "EFT.Atlas.Merger",

"ts": "2025-09-02T11:05:00Z",

"base": "hash://atlas-7f..",

"patch": ["hash://patch-01..", "hash://patch-02.."],

"merge_policy": { "conflict": "keep-both+weight", "Σψ≡1": true },

"post_merge": { "Atlas*": "hash://atlas-8a..", "Δ_cyc": 9.7e-4, "tol": 1e-3 },

"contracts": [{ "id": "C90-111", "status": "pass" }],

"signature": { "alg": "SHA256-RSA", "digest": "hash://sig-.." }

}

VI. 生成与校核流程 M90-C1

• 收集元数据：TraceID/producer/ts/code.ver/deps/seed；校核 RefCond 完整（见 C90-002）。
• 产物登记：对 D/Atlas/Γ/Inv 生成 data_hash 并落 artifacts。
• 两口径记录：并行计算 formA/B 或 stream/offline，生成 delta_form 与分位数。
• 单位与量纲：填充 units/dim，执行 check_dim；整数不变量取整前后并存 u/U/coverage。
• 契约评估：执行 assert_*，将结果与证据填入 contracts。
• 签名：计算 digest = SHA256( bytes(clean_manifest_without_signature) )；用 key_id 签名。
• 发布：写入对象存储并回传 uri；仪表板引用 panel.uri（运行态）。

VII. 合规细则（发布门）

• 硬门：缺任一必填键、Σ_a ψ_a ≡ 1 不通过、non_decreasing(τ) 失败，直接拒绝发布。
• 一致性门：delta_form ≤ tol、Δ_cyc ≤ tol_cyc；失败触发策略卡 SC90-02/03/04 回退。
• 不确定度门：coverage ≥ 0.95 或按策略扩大 U = k * u_c。
• 取整门：发布前整数不变量必须满足 C90-101。

VIII. 存储、分片与压缩

• 二进制大件：*.npz/*.parquet 分片（默认 64 MiB），记录 parts = [{uri, size, sha256}]。
• 压缩：codec ∈ {zstd, lz4}；在 artifacts.meta.codec 标明。
• 内容寻址：所有 hash:// 统一 sha256:hex；可选 Merkle 根 merkle_root 以支持子集校验。

IX. 面板映射与SLO

1. 将 metrics 字段映射到面板：
   • Δ_cyc, cond_max(∂φ) → “Atlas 质量”面板；
   • d_B, lifespan_p95 → “拓扑稳定性”；
   • β, H_cache, lag_ms_p95 → “运行时健康”。
2. 建议 SLO：Δ_cyc ≤ 1e-3，delta_form_p95 ≤ 0.02*scale_τ，lag_ms_p95 ≤ 2*τ_window。

X. 变更与兼容

• 次版本新增字段须置于 optional；移除字段在两个小版本后执行。
• 提供 upgrade_manifest(manifest) 工具以迁移旧版到 1.0.x。
• 对外接口 I90-13B/I90-14B/I90-159 必能消费本模板生成的清单。

小结

• 本附录提供了 manifest.topo.atlas/case/search/runtime/patch 五类清单的最小键集、模板与样例，并给出从生成到校核、签名与发布的全流程。
• 通过统一的 RefCond/units/forms/contracts/signature 结构，保证拓扑图谱在多团队、多环境间的可复现、可审计与可集成。