dsh-math-calculator 0.0.0-stage → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (278) hide show
  1. package/CHANGELOG.md +294 -0
  2. package/LICENSE +21 -0
  3. package/README.md +495 -2
  4. package/cordis.patch.yml +7 -0
  5. package/dsh.plugin.json +15 -0
  6. package/lib/ai-brief.js +119 -0
  7. package/lib/anchor-solve.js +217 -0
  8. package/lib/api.js +798 -0
  9. package/lib/awareness.js +222 -0
  10. package/lib/back-solve.js +232 -0
  11. package/lib/balance.js +154 -0
  12. package/lib/body-catalog.js +488 -0
  13. package/lib/body-scaling.js +288 -0
  14. package/lib/body-taxonomy.js +719 -0
  15. package/lib/civilization.js +329 -0
  16. package/lib/climate.js +388 -0
  17. package/lib/compute-budget.js +173 -0
  18. package/lib/consequences.js +342 -0
  19. package/lib/constants-core.js +241 -0
  20. package/lib/constants-graph.js +692 -0
  21. package/lib/custom-constants.js +320 -0
  22. package/lib/dead-universe.js +288 -0
  23. package/lib/derivation-log.js +186 -0
  24. package/lib/derivation-stack.js +471 -0
  25. package/lib/detector.js +582 -0
  26. package/lib/ecosystem.js +231 -0
  27. package/lib/empirical-decomposition.js +321 -0
  28. package/lib/fantasy-layer.js +213 -0
  29. package/lib/feasibility.js +386 -0
  30. package/lib/flip-claims.js +93 -0
  31. package/lib/flip.js +166 -0
  32. package/lib/format.js +325 -0
  33. package/lib/formula-bridge.js +78 -0
  34. package/lib/formula-builtins.js +110 -0
  35. package/lib/formula-library-basic.js +712 -0
  36. package/lib/formula-library-ext.js +1036 -0
  37. package/lib/formula-library-generic.js +226 -0
  38. package/lib/formula-library-perception.js +593 -0
  39. package/lib/formula-library-power.js +276 -0
  40. package/lib/formula-library-story.js +487 -0
  41. package/lib/formula-library-story2.js +420 -0
  42. package/lib/formula-library.js +1333 -0
  43. package/lib/formula-pack.js +173 -0
  44. package/lib/formula-table.js +221 -0
  45. package/lib/formulas.js +533 -0
  46. package/lib/graph-layout.js +172 -0
  47. package/lib/graph-render.js +136 -0
  48. package/lib/heatmap.js +93 -0
  49. package/lib/impact.js +326 -0
  50. package/lib/index.js +2944 -0
  51. package/lib/integration.js +145 -0
  52. package/lib/life.js +172 -0
  53. package/lib/moons.js +221 -0
  54. package/lib/numeric.js +282 -0
  55. package/lib/observer.js +187 -0
  56. package/lib/ode.js +320 -0
  57. package/lib/ops/balance-op.js +141 -0
  58. package/lib/ops/bodies-op.js +368 -0
  59. package/lib/ops/constants-op.js +278 -0
  60. package/lib/ops/custom-op.js +191 -0
  61. package/lib/ops/derivation-op.js +710 -0
  62. package/lib/ops/feasibility-op.js +160 -0
  63. package/lib/ops/formula-table-op.js +261 -0
  64. package/lib/ops/impact-op.js +150 -0
  65. package/lib/ops/ode-op.js +113 -0
  66. package/lib/ops/quantities-op.js +176 -0
  67. package/lib/ops/shared.js +228 -0
  68. package/lib/ops/units-op.js +227 -0
  69. package/lib/ops/workspace-op.js +359 -0
  70. package/lib/ops/world-op.js +323 -0
  71. package/lib/pipeline.js +304 -0
  72. package/lib/playbook.js +357 -0
  73. package/lib/precision-report.js +80 -0
  74. package/lib/provenance-graph.js +262 -0
  75. package/lib/provenance.js +152 -0
  76. package/lib/quantities.js +530 -0
  77. package/lib/result-cache.js +144 -0
  78. package/lib/sky.js +348 -0
  79. package/lib/star-catalog.js +120 -0
  80. package/lib/stats.js +373 -0
  81. package/lib/stellar.js +175 -0
  82. package/lib/summary.js +225 -0
  83. package/lib/symbolic.js +264 -0
  84. package/lib/symbols.js +190 -0
  85. package/lib/systems.js +280 -0
  86. package/lib/taxonomy.js +278 -0
  87. package/lib/terrain.js +350 -0
  88. package/lib/timeline.js +244 -0
  89. package/lib/types/ai-brief.d.ts +72 -0
  90. package/lib/types/anchor-solve.d.ts +67 -0
  91. package/lib/types/api.d.ts +75 -0
  92. package/lib/types/awareness.d.ts +59 -0
  93. package/lib/types/back-solve.d.ts +70 -0
  94. package/lib/types/balance.d.ts +94 -0
  95. package/lib/types/body-catalog.d.ts +156 -0
  96. package/lib/types/body-scaling.d.ts +123 -0
  97. package/lib/types/body-taxonomy.d.ts +95 -0
  98. package/lib/types/civilization.d.ts +98 -0
  99. package/lib/types/client.d.ts +353 -0
  100. package/lib/types/climate.d.ts +256 -0
  101. package/lib/types/compute-budget.d.ts +103 -0
  102. package/lib/types/consequences.d.ts +49 -0
  103. package/lib/types/constants-core.d.ts +125 -0
  104. package/lib/types/constants-graph.d.ts +122 -0
  105. package/lib/types/custom-constants.d.ts +136 -0
  106. package/lib/types/dead-universe.d.ts +80 -0
  107. package/lib/types/derivation-log.d.ts +110 -0
  108. package/lib/types/derivation-stack.d.ts +191 -0
  109. package/lib/types/detector.d.ts +105 -0
  110. package/lib/types/ecosystem.d.ts +140 -0
  111. package/lib/types/empirical-decomposition.d.ts +107 -0
  112. package/lib/types/fantasy-layer.d.ts +145 -0
  113. package/lib/types/feasibility.d.ts +136 -0
  114. package/lib/types/flip-claims.d.ts +51 -0
  115. package/lib/types/flip.d.ts +81 -0
  116. package/lib/types/format.d.ts +70 -0
  117. package/lib/types/formula-bridge.d.ts +51 -0
  118. package/lib/types/formula-builtins.d.ts +29 -0
  119. package/lib/types/formula-library-basic.d.ts +31 -0
  120. package/lib/types/formula-library-ext.d.ts +18 -0
  121. package/lib/types/formula-library-generic.d.ts +37 -0
  122. package/lib/types/formula-library-perception.d.ts +25 -0
  123. package/lib/types/formula-library-power.d.ts +37 -0
  124. package/lib/types/formula-library-story.d.ts +19 -0
  125. package/lib/types/formula-library-story2.d.ts +16 -0
  126. package/lib/types/formula-library.d.ts +65 -0
  127. package/lib/types/formula-pack.d.ts +65 -0
  128. package/lib/types/formula-table.d.ts +96 -0
  129. package/lib/types/formulas.d.ts +128 -0
  130. package/lib/types/graph-layout.d.ts +82 -0
  131. package/lib/types/graph-render.d.ts +68 -0
  132. package/lib/types/heatmap.d.ts +91 -0
  133. package/lib/types/impact.d.ts +89 -0
  134. package/lib/types/index.d.ts +111 -0
  135. package/lib/types/integration.d.ts +69 -0
  136. package/lib/types/life.d.ts +91 -0
  137. package/lib/types/moons.d.ts +103 -0
  138. package/lib/types/numeric.d.ts +61 -0
  139. package/lib/types/observer.d.ts +104 -0
  140. package/lib/types/ode.d.ts +104 -0
  141. package/lib/types/ops/balance-op.d.ts +26 -0
  142. package/lib/types/ops/bodies-op.d.ts +35 -0
  143. package/lib/types/ops/constants-op.d.ts +16 -0
  144. package/lib/types/ops/custom-op.d.ts +19 -0
  145. package/lib/types/ops/derivation-op.d.ts +31 -0
  146. package/lib/types/ops/feasibility-op.d.ts +19 -0
  147. package/lib/types/ops/formula-table-op.d.ts +16 -0
  148. package/lib/types/ops/impact-op.d.ts +15 -0
  149. package/lib/types/ops/ode-op.d.ts +16 -0
  150. package/lib/types/ops/quantities-op.d.ts +22 -0
  151. package/lib/types/ops/shared.d.ts +425 -0
  152. package/lib/types/ops/units-op.d.ts +31 -0
  153. package/lib/types/ops/workspace-op.d.ts +20 -0
  154. package/lib/types/ops/world-op.d.ts +15 -0
  155. package/lib/types/pipeline.d.ts +69 -0
  156. package/lib/types/playbook.d.ts +157 -0
  157. package/lib/types/precision-report.d.ts +59 -0
  158. package/lib/types/provenance-graph.d.ts +101 -0
  159. package/lib/types/provenance.d.ts +41 -0
  160. package/lib/types/quantities.d.ts +117 -0
  161. package/lib/types/result-cache.d.ts +78 -0
  162. package/lib/types/sky.d.ts +137 -0
  163. package/lib/types/star-catalog.d.ts +57 -0
  164. package/lib/types/stats.d.ts +95 -0
  165. package/lib/types/stellar.d.ts +69 -0
  166. package/lib/types/summary.d.ts +75 -0
  167. package/lib/types/symbolic.d.ts +58 -0
  168. package/lib/types/symbols.d.ts +67 -0
  169. package/lib/types/systems.d.ts +41 -0
  170. package/lib/types/taxonomy.d.ts +75 -0
  171. package/lib/types/terrain.d.ts +95 -0
  172. package/lib/types/timeline.d.ts +156 -0
  173. package/lib/types/units.d.ts +115 -0
  174. package/lib/types/universe-ops.d.ts +143 -0
  175. package/lib/types/whitepaper.d.ts +106 -0
  176. package/lib/types/workspace.d.ts +339 -0
  177. package/lib/types/world-params.d.ts +111 -0
  178. package/lib/types/world-validation.d.ts +74 -0
  179. package/lib/types/world.d.ts +263 -0
  180. package/lib/units.js +294 -0
  181. package/lib/universe-ops.js +209 -0
  182. package/lib/whitepaper.js +219 -0
  183. package/lib/workspace.js +763 -0
  184. package/lib/world-params.js +369 -0
  185. package/lib/world-validation.js +296 -0
  186. package/lib/world.js +643 -0
  187. package/package.json +94 -4
  188. package/src/ai-brief.ts +141 -0
  189. package/src/algebrite.d.ts +19 -0
  190. package/src/anchor-solve.ts +262 -0
  191. package/src/api.ts +885 -0
  192. package/src/awareness.ts +243 -0
  193. package/src/back-solve.ts +274 -0
  194. package/src/balance.ts +205 -0
  195. package/src/body-catalog.ts +619 -0
  196. package/src/body-scaling.ts +357 -0
  197. package/src/body-taxonomy.ts +806 -0
  198. package/src/civilization.ts +385 -0
  199. package/src/climate.ts +586 -0
  200. package/src/compute-budget.ts +204 -0
  201. package/src/consequences.ts +401 -0
  202. package/src/constants-core.ts +336 -0
  203. package/src/constants-graph.ts +772 -0
  204. package/src/custom-constants.ts +389 -0
  205. package/src/dead-universe.ts +328 -0
  206. package/src/derivation-log.ts +257 -0
  207. package/src/derivation-stack.ts +600 -0
  208. package/src/detector.ts +684 -0
  209. package/src/ecosystem.ts +271 -0
  210. package/src/empirical-decomposition.ts +411 -0
  211. package/src/fantasy-layer.ts +295 -0
  212. package/src/feasibility.ts +519 -0
  213. package/src/flip-claims.ts +119 -0
  214. package/src/flip.ts +210 -0
  215. package/src/format.ts +321 -0
  216. package/src/formula-bridge.ts +92 -0
  217. package/src/formula-builtins.ts +108 -0
  218. package/src/formula-library-basic.ts +747 -0
  219. package/src/formula-library-ext.ts +1048 -0
  220. package/src/formula-library-generic.ts +242 -0
  221. package/src/formula-library-perception.ts +604 -0
  222. package/src/formula-library-power.ts +297 -0
  223. package/src/formula-library-story.ts +496 -0
  224. package/src/formula-library-story2.ts +428 -0
  225. package/src/formula-library.ts +1396 -0
  226. package/src/formula-pack.ts +189 -0
  227. package/src/formula-table.ts +277 -0
  228. package/src/formulas.ts +560 -0
  229. package/src/graph-layout.ts +209 -0
  230. package/src/graph-render.ts +158 -0
  231. package/src/heatmap.ts +139 -0
  232. package/src/impact.ts +393 -0
  233. package/src/index.ts +3257 -0
  234. package/src/integration.ts +198 -0
  235. package/src/life.ts +233 -0
  236. package/src/moons.ts +341 -0
  237. package/src/numeric.ts +268 -0
  238. package/src/observer.ts +245 -0
  239. package/src/ode.ts +415 -0
  240. package/src/ops/balance-op.ts +170 -0
  241. package/src/ops/bodies-op.ts +415 -0
  242. package/src/ops/constants-op.ts +324 -0
  243. package/src/ops/custom-op.ts +188 -0
  244. package/src/ops/derivation-op.ts +677 -0
  245. package/src/ops/feasibility-op.ts +174 -0
  246. package/src/ops/formula-table-op.ts +309 -0
  247. package/src/ops/impact-op.ts +166 -0
  248. package/src/ops/ode-op.ts +127 -0
  249. package/src/ops/quantities-op.ts +178 -0
  250. package/src/ops/shared.ts +620 -0
  251. package/src/ops/units-op.ts +261 -0
  252. package/src/ops/workspace-op.ts +412 -0
  253. package/src/ops/world-op.ts +355 -0
  254. package/src/pipeline.ts +386 -0
  255. package/src/playbook.ts +429 -0
  256. package/src/precision-report.ts +87 -0
  257. package/src/provenance-graph.ts +297 -0
  258. package/src/provenance.ts +176 -0
  259. package/src/quantities.ts +617 -0
  260. package/src/result-cache.ts +157 -0
  261. package/src/sky.ts +465 -0
  262. package/src/star-catalog.ts +241 -0
  263. package/src/stats.ts +409 -0
  264. package/src/stellar.ts +227 -0
  265. package/src/summary.ts +275 -0
  266. package/src/symbolic.ts +279 -0
  267. package/src/symbols.ts +216 -0
  268. package/src/systems.ts +320 -0
  269. package/src/taxonomy.ts +312 -0
  270. package/src/terrain.ts +461 -0
  271. package/src/timeline.ts +315 -0
  272. package/src/units.ts +353 -0
  273. package/src/universe-ops.ts +283 -0
  274. package/src/whitepaper.ts +278 -0
  275. package/src/workspace.ts +911 -0
  276. package/src/world-params.ts +440 -0
  277. package/src/world-validation.ts +314 -0
  278. package/src/world.ts +988 -0
@@ -0,0 +1,297 @@
1
+ /**
2
+ * 因果溯源:从任意节点逆向找到它的依赖链。
3
+ *
4
+ * @module dsh-math-calculator/provenance-graph
5
+ * @description
6
+ * 方案补丁4。推演栈跑起来之后会遇到一个实际问题:
7
+ * 用户问「这个 4903 米的建筑上限是怎么来的?」
8
+ *
9
+ * 答案是一条链:
10
+ *
11
+ * 建筑高度上限
12
+ * ← 材料强度密度比
13
+ * ← 键能范围
14
+ * ← e_charge, epsilon0, hbar, c
15
+ *
16
+ * 没有溯源,用户只能看到一个孤立的数字。有了溯源,他知道该改哪一项。
17
+ *
18
+ * ## 两种依赖源
19
+ *
20
+ * 1. **常数图**(`CONSTANT_GRAPH`):派生常数依赖基础常数;
21
+ * 2. **接口卡**(`INTERFACE_CARDS`):上层的接口变量依赖下层。
22
+ *
23
+ * 两者拼成一张大图,节点是量名,边是「被谁决定」。
24
+ */
25
+
26
+ import { CONSTANT_GRAPH } from './constants-graph.js'
27
+ import { INTERFACE_CARDS } from './derivation-stack.js'
28
+ import { CONSTRAINTS } from './feasibility.js'
29
+
30
+ /** 图中的一条边:from 依赖 to。 */
31
+ export interface Edge {
32
+ /** 下游(被决定的量)。 */
33
+ from: string
34
+ /** 上游(决定它的量)。 */
35
+ to: string
36
+ /** 边所属的层(constant / P1 / P2 …)。 */
37
+ layer: string
38
+ }
39
+
40
+ /** 溯源结果。 */
41
+ export interface TraceResult {
42
+ /** 起点。 */
43
+ target: string
44
+ /** 是否找到。 */
45
+ found: boolean
46
+ /** 直接依赖(第一层)。 */
47
+ direct: string[]
48
+ /** 完整路径(从目标往下,去重)。 */
49
+ chain: string[]
50
+ /** 最终落到哪些「基础量」(不能再往上追的)。 */
51
+ roots: string[]
52
+ /** 面包屑导航(每层一行)。 */
53
+ breadcrumb: Array<{ depth: number; names: string[] }>
54
+ /** 若想改变这个量,最该动哪几个。 */
55
+ adjust: string[]
56
+ }
57
+
58
+ /**
59
+ * 构建完整的依赖图。
60
+ *
61
+ * @returns 边列表
62
+ */
63
+ export function buildGraph(): Edge[] {
64
+ const edges: Edge[] = []
65
+
66
+ // ① 常数图
67
+ for (const node of CONSTANT_GRAPH) {
68
+ if (!node.dependsOn) continue
69
+ for (const dependency of node.dependsOn) {
70
+ edges.push({ from: node.name, to: dependency, layer: 'constant' })
71
+ }
72
+ }
73
+
74
+ // ② 接口卡
75
+ for (const layer of Object.keys(INTERFACE_CARDS)) {
76
+ for (const card of INTERFACE_CARDS[layer]) {
77
+ for (const dependency of card.dependsOn) {
78
+ edges.push({ from: card.name, to: dependency, layer: layer })
79
+ }
80
+ }
81
+ }
82
+
83
+ // ③ 桥接边:让中间量能追到真正的基础参数
84
+ // 没有这层,溯源会停在「表面重力」这种中间概念上——
85
+ // 用户知道「建筑上限依赖重力」,但还是不知道该改什么。
86
+ const bridges: Array<[string, string[], string]> = [
87
+ ['表面重力', ['行星质量', '行星半径'], 'bridge'],
88
+ ['大气密度', ['表面重力', '气压', '地表温度'], 'bridge'],
89
+ ['地表温度', ['恒星辐射', '温室效应', '反照率'], 'bridge'],
90
+ ['恒星质量', ['基础常数'], 'bridge'],
91
+ ['恒星辐射', ['恒星质量', '轨道距离', '恒星光度'], 'bridge'],
92
+ ]
93
+ for (const bridge of bridges) {
94
+ for (const dependency of bridge[1]) {
95
+ edges.push({ from: bridge[0], to: dependency, layer: bridge[2] })
96
+ }
97
+ }
98
+
99
+ // ④ 可行性约束:从 formula 里抽取它依赖的量
100
+ // 这些约束名(如「建筑高度上限」)是作者最常问「这个数怎么来的」的对象,
101
+ // 必须能溯源,否则用户只能看到一个孤立数字。
102
+ for (const constraint of CONSTRAINTS) {
103
+ const deps = extractDeps(constraint.formula, constraint.id)
104
+ for (const dependency of deps) {
105
+ edges.push({ from: constraint.name, to: dependency, layer: 'constraint' })
106
+ }
107
+ }
108
+
109
+ return edges
110
+ }
111
+
112
+ /**
113
+ * 从公式文本里抽取依赖的量名。
114
+ *
115
+ * 只做保守匹配——宁可少报,不要错报。
116
+ *
117
+ * @param formula - 公式文本
118
+ * @param selfId - 自身 id(避免自依赖)
119
+ * @returns 依赖的量名列表
120
+ */
121
+ function extractDeps(formula: string, selfId: string): string[] {
122
+ const deps: string[] = []
123
+ const text = String(formula || '')
124
+ // 用显式规则而非正则——公式文本格式不统一,正则容易误判。
125
+ // 宁可少报依赖,也不要把错的量算进去(错误的溯源比没有更糟)。
126
+ if (text.includes('g') || text.includes('重力')) deps.push('表面重力')
127
+ if (text.includes('材料强度') || text.includes('strength')) deps.push('材料强度密度比')
128
+ if (text.includes('ρ_air') || text.includes('空气密度')) deps.push('大气密度')
129
+ if (text.includes('温度')) deps.push('地表温度')
130
+ if (text.includes('恒星质量') || text.includes('M☉')) deps.push('恒星质量')
131
+ return Array.from(new Set(deps))
132
+ }
133
+
134
+ /** 所有节点名。 */
135
+ export function allNodes(edges: Edge[]): Set<string> {
136
+ const names = new Set<string>()
137
+ for (const edge of edges) {
138
+ names.add(edge.from)
139
+ names.add(edge.to)
140
+ }
141
+ return names
142
+ }
143
+
144
+ /**
145
+ * 从目标节点逆向溯源。
146
+ *
147
+ * @param target - 目标量名
148
+ * @param edges - 依赖图(省略则现建)
149
+ * @param maxDepth - 最大深度(防止图有环时无限递归)
150
+ * @returns 溯源结果
151
+ */
152
+ export function trace(target: string, edges?: Edge[], maxDepth = 8): TraceResult {
153
+ const graph = edges ?? buildGraph()
154
+ const byFrom = new Map<string, string[]>()
155
+ for (const edge of graph) {
156
+ const list = byFrom.get(edge.from) ?? []
157
+ list.push(edge.to)
158
+ byFrom.set(edge.from, list)
159
+ }
160
+
161
+ const direct = byFrom.get(target) ?? []
162
+ const chain: string[] = []
163
+ const roots: string[] = []
164
+ const breadcrumb: Array<{ depth: number; names: string[] }> = []
165
+
166
+ const visited = new Set<string>()
167
+ const queue: Array<{ name: string; depth: number }> = direct.map(function (name) {
168
+ return { name: name, depth: 1 }
169
+ })
170
+ breadcrumb.push({ depth: 0, names: [target] })
171
+
172
+ while (queue.length > 0) {
173
+ const current = queue.shift() as { name: string; depth: number }
174
+ if (visited.has(current.name)) continue
175
+ visited.add(current.name)
176
+ if (current.depth > maxDepth) continue
177
+
178
+ chain.push(current.name)
179
+ const level = breadcrumb[current.depth]
180
+ if (level === undefined) breadcrumb[current.depth] = { depth: current.depth, names: [current.name] }
181
+ else level.names.push(current.name)
182
+
183
+ const next = byFrom.get(current.name) ?? []
184
+ if (next.length === 0) {
185
+ // 没有上游 = 基础量
186
+ if (!roots.includes(current.name)) roots.push(current.name)
187
+ continue
188
+ }
189
+ for (const name of next) {
190
+ queue.push({ name: name, depth: current.depth + 1 })
191
+ }
192
+ }
193
+
194
+ // 「最该动哪几个」= 基础量(它们没有任何上游,改它们最直接)
195
+ const adjust = roots.slice(0, 6)
196
+
197
+ return {
198
+ target: target,
199
+ found: direct.length > 0,
200
+ direct: direct,
201
+ chain: chain,
202
+ roots: roots,
203
+ breadcrumb: breadcrumb,
204
+ adjust: adjust,
205
+ }
206
+ }
207
+
208
+ /**
209
+ * 找出「哪些量依赖目标」——反向溯源。
210
+ *
211
+ * 改一个常数时,这个函数告诉你影响面有多大。
212
+ *
213
+ * @param target - 目标量名(如 c)
214
+ * @param edges - 依赖图
215
+ * @returns 直接与间接下游
216
+ */
217
+ export function impact(target: string, edges?: Edge[]): { direct: string[]; indirect: string[] } {
218
+ const graph = edges ?? buildGraph()
219
+ const byTo = new Map<string, string[]>()
220
+ for (const edge of graph) {
221
+ const list = byTo.get(edge.to) ?? []
222
+ list.push(edge.from)
223
+ byTo.set(edge.to, list)
224
+ }
225
+
226
+ const direct = byTo.get(target) ?? []
227
+ const indirect: string[] = []
228
+ const visited = new Set<string>(direct)
229
+ const queue = direct.slice()
230
+
231
+ while (queue.length > 0) {
232
+ const current = queue.shift() as string
233
+ const next = byTo.get(current) ?? []
234
+ for (const name of next) {
235
+ if (visited.has(name)) continue
236
+ visited.add(name)
237
+ indirect.push(name)
238
+ queue.push(name)
239
+ }
240
+ }
241
+
242
+ return { direct: direct, indirect: indirect }
243
+ }
244
+
245
+ /**
246
+ * 渲染溯源报告。
247
+ *
248
+ * @param result - trace 的结果
249
+ * @returns 可读文本
250
+ */
251
+ export function renderTrace(result: TraceResult): string {
252
+ const out: string[] = []
253
+ out.push('═══ 因果溯源:' + result.target + ' ═══')
254
+ out.push('')
255
+ if (!result.found) {
256
+ out.push(' 这个量没有上游依赖——它本身就是基础量,改它最直接。')
257
+ return out.join(String.fromCharCode(10))
258
+ }
259
+ out.push('【依赖链】(越往下越基础)')
260
+ for (const level of result.breadcrumb) {
261
+ if (level.names.length === 0) continue
262
+ const indent = ' ' + ' '.repeat(Math.min(level.depth, 6))
263
+ const arrow = level.depth === 0 ? '●' : '←'
264
+ out.push(indent + arrow + ' ' + level.names.join(', '))
265
+ }
266
+ out.push('')
267
+ out.push('【最终落到的基础量】')
268
+ out.push(' ' + (result.roots.length > 0 ? result.roots.join(', ') : '(无法继续追溯)'))
269
+ out.push('')
270
+ out.push('【想改变「' + result.target + '」,最该动这些】')
271
+ out.push(' ' + (result.adjust.length > 0 ? result.adjust.join(', ') : '(直接改它自己)'))
272
+ out.push('')
273
+ out.push('说明:基础量没有任何上游,改它们最直接;中间量也能改,但会与其它推导冲突。')
274
+ return out.join(String.fromCharCode(10))
275
+ }
276
+
277
+ /**
278
+ * 渲染影响面报告。
279
+ *
280
+ * @param target - 目标量
281
+ * @param result - impact 的结果
282
+ * @returns 可读文本
283
+ */
284
+ export function renderImpact(target: string, result: { direct: string[]; indirect: string[] }): string {
285
+ const out: string[] = []
286
+ out.push('═══ 影响面:改 ' + target + ' 会波及什么 ═══')
287
+ out.push('')
288
+ out.push('【直接依赖它的】' + (result.direct.length > 0 ? '' : '(无)'))
289
+ for (const name of result.direct) out.push(' · ' + name)
290
+ out.push('')
291
+ out.push('【间接波及的】共 ' + result.indirect.length + ' 项')
292
+ for (const name of result.indirect.slice(0, 15)) out.push(' · ' + name)
293
+ if (result.indirect.length > 15) out.push(' …还有 ' + (result.indirect.length - 15) + ' 项')
294
+ out.push('')
295
+ out.push('改之前先看这个清单——波及面越大,越需要重新校验。')
296
+ return out.join(String.fromCharCode(10))
297
+ }
@@ -0,0 +1,176 @@
1
+ /**
2
+ * 模型出处登记:把"哪些数字是物理、哪些只是地球标定、哪些根本推不出来"摊开。
3
+ *
4
+ * 为什么需要(ADR-0001):用户要的是"逻辑自洽、不矛盾太大",不是科研精度。
5
+ * 但自洽的前提是**知道自己哪里在估算** —— 否则作者会拿一个地球标定的经验系数
6
+ * 当物理定律用,写进小说后在第 20 章崩掉。
7
+ *
8
+ * 三类:
9
+ * first-principles 严格物理关系,改常数只需换公式
10
+ * calibrated 地球标定 + 标度律,只在给定适用域内可信
11
+ * contingent 不可推导,纯作者选择(卫星数量、生物上限、反照率……)
12
+ *
13
+ * @module dsh-math-calculator/provenance
14
+ */
15
+
16
+ /** 一个模型常数的来源类别。 */
17
+ export type ModelSource = 'first-principles' | 'calibrated' | 'contingent'
18
+
19
+ /** 登记条目。 */
20
+ export interface ModelConstant {
21
+ id: string
22
+ value: number | string
23
+ unit?: string
24
+ source: ModelSource
25
+ /** 是否随精细结构常数缩放(以及怎么缩)。 */
26
+ scalesWithAlpha: boolean
27
+ /** 适用域;超出只降级不拒绝。 */
28
+ domain: string
29
+ note: string
30
+ }
31
+
32
+ /** 全部经验/标定/设定项。 */
33
+ export const MODEL_CONSTANTS: ModelConstant[] = [
34
+ {
35
+ id: 'granite-strength',
36
+ value: 1.3e8,
37
+ unit: 'Pa',
38
+ source: 'calibrated',
39
+ scalesWithAlpha: true,
40
+ domain: 'α 偏离现实 < 50%',
41
+ note: '花岗岩抗压强度,作为材料强度 S ∝ α⁵ 的标定点(现实宇宙取值)',
42
+ },
43
+ {
44
+ id: 'lapse-moist-factor',
45
+ value: 0.665,
46
+ source: 'calibrated',
47
+ scalesWithAlpha: false,
48
+ domain: '地球型大气(N₂/O₂/CO₂ 量级)',
49
+ note: '干绝热 Γ=g·M/(3.5R) 到湿绝热的修正系数,用地球 6.5 K/km 标定',
50
+ },
51
+ {
52
+ id: 'ocean-inertia',
53
+ value: 0.5,
54
+ source: 'calibrated',
55
+ scalesWithAlpha: true,
56
+ domain: 'α 偏离现实 < 20%',
57
+ note: '海洋热惯性对季节振幅的阻尼;热容 ∝ 键能 ∝ α²',
58
+ },
59
+ {
60
+ id: 'atmosphere-inertia',
61
+ value: 0.15,
62
+ source: 'calibrated',
63
+ scalesWithAlpha: false,
64
+ domain: '气压 0–5 atm',
65
+ note: '大气输运对季节振幅的阻尼系数(每 atm)',
66
+ },
67
+ {
68
+ id: 'rayleigh-tau550',
69
+ value: 0.1,
70
+ source: 'calibrated',
71
+ scalesWithAlpha: true,
72
+ domain: 'α 偏离现实 < 20%',
73
+ note: '地球大气 550nm 垂直光学厚度;散射截面 ∝ α²',
74
+ },
75
+ {
76
+ id: 'tidal-lock-timescale',
77
+ value: '0.5 Gyr',
78
+ source: 'calibrated',
79
+ scalesWithAlpha: false,
80
+ domain: '岩石质卫星、近圆顺行轨道',
81
+ note: '地月系统标定的潮汐锁定时间尺度;换材料只保证量级',
82
+ },
83
+ {
84
+ id: 'mutual-hill-spacing',
85
+ value: 3.5,
86
+ source: 'calibrated',
87
+ scalesWithAlpha: false,
88
+ domain: '顺行、近圆轨道、质量比 < 1e-2',
89
+ note: 'Gladman 1993 数值判据:相邻卫星间距 ≥ 3.5 倍互相希尔半径',
90
+ },
91
+ {
92
+ id: 'roche-fluid-factor',
93
+ value: 2.44,
94
+ source: 'first-principles',
95
+ scalesWithAlpha: false,
96
+ domain: '流体假设;刚体约 1.26',
97
+ note: '洛希极限系数 d = 2.44·R·(ρp/ρm)^(1/3)',
98
+ },
99
+ {
100
+ id: 'night-star-count',
101
+ value: 9100,
102
+ source: 'calibrated',
103
+ scalesWithAlpha: false,
104
+ domain: '地球夜空、极限星等 6.5',
105
+ note: '全天可见星数基准,用于亮度↔星数换算',
106
+ },
107
+ {
108
+ id: 'full-moon-lux',
109
+ value: 0.25,
110
+ unit: 'lux',
111
+ source: 'calibrated',
112
+ scalesWithAlpha: false,
113
+ domain: '地球月球的反照率与距离',
114
+ note: '满月在地表的照度基准',
115
+ },
116
+ {
117
+ id: 'moon-albedo',
118
+ value: 0.12,
119
+ source: 'contingent',
120
+ scalesWithAlpha: false,
121
+ domain: '作者可改',
122
+ note: '月球几何反照率;不同卫星差异可达数倍',
123
+ },
124
+ {
125
+ id: 'moon-density',
126
+ value: 3344,
127
+ unit: 'kg/m³',
128
+ source: 'contingent',
129
+ scalesWithAlpha: false,
130
+ domain: '作者可改',
131
+ note: '月球密度;冰质卫星约 1000–2000,铁质更高',
132
+ },
133
+ {
134
+ id: 'biological-size-limit',
135
+ value: '25 m',
136
+ source: 'contingent',
137
+ scalesWithAlpha: false,
138
+ domain: '地球碳基生物 + 平方-立方定律',
139
+ note: '陆生生物体长上限基准(蜥脚类),随重力反比缩放',
140
+ },
141
+ ]
142
+
143
+ /** 按来源统计条数。 */
144
+ export function provenanceSummary(): { firstPrinciples: number; calibrated: number; contingent: number } {
145
+ return {
146
+ firstPrinciples: MODEL_CONSTANTS.filter((x) => x.source === 'first-principles').length,
147
+ calibrated: MODEL_CONSTANTS.filter((x) => x.source === 'calibrated').length,
148
+ contingent: MODEL_CONSTANTS.filter((x) => x.source === 'contingent').length,
149
+ }
150
+ }
151
+
152
+ /**
153
+ * 生成给作者看的可信度说明(逐行)。
154
+ * @param onlyCalibrated - 只列地球标定项(默认 false,三类都列概要)。
155
+ */
156
+ export function describeProvenance(onlyCalibrated = false): string[] {
157
+ const s = provenanceSummary()
158
+ const lines: string[] = []
159
+ lines.push(
160
+ `第一性原理 ${s.firstPrinciples} 条(严格物理关系);地球标定 ${s.calibrated} 条(有效范围有限);设定自由 ${s.contingent} 条(不可推导)。`,
161
+ )
162
+
163
+ if (!onlyCalibrated) {
164
+ lines.push(' 地球标定项(这些会随常数偏离而失真):')
165
+ for (const item of MODEL_CONSTANTS.filter((x) => x.source === 'calibrated')) {
166
+ lines.push(` · ${item.id}: ${item.value}${item.unit ?? ''} 适用域 ${item.domain}`)
167
+ }
168
+ }
169
+
170
+ lines.push(' 设定自由项(这些不是物理,是作者选择):')
171
+ for (const item of MODEL_CONSTANTS.filter((x) => x.source === 'contingent')) {
172
+ lines.push(` · ${item.id}: ${item.value}${item.unit ?? ''}`)
173
+ }
174
+
175
+ return lines
176
+ }