@sleep2agi/commhub-server 0.9.0-preview.26 → 0.9.0-preview.261

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 (431) hide show
  1. package/README.md +120 -3
  2. package/bin/commhub.ts +93 -9
  3. package/build-info.json +7 -0
  4. package/package.json +10 -8
  5. package/src/ack-create-request-transport.test.ts +182 -0
  6. package/src/ack-create-request.test.ts +52 -8
  7. package/src/admin-delete-network-http.test.ts +228 -0
  8. package/src/admin-networks-http.test.ts +88 -0
  9. package/src/adoption-candidates-http.test.ts +140 -0
  10. package/src/adoption-candidates.ts +158 -0
  11. package/src/agent-access-batch.test.ts +210 -0
  12. package/src/agent-access.ts +487 -0
  13. package/src/agent-acl-groups-http.test.ts +247 -0
  14. package/src/agent-acl-http.test.ts +680 -0
  15. package/src/agent-acl-slice3-http.test.ts +885 -0
  16. package/src/agent-department-http.test.ts +215 -0
  17. package/src/agent-groups-perf.test.ts +223 -0
  18. package/src/agent-notice.ts +48 -0
  19. package/src/agent-team-whoami-http.test.ts +98 -0
  20. package/src/agent-teams-http.test.ts +330 -0
  21. package/src/agent-teams.ts +244 -0
  22. package/src/alias-baseline-2571.test.ts +162 -0
  23. package/src/alias-baseline.ts +113 -0
  24. package/src/alias-filter.test.ts +72 -0
  25. package/src/alias-filter.ts +42 -0
  26. package/src/api-host-supervisors-can-create-nodes.test.ts +350 -0
  27. package/src/api-host-supervisors-fallback.test.ts +6 -7
  28. package/src/api-host-supervisors-runtime-readiness.test.ts +195 -0
  29. package/src/api-nodes-shape.test.ts +131 -4
  30. package/src/auth-abuse-counters.test.ts +144 -0
  31. package/src/auth-abuse-counters.ts +122 -0
  32. package/src/auth-password-change-cli-tokens-http.test.ts +423 -0
  33. package/src/auth-sessions-http.test.ts +260 -0
  34. package/src/auth-validate.test.ts +5 -1
  35. package/src/auth-weak-password-login.test.ts +176 -0
  36. package/src/auth.ts +609 -56
  37. package/src/backfill-node-ids-2664.test.ts +128 -0
  38. package/src/binding-generation-http.test.ts +141 -0
  39. package/src/blocked-exit-on-reply.test.ts +122 -0
  40. package/src/broadcast-fanout-2721.test.ts +149 -0
  41. package/src/broadcast-fanout.ts +117 -0
  42. package/src/build-commit-report-http.test.ts +128 -0
  43. package/src/build-info.test.ts +60 -0
  44. package/src/build-info.ts +85 -0
  45. package/src/chain-attempt-dedup.test.ts +447 -0
  46. package/src/clip.test.ts +36 -0
  47. package/src/clip.ts +48 -0
  48. package/src/clone-node.test.ts +269 -0
  49. package/src/clone-node.ts +289 -0
  50. package/src/codex-config-flags.ts +77 -0
  51. package/src/codex-fork-contract.ts +23 -0
  52. package/src/codex-fork-migration.test.ts +38 -0
  53. package/src/commhub-bin-args.test.ts +85 -0
  54. package/src/config-apply-validate.test.ts +188 -1
  55. package/src/config-apply-validate.ts +222 -3
  56. package/src/cors-origins.test.ts +73 -0
  57. package/src/create-node-blocked-gate.test.ts +365 -0
  58. package/src/create-node-error-domain.test.ts +127 -0
  59. package/src/create-node-network-id.test.ts +91 -0
  60. package/src/create-node-tool-schema.test.ts +49 -0
  61. package/src/create-node-unicode-name.test.ts +126 -0
  62. package/src/create-node-validate.test.ts +199 -7
  63. package/src/create-node-validate.ts +232 -15
  64. package/src/create-node-workdir.test.ts +298 -0
  65. package/src/create-node.ts +88 -23
  66. package/src/daemon-provider-snapshots.test.ts +453 -0
  67. package/src/daemon-provider-snapshots.ts +327 -0
  68. package/src/daemon-token-owner-http.test.ts +346 -0
  69. package/src/dashboard-slash-routing-http.test.ts +109 -0
  70. package/src/db-adapter-guard.test.ts +148 -0
  71. package/src/db-adapter-translate.test.ts +128 -0
  72. package/src/db-adapter.ts +377 -91
  73. package/src/db-timestamp.test.ts +38 -0
  74. package/src/db-timestamp.ts +15 -0
  75. package/src/db.ts +1269 -153
  76. package/src/delivered-without-push.test.ts +140 -0
  77. package/src/department-groups-http.test.ts +209 -0
  78. package/src/department-groups-sync-http.test.ts +328 -0
  79. package/src/department-groups.ts +434 -0
  80. package/src/department-heads-http.test.ts +350 -0
  81. package/src/department-heads.ts +226 -0
  82. package/src/departments-agent-count.test.ts +139 -0
  83. package/src/departments-http.test.ts +185 -0
  84. package/src/departments-mcp-error-domain.test.ts +135 -0
  85. package/src/departments-mcp.test.ts +128 -0
  86. package/src/departments.ts +318 -0
  87. package/src/desktop-message-seam.test.ts +150 -0
  88. package/src/desktop-message.test.ts +368 -0
  89. package/src/dm-file-scope-http.test.ts +178 -0
  90. package/src/empty-node-sweeper.test.ts +104 -0
  91. package/src/empty-node-sweeper.ts +88 -0
  92. package/src/env-transport-gate-http.test.ts +240 -0
  93. package/src/env-transport-gate.ts +80 -0
  94. package/src/env-transport-policy.ts +56 -0
  95. package/src/etag-of.test.ts +57 -0
  96. package/src/event-loop-lag.test.ts +180 -0
  97. package/src/event-loop-lag.ts +201 -0
  98. package/src/expiry-counters.test.ts +187 -0
  99. package/src/expiry-counters.ts +227 -0
  100. package/src/expiry-evidence-db.test.ts +103 -0
  101. package/src/ext-token-shared.test.ts +60 -0
  102. package/src/ext-validation-regression.test.ts +10 -17
  103. package/src/external-schedule-edits-http.test.ts +321 -0
  104. package/src/external-schedule-edits-timestamps.test.ts +64 -0
  105. package/src/external-schedule-edits.ts +327 -0
  106. package/src/file-download-authz-dev-open.test.ts +1 -1
  107. package/src/file-download-authz.test.ts +25 -4
  108. package/src/file-download-date-bucket.test.ts +1 -1
  109. package/src/file-network-scope-dev-open.test.ts +1 -1
  110. package/src/file-network-scope.test.ts +7 -6
  111. package/src/group-membership-events-http.test.ts +264 -0
  112. package/src/group-messages-http.test.ts +483 -0
  113. package/src/group-messages.ts +297 -0
  114. package/src/health-anon-readers.ts +67 -0
  115. package/src/health-host-disk-2756.test.ts +71 -0
  116. package/src/health-redaction.test.ts +1576 -7
  117. package/src/host-supervisor-identity-http.test.ts +152 -0
  118. package/src/host-supervisor-identity.ts +92 -0
  119. package/src/host-supervisors-daemon-version.test.ts +137 -0
  120. package/src/http-gzip.test.ts +94 -0
  121. package/src/http-gzip.ts +112 -0
  122. package/src/hub-catalog-read-http.test.ts +641 -0
  123. package/src/hub-provider-config.test.ts +166 -0
  124. package/src/hub-provider-config.ts +202 -0
  125. package/src/hub-timestamp.test.ts +38 -0
  126. package/src/hub-timestamp.ts +27 -0
  127. package/src/human-dm.ts +215 -0
  128. package/src/human-inbox.ts +42 -0
  129. package/src/inbox-caller.ts +49 -0
  130. package/src/inbox-count-sse.test.ts +318 -0
  131. package/src/inbox-count.ts +29 -0
  132. package/src/index.ts +6 -2
  133. package/src/license-state.test.ts +56 -0
  134. package/src/license-state.ts +48 -0
  135. package/src/lifecycle-error-domain.test.ts +149 -0
  136. package/src/list-ack-error-domain.test.ts +108 -0
  137. package/src/list-host-supervisors.test.ts +15 -4
  138. package/src/mcp-context-cost-http.test.ts +127 -0
  139. package/src/mcp-inflight.test.ts +92 -0
  140. package/src/mcp-inflight.ts +38 -0
  141. package/src/mcp-projects-events-http.test.ts +168 -0
  142. package/src/mcp-route-label-http.test.ts +120 -0
  143. package/src/mcp-write-network-resolution.test.ts +21 -0
  144. package/src/member-audit-network-id-http.test.ts +93 -0
  145. package/src/member-presence-http.test.ts +210 -0
  146. package/src/messages-ack-by-agent-http.test.ts +142 -0
  147. package/src/migrate-sqlite-to-pg.test.ts +47 -0
  148. package/src/migrate-sqlite-to-pg.ts +263 -0
  149. package/src/model-auth-notify-http.test.ts +181 -0
  150. package/src/model-auth-notify.ts +116 -0
  151. package/src/network-name-http.test.ts +75 -0
  152. package/src/network-rules-http.test.ts +169 -0
  153. package/src/network-rules.ts +129 -0
  154. package/src/network-scope.ts +222 -3
  155. package/src/network-token-membership-http.test.ts +186 -0
  156. package/src/node-alias-control.ts +12 -0
  157. package/src/node-attrs.test.ts +47 -2
  158. package/src/node-caller-identity-http.test.ts +1108 -0
  159. package/src/node-create-request-status-http.test.ts +105 -0
  160. package/src/node-daemon-bindings.test.ts +142 -0
  161. package/src/node-daemon-bindings.ts +135 -0
  162. package/src/node-failure-alert.test.ts +150 -0
  163. package/src/node-failure-alert.ts +177 -0
  164. package/src/node-files-transport.test.ts +350 -0
  165. package/src/node-health-codex-login.test.ts +120 -0
  166. package/src/node-health-dispatch-http.test.ts +373 -0
  167. package/src/node-health-guard.ts +121 -0
  168. package/src/node-health-passthrough.test.ts +115 -0
  169. package/src/node-health-store.ts +101 -0
  170. package/src/node-id-alias.test.ts +190 -0
  171. package/src/node-identity-conflict-http.test.ts +269 -0
  172. package/src/node-identity-conflict.ts +142 -0
  173. package/src/node-identity-mismatch.test.ts +74 -0
  174. package/src/node-in-flight-tasks.ts +31 -0
  175. package/src/node-lifecycle-controllable.test.ts +64 -0
  176. package/src/node-lifecycle-controllable.ts +53 -0
  177. package/src/node-lifecycle-read-http.test.ts +257 -0
  178. package/src/node-lifecycle-read.ts +124 -0
  179. package/src/node-logs-transport.test.ts +266 -0
  180. package/src/node-peer-allowlist.test.ts +114 -0
  181. package/src/node-permissions-http.test.ts +728 -0
  182. package/src/node-permissions.ts +494 -0
  183. package/src/node-request-retention.test.ts +281 -0
  184. package/src/node-request-retention.ts +120 -0
  185. package/src/node-secret-rest-http.test.ts +190 -0
  186. package/src/node-security-write-gate.test.ts +72 -0
  187. package/src/node-serviceability.test.ts +86 -0
  188. package/src/node-serviceability.ts +124 -0
  189. package/src/node-session-control-http.test.ts +310 -0
  190. package/src/node-session-control.ts +258 -0
  191. package/src/node-skills-transport.test.ts +212 -0
  192. package/src/node-token-identity.ts +35 -0
  193. package/src/node-token-ownership.ts +51 -0
  194. package/src/node-token-privilege-http.test.ts +158 -0
  195. package/src/not-found-api-http.test.ts +67 -0
  196. package/src/observer-avatar-http.test.ts +103 -10
  197. package/src/observer-push.test.ts +76 -0
  198. package/src/opencode-catalog-report-http.test.ts +139 -0
  199. package/src/opencode-v2-catalog.test.ts +268 -0
  200. package/src/opencode-v2-catalog.ts +356 -0
  201. package/src/package-version-consistency.test.ts +25 -0
  202. package/src/parent-infer.test.ts +82 -0
  203. package/src/parent-infer.ts +110 -0
  204. package/src/parent-source-marker.test.ts +70 -0
  205. package/src/password-network-tokens.ts +25 -0
  206. package/src/peer-reply-atomic.test.ts +462 -0
  207. package/src/peer-reply-capability.test.ts +70 -0
  208. package/src/pg-worker.ts +87 -0
  209. package/src/poll-pacing.test.ts +74 -0
  210. package/src/poll-pacing.ts +123 -0
  211. package/src/probe-provider-error-domain.test.ts +145 -0
  212. package/src/project-dir-warn-clear-http.test.ts +132 -0
  213. package/src/project-viewer-can-http.test.ts +116 -0
  214. package/src/provider-skill-error-domain.test.ts +130 -0
  215. package/src/provider-tools-shape.test.ts +165 -0
  216. package/src/push.test.ts +20 -10
  217. package/src/push.ts +373 -9
  218. package/src/redact-tokens.test.ts +86 -0
  219. package/src/redact-tokens.ts +43 -0
  220. package/src/rejection-counters.test.ts +72 -0
  221. package/src/rejection-counters.ts +173 -0
  222. package/src/rename.ts +38 -10
  223. package/src/reply-target-derivation.test.ts +96 -0
  224. package/src/report-status-handover-capabilities-http.test.ts +124 -0
  225. package/src/report-status-host-schema.test.ts +235 -0
  226. package/src/report-status-resume-id-handover.test.ts +184 -0
  227. package/src/report-status-secret-keys.test.ts +140 -0
  228. package/src/require-explicit-test-db.ts +9 -0
  229. package/src/requirement-due-reminders-http.test.ts +620 -0
  230. package/src/requirement-due-reminders.ts +416 -0
  231. package/src/requirement-events-http.test.ts +318 -0
  232. package/src/requirement-events.test.ts +45 -0
  233. package/src/requirement-events.ts +144 -0
  234. package/src/requirement-notify.ts +165 -0
  235. package/src/requirement-participant-notify-http.test.ts +313 -0
  236. package/src/requirement-tag-ops-http.test.ts +454 -0
  237. package/src/requirement-tag-tree-http.test.ts +275 -0
  238. package/src/requirement-tag-tree.ts +127 -0
  239. package/src/requirement-tags.ts +102 -0
  240. package/src/requirements-abandoned-http.test.ts +236 -0
  241. package/src/requirements-assignee-drift.test.ts +154 -0
  242. package/src/requirements-comment-http.test.ts +174 -0
  243. package/src/requirements-completed-at-migration.test.ts +70 -0
  244. package/src/requirements-errors-mcp-http.test.ts +164 -0
  245. package/src/requirements-errors.ts +158 -0
  246. package/src/requirements-etag-http.test.ts +91 -0
  247. package/src/requirements-http.test.ts +709 -0
  248. package/src/requirements-last-event-http.test.ts +349 -0
  249. package/src/requirements-list-mcp-slim-http.test.ts +155 -0
  250. package/src/requirements-list-slim-http.test.ts +324 -0
  251. package/src/requirements-mcp.test.ts +180 -0
  252. package/src/requirements-migrate.ts +283 -0
  253. package/src/requirements-owner-strict-mcp-http.test.ts +145 -0
  254. package/src/requirements-people-http.test.ts +114 -0
  255. package/src/requirements-people-mcp-http.test.ts +231 -0
  256. package/src/requirements-people.ts +196 -0
  257. package/src/requirements-priority-lowest.test.ts +114 -0
  258. package/src/requirements-projects-network-echo.test.ts +57 -0
  259. package/src/requirements-projects-parent-http.test.ts +123 -0
  260. package/src/requirements-search-http.test.ts +182 -0
  261. package/src/requirements-search.test.ts +32 -0
  262. package/src/requirements-search.ts +145 -0
  263. package/src/requirements-seq-http.test.ts +193 -0
  264. package/src/requirements-seq-migration.test.ts +63 -0
  265. package/src/requirements-start-date.test.ts +125 -0
  266. package/src/requirements-stats-http.test.ts +357 -0
  267. package/src/requirements-stats.ts +195 -0
  268. package/src/requirements-status-participants-http.test.ts +222 -0
  269. package/src/requirements-upgrade-e2e.test.ts +126 -0
  270. package/src/requirements-upgrade-migration.test.ts +98 -0
  271. package/src/requirements.ts +2205 -0
  272. package/src/resolve-port.test.ts +57 -0
  273. package/src/resolve-port.ts +44 -0
  274. package/src/rest-alias-network-fallback-http.test.ts +123 -0
  275. package/src/rest-alias-network-fallback.test.ts +60 -0
  276. package/src/rest-alias-network-fallback.ts +65 -0
  277. package/src/rest-explicit-columns-http.test.ts +266 -0
  278. package/src/rest-identity.test.ts +130 -0
  279. package/src/rest-identity.ts +141 -0
  280. package/src/rest-projections.ts +72 -0
  281. package/src/rest-read-network-real-chain.test.ts +97 -0
  282. package/src/rest-write-network-resolution.test.ts +133 -0
  283. package/src/restart-readiness-http.test.ts +121 -0
  284. package/src/restricted-files.ts +76 -0
  285. package/src/retention-first-sweep-quiet.test.ts +31 -0
  286. package/src/retention.test.ts +100 -40
  287. package/src/retention.ts +423 -104
  288. package/src/route-callers-http.test.ts +120 -0
  289. package/src/route-timing.test.ts +218 -0
  290. package/src/route-timing.ts +262 -0
  291. package/src/rules-file-duplicate-alias.test.ts +234 -0
  292. package/src/rules-file-session-target.test.ts +207 -0
  293. package/src/rules-file-transport.test.ts +271 -0
  294. package/src/runtime-label.test.ts +22 -0
  295. package/src/runtime-label.ts +21 -0
  296. package/src/runtime-readiness.ts +90 -0
  297. package/src/schedule-agent-mcp-http.test.ts +486 -0
  298. package/src/schedule-agent.ts +252 -0
  299. package/src/schedule-starved.test.ts +92 -0
  300. package/src/schedule-starved.ts +114 -0
  301. package/src/scheduled-backoff-http.test.ts +203 -0
  302. package/src/scheduled-backoff.ts +64 -0
  303. package/src/scheduled-doorbell-nodeless-session.test.ts +134 -0
  304. package/src/scheduled-failure-backoff-2622.test.ts +145 -0
  305. package/src/scheduled-failure-code.test.ts +73 -0
  306. package/src/scheduled-failure-code.ts +105 -0
  307. package/src/scheduled-failures-http.test.ts +279 -0
  308. package/src/scheduled-failures.ts +425 -0
  309. package/src/scheduled-noprogress-backoff-2622.test.ts +163 -0
  310. package/src/scheduled-offline-backoff-probe.test.ts +56 -0
  311. package/src/scheduled-offline.test.ts +131 -0
  312. package/src/scheduled-offline.ts +66 -0
  313. package/src/scheduled-outcome-guidance-http.test.ts +139 -0
  314. package/src/scheduled-outcome-guidance.ts +9 -0
  315. package/src/scheduled-reply-unread-http.test.ts +212 -0
  316. package/src/scheduled-requirement-wake-http.test.ts +289 -0
  317. package/src/scheduled-requirement-wake.ts +125 -0
  318. package/src/scheduled-run-terminal.test.ts +290 -0
  319. package/src/scheduled-skip-blocking-task.test.ts +120 -0
  320. package/src/scheduled-skip-path-backoff-2622.test.ts +98 -0
  321. package/src/scheduled-stuck-http.test.ts +316 -0
  322. package/src/scheduled-stuck-notice-cap.test.ts +80 -0
  323. package/src/scheduled-stuck.ts +219 -0
  324. package/src/scheduled-tasks-http.test.ts +679 -0
  325. package/src/scheduled-tasks.ts +959 -0
  326. package/src/scheduled-work-outcome-http.test.ts +154 -0
  327. package/src/scheduled-work-outcome.ts +50 -0
  328. package/src/scoped-secrets.ts +141 -0
  329. package/src/secret-echo-negative-control.test.ts +118 -0
  330. package/src/send-dedup-request-id.test.ts +229 -0
  331. package/src/send-reply-agent-warning.test.ts +38 -38
  332. package/src/send-reply-alias-optional.test.ts +131 -0
  333. package/src/send-reply-attachments.test.ts +28 -7
  334. package/src/send_dedup.test.ts +54 -0
  335. package/src/send_dedup.ts +52 -6
  336. package/src/serve-error.test.ts +73 -0
  337. package/src/serve-error.ts +56 -0
  338. package/src/server.ts +4846 -325
  339. package/src/session-task-on-dispatch.ts +14 -0
  340. package/src/session-token-ownership-http.test.ts +122 -0
  341. package/src/shared/codex-inventory.ts +41 -0
  342. package/src/shared/daemon-provider-login.ts +31 -0
  343. package/src/shared/daemon-provider-snapshot.ts +52 -0
  344. package/src/shared/external-schedule-contract.ts +60 -0
  345. package/src/shared/node-name.test.ts +62 -0
  346. package/src/shared/node-name.ts +161 -0
  347. package/src/shared/probe-host-allowlist-drift.test.ts +45 -0
  348. package/src/shared/provider-application.ts +29 -0
  349. package/src/shared/provider-collection.ts +14 -0
  350. package/src/shared/provider-initialization.ts +8 -0
  351. package/src/shared/reserved-env-drift.test.ts +10 -0
  352. package/src/shared/scoped-secret-contract.ts +5 -0
  353. package/src/shared/task-content-limit-drift.test.ts +28 -0
  354. package/src/shared/task-content-limit.ts +25 -0
  355. package/src/side-thread-command-transport.test.ts +312 -0
  356. package/src/side-thread-command-transport.ts +318 -0
  357. package/src/side-thread-http-integration.test.ts +233 -0
  358. package/src/side-thread-http.ts +504 -0
  359. package/src/side-thread-production.test.ts +72 -0
  360. package/src/side-thread-production.ts +118 -0
  361. package/src/side-thread.test.ts +1067 -0
  362. package/src/side-thread.ts +2499 -0
  363. package/src/skillhub-http.test.ts +144 -0
  364. package/src/sqlite-close-checkpoint.test.ts +78 -0
  365. package/src/start-node.test.ts +265 -0
  366. package/src/start-request-error-domain.test.ts +182 -0
  367. package/src/start-skill-error-domain.test.ts +122 -0
  368. package/src/stats-versions-http.test.ts +65 -0
  369. package/src/status-alias-filter-http.test.ts +106 -0
  370. package/src/status-alias-resolver-http.test.ts +163 -0
  371. package/src/status-alias-resolver.ts +19 -0
  372. package/src/status-node-id-filter-http.test.ts +161 -0
  373. package/src/status-read-cache-http.test.ts +229 -0
  374. package/src/status-read-cache.ts +129 -0
  375. package/src/stop-delete-node.test.ts +567 -1
  376. package/src/task-access-http.test.ts +402 -0
  377. package/src/task-access.ts +420 -0
  378. package/src/task-activity.ts +60 -0
  379. package/src/task-auth-origin-http.test.ts +93 -0
  380. package/src/task-auth-origin.test.ts +24 -0
  381. package/src/task-auth-origin.ts +7 -0
  382. package/src/task-consumption.test.ts +508 -0
  383. package/src/task-diagnostic-http.test.ts +149 -0
  384. package/src/task-diagnostic.test.ts +115 -0
  385. package/src/task-diagnostic.ts +118 -0
  386. package/src/task-expiry-notice-http.test.ts +298 -0
  387. package/src/task-expiry-notice.ts +318 -0
  388. package/src/task-idempotency-mcp.test.ts +148 -0
  389. package/src/task-idempotency.test.ts +76 -0
  390. package/src/task-idempotency.ts +81 -0
  391. package/src/task-late-replies.ts +54 -0
  392. package/src/task-late-reply-http.test.ts +227 -0
  393. package/src/task-lifecycle-watcher-busy.test.ts +114 -0
  394. package/src/task-lifecycle-watcher.test.ts +209 -0
  395. package/src/task-lifecycle-watcher.ts +109 -0
  396. package/src/task-network-resolution-http.test.ts +140 -0
  397. package/src/task-not-found-error-domain.test.ts +114 -0
  398. package/src/task-offline-delivery-2668.test.ts +119 -0
  399. package/src/task-offline-delivery.ts +81 -0
  400. package/src/task-orphan-http.test.ts +287 -0
  401. package/src/task-orphan.ts +119 -0
  402. package/src/task-queue-ahead-http.test.ts +309 -0
  403. package/src/task-queue-ahead-scale.test.ts +236 -0
  404. package/src/task-queue-ahead.ts +186 -0
  405. package/src/task-rejection-log-http.test.ts +160 -0
  406. package/src/task-rejection-log.ts +61 -0
  407. package/src/task-sender-http.test.ts +143 -0
  408. package/src/task-stale-open-http.test.ts +292 -0
  409. package/src/task-stale-open.ts +103 -0
  410. package/src/tasks-pagination-http.test.ts +141 -0
  411. package/src/team-rules-status-http.test.ts +90 -0
  412. package/src/team-rules-status.test.ts +59 -0
  413. package/src/team-rules-status.ts +72 -0
  414. package/src/tmux-allowlist.test.ts +48 -0
  415. package/src/tool-audience-http.test.ts +248 -0
  416. package/src/tool-audience.ts +127 -0
  417. package/src/tools-list-json-schema.test.ts +94 -0
  418. package/src/tools.ts +4229 -397
  419. package/src/update-node-config-error-domain.test.ts +107 -0
  420. package/src/uploads-http.test.ts +6 -4
  421. package/src/uploads.ts +23 -4
  422. package/src/user-avatar-http.test.ts +74 -0
  423. package/src/user-avatar-image.ts +160 -0
  424. package/src/user-avatar-migration.test.ts +25 -0
  425. package/src/user-avatar-upload-http.test.ts +348 -0
  426. package/src/user-inbox-by-agent-http.test.ts +165 -0
  427. package/src/user-inbox-netid-notnull.test.ts +122 -0
  428. package/src/user-inbox-read-http.test.ts +223 -0
  429. package/src/user-inbox-schema.test.ts +54 -0
  430. package/src/version-stats.test.ts +66 -0
  431. package/src/version-stats.ts +109 -0
@@ -15,8 +15,11 @@ import { describe, expect, test, beforeAll, afterAll } from "bun:test";
15
15
  import { mkdtempSync, rmSync } from "fs";
16
16
  import { join } from "path";
17
17
  import { tmpdir } from "os";
18
+ import { createHash } from "node:crypto";
18
19
  import { register, addNetworkMember, removeNetworkMember } from "./auth.js";
19
20
  import { db } from "./db.js";
21
+ import { MAX_REQUEST_CONTENT_LENGTH, MAX_UPLOAD_BYTES } from "./uploads.js";
22
+ import { HEALTH_FIELD_META, PUBLIC_HEALTH_KEYS, mayBePublic, projectPublicHealth } from "./server.js";
20
23
 
21
24
  const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-health-red-db-")) + "/commhub.db";
22
25
 
@@ -29,6 +32,10 @@ let userNetworkId = "";
29
32
  let userName = "";
30
33
  let adminToken = "";
31
34
 
35
+ // 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
36
+ // 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
37
+ // (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
38
+ // 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
32
39
  beforeAll(async () => {
33
40
  process.env.COMMHUB_DB = process.env.COMMHUB_DB || SERVER_DB;
34
41
  process.env.HOST = "127.0.0.1";
@@ -71,7 +78,7 @@ beforeAll(async () => {
71
78
  if (res.status !== 200) throw new Error("SSE subscribe failed: " + res.status);
72
79
  sseReader = res.body!.getReader();
73
80
  await sseReader.read(); // consume the connected frame → registration done
74
- });
81
+ }, 30_000);
75
82
 
76
83
  afterAll(() => {
77
84
  try { sseReader?.cancel(); } catch {}
@@ -85,12 +92,1526 @@ describe("#473 anonymous /health — watchdog contract intact, no topology leak"
85
92
  expect(res.status).toBe(200);
86
93
  const body = await res.json() as any;
87
94
  expect(body.ok).toBe(true);
88
- expect(typeof body.version).toBe("string");
89
- expect(typeof body.sessions_count).toBe("number");
90
- expect(typeof body.sse_connections).toBe("number");
95
+ // 2026-10-31 —— **类型不是断言**(外部复核:「写『存在』⇒ 它被改成任何值都绿」)。
96
+ // 这三行原来只断言 typeof ⇒ 一个空字符串版本号、一个负数会话数、一个 -1 连接数都会绿。
97
+ expect(body.version).toMatch(/^\d+\.\d+\.\d+(-[a-z0-9.]+)?$/); // 形如 0.9.0-preview.244
98
+ expect(Number.isInteger(body.sessions_count)).toBe(true);
99
+ expect(body.sessions_count).toBeGreaterThanOrEqual(0);
100
+ expect(Number.isInteger(body.sse_connections)).toBe(true);
91
101
  expect(body.sse_connections).toBeGreaterThanOrEqual(1);
92
102
  });
93
103
 
104
+ // 2026-10-31 —— 站位要可验,但**匿名读者只配知道「有没有」,不配知道「是什么」**。
105
+ // /health 是匿名端点;commit sha 对匿名读者 = 精确告诉外部这是哪一版代码(本仓公开)。
106
+ // ⇒ 匿名给布尔 build_identified;完整 sha(+dirty)只给已鉴权者。
107
+ test("anonymous /health discloses only whether a build id exists, never the sha", async () => {
108
+ const res = await fetch(`${BASE}/health`);
109
+ const body = await res.json() as any;
110
+ expect("git_commit" in body).toBe(false);
111
+ expect("git_dirty" in body).toBe(false);
112
+ // 2026-10-31 —— #3214 收尾:这里原来是 `typeof === "boolean"`,它证明「有个布尔」,
113
+ // 不证明这个布尔**说的是实话**。改问两个投影是否一致:
114
+ // 匿名给「有没有」,鉴权给「是什么」⇒ 两个投影必须互相印证(同一台 server 同一 BOOT_GIT_COMMIT)。
115
+ // 这能抓住「匿名侧按请求现算是非、鉴权侧读启动常量」这类分叉,类型断言抓不住。
116
+ const authed = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
117
+ expect(body.build_identified).toBe(authed.git_commit !== null);
118
+ });
119
+
120
+ test("authenticated admin /health carries git_commit (40-hex or null) and git_dirty", async () => {
121
+ const res = await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } });
122
+ const body = await res.json() as any;
123
+ expect("git_commit" in body).toBe(true);
124
+ const value = body.git_commit;
125
+ const isSha = typeof value === "string" && /^[0-9a-f]{40}$/.test(value);
126
+ // null 是设计(没有 .git),不是缺陷;但任何别的形状都不允许。
127
+ expect(isSha || value === null).toBe(true);
128
+ if (value !== null) expect(value).not.toBe(body.version);
129
+ // dirty 位必须与 sha 成对,否则 vantage 会把脏树读数当成提交。
130
+ //
131
+ // 2026-10-31 —— 这里原来写的是 `if (value === null) expect(git_dirty).toBe(false)`。
132
+ // 它与服务端的契约**相反**:server.ts 是 `git_dirty: BOOT_GIT.commit ? BOOT_GIT.dirty : null`
133
+ // (「commit 为空时必须是 null(不是 false)」)。
134
+ // 而本地跑永远走不到这一支 —— 因为仓库里**有** .git ⇒ value 非空 ⇒ 那条断言一次都没执行过。
135
+ // CI 的容器镜像只 COPY 源码(没有 .git)⇒ 走 null 支 ⇒ 立刻红(run 41140921488)。
136
+ // ⇒ 两个环境各只能看到一半,所以这里必须把**两条分支都写成断言**,而不是只写走到的那条。
137
+ if (value === null) expect(body.git_dirty).toBeNull();
138
+ else expect(typeof body.git_dirty).toBe("boolean");
139
+ });
140
+
141
+ // 2026-10-31 —— 拒绝计数的 **must-fire**:注入一次真实拒绝,看它跳不跳。
142
+ //
143
+ // 为什么必须有这一条:光断言 by_reason 存在,测的是形状;形状对、接线错,读数照样是 0。
144
+ // 而「只有异常路径能让它 +1」这一类,0 与「从没出过错」同形 —— 不注入就永远发现不了。
145
+ test("a real rejected /api/task actually bumps the counter (must-fire, not just shape)", async () => {
146
+ const before = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
147
+ const beforeTotal = before.counters.task_rejections.total as number;
148
+
149
+ // 🔴 必须**带登录态**、并在 handler 内部失败:
150
+ // 全局鉴权中间件的 401 在到达 /api/task 之前就返回 ⇒ 根本不经过 logTaskRejection。
151
+ // (这本身就是一条已知缺口,写在 rejection-counters.ts 的注释里。)
152
+ const rej = await fetch(`${BASE}/api/task`, {
153
+ method: "POST",
154
+ headers: { "content-type": "application/json", Authorization: `Bearer ${userToken}` },
155
+ body: JSON.stringify({}), // schema 校验失败 ⇒ 400,走 reject()
156
+ });
157
+ expect(rej.status).toBeGreaterThanOrEqual(400);
158
+
159
+ const after = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
160
+ expect(after.counters.task_rejections.total).toBe(beforeTotal + 1);
161
+ // 🔴 窗口起点必须不动:计数器 +1 而 since 变化,会让「这段时间拒了几次」算错。
162
+ // 没有窗口的计数器是「没有域的数」;没有 must-fire 的计数器是「没有证据的数」。
163
+ expect(after.counters.since).toBe(before.counters.since);
164
+ expect(after.startedAt).toBe(before.startedAt);
165
+ // 2026-10-31 —— **窗口与值必须同响应**(外部复核 ③:窗口是分母,必须先固定再取数)。
166
+ // 本仓的结构比「s1 = since; v = counter; s2 = since」更强:since 与各计数在**同一份载荷**里,
167
+ // 单次读就原子,不存在跨越 reset 的长读。⇒ 这里把「同一个对象里」这件事钉住。
168
+ expect(Object.prototype.hasOwnProperty.call(before.counters, "since")).toBe(true);
169
+ // 2026-10-31 —— #3214 收尾:`typeof === "string"` 换成**同源**断言。
170
+ // counters.since 就是窗口起点 startedAt(server.ts: `counters: { since: startedAtIso, ... }`),
171
+ // 不是另取一次时间 ⇒ 两者必须逐字符相同;否则「窗口」与「计数」来自两个时钟域。
172
+ expect(before.counters.since).toBe(before.startedAt);
173
+ // 跨两次读的读者(如上面的 before/after 比较)必须自己比对 since —— 本条就是那个例子。
174
+ expect(before.counters.since.length).toBeGreaterThan(0);
175
+ const bumped = Object.keys(after.counters.task_rejections.by_reason).find(
176
+ (k) => k.startsWith(`${rej.status}:`),
177
+ );
178
+ expect(bumped).toBeTruthy();
179
+ });
180
+
181
+ // 2026-10-31 —— 把「已知缺口」钉在 CI 里,而不是只写在注释里。
182
+ //
183
+ // 🔴 这条断言的语义是:**目前如此**,不是「应该如此」。
184
+ // 将来谁把计数上移到中间件,这条会红 —— 那就对了:他必须同时更新
185
+ // 模块注释里的覆盖比例(现在是 2/6 类出口)。
186
+ test("KNOWN GAP: unauthenticated /api/task rejection is NOT counted (see rejection-counters.ts)", async () => {
187
+ const before = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
188
+ const beforeTotal = before.counters.task_rejections.total as number;
189
+
190
+ // 不带 Authorization ⇒ 鉴权中间件在到达 handler 之前就返回 401。
191
+ const rej = await fetch(`${BASE}/api/task`, {
192
+ method: "POST",
193
+ headers: { "content-type": "application/json" },
194
+ body: JSON.stringify({}),
195
+ });
196
+ expect(rej.status).toBeGreaterThanOrEqual(400);
197
+
198
+ const after = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
199
+ if (after.counters.task_rejections.total !== beforeTotal) {
200
+ throw new Error(
201
+ "已知缺口已被修复?401 出口现在会计数了 —— "
202
+ + "请同时更新 rejection-counters.ts 的出口清单与覆盖比例(当前 2/6),"
203
+ + "并把这条测试改成断言「已被计数」。",
204
+ );
205
+ }
206
+ expect(after.counters.task_rejections.total).toBe(beforeTotal);
207
+ });
208
+
209
+ // 2026-10-31 —— 出口清单里最后一行空 pinned_by:**请求体超限**(Bun maxRequestBodySize)。
210
+ // 它是**运行时在 fetch() 之前**拒绝的:我们的代码一行都没跑 ⇒ 不可能计数。
211
+ // 这一条钉住的是「不计数」,而它最容易怀疑的方向恰好相反("那么大一个请求,肯定记了吧")。
212
+ test("KNOWN GAP: body over runtime maxRequestBodySize is NOT counted (rejected before fetch())", async () => {
213
+ const read = async () => (await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any);
214
+ const before = await read();
215
+ const huge = "x".repeat(MAX_REQUEST_CONTENT_LENGTH + 1024);
216
+ let status: number | null = null;
217
+ let rejectedAtTransport = false;
218
+ try {
219
+ const r = await fetch(`${BASE}/api/task`, {
220
+ method: "POST",
221
+ headers: { "content-type": "application/json", Authorization: `Bearer ${userToken}` },
222
+ body: huge,
223
+ });
224
+ status = r.status;
225
+ await r.text();
226
+ } catch {
227
+ rejectedAtTransport = true;
228
+ }
229
+ const after = await read();
230
+ // 形态有两条:运行时回 413,或传输层直接断(两者都算「没到我们的代码」)。
231
+ // 本机实测:**status=413**(Bun 在 fetch() 之前就回了,响应体不是我们的 handler 生成的)。
232
+ expect(rejectedAtTransport || status === 413).toBe(true);
233
+
234
+ // 2026-10-31 —— **否定断言必须配镜像**:上面「没计数」在「这条路由根本不通」时也成立。
235
+ // ⇒ 同一条路由 + 同一组鉴权头,用小请求体必须**走到 handler**(拿到 HTTP 状态码)。
236
+ // 两条合起来才说明:计数没变是**因为这个请求太大了**,不是因为这条路本来就不计数。
237
+ const control = await fetch(`${BASE}/api/task`, {
238
+ method: "POST",
239
+ headers: { "content-type": "application/json", Authorization: `Bearer ${userToken}` },
240
+ body: JSON.stringify({}),
241
+ });
242
+ expect(control.status).toBeGreaterThanOrEqual(200);
243
+ await control.text();
244
+ if (after.counters.task_rejections.total !== before.counters.task_rejections.total) {
245
+ throw new Error("已知缺口已被修复?超限请求体现在会计数了 —— 请更新 TASK_REJECTION_EXITS 与这条测试。");
246
+ }
247
+ expect(after.counters.task_rejections.total).toBe(before.counters.task_rejections.total);
248
+ });
249
+
250
+ // #3271 —— 「派单硬闸有没有真的 fire 过」必须是**匿名可读的聚合**。
251
+ // 我第一版把它只放在鉴权投影里(counters.task_expiries_never_consumed),
252
+ // 于是没有 token 的读者——包括当时的我——看不到它,也就无法验证它有没有 fire。
253
+ // 这两条断言把「公开的那一半」钉住:**给总数与窗口,不给 by_node**(节点名是拓扑)。
254
+ test("#3271 派单硬闸的读数:匿名给总数+窗口,by_node 留在鉴权投影", async () => {
255
+ const { PUBLIC_HEALTH_KEYS } = await import("./server.js");
256
+ expect(PUBLIC_HEALTH_KEYS.has("task_expiries_never_consumed_total")).toBe(true);
257
+ expect(PUBLIC_HEALTH_KEYS.has("counters_since")).toBe(true);
258
+ // by_node / last_at 不在公开白名单里 —— 拓扑不外泄(这条是**否定断言**,所以要配上面两条肯定断言)
259
+ expect(PUBLIC_HEALTH_KEYS.has("task_expiries_never_consumed")).toBe(false);
260
+ expect(PUBLIC_HEALTH_KEYS.has("by_node")).toBe(false);
261
+ const { neverConsumedExpiryCounters, noteNeverConsumedExpiry } = await import("./expiry-counters.js");
262
+ noteNeverConsumedExpiry("unread-probe-node");
263
+ const agg = neverConsumedExpiryCounters();
264
+ expect(agg.total).toBeGreaterThan(0);
265
+ expect(typeof agg.since).toBe("string");
266
+ expect(Object.keys(agg.by_node)).toContain("unread-probe-node");
267
+ });
268
+
269
+ // #3193 子卡 —— 拒绝次数的**总数**也必须匿名可读(明细 by_reason 仍留鉴权投影)。
270
+ test("#3193 拒绝计数:匿名给总数,by_reason 留鉴权", async () => {
271
+ const { PUBLIC_HEALTH_KEYS } = await import("./server.js");
272
+ expect(PUBLIC_HEALTH_KEYS.has("task_rejections_total")).toBe(true);
273
+ expect(PUBLIC_HEALTH_KEYS.has("counters")).toBe(false); // 明细不外泄
274
+ const { recordTaskRejection, taskRejectionCounters, resetTaskRejectionCounters } = await import("./rejection-counters.js");
275
+ resetTaskRejectionCounters();
276
+ recordTaskRejection(401, "invalid_token");
277
+ recordTaskRejection(401, "invalid_token");
278
+ recordTaskRejection(403, "forbidden");
279
+ const c = taskRejectionCounters();
280
+ expect(c.total).toBe(3);
281
+ expect(c.by_reason["401:invalid_token"]).toBe(2);
282
+ expect(c.by_reason["403:forbidden"]).toBe(1);
283
+ });
284
+
285
+ // 2026-10-31 —— 出口清单里「before_route_table」那一行原本 pinned_by 为空(= 缺口)。
286
+ // 补上它的钉:未匹配的 /api/* 在路由表之前就 404,**不经过 handler,也不计数**。
287
+ // 这一条同时是「清单要能被一次坏输入打出来」的实例(对方那句)。
288
+ test("KNOWN GAP: unmatched /api/* route 404 is NOT counted (route table rejects before handler)", async () => {
289
+ const read = async () => (await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any);
290
+ const before = await read();
291
+ const r = await fetch(`${BASE}/api/definitely-not-a-route-xyz`, {
292
+ method: "POST",
293
+ headers: { "content-type": "application/json", Authorization: `Bearer ${userToken}` },
294
+ body: JSON.stringify({}),
295
+ });
296
+ expect(r.status).toBeGreaterThanOrEqual(400);
297
+ const after = await read();
298
+ if (after.counters.task_rejections.total !== before.counters.task_rejections.total) {
299
+ throw new Error("已知缺口已被修复?404 出口现在会计数了 —— 请更新 TASK_REJECTION_EXITS 与这条测试。");
300
+ }
301
+ expect(after.counters.task_rejections.total).toBe(before.counters.task_rejections.total);
302
+ });
303
+
304
+ // 2026-10-31 —— **出口清单的分母要有来源**(外部复核 ②):
305
+ // 六行以前只活在注释里;现在它是数据,这条断言把「表」与「钉住它的测试」绑在一起。
306
+ // 2026-10-31 —— **白名单条目必须指得出读者**(外部复核 ⑤ 第 ②′ 问:路标还是仪表)。
307
+ // 三分类(landmark/gauge/credential)回答「该不该给」,这张表回答「谁在读」。
308
+ // 关键是它**跨源**:声明 reader=cli 的键,必须在 agent-network/src 里真的出现,
309
+ // 否则「有人在读」就只是白名单里的一个愿望。
310
+ test("every anonymous key names a reader, and reader=cli is cross-checked against the CLI source", async () => {
311
+ const { PUBLIC_HEALTH_KEYS } = await import("./server.js");
312
+ const { PUBLIC_HEALTH_KEY_READERS } = await import("./health-anon-readers.js");
313
+ const { readFileSync, readdirSync, statSync } = await import("node:fs");
314
+ const { join } = await import("node:path");
315
+
316
+ // ① 覆盖:白名单里每个键都要有读者登记,反之亦然(两边同集合,防「删了白名单留下登记」)
317
+ // 2026-10-31 —— 同样的空集风险:两个集合同时为空时这条相等断言照样通过。
318
+ expect([...PUBLIC_HEALTH_KEYS].length).toBeGreaterThan(10); // 今天 51 个;钉下限而不是钉具体数
319
+ expect(Object.keys(PUBLIC_HEALTH_KEY_READERS).sort()).toEqual([...PUBLIC_HEALTH_KEYS].sort());
320
+
321
+ // ② 读者类别必须在闭集里(防「reader: 某个系统」这种自由文本)
322
+ for (const [key, entry] of Object.entries(PUBLIC_HEALTH_KEY_READERS)) {
323
+ expect(["cli", "probe", "external", "operator"]).toContain(entry.reader);
324
+ // 「同上」在这一类表里是无效理由:它把理由指向另一行,而那行改了它不会跟着改。
325
+ expect(entry.why).not.toContain("同上");
326
+ expect(entry.why.length).toBeGreaterThan(3);
327
+ // external 必须写明「未验」或指明是哪类系统 —— 两种都接受,但不能什么都不说
328
+ if (entry.reader === "external") expect(entry.why.length).toBeGreaterThan(10);
329
+ expect(key.length).toBeGreaterThan(0);
330
+ }
331
+
332
+ // ③ 跨源:reader=cli 必须能在客户端源码里找到这个名字
333
+ // 两个根都要扫:`src/`(库)与 `bin/`(CLI 入口)。第一版只扫了 src,
334
+ // 于是把「只在 cli.ts 里读」的 4 个键误判成「没有读者」——
335
+ // 这正是这类跨源断言最容易出的错:**读者在,只是不在我扫的那个目录里**。
336
+ const roots = [
337
+ join(import.meta.dir, "..", "..", "agent-network", "src"),
338
+ join(import.meta.dir, "..", "..", "agent-network", "bin"),
339
+ ];
340
+ const walk = (dir: string, out: string[] = []): string[] => {
341
+ for (const name of readdirSync(dir)) {
342
+ const full = join(dir, name);
343
+ if (statSync(full).isDirectory()) walk(full, out);
344
+ else if (name.endsWith(".ts") && !name.endsWith(".test.ts")) out.push(full);
345
+ }
346
+ return out;
347
+ };
348
+ const cliSource = roots.flatMap((r) => walk(r)).map((f) => readFileSync(f, "utf8")).join("\n");
349
+ const cliKeys = Object.entries(PUBLIC_HEALTH_KEY_READERS).filter(([, e]) => e.reader === "cli").map(([k]) => k);
350
+ expect(cliKeys.length).toBeGreaterThan(0);
351
+ const missing = cliKeys.filter((k) => !new RegExp(`\\b${k}\\b`).test(cliSource));
352
+ if (missing.length) throw new Error(`声明 reader=cli 但这些键在客户端源码里找不到:${missing.join(", ")}`);
353
+ });
354
+
355
+ test("rejection exit inventory: 6 rows, and every counted row names a pinning test", async () => {
356
+ const { TASK_REJECTION_EXITS } = await import("./rejection-counters.js");
357
+ expect(TASK_REJECTION_EXITS.length).toBe(6);
358
+ // counted 的位置必须有测试钉住(空串 ⇒ 缺口,红)
359
+ for (const row of TASK_REJECTION_EXITS) {
360
+ if (row.counted) expect(row.pinned_by.length).toBeGreaterThan(0);
361
+ }
362
+ // 2026-10-31 —— **空 pinned_by 必须自报家门**(外部复核 (b):「兜底值必须说出自己是兜底」)。
363
+ // 空的 pinned_by 与「忘了填」在数据里长得一样 ⇒ 要求 `pinned_by` 与 `gap_reason` **恰好填一个**。
364
+ // 两个都填 = 自相矛盾(既说钉住了又说钉不住);都不填 = 又回到静默缺口。
365
+ for (const row of TASK_REJECTION_EXITS) {
366
+ const hasPin = row.pinned_by.length > 0;
367
+ const hasGap = (row.gap_reason ?? "").length > 0;
368
+ expect(hasPin !== hasGap).toBe(true);
369
+ }
370
+ // 声明为缺口的行:目前恰好 1 行(error_hook_500),且理由里必须同时写出「卡在哪」与「什么能解锁」
371
+ const gaps = TASK_REJECTION_EXITS.filter((r) => !r.pinned_by.length);
372
+ expect(gaps.map((r) => r.position)).toEqual(["error_hook_500"]);
373
+ expect(gaps[0].gap_reason).toContain("解锁条件");
374
+
375
+ // 反过来:未计数的位置若已有测试钉住,名字必须非空 —— 否则「钉住了」只是注释
376
+ const pinnedNames = TASK_REJECTION_EXITS.map((r) => r.pinned_by).filter(Boolean);
377
+ expect(pinnedNames.length).toBeGreaterThanOrEqual(3);
378
+ // 位置名必须唯一(否则两行描述同一处,比例就重复计了)
379
+ expect(new Set(TASK_REJECTION_EXITS.map((r) => r.position)).size).toBe(TASK_REJECTION_EXITS.length);
380
+
381
+ // 2026-10-31 —— **「数对、集合错」**(外部复核 164b3e5e 那条:14 个块数得对,
382
+ // 而「13 个公共头」不成立,因为 14 个头集合的交集是空集)。
383
+ // 本表同款:有 2 个位置装了表(一个**计数**),但链路必须先过前面若干个位置 ——
384
+ // 所以「链路覆盖」只能是**前缀长度**,不能是「计数 / 总数」。
385
+ const instrumented = TASK_REJECTION_EXITS.filter((r) => r.counted).length;
386
+ let prefix = 0;
387
+ for (const r of TASK_REJECTION_EXITS) { if (r.counted) prefix += 1; else break; }
388
+ expect(instrumented).toBe(2); // 装了几个点(计数)
389
+ expect(prefix).toBe(0); // 链路覆盖(前缀)—— 第 1 个位置就是洞
390
+ // 反例守卫:一旦数错集合(把第 1 行改成 counted),前缀与计数会一起变 —— 那时必须改比例与注释
391
+ expect(instrumented).not.toBe(prefix);
392
+
393
+ // 2026-10-31 —— **构造自洽的断言不会以我们关心的方式失败**(外部复核 164b3e5e:
394
+ // 「14 个块数得对,但那是构造自洽的断言,不会以我们关心的方式失败」)。
395
+ // 上面那些都是对着**自己声明的表**断言 —— 它只证明「表没被改」,不证明「表描述的世界还在」。
396
+ // ⇒ 加一条**跨源**检查:计数器的主语(/api/task)必须真的出现在生成的路由清单里。
397
+ // 若有人改了路由名而没改计数器,这条会红;而只对自己的表断言的测试永远不会。
398
+ const { readFileSync } = await import("node:fs");
399
+ // 仓根的 docs/(从 server/src 出发是 ../../docs),不是 server/docs
400
+ const table = JSON.parse(readFileSync(new URL("../../docs/rest-route-table.json", import.meta.url), "utf8"));
401
+ expect(table.rows.some((r: any) => r.path === "/api/task")).toBe(true);
402
+ });
403
+
404
+ // 2026-10-31 —— parser 级拒绝在本仓**是**被计数的,因为我们在 handler 内 await req.json()。
405
+ // 与 Express 恰好相反(express.json() 走 next(err) ⇒ 错误中间件 ⇒ 不计)。
406
+ // ⇒ 这类出口的归属取决于 parser 放在哪,而不是取决于框架。
407
+ test("malformed JSON on /api/task IS counted — parser lives inside our handler", async () => {
408
+ const before = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
409
+ const beforeTotal = before.counters.task_rejections.total as number;
410
+ const rej = await fetch(`${BASE}/api/task`, {
411
+ method: "POST",
412
+ headers: { "content-type": "application/json", Authorization: `Bearer ${userToken}` },
413
+ body: "{bad",
414
+ });
415
+ expect(rej.status).toBe(400);
416
+ const after = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
417
+ expect(after.counters.task_rejections.total).toBe(beforeTotal + 1);
418
+ });
419
+
420
+ // 2026-10-31 —— served_at 的**敏感性**:单调不减只证「它没倒退」,常量也满足。
421
+ // 要证「它在跟着墙钟走」,断言里必须出现**两次读数之差**。
422
+ // (今晚的教训:startedAt 的敏感性当初是靠「换进程才变」证的,不是靠「刷新两次相同」。)
423
+ test("served_at actually advances with the wall clock (difference, not just monotonicity)", async () => {
424
+ const read = async () => (await (await fetch(`${BASE}/health`)).json() as any).served_at;
425
+ const t1 = await read();
426
+ const startedAt = Date.now();
427
+ await new Promise((r) => setTimeout(r, 250));
428
+ const t2 = await read();
429
+ const elapsed = Date.now() - startedAt;
430
+ const delta = Date.parse(t2) - Date.parse(t1);
431
+ expect(delta).toBeGreaterThan(0); // 真的走了(否定「常量」)
432
+ // 2026-10-31 —— (b) 容差必须**大于被测时钟可能的最大步进**,否则一次 NTP 步进就假红,
433
+ // 而假红会被读成「字段坏了」,实际是「时钟动了一下」。
434
+ // NTP:slew 阈 128ms,超阈值即步进(秒级)。⇒ 容差 5s,不是 1s。
435
+ // ⚠️ 这条量的是**速率**(差 / 等待);「时钟偏置」(绝对值)在 epoch_delta_ms 那条,
436
+ // 两者不能共用容差 —— 它们量的是两件事。
437
+ const STEP_ALLOWANCE_MS = 5000;
438
+ expect(Math.abs(delta - elapsed)).toBeLessThanOrEqual(STEP_ALLOWANCE_MS);
439
+ // 2026-10-31 —— (a) 「必须变」没排除「以错误的方式变」:
440
+ // 每次请求变 / 每秒变 / 每次部署变 都满足「差 > 0」,而语义完全不同。
441
+ // 两次读数上,「每次请求变」与「每秒变」同形 ⇒ 需要第二条锁定**时间尺度**:
442
+ // 在同样的等待里多打若干请求,差值不应随请求数增长。
443
+ const t3 = await read();
444
+ const burstStart = Date.now();
445
+ const BURST = 20;
446
+ for (let i = 0; i < BURST; i++) await read(); // 20 次额外请求
447
+ await new Promise((r) => setTimeout(r, 250));
448
+ const t4 = await read();
449
+ const burstElapsed = Date.now() - burstStart;
450
+ const burstDelta = Date.parse(t4) - Date.parse(t3);
451
+ // ⚠️ 这一条的容差**不能**用上面那个时钟步进容差,否则判据被它自己压平:
452
+ // 20 次请求 × 每次 +150ms 的假实现 = +3000ms,而我第一版给的是 +5000ms ⇒ 照样绿。
453
+ // (witnessed-red 抓到了:把 served_at 改成每次请求 +150ms,那一版仍然 68 pass。)
454
+ // ⇒ 这里用「与请求数无关」的紧口:20 次请求带来的增量必须远小于其漂移规模。
455
+ const PER_REQUEST_ALLOWANCE_MS = 1000; // 20 次请求合计只许 +1s;每请求漂移 ≥50ms 就会红
456
+ expect(burstDelta).toBeLessThanOrEqual(burstElapsed + PER_REQUEST_ALLOWANCE_MS);
457
+ expect(burstDelta).toBeGreaterThanOrEqual(0);
458
+ });
459
+
460
+ // 2026-10-31 —— 误差界必须有**地板**。
461
+ // uptime×|delta|/value 只覆盖尺子自己的舍入,delta=0 时报 0;
462
+ // 而 btime 是整秒(±500ms)、jiffies 是 10ms 量化 —— 这两项不会因为尺子变准而消失。
463
+ // ⇒ 判据:误差界的最小值是「尺子之外的误差之和」,不是 0。
464
+ describe("clk_tck 的误差界与守卫的可检出下限", () => {
465
+ test("error bound never reports 0 (floor from btime seconds + jiffies quantum)", async () => {
466
+ const b = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
467
+ if (b.kernel_started_at === null) return; // 非 Linux:这一族本来就不发布
468
+ expect(typeof b.kernel_started_at_error_ms).toBe("number");
469
+ expect(b.kernel_started_at_error_ms).toBeGreaterThanOrEqual(510);
470
+ // 即使 delta=0(尺子最准的那一刻),地板仍然在
471
+ if (b.clk_tck_delta === 0) expect(b.kernel_started_at_error_ms).toBeGreaterThanOrEqual(510);
472
+ });
473
+
474
+ // 2026-10-31 —— 阈值决定了它抓得住多大的异常;不报换算,读者无法区分
475
+ // 「没有挂起过」与「挂起太小,抓不到」—— 两者都读成 derived。
476
+ test("publishes the smallest suspend the 1% guard could actually catch", async () => {
477
+ const b = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
478
+ if (b.kernel_started_at === null) return;
479
+ // 2026-10-31 —— 「是数字」不是断言(外部复核 (b)):负数、NaN、Infinity 都是 number。
480
+ expect(Number.isFinite(b.clk_tck_guard_min_suspend_s)).toBe(true);
481
+ expect(b.clk_tck_guard_min_suspend_s).toBeGreaterThanOrEqual(0);
482
+ // relErr ≈ 挂起 / **机器** uptime ⇒ 1% ⇒ 0.01 × host_uptime_s
483
+ // ⚠️ 不是 b.uptime(那是进程的),两者相差可以上万倍 —— 这一条正是在钉这个区别
484
+ expect(Number.isFinite(b.host_uptime_s)).toBe(true);
485
+ expect(b.host_uptime_s).toBeGreaterThanOrEqual(0);
486
+ // 机器 uptime 至少不短于进程 uptime(同一台机上,这是结构关系,不是巧合)
487
+ expect(b.host_uptime_s).toBeGreaterThanOrEqual(b.uptime - 5);
488
+ const expected = 0.01 * b.host_uptime_s;
489
+ expect(Math.abs(b.clk_tck_guard_min_suspend_s - expected)).toBeLessThanOrEqual(2);
490
+ expect(b.clk_tck_guard_min_suspend_s).toBeGreaterThan(0);
491
+ // 机器 uptime ≥ 进程 uptime(本进程是这台机器上后起的)—— 两个量确实不同名不同物
492
+ expect(b.host_uptime_s).toBeGreaterThanOrEqual(b.uptime);
493
+ // 2026-10-31 —— 原始估计与阈值判定分开报:
494
+ // 本机实测 estimate=99.35 而 suspend_total_s=0 ⇒ 被打回 assumed 不是挂起造成的,是估计器偏置。
495
+ // 没有这一格,那句「为什么是 assumed」说不出来(只能看到 assumed)。
496
+ expect(typeof b.clk_tck_estimate).toBe("number");
497
+ expect(Math.abs(b.clk_tck_estimate - 100)).toBeLessThan(10);
498
+ if (b.clk_tck_source === "confirmed") expect(Math.abs(b.clk_tck_estimate - 100)).toBeLessThan(0.5);
499
+ });
500
+
501
+ // 2026-10-31 —— 把**推导的前提**做成读数:累计挂起 = (now − btime) − /proc/uptime。
502
+ // 没有它,derived 与 confirmed 在读数上只差一个容差,而「没挂起过」这个前提在两者之外。
503
+ test("derived carries its premise: suspend_total_s is published (null ≠ 0)", async () => {
504
+ const b = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
505
+ if (b.kernel_started_at === null) return;
506
+ expect("suspend_total_s" in b).toBe(true);
507
+ const s = b.suspend_total_s;
508
+ expect(s === null || (typeof s === "number" && s >= 0)).toBe(true);
509
+ // 前提与结论必须一致:若已挂起超过守卫的可检出下限,就不该还报 confirmed
510
+ if (typeof s === "number" && s > (b.clk_tck_guard_min_suspend_s ?? Infinity)) {
511
+ expect(b.clk_tck_source).not.toBe("confirmed");
512
+ }
513
+ });
514
+ });
515
+
516
+ // 2026-10-31 —— `/health` 的 validator 语义:**不发 ETag,且 `If-None-Match: *` 也回 200**。
517
+ //
518
+ // 起因(外部复核在同族端点上实测到的):当响应体里带时间/计数器时,
519
+ // 「回不回 304」从头到尾不由 cache-control 决定:
520
+ // · Express 的默认 etag 对每个 body 都变 ⇒ validator 永远匹配不上 ⇒ 一次 If-None-Match 测不出任何东西
521
+ // · `if-none-match: *` 会**直接跳过** etag 比较(RFC 9110 §13.1.2:资源存在 ⇒ 304)
522
+ // ⇒ 本仓的选择是:不发 ETag(没有 validator 可匹配),并且对 `*` 也回 200 ——
523
+ // 因为我们每一份正文都是「此刻的读数」,回 304 等于告诉客户端「你手里那份是当前的」,那是假话。
524
+ // 这条断言把「不发的决定」和「对 * 的例外」都钉住;否则它只是注释里的一句话。
525
+ describe("/health 的 validator 语义", () => {
526
+ test("no ETag at all, and If-None-Match: * still returns 200 with fresh body", async () => {
527
+ const a = await fetch(`${BASE}/health`);
528
+ expect(a.headers.get("etag")).toBeNull(); // 没有 validator 可匹配
529
+ expect(a.headers.get("cache-control")).toBe("no-store");
530
+ const b = await fetch(`${BASE}/health`, { headers: { "If-None-Match": "*" } });
531
+ expect(b.status).toBe(200); // RFC 会要 304;我们是**故意的例外**
532
+ const bodyB = await b.json() as any;
533
+ const bodyA = await a.json() as any;
534
+ // 而且正文确实是新的(不是把上一份原样回给条件请求)
535
+ expect(typeof bodyB.served_at).toBe("string");
536
+ expect(Date.parse(bodyB.served_at)).toBeGreaterThanOrEqual(Date.parse(bodyA.served_at));
537
+ });
538
+ });
539
+
540
+ // 2026-10-31 —— 补的是**反方向**:既有的
541
+ // "every field in the authenticated body carries a class"
542
+ // 只查 payload → meta(加字段忘了分类);它查不到 meta → payload(**声明了一个永远不出现的字段**)。
543
+ // 后者是「死 meta」:一条 meta 写着 class/granularity/frozen_at_boot,而没有任何响应会带它,
544
+ // 于是它会一直正确地描述一个不存在的东西 —— 并且看起来比没有更权威。
545
+ // (写这条时我以为两个方向都没覆盖;实测 witness 表明正向早就有,只有反向是空的。)
546
+ test("every field in the full payload has meta, and every meta appears in it", async () => {
547
+ const full = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
548
+ const payloadKeys = Object.keys(full);
549
+ const metaKeys = Object.keys(HEALTH_FIELD_META);
550
+ const undocumented = payloadKeys.filter((k) => !metaKeys.includes(k)).sort();
551
+ // **有条件出现的字段**:meta 里有、默认响应里没有。每一项都必须能说出触发条件,
552
+ // 并且在这里当场把它触发一次 —— 否则「有条件出现」与「写错了」同形。
553
+ const conditional: Record<string, string> = {
554
+ probe_nonce: "只在带 X-Probe-Nonce 时出现",
555
+ };
556
+ const phantom = metaKeys.filter((k) => !payloadKeys.includes(k) && !(k in conditional)).sort();
557
+ expect({ undocumented, phantom }).toEqual({ undocumented: [], phantom: [] });
558
+ // 把每个条件字段真的触发一次
559
+ for (const k of Object.keys(conditional)) {
560
+ if (k !== "probe_nonce") continue;
561
+ const withNonce = await (await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": "meta-bijection" } })).json() as any;
562
+ expect(Object.prototype.hasOwnProperty.call(withNonce, k)).toBe(true);
563
+ }
564
+ });
565
+
566
+ // 2026-10-31 —— license 三态必须是「三种不同的可修性」,不能折成一个 "none"。
567
+ // 本条只断言形状(测试库没有 license 行 ⇒ absent);四种映射由 license-state.test.ts 钉死。
568
+ test("license_state distinguishes absent from unknown instead of collapsing to none", async () => {
569
+ const body = await (await fetch(`${BASE}/health`)).json() as any;
570
+ expect(typeof body.license).toBe("string"); // 兼容字段仍在
571
+ const st = body.license_state;
572
+ expect(st && typeof st.kind).toBeTruthy();
573
+ expect(["known", "absent", "unknown"]).toContain(st.kind);
574
+ if (st.kind === "known") expect(typeof st.type).toBe("string");
575
+ if (st.kind === "unknown") expect(typeof st.reason).toBe("string");
576
+
577
+ // 2026-10-31 —— 兼容字段 `license` 与三态之间的**配对约束**(外部复核在本仓指到的那个洞):
578
+ // `license: "none"` 同时表示 absent 与 unknown ⇒ 单看它无法支撑「是否商业授权」。
579
+ // 这一条把它的歧义**限定在一个范围内**:只有这两种状态才允许渲染成 "none";
580
+ // 反过来,known 时 "none" 绝不允许出现(那才是真的把「有授权」读成「没有」)。
581
+ const legacy = body.license;
582
+ if (legacy === "none") expect(["absent", "unknown"]).toContain(st.kind);
583
+ if (st.kind === "known") expect(legacy).not.toBe("none");
584
+ });
585
+
586
+ // 2026-10-31 —— 匿名投影必须是**白名单**:新字段默认不出现。
587
+ // 这条断言的是「每一个匿名可见的键都在白名单里」——
588
+ // 于是「忘了想」的结果是**少给**,不是泄露。
589
+ test("anonymous /health exposes ONLY allow-listed keys (new fields default to authenticated)", async () => {
590
+ const body = await (await fetch(`${BASE}/health`)).json() as any;
591
+ const { PUBLIC_HEALTH_KEYS } = await import("./server.js");
592
+ for (const key of Object.keys(body)) {
593
+ expect(PUBLIC_HEALTH_KEYS.has(key)).toBe(true);
594
+ }
595
+ // 两个敏感的典型:不进匿名投影。
596
+ expect("git_commit" in body).toBe(false);
597
+ expect("counters" in body).toBe(false);
598
+ expect("sse_sessions" in body).toBe(false);
599
+
600
+ // 2026-10-31 —— **witness 已做隔离版**(上一轮记的是「未验」,本轮转「已验」):
601
+ // 只在**鉴权分支**丢掉 sse_sessions(匿名投影一字未动)
602
+ // ⇒ 上面三条否定断言**全绿**("不存在"仍然成立),失败点恰好落在下面第 446 行的镜像上。
603
+ // ⇒ 这就是「否定断言单独的强度是零」的现场:它抓不住「鉴权侧丢键」,镜像抓得住。
604
+ //
605
+ // 2026-10-31 —— **否定断言必须配镜像**(外部复核:「一条否定断言单独的强度是零 ——
606
+ // 它和『这里什么都没有』无法区分」)。
607
+ // 上面三条都是「不出现在匿名里」;若投影实现坏成「什么都不给」,它们仍然全绿。
608
+ // ⇒ 镜像:同一 URL 在**鉴权态**下,这几个键必须真的出现。
609
+ const authed = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
610
+ expect("git_commit" in authed).toBe(true);
611
+ expect("counters" in authed).toBe(true);
612
+ expect("sse_sessions" in authed).toBe(true);
613
+ // 再强一格:鉴权投影必须**严格大于**匿名投影(否则「白名单」可能只是把两边都截了)
614
+ expect(Object.keys(authed).length).toBeGreaterThan(Object.keys(body).length);
615
+ });
616
+
617
+ // 2026-10-31 —— 内核口径的进程身份:与自报 startedAt 互为独立的第二条腿。
618
+ // 2026-10-31 修订 —— 原来这条写的是「两条腿一致才发布」,那是**让自报字段否决内核读数**。
619
+ // 现在:判据 = 内核三元组(无条件发布);展示 = kernel_started_at(永远带 agreement 标记);
620
+ // 不一致 = 一条独立读数(disagree + delta),**不再折成 null**。
621
+ test("kernel identity is the judgment basis; disagreement with the self-report is its own reading, not a null", async () => {
622
+ // 🔴 用**鉴权**响应:pid / boot_id / kernel_started_at 是「路标」不是「仪表」
623
+ // ⇒ 不在匿名白名单里(这条测试第一次就是因为读了匿名响应而红 —— 白名单生效了)。
624
+ const body = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
625
+ expect(body.pid).toBe(process.pid);
626
+ if (body.boot_id !== null) expect(String(body.boot_id)).toMatch(/^[0-9a-f-]{16,64}$/i);
627
+ expect(body.proc_start_ticks === null || typeof body.proc_start_ticks === "number").toBe(true);
628
+
629
+ // 判据三元组:pid 必须等于真值;boot_id 可读时必须合法 —— 二者都不依赖 startedAt
630
+ // 换算假设必须显式
631
+ // 一个叫 assumed 的字段必须有一条「它是否成立」的判定:
632
+ // 在 x86 上应当 confirmed;非 100 的架构上应当 derived;读不到才 assumed。
633
+ expect([100].includes(body.clk_tck_assumed) || Number.isInteger(body.clk_tck_assumed)).toBe(true);
634
+ expect(["confirmed", "derived", "assumed"]).toContain(body.clk_tck_source);
635
+ // 2026-10-31 —— confirmed 不能只说「相等」,必须报「差多少」+ 误差界;
636
+ // 而且差值大到不可能是舍入时,source 必须退回 assumed(典型成因:机器挂起过)。
637
+ if (body.clk_tck_source === "assumed") {
638
+ expect(body.clk_tck_source).toBe("assumed");
639
+ } else {
640
+ expect(typeof body.clk_tck_delta).toBe("number");
641
+ expect(typeof body.kernel_started_at_error_ms).toBe("number");
642
+ expect(Math.abs(body.clk_tck_delta)).toBeLessThan(0.01 * body.clk_tck_assumed);
643
+ }
644
+ expect(["agree", "disagree", "unknown"]).toContain(body.epoch_agreement);
645
+
646
+ if (body.kernel_started_at !== null) {
647
+ expect(typeof body.kernel_started_at).toBe("string");
648
+ expect(body.kernel_started_at_note).toBeNull();
649
+ // 🔴 关键:发布条件**不再**是「与自报一致」
650
+ // 实测这台机器上应当一致 ⇒ 断言的是一条**真实现象**,而不是发布条件的复述
651
+ const delta = Math.abs(Date.parse(body.kernel_started_at) - Date.parse(body.startedAt));
652
+ if (body.epoch_agreement === "agree") expect(delta).toBeLessThanOrEqual(10_000);
653
+ // 2026-10-31 —— 「两次读数相同」只证明相同,证明不了「它会变」:
654
+ // 一个写死的常量头与真的 startedAt 在那个测法下完全一样。
655
+ // 我们的独立生产者是**内核**:epoch_delta_ms = (btime + ticks/CLK_TCK) − startedAt。
656
+ // ⇒ 只有当 startedAt 与内核推出的时刻一致时,它才不是抄来的配置值。
657
+ if (body.epoch_agreement === "agree") {
658
+ expect(typeof body.epoch_delta_ms).toBe("number");
659
+ expect(Math.abs(body.epoch_delta_ms)).toBeLessThanOrEqual(10_000);
660
+ expect(body.kernel_started_at).not.toBeNull();
661
+ }
662
+ if (body.epoch_agreement === "disagree") {
663
+ // 分歧必须能被外部算出来:delta 与 agreement 同向,不能一个说 disagree 一个给个小 delta
664
+ expect(delta).toBeGreaterThan(10_000);
665
+ expect(typeof body.epoch_delta_ms).toBe("number");
666
+ }
667
+ } else {
668
+ // 算不出来时必须给出原因,不能是“静默的 null”
669
+ expect(typeof body.kernel_started_at_note).toBe("string");
670
+ expect(body.epoch_agreement).toBe("unknown");
671
+ }
672
+ });
673
+
674
+ // 否定断言必须配镜像肯定断言:上面允许 null,这条要求「在 Linux 上它必须不是 null」。
675
+ // 否则「永远给 null」也能满足上面那条。
676
+ test("on Linux the kernel trio is actually present (a permanent null would satisfy the test above)", async () => {
677
+ if (process.platform !== "linux") return;
678
+ const body = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
679
+ expect(body.boot_id).not.toBeNull();
680
+ expect(body.proc_start_ticks).not.toBeNull();
681
+ expect(body.kernel_started_at).not.toBeNull();
682
+ expect(body.epoch_agreement).not.toBe("unknown");
683
+ });
684
+
685
+ // 2026-10-31 —— `limits` 故意保持匿名(dashboard 上传代理开流前要读,且已在公开文档里),
686
+ // 但「故意公开」不等于「可以长东西」:它必须只有静态容量上限,不许出现路径/主机/用户。
687
+ test("anonymous `limits` carries ONLY static byte caps (public by decision, pinned in shape)", async () => {
688
+ const b = await (await fetch(`${BASE}/health`)).json() as any;
689
+ expect(Object.keys(b.limits).sort()).toEqual(["max_request_content_length", "max_upload_bytes"]);
690
+ for (const v of Object.values(b.limits)) expect(typeof v).toBe("number");
691
+ // 反例守卫:路径/用户名/主机名一类的字符串一旦混进来,这条会红
692
+ expect(JSON.stringify(b.limits)).not.toMatch(/\/|[A-Za-z]:\\|@/);
693
+ });
694
+
695
+ // 2026-10-31 —— 头集合断言:**与登录无关**的那条判据。
696
+ //
697
+ // 为什么需要它:凡是「需要会话才能判」的断言都会继承 vantage 病
698
+ // (未登录 CI 恒红 / 有会话环境恒绿 ⇒ 它测的是环境,不是代码)。
699
+ // 头集合不需要会话就能读 ⇒ 它回答的是「我站在哪一层」,而不是「我有没有登录」。
700
+ describe("header set (vantage-free: readable without a session)", () => {
701
+ test("anonymous /health does not leak build identity through headers", async () => {
702
+ const res = await fetch(`${BASE}/health`);
703
+ expect(res.status).toBe(200);
704
+ expect((res.headers.get("content-type") || "").split(";")[0].trim()).toBe("application/json");
705
+ // 正文里我们只给 build_identified;头里更不能给指纹
706
+ const leaky = [...res.headers.keys()].filter((h) => /git|commit|build[-_]?(sha|id)/i.test(h));
707
+ expect(leaky).toEqual([]);
708
+ // 2026-10-31 —— 镜像必须针对**同一个属性在另一种条件下确实存在**,
709
+ // 而不是「这个响应是 JSON」(那只排除了取错对象)。
710
+ const authed = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
711
+ // 同一 URL、登录态下**这个字段确实存在**(值可能是 null:容器镜像里没有 .git)。
712
+ // 2026-10-31 —— 原来这里写 `typeof authed.git_commit === "string"`:只在**有 .git** 的环境成立,
713
+ // 于是它在本地永远绿、在 CI 容器里永远红(run 41140921488 的两条失败之一)。
714
+ // 对照的强度取决于环境,这一点必须写出来而不是假装验过:
715
+ expect("git_commit" in authed).toBe(true);
716
+ if (authed.build_identified === true) {
717
+ expect(typeof authed.git_commit).toBe("string"); // 有指纹 ⇒ 匿名侧确实不带,这才是有对照的读数
718
+ } else {
719
+ expect(authed.git_commit).toBeNull(); // 没有指纹 ⇒ 「匿名不带」在这一轮**没有对照**
720
+ }
721
+ });
722
+
723
+ test("version carries its role in the payload (a label, not a fingerprint)", async () => {
724
+ const body = await (await fetch(`${BASE}/health`)).json() as any;
725
+ expect(body.version_role).toBe("deployment_label");
726
+ // 反证:同一次响应里**没有**匿名可读的 commit(否则那条角色声明是多余的)
727
+ expect(body.git_commit).toBeUndefined();
728
+ });
729
+ });
730
+
731
+ // #3174 —— stall_count / last_stall_at 原来只有 [startedAt, now] 这个**隐含**窗口:
732
+ // 单独引用它,读者会把「计数器归零」读成「从未卡过」。
733
+ // ⇒ 现在窗口两端跟着读数一起走(event_loop.since / event_loop.observed_at)。
734
+ // 2026-10-31 —— **0 只能作为读数出现,不能冒充「没测」**(外部复核 ④:
735
+ // 「『未取』被系统翻译成『正常』——而零恰好是最好看的那个值」)。
736
+ // event_loop 的计数类字段天然可能是 0(真的没停顿)。所以必须能区分:
737
+ // 窗口存在 ⇒ 0 是「这段时间内没有停顿」(读数)
738
+ // 窗口为零长 ⇒ 0 是「还没测」(不是读数)
739
+ // 断言:窗口两端必须同时存在,且 since ≤ observed_at;窗口为空时**不得**声称 0 是结论。
740
+ test("zero-valued stall counters carry a window, so 0 is a reading rather than 'not measured'", async () => {
741
+ const body = await (await fetch(`${BASE}/health`)).json() as any;
742
+ const el = body.event_loop;
743
+ const since = Date.parse(el.since), observed = Date.parse(el.observed_at);
744
+ expect(Number.isFinite(since)).toBe(true);
745
+ expect(Number.isFinite(observed)).toBe(true);
746
+ expect(observed).toBeGreaterThanOrEqual(since);
747
+ if (el.stall_count === 0) {
748
+ // 0 停顿 + 正长度窗口 = 读数;0 停顿 + 零长度窗口 = 还没测,此时不能当成「没有停顿」
749
+ expect(observed - since).toBeGreaterThan(0);
750
+ }
751
+ });
752
+
753
+ describe("event_loop carries its own window (no implicit [startedAt, now])", () => {
754
+ test("both ends are present, and they are ordered", async () => {
755
+ const body = await (await fetch(`${BASE}/health`)).json() as any;
756
+ expect(typeof body.event_loop.since).toBe("string");
757
+ expect(typeof body.event_loop.observed_at).toBe("string");
758
+ expect(Date.parse(body.event_loop.since)).toBeLessThanOrEqual(Date.parse(body.event_loop.observed_at));
759
+ });
760
+
761
+ // 敏感性:起点**不许**跟着时间走,终点**必须**跟着时间走。
762
+ // 只断言「两者可比」的话,一个冻结的时钟也能通过。
763
+ test("since is frozen while observed_at advances (difference, not just comparability)", async () => {
764
+ const a = (await (await fetch(`${BASE}/health`)).json() as any).event_loop;
765
+ const waitStart = Date.now();
766
+ await new Promise((r) => setTimeout(r, 250));
767
+ const b = (await (await fetch(`${BASE}/health`)).json() as any).event_loop;
768
+ const elapsed = Date.now() - waitStart;
769
+
770
+ expect(b.since).toBe(a.since); // 起点不动
771
+ const delta = Date.parse(b.observed_at) - Date.parse(a.observed_at);
772
+ expect(delta).toBeGreaterThan(0); // 终点真的走
773
+ expect(Math.abs(delta - elapsed)).toBeLessThanOrEqual(1000); // 且走的是同一个墙钟
774
+ });
775
+ });
776
+
777
+ // 2026-10-31 —— 「累计值 ÷ (now − since)」这个用法本身是错的,而且错法很隐蔽。
778
+ //
779
+ // 本仓的 counters.since **就等于 startedAt**(同一个字符串)⇒ 分母是 uptime,不是窗口长度。
780
+ // · 进程刚重启 ⇒ 分母趋近 0 ⇒ 比值巨大 ⇒ 与 flapping 长得一模一样
781
+ // 而「刚部署」比 flapping 常见得多 ⇒ **这条判据的主要阳性是正常状态**
782
+ // · 而且分子会被派去看它的人推动(如果那是应答计数)
783
+ // ⇒ 正确判据是**两次读数的差分**:S2 ≠ S1 ∧ (t2 − t1 很小),不需要除法。
784
+ //
785
+ // 这条测试不是「验证除法」,是**把那个事实钉住**:
786
+ // 哪一天有人给 counters 加了真正的窗口起点,这里会红,届时才允许重新讨论除法。
787
+ test("counters.since is the process start, so it is NOT a window length (denominator trap)", async () => {
788
+ const body = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
789
+ expect(body.counters.since).toBe(body.startedAt);
790
+ expect(body.counters.task_rejections.scope).toBe("process_lifetime");
791
+ });
792
+
793
+ // 2026-10-31 —— 304 会让「重启判据」假阳性:
794
+ // 若某层做协商缓存,304 会冻结 startedAt,而 counters 照涨 ⇒ 看起来像 flapping。
795
+ // ⇒ 探针必须显式拿到 200,且服务端必须禁止缓存。
796
+ test("health is never cacheable, and a conditional request still yields 200 (not 304)", async () => {
797
+ const plain = await fetch(`${BASE}/health`);
798
+ expect(plain.status).toBe(200);
799
+ // 2026-10-31 —— 「包含」不是值级:`toContain("no-store")` 允许
800
+ // `private, no-store, max-age=31536000`(两者矛盾)而不红,而「被加料」正是缓存头最危险的改法。
801
+ // 合法值唯一(就是 no-store)⇒ 用「等于」。
802
+ expect(plain.headers.get("cache-control")).toBe("no-store");
803
+
804
+ // 2026-10-31 —— 先分清「不可能 304」与「可能 304 但服务端拒绝了」:
805
+ // 没有 ETag 时,条件请求必然 200,那条断言是**空的**(vacuous),
806
+ // 而它与「实测过 304 不存在」在报告里长得一样。
807
+ const etag = plain.headers.get("etag");
808
+ if (etag === null) {
809
+ // 明确记录:本服务不产生 ETag ⇒ 304 在协议层不可能发生;这一格不靠条件请求证明。
810
+ expect(plain.headers.get("etag")).toBeNull();
811
+ }
812
+ const conditional = await fetch(`${BASE}/health`, {
813
+ headers: { "cache-control": "no-cache", "if-none-match": etag ?? "*" },
814
+ });
815
+ expect(conditional.status).toBe(200); // 304 会让 startedAt 冻结、counters 照涨 = 假 flapping
816
+ const body = await conditional.json() as any;
817
+ expect(typeof body.startedAt).toBe("string");
818
+ expect(typeof body.served_at).toBe("string");
819
+ });
820
+
821
+ // 2026-10-31 —— 「读不到」不许渲染成 0。
822
+ // 0 是一个合法值,而它会被当成事实;「0 个会话」与「读库失败」在读数上同形。
823
+ // 兄弟字段 status_reasons 里已有 db_unreadable ⇒ 两者一起读才完整。
824
+ test("sessions_count is a number when the DB is readable, and null (not 0) when it is not", async () => {
825
+ const b = await (await fetch(`${BASE}/health`)).json() as any;
826
+ const dbBad = Array.isArray(b.status_reasons) && b.status_reasons.includes("db_unreadable");
827
+ if (dbBad) {
828
+ expect(b.sessions_count).toBeNull();
829
+ } else {
830
+ expect(Number.isInteger(b.sessions_count)).toBe(true);
831
+ expect(b.sessions_count).toBeGreaterThanOrEqual(0); // 类型不是断言
832
+ }
833
+ });
834
+
835
+ // 2026-10-31 —— 「200 那一格」必须有 body 判据:ok 恒 true 不等于健康。
836
+ // 与 counters.releases 同族:一个恒真的字段,读起来像「一切正常」。
837
+ test("status separates alive-but-degraded from all-normal (200 stays a promise, not a verdict)", async () => {
838
+ const res = await fetch(`${BASE}/health`);
839
+ expect(res.status).toBe(200); // 承诺不变
840
+ const b = await res.json() as any;
841
+ expect(["ok", "degraded"]).toContain(b.status);
842
+ expect(Array.isArray(b.status_reasons)).toBe(true);
843
+ if (b.status === "ok") expect(b.status_reasons).toEqual([]); // 两字段必须自洽
844
+ else expect(b.status_reasons.length).toBeGreaterThan(0);
845
+ expect(b.ok).toBe(true); // 兼容字段仍在,但不再承担判据
846
+ });
847
+
848
+ // 2026-10-31 —— 契约测试,不是碰撞测试:用**对抗输入**证明「不在白名单里就进不去」,
849
+ // 而不是去证明某个具体分隔符撞不撞。
850
+ // (外部复核的原话:只写「不能碰撞」的测试,测的是实现;契约是「键集恰好是这些」。)
851
+ test("adversarial keys (separator-in-name / extra / landmark) never survive the projection", () => {
852
+ const adversarial = {
853
+ "ok\u0000version": 1, // 含分隔符的键名:任何 join 方案都会在这里含糊
854
+ "ok,version": 2, // 逗号分隔符
855
+ ok: true, // 合法
856
+ git_commit: "deadbeef", // landmark:必须被丢
857
+ sessions_count: 3, // 合法
858
+ "__proto__": { polluted: true },// 原型污染形态
859
+ } as Record<string, unknown>;
860
+ const out = projectPublicHealth(adversarial);
861
+ const keys = Object.keys(out).sort();
862
+ // 断言的是**键集恰好**,不是「某些键被丢」—— 后者在「什么都丢」时也成立
863
+ expect(keys).toEqual(["ok", "sessions_count"]);
864
+ expect((out as any)["ok\u0000version"]).toBeUndefined();
865
+ expect(JSON.stringify(out)).not.toContain("polluted");
866
+ });
867
+
868
+ // 2026-10-31 —— 形状测试必须先证明**输入彼此不同**,否则它测的是同一个形状 N 次。
869
+ // 顺序不能反:先断言两两不等,再断言各自的行为。
870
+ // 2026-10-31 —— 夹具的身份写进**测试名**(每次运行都会打印、且不依赖测试通过)。
871
+ // 有人后加一份重复的 ⇒ 名字里的 sha 立刻变,diff 里就能看见,而不用等断言红。
872
+ const WITNESS_SET_SHA = createHash("sha256")
873
+ .update(JSON.stringify({ unknown_field: { ok: true }, landmark: { git_commit: "deadbeef" } }))
874
+ .digest("hex")
875
+ .slice(0, 8);
876
+ test(`the four projection witnesses are pairwise distinct inputs (fixtureset=${WITNESS_SET_SHA})`, () => {
877
+ const cases = {
878
+ unknown_field: { ok: true, future_issued_token: "abc" }, // 未登记 ⇒ 丢
879
+ landmark: { ok: true, git_commit: "deadbeef" }, // landmark ⇒ 丢
880
+ gauge: { ok: true, sessions_count: 3 }, // gauge ⇒ 留
881
+ echo: { probe_nonce: "n-1" }, // credential(echo) ⇒ 留
882
+ };
883
+ const serialized = Object.entries(cases).map(([k, v]) => [k, JSON.stringify(v)] as const);
884
+ // 2026-10-31 —— 报「哪一对相等」,不是只报「存在相等」。
885
+ // 只报「存在相等」时,红的人要在四份夹具里自己找,而他通常先怀疑新加的那份;
886
+ // 而问题可能在一份旧的里(旧的那份才是标准)。
887
+ const equalPairs: string[] = [];
888
+ for (let i = 0; i < serialized.length; i += 1) {
889
+ for (let j = i + 1; j < serialized.length; j += 1) {
890
+ if (serialized[i][1] === serialized[j][1]) {
891
+ equalPairs.push(`${serialized[i][0]} == ${serialized[j][0]}`);
892
+ }
893
+ }
894
+ }
895
+ expect(equalPairs).toEqual([]);
896
+ // 2026-10-31 —— 这条前置断言自己也要有反例,否则它只是在数份数:
897
+ // 用「内容不同但长度相同」的对,证明判定按**内容**而不是按长度/份数。
898
+ const sameLenDifferent = [{ a: "xy" }, { a: "yz" }];
899
+ expect(JSON.stringify(sameLenDifferent[0]).length).toBe(JSON.stringify(sameLenDifferent[1]).length);
900
+ expect(JSON.stringify(sameLenDifferent[0])).not.toBe(JSON.stringify(sameLenDifferent[1]));
901
+
902
+ // 再断言各自行为(顺序与上面一致:先证输入不同,再看结果)
903
+ expect(Object.keys(projectPublicHealth(cases.unknown_field))).toEqual(["ok"]);
904
+ expect(Object.keys(projectPublicHealth(cases.landmark))).toEqual(["ok"]);
905
+ expect(Object.keys(projectPublicHealth(cases.gauge)).sort()).toEqual(["ok", "sessions_count"]);
906
+ expect(Object.keys(projectPublicHealth(cases.echo))).toEqual(["probe_nonce"]);
907
+ });
908
+
909
+ // 2026-10-31 —— 分类必须写出**谁不算**:形似启动快照但会变的那个字段。
910
+ // 读初始快照的判据只会漏报、不会误报;而它的失效形态与「真的没有」同形。
911
+ test("test_spawn_time_snapshot_family_excludes_the_one_field_that_must_change", async () => {
912
+ const { HEALTH_FIELD_META } = await import("./server.js");
913
+ // 分子:至少 5 个被明确标成启动快照(今天:startedAt / git_commit / boot_id / pid / proc_start_ticks / kernel_started_at)
914
+ const frozen = Object.entries(HEALTH_FIELD_META).filter(([, m]) => m.frozen_at_boot === true).map(([k]) => k);
915
+ expect(frozen.length).toBeGreaterThanOrEqual(5);
916
+ // 例外必须显式:served_at 长得一模一样,但它会变。
917
+ // ⚠️ 但「不被冻结」只是一个**否定**,它在很多实现上都成立(没打标 / 标打错 / 字段不存在)。
918
+ // ⇒ 它的正面断言在别处:「served_at actually advances with the wall clock」——
919
+ // 那条要求**连续两次读数不同**,是「必须变」而不是「没有被打标」。
920
+ expect(frozen).not.toContain("served_at");
921
+ expect(HEALTH_FIELD_META.served_at.frozen_at_boot).toBeUndefined();
922
+ });
923
+
924
+ // 2026-10-31 —— **分类不决定「变不变」,还缺「窗口」这个参数**(外部复核 (e):
925
+ // 「`startedAt` 属 instance,却会在 failover 时变,正是你自己那张表的反例;
926
+ // 处理分三态 pinned / excluded / allowed,而不是混进白名单」)。
927
+ //
928
+ // 本仓的 `frozen_at_boot: true` 到此为止只是一条**声明**:没有任何断言把它和
929
+ // 「同一个进程在窗口内读两次,这个值不变」对上。声明与行为之间没有桥,
930
+ // 于是分类错了只会被下一个人读出来,不会被测试读出来。
931
+ //
932
+ // 判据(三态在这里的落法):
933
+ // pinned = frozen_at_boot:true ⇒ 窗口内必须**逐字节相同**,变了就红
934
+ // allowed = 没打 frozen 标 ⇒ 变不变都可以,本测试不管
935
+ // excluded = 会变且不该被 pinned ⇒ 必须存在并在正向对照里出现(见下)
936
+ // 窗口显式:WINDOW_MS 写在断言里,而不是「两次读一下大概就行」。
937
+ test("frozen_at_boot fields do not change within a declared window (and this does NOT prove the pinning is correct)", async () => {
938
+ const { HEALTH_FIELD_META } = await import("./server.js");
939
+ const WINDOW_MS = 1200;
940
+ expect(WINDOW_MS).toBeGreaterThan(0); // 窗口为 0 的「没变」不构成读数
941
+
942
+ const a = await (await fetch(`${BASE}/health`)).json() as Record<string, unknown>;
943
+ await new Promise((r) => setTimeout(r, WINDOW_MS));
944
+ const b = await (await fetch(`${BASE}/health`)).json() as Record<string, unknown>;
945
+
946
+ // 每一个 pinned 字段还必须**声明窗口**:不写窗口的「不变」无法被证伪。
947
+ // 三态(外部复核 (e)):pinned = 有窗口且窗口内必须不变;allowed = 没打标;
948
+ // excluded = 会变且不该被打成 pinned —— 它必须存在,否则「都 pinned」就没有反例。
949
+ const pinnedAll = Object.entries(HEALTH_FIELD_META).filter(([, m]) => m.frozen_at_boot === true);
950
+ const noWindow = pinnedAll.filter(([, m]) => !m.stable_within).map(([k]) => k);
951
+ expect(noWindow).toEqual([]); // 声明了 pinned 就必须声明窗口
952
+ const windows = new Set(pinnedAll.map(([, m]) => m.stable_within));
953
+ for (const w of windows) expect(["request", "process", "deploy"]).toContain(w as string);
954
+
955
+ const pinned = pinnedAll
956
+ .map(([k]) => k)
957
+ .filter((k) => k in a && k in b);
958
+ // 分母:匿名投影里至少要能看见 1 个 pinned 字段,否则这条测试是真空真
959
+ expect(pinned.length).toBeGreaterThan(0);
960
+
961
+ const moved = pinned.filter((k) => JSON.stringify(a[k]) !== JSON.stringify(b[k]));
962
+ expect(moved).toEqual([]); // 声明是 pinned,就必须在窗口内真的不动
963
+
964
+ // 2026-10-31 —— **节流会让「不变」变得廉价**(外部复核:
965
+ // 「三个 `*_age_sec` 里有两个是 10s 节流采样的,同一秒两次读 diff 恒为 0
966
+ // ⇒ 会被误判成 pinned,而 pinned 正好放行最不该放行的字节比较」)。
967
+ // 本仓的同形风险:任何按 10s/30s 节流刷新的字段,在 1.2s 窗口里都必然「不变」。
968
+ // ⇒ 所以这条窗口断言**只对「启动快照族」成立**(它们与时间无关),
969
+ // 不能拿它去证明「这个字段是稳定的」——后者需要跨节流周期的窗口。
970
+ //
971
+ // ⚠️ 这条检查的**弱点必须写出来**(否则它会被读成比实际更强的东西):
972
+ // 一个值**本来就在这个窗口里不变**的字段,即使被错误地标成 pinned,也照样通过。
973
+ // 实测 witness:把 `sessions_count` 标成 `frozen_at_boot + stable_within:"process"`,
974
+ // 测试**仍然绿** —— 因为空测试库里它恒为 0。
975
+ // ⇒ 这条断言真正守住的是「标了 pinned 的字段在窗口内不许变」,
976
+ // 它**不能**守住「pinned 打得对」。后者只有两种办法:
977
+ // ① 造一个真会变的场景(连接数变化 / 重启 / failover)再读两次;
978
+ // ② 用第二个观测者(另一个实例、另一台机器),而不是对同一实例再采样一次。
979
+ // 今天本仓两样都没有 ⇒ 这一格只能到「窗口声明 + 窗口内不变」为止。
980
+ //
981
+ // 2026-10-31 —— **名字生成候选,差值定罪**(外部复核 ②:
982
+ // 「名字匹配 /(age|elapsed|uptime|remaining|ttl|since)/ ⇒ 候选;
983
+ // 同一秒两次读,逐字段算差:过去时刻 ⇒ 差 == 0;时长 ⇒ 差 == 间隔」)。
984
+ // 只靠名字会漏掉改了名的那个,只靠表达式会误抓所有 now 派生量 ⇒ 两条都要。
985
+ if (typeof a.uptime === "number" && typeof b.uptime === "number") {
986
+ const dUp = b.uptime - a.uptime;
987
+ // uptime 是「活着的时长」:窗口 1.2s,它的增量必须落在 (0, 窗口+1s] 内
988
+ expect(dUp).toBeGreaterThan(0);
989
+ expect(dUp).toBeLessThanOrEqual(WINDOW_MS / 1000 + 1);
990
+ }
991
+ if (typeof a.startedAt === "string" && typeof b.startedAt === "string") {
992
+ // startedAt 是「过去的时刻」:差值必须恰好 0(它不该像 uptime 那样走)
993
+ expect(b.startedAt).toBe(a.startedAt);
994
+ }
995
+ if (typeof a.served_at === "string" && typeof b.served_at === "string") {
996
+ const dServed = Date.parse(b.served_at) - Date.parse(a.served_at);
997
+ expect(dServed).toBeGreaterThanOrEqual(WINDOW_MS - 50); // 它必须走满窗口(不是抄同一份)
998
+ expect(dServed).toBeLessThanOrEqual(WINDOW_MS + 5_000);
999
+ }
1000
+
1001
+ // 正向对照:窗口内必须**有东西会变**,否则「都没变」可能只是「两次读的是同一份缓存」。
1002
+ // 这不是洁癖:一个恒定的响应体可以让上面那条永远绿。
1003
+ const changed = Object.keys(a).filter((k) => k in b && JSON.stringify(a[k]) !== JSON.stringify(b[k]));
1004
+ expect(changed.length).toBeGreaterThan(0);
1005
+ // 且变化必须**不含**任何 pinned 字段(与上面互为镜像:一条说“没变”,一条说“别的在变”)
1006
+ expect(changed.filter((k) => pinned.includes(k))).toEqual([]);
1007
+ });
1008
+
1009
+ // 2026-10-31 —— credential 的「可对账性」是**字段取值**,不是注释里的辩论。
1010
+ test("joinability decides anonymity, not the reader's interpretation", async () => {
1011
+ const { HEALTH_FIELD_META, mayBePublic } = await import("./server.js");
1012
+ const creds = Object.entries(HEALTH_FIELD_META).filter(([, m]) => m.class === "credential");
1013
+ expect(creds.length).toBeGreaterThan(0); // 分母非空
1014
+ const bad = creds.filter(([, m]) => m.joinability !== "echo_only" && mayBePublic(m)).map(([k]) => k);
1015
+ expect(bad).toEqual([]); // 服务端生成的一律不可匿名
1016
+ expect(HEALTH_FIELD_META.probe_nonce.joinability).toBe("echo_only");
1017
+ });
1018
+
1019
+ // 2026-10-31 —— gauge 的粒度词表是**封闭枚举**,且必须分清「电平」与「累积」。
1020
+ // 一个电平不能算速率,一个累积不能回答「现在怎么样」——两者在 JSON 里都是数字。
1021
+ describe("granularity vocabulary is closed and distinguishes level from cumulative", () => {
1022
+ test("every gauge declares one of level/cumulative/instant/label/boolean/verdict", async () => {
1023
+ const { HEALTH_FIELD_META } = await import("./server.js");
1024
+ const allowed = ["level", "cumulative", "instant", "label", "boolean", "verdict"];
1025
+ const bad = Object.entries(HEALTH_FIELD_META)
1026
+ .filter(([, m]) => m.class === "gauge" && !allowed.includes(String(m.granularity)))
1027
+ .map(([k, m]) => `${k}=${m.granularity}`);
1028
+ expect(bad).toEqual([]);
1029
+ // 分母非空:这一条今天必须有东西可查
1030
+ expect(Object.values(HEALTH_FIELD_META).filter((m) => m.class === "gauge").length).toBeGreaterThan(20);
1031
+ });
1032
+
1033
+ // 2026-10-31 —— verdict 与 label 的差别只有一条,但它是致命的:
1034
+ // label 是描述("streamable-http")⇒ 为常量无害
1035
+ // verdict 是判定("ok"/"degraded")⇒ 若另一支不可观测,它就不是判定而是装饰
1036
+ // 起因:一次复核提议给 /health 加 `ptyWsAttached`,而 attach 在 listen 回调里无条件执行
1037
+ // ⇒ true 恒成立、false 不可观测 ⇒ 这个字段永远只有一个读数,正是被审的「一侧不可达」缺陷本身。
1038
+ // 2026-10-31 —— **身份三分类,且恰好一个权威**(外部复核:产物属性 / 调用属性 / 声明)。
1039
+ // 「三类混在一起且不标注,就是『六个身份』的根。」
1040
+ test("identity fields carry a class; exactly one artifact-class authority", async () => {
1041
+ const { HEALTH_FIELD_META } = await import("./server.js");
1042
+ const rows = Object.entries(HEALTH_FIELD_META).filter(([, m]: any) => m.identity_class);
1043
+ const cls = (r: [string, any]) => r[1].identity_class;
1044
+ // 三类都必须有代表(否则分类只是给已有字段贴了个词)
1045
+ for (const want of ["artifact", "call", "declaration"]) {
1046
+ expect(rows.filter((r) => cls(r as [string, any]) === want).length).toBeGreaterThanOrEqual(1);
1047
+ }
1048
+ // **恰好一个 artifact 类权威** —— 两个权威等于回到「谁说了算」
1049
+ expect(rows.filter((r) => cls(r as [string, any]) === "artifact").length).toBe(1);
1050
+ // 有 call 类覆盖时,必须同时存在 artifact 类(否则「怎么被启动的」在冒充「跑的是什么」)
1051
+ if (rows.some((r) => cls(r as [string, any]) === "call")) {
1052
+ expect(rows.some((r) => cls(r as [string, any]) === "artifact")).toBe(true);
1053
+ }
1054
+ });
1055
+
1056
+ // 2026-10-31 —— **身份是从哪个根读的**(外部复核那条:release 读的是 cwd,不是可执行文件目录)。
1057
+ // 我们优先模块目录,只在拿不到时退回 cwd —— 但若没有字段说明是哪一支,
1058
+ // 「读到的是本包的身份」与「读到的是启动目录里另一个仓库」在载荷上完全同形。
1059
+ test("git identity says which root it came from (build_info vs module_dir vs cwd)", async () => {
1060
+ const b = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1061
+ // 2026-10-31 —— 加了第三支 `build_info`(#3177:生产 runtime 没有 .git,
1062
+ // 只有在**打包时**写进 build-info.json 才可能有标识)。
1063
+ expect(["build_info", "module_dir", "cwd"]).toContain(b.git_identity_root);
1064
+ // 从 cwd 读出来的身份,必须显式承认它不是制品身份
1065
+ if (b.git_identity_root === "cwd") {
1066
+ expect(b.build_identity_note === null || typeof b.build_identity_note === "string").toBe(true);
1067
+ }
1068
+ // 反向:有 commit 却说不出来源 ⇒ 这条断言不允许
1069
+ if (b.git_commit) expect(["build_info", "module_dir", "cwd"]).toContain(b.git_identity_root);
1070
+ // 新支的存在意义:**注入存在 ⇒ 标识必须存在**。
1071
+ // 这一条让「注入了但读不到」变成红,而不是静默退回「没有标识」。
1072
+ if (b.git_identity_root === "build_info") {
1073
+ expect(b.build_identified).toBe(true);
1074
+ expect(b.git_commit).toMatch(/^[0-9a-f]{40}$/);
1075
+ expect(typeof b.git_dirty).toBe("boolean");
1076
+ }
1077
+ });
1078
+
1079
+ // 2026-10-31 —— **每个 verdict 都要有仲裁字段**(外部复核那条:
1080
+ // 「每个问题一个权威字段 + 一个仲裁字段」)。
1081
+ // 只有权威字段时,读者无法区分「结论是对的」与「检查没跑」。
1082
+ test("every verdict declares an arbiter field that is actually in the payload", async () => {
1083
+ const full = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1084
+ const verdicts = Object.entries(HEALTH_FIELD_META).filter(([, m]: any) => m.granularity === "verdict");
1085
+ expect(verdicts.length).toBeGreaterThanOrEqual(4);
1086
+ for (const [k, m] of verdicts as Array<[string, any]>) {
1087
+ expect(typeof m.arbiter).toBe("string");
1088
+ expect(m.arbiter.length).toBeGreaterThan(2);
1089
+ // 仲裁字段必须在同一个载荷里(否则读者还得再发一次请求,那就不是仲裁而是推测)
1090
+ expect(Object.prototype.hasOwnProperty.call(full, m.arbiter)).toBe(true);
1091
+ // 不能自己仲裁自己
1092
+ expect(m.arbiter).not.toBe(k);
1093
+ }
1094
+ });
1095
+
1096
+ test("every verdict names how to make the OTHER branch fire", async () => {
1097
+ const { HEALTH_FIELD_META } = await import("./server.js");
1098
+ // HEALTH_FIELD_META 覆盖**两个投影**(匿名 + 鉴权)⇒ 存在性要对着完整那份查。
1099
+ const full = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1100
+ const anon = await (await fetch(`${BASE}/health`)).json() as any;
1101
+ const verdicts = Object.entries(HEALTH_FIELD_META).filter(([, m]) => m.granularity === "verdict");
1102
+ // 分母非空:今天至少要有这么多真判定,否则这条门是装饰
1103
+ expect(verdicts.length).toBeGreaterThanOrEqual(4);
1104
+ for (const [k, m] of verdicts) {
1105
+ expect((m.verdict_other_branch ?? "").length).toBeGreaterThanOrEqual(20);
1106
+ // 判定必须真的在载荷里(不许给不存在的字段配说明)
1107
+ expect(Object.prototype.hasOwnProperty.call(full, k)).toBe(true);
1108
+ }
1109
+ // 匿名/鉴权的边界也钉住:新增一个 verdict 时必须**显式决定**它匿不匿名,
1110
+ // 否则它会静默地默认进匿名载荷(或默认被滤掉,而没人注意到)。
1111
+ const anonVerdicts = verdicts.map(([k]) => k)
1112
+ .filter((k) => Object.prototype.hasOwnProperty.call(anon, k)).sort();
1113
+ expect(anonVerdicts).toEqual(["build_identified", "license_state", "status"]);
1114
+ });
1115
+
1116
+ // 反面:断言自己是常量的字段,必须给出「另一支为什么不会出现」,并且**真的还是那个常量**。
1117
+ test("fields declared constant-by-design still read as that constant", async () => {
1118
+ const { HEALTH_FIELD_META } = await import("./server.js");
1119
+ const b = await (await fetch(`${BASE}/health`)).json() as any;
1120
+ const claimed: Record<string, unknown> = {
1121
+ ok: true,
1122
+ api_version: "v3",
1123
+ transport: "streamable-http",
1124
+ version_role: "deployment_label",
1125
+ v3_auth: true,
1126
+ multi_network: true,
1127
+ };
1128
+ for (const [k, want] of Object.entries(claimed)) {
1129
+ const m = (HEALTH_FIELD_META as any)[k];
1130
+ expect((m.constant_by_design ?? "").length).toBeGreaterThanOrEqual(20);
1131
+ expect(b[k]).toBe(want);
1132
+ }
1133
+ // 反例守卫:一条「常量」若其实是可变的,claim 就写错了 ⇒ 这里会红
1134
+ expect(b.status).toBe("ok");
1135
+ });
1136
+
1137
+ test("the two that people confuse are labelled right (peak is cumulative, inflight is a level)", async () => {
1138
+ const { HEALTH_FIELD_META } = await import("./server.js");
1139
+ expect(HEALTH_FIELD_META.mcp_inflight_peak.granularity).toBe("cumulative");
1140
+ expect(HEALTH_FIELD_META.mcp_inflight.granularity).toBe("level");
1141
+ expect(HEALTH_FIELD_META.uptime.granularity).toBe("cumulative");
1142
+ });
1143
+ });
1144
+
1145
+ // 2026-10-31 —— 规则:「每个可为 null 的字段都必须有一个能解释它的兄弟字段。」
1146
+ // 反过来:不许用 false 冒充「不知道」—— git_dirty=false 读起来是「干净树」。
1147
+ describe("nullable fields carry an explainer", () => {
1148
+ test("git identity: committed ⇒ note null & dirty boolean; absent ⇒ note non-null & dirty null", async () => {
1149
+ const b = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1150
+ if (b.git_commit !== null) {
1151
+ expect(b.build_identity_note).toBeNull();
1152
+ expect(typeof b.git_dirty).toBe("boolean");
1153
+ } else {
1154
+ expect(typeof b.build_identity_note).toBe("string");
1155
+ expect(b.git_dirty).toBeNull(); // 不知道 ≠ 干净
1156
+ }
1157
+ });
1158
+
1159
+ test("kernel_started_at has its explainer sibling (already true, pinned so it stays true)", async () => {
1160
+ const b = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1161
+ if (b.kernel_started_at === null) expect(typeof b.kernel_started_at_note).toBe("string");
1162
+ else expect(b.kernel_started_at_note).toBeNull();
1163
+ });
1164
+ });
1165
+
1166
+ // 2026-10-31 —— 三分类从「注释里的提醒」变成「字段上的必填标签」。
1167
+ //
1168
+ // 原来的问题:probe_nonce 恰好是对的,但那是因为**恰好这样写**;
1169
+ // 「凭证类要慎给」这四个字在代码里没有任何东西能检查。
1170
+ // ⇒ 现在每个字段必填一档,匿名合法与否由这一档推出来。
1171
+ describe("field classification is machine-checked, not documentation", () => {
1172
+ test("every field in the authenticated body carries a class (no untagged field may exist)", async () => {
1173
+ const body = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1174
+ const untagged = Object.keys(body).filter((k) => !HEALTH_FIELD_META[k]);
1175
+ expect(untagged).toEqual([]); // 空数组 ⇒ 没有「加字段忘了分类」的路
1176
+ });
1177
+
1178
+ test("nothing in the anonymous whitelist is a landmark or a server-issued credential", () => {
1179
+ const illegal = [...PUBLIC_HEALTH_KEYS].filter((k) => !mayBePublic(HEALTH_FIELD_META[k]));
1180
+ expect(illegal).toEqual([]);
1181
+ });
1182
+
1183
+ test("no landmark field actually appears in the anonymous body (the rule has a witness today: git_commit/pid/boot_id)", async () => {
1184
+ const authBody = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1185
+ const anonBody = await (await fetch(`${BASE}/health`)).json() as any;
1186
+ const landmarks = Object.keys(HEALTH_FIELD_META).filter((k) => HEALTH_FIELD_META[k].class === "landmark");
1187
+ // 分母:这份断言今天必须有分子可看,否则它是空的。
1188
+ // 2026-10-31 —— 分母**写死今天的数**(不是在运行时重算),这样:
1189
+ // 有人把某个字段从 landmark 改成 gauge ⇒ 分母下降 ⇒ 这里先红。
1190
+ // 若只检查「一个都不出现」,那次改动会让断言**更容易通过**。
1191
+ const present = landmarks.filter((k) => k in authBody).length;
1192
+ expect(present).toBeGreaterThanOrEqual(5);
1193
+ expect(landmarks.filter((k) => k in anonBody)).toEqual([]);
1194
+ });
1195
+
1196
+ // 合成体见证:将来有人加一个「我们生成的凭证」字段,这一条必须红。
1197
+ test("projection drops unknown fields and landmarks; keeps only gauge + caller-supplied echo (synthetic witness)", () => {
1198
+ const out = projectPublicHealth({
1199
+ ok: true,
1200
+ git_commit: "deadbeef",
1201
+ future_issued_token: "abc123", // 没登记 ⇒ 未分类 ⇒ 丢掉(默认安全方向)
1202
+ probe_nonce: "n-1", // 请求方自带 ⇒ 保留
1203
+ });
1204
+ expect(out).toEqual({ ok: true, probe_nonce: "n-1" });
1205
+ });
1206
+ });
1207
+
1208
+ // 2026-10-31 —— 白名单的另一半:**无死条目**。
1209
+ //
1210
+ // 已有的那条断言「匿名响应里每个键都在白名单内」防的是泄露;
1211
+ // 缺的这半边防的是「死条目」:白名单里的键若早就不再出现(改名/删除),
1212
+ // 它却一直躺在那里,看起来「这个字段是公开的」⇒ 下一个人把同名字段加回来时**默认就是公开的**。
1213
+ // ⇒ 白名单会从「审批记录」退化成「历史残留」。
1214
+ // 这与今晚那条镜像规则同构:否定断言必须配肯定断言,否则前者可被「永远不给」满足。
1215
+ // 2026-10-31 —— **2×2 的第四格**(外部复核 (e):「等价性断言必须按 (通道 × 配置) 组合进行」)。
1216
+ // 本仓的 /health 有两个维度:谁在读(匿名 / 鉴权)× 有没有带 X-Probe-Nonce。
1217
+ // 前面只覆盖了三格(匿名、匿名+探针、鉴权),**鉴权+探针**这一格没测过 ——
1218
+ // 而它正是「探针回显会不会被鉴权分支吃掉」的唯一读数。
1219
+ test("all four cells of (audience × probe-header) carry the fields they must", async () => {
1220
+ const anon = await (await fetch(`${BASE}/health`)).json() as any;
1221
+ const anonProbe = await (await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": "cell-anon" } })).json() as any;
1222
+ const authed = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1223
+ const authedProbe = await (await fetch(`${BASE}/health`, {
1224
+ headers: { Authorization: `Bearer ${adminToken}`, "X-Probe-Nonce": "cell-authed" },
1225
+ })).json() as any;
1226
+
1227
+ // 探针格:带头的两格都必须回显 nonce,且 served_at 都在(窗口两端同域)
1228
+ expect(anonProbe.probe_nonce).toBe("cell-anon");
1229
+ expect(authedProbe.probe_nonce).toBe("cell-authed");
1230
+ for (const body of [anon, anonProbe, authed, authedProbe]) {
1231
+ expect(typeof body.served_at).toBe("string");
1232
+ }
1233
+ // 不带头的一格不该出现 probe_nonce(否则「这一次的凭据」变成常驻字段)
1234
+ expect("probe_nonce" in anon).toBe(false);
1235
+ // 鉴权格必须比匿名格多(否则白名单形同虚设)——第四格同样成立
1236
+ expect(Object.keys(authedProbe).length).toBeGreaterThan(Object.keys(anonProbe).length);
1237
+ });
1238
+
1239
+ // 2026-10-31 —— **未被读的字段 = 未验证的字段**(外部复核 ①:
1240
+ // 「not_applicable 占用了 hash 槽却活到今天,是因为那个字段从未被读取;
1241
+ // 字段『看起来有值』比『未被测的代码』更隐蔽」)。
1242
+ // 断言:HEALTH_FIELD_META 里每个键都必须至少被一条 server 测试提到;例外显式登记。
1243
+ // 上面那条 ratchet 抓出来的两个「被产出但没人读」字段,这里补上断言(而不是登记成例外)。
1244
+ test("alert_baselines and clk_tck_assumed_reason are actually read (not just produced)", async () => {
1245
+ const body = await (await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
1246
+ // alert_baselines:null(还没刷过)或 {at, rows, aliases} —— 两种形态都必须能说清
1247
+ expect(body).toHaveProperty("alert_baselines");
1248
+ if (body.alert_baselines !== null) {
1249
+ expect(typeof body.alert_baselines.at).toBe("string");
1250
+ expect(Number.isInteger(body.alert_baselines.rows)).toBe(true);
1251
+ expect(Number.isInteger(body.alert_baselines.aliases)).toBe(true);
1252
+ }
1253
+ // clk_tck_assumed_reason:一个必须能解释「为什么用假设值」的字符串(空串是合法的:读到了真实值)
1254
+ expect(typeof body.clk_tck_assumed_reason).toBe("string");
1255
+ // 它与 clk_tck_source 配对:source=assumed 时必须有理由,否则必须是空串
1256
+ if (body.clk_tck_source === "assumed") expect(body.clk_tck_assumed_reason.length).toBeGreaterThan(0);
1257
+ else expect(body.clk_tck_assumed_reason).toBe("");
1258
+ });
1259
+
1260
+ test("every /health field is read by at least one test (unread = unverified)", async () => {
1261
+ const { readFileSync, readdirSync, statSync } = await import("node:fs");
1262
+ const { join } = await import("node:path");
1263
+ const src = readFileSync(new URL("./server.ts", import.meta.url), "utf8");
1264
+ const start = src.indexOf("HEALTH_FIELD_META");
1265
+ const block = src.slice(start, src.indexOf("};", start));
1266
+ const keys = [...block.matchAll(/^ {2}([A-Za-z_][A-Za-z0-9_]*):\s*\{/gm)].map((m) => m[1]);
1267
+ expect(keys.length).toBeGreaterThan(30);
1268
+ const walk = (dir: string, out: string[] = []): string[] => {
1269
+ for (const name of readdirSync(dir)) {
1270
+ const full = join(dir, name);
1271
+ if (statSync(full).isDirectory()) walk(full, out);
1272
+ else if (name.endsWith(".test.ts")) out.push(full);
1273
+ }
1274
+ return out;
1275
+ };
1276
+ const testSource = walk(join(import.meta.dir)).map((f) => readFileSync(f, "utf8")).join("\n");
1277
+ const ALLOW_UNREAD: Record<string, string> = {};
1278
+ const unread = keys.filter((k) => !ALLOW_UNREAD[k] && !new RegExp(`\\b${k}\\b`).test(testSource));
1279
+ if (unread.length) {
1280
+ throw new Error(`这 ${unread.length} 个字段被产出但没有任何测试读它们:${unread.join(", ")}\n ⇒ 要么加断言,要么登记进 ALLOW_UNREAD 并写明为什么可以不读。`);
1281
+ }
1282
+ });
1283
+
1284
+ // 2026-10-31 —— **有覆盖、零仲裁**(外部复核 (d)):version 有两个来源
1285
+ // (standalone 二进制注入的 env / 磁盘 package.json),此前只报结果、不报谁赢了。
1286
+ // version_source 就是那个仲裁位;下面四例钉住它的语义。
1287
+ test("version_source names which override won (and splits the two failure causes)", async () => {
1288
+ const { resolveServerVersion } = await import("./server.js");
1289
+ expect(resolveServerVersion("0.9.0-preview.999", () => "0.9.0-preview.1"))
1290
+ .toEqual({ version: "0.9.0-preview.999", source: "embedded_env" });
1291
+ // env 形状不对 ⇒ 落到磁盘,而不是把非法值当版本号
1292
+ expect(resolveServerVersion("latest", () => "0.9.0-preview.1"))
1293
+ .toEqual({ version: "0.9.0-preview.1", source: "package_json" });
1294
+ // 磁盘读失败 ⇒ read_failed;读到空 ⇒ empty_value(**两个成因两个值**,不是一个 unknown)
1295
+ expect(resolveServerVersion(undefined, () => { throw new Error("ENOENT"); }))
1296
+ .toEqual({ version: "?", source: "read_failed" });
1297
+ expect(resolveServerVersion(" ", () => "?"))
1298
+ .toEqual({ version: "?", source: "empty_value" });
1299
+
1300
+ // 线上读数与语义自洽:unknown ⇔ version 是 "?"
1301
+ const body = await (await fetch(`${BASE}/health`)).json() as any;
1302
+ expect(["embedded_env", "package_json", "read_failed", "empty_value"]).toContain(body.version_source);
1303
+ if (body.version_source === "read_failed" || body.version_source === "empty_value") expect(body.version).toBe("?");
1304
+ else expect(body.version).not.toBe("?");
1305
+ });
1306
+
1307
+ // 2026-10-31 —— **granularity=instant 的字段必须写出反事实**(外部复核 (c):
1308
+ // 「判法改为对『这个值变了,世界上什么变了』做反事实询问」)。
1309
+ // 这一类的共同陷阱:值在变,看起来有信息,而它变的可能只是**读的时刻**。
1310
+ test("every instant-granularity field states its counterfactual (why is mandatory)", async () => {
1311
+ const { HEALTH_FIELD_META } = await import("./server.js");
1312
+ const instant = Object.entries(HEALTH_FIELD_META).filter(([, m]: any) => m.granularity === "instant");
1313
+ expect(instant.length).toBeGreaterThanOrEqual(2);
1314
+ const missing = instant.filter(([, m]: any) => !(m.why && String(m.why).length > 8)).map(([k]) => k);
1315
+ if (missing.length) {
1316
+ throw new Error(`instant 字段没有写「变了意味着什么」:${missing.join(", ")}\n ⇒ 它可能只是读的时刻在变,而不是状态在变。`);
1317
+ }
1318
+ });
1319
+
1320
+ // 2026-10-31 —— **单一出口**(外部复核 (a):
1321
+ // 「一个必须在『所有字段写完之后』执行的变换,只有收敛到单一出口才可靠 —— 多出口 × 惰性 = 迟早漏」)。
1322
+ // 这条门只看一件事:`shape(...)` 在源码里只能出现在**一处**。
1323
+ // 出现第二处 ⇒ 说明又有一个 return 各自记得调它 ⇒ 下一个人加第三个出口时就会裸奔。
1324
+ test("the anonymous projection is applied at exactly one call site", async () => {
1325
+ const { readFileSync } = await import("node:fs");
1326
+ const src = readFileSync(new URL("./server.ts", import.meta.url), "utf8");
1327
+ const calls = [...src.matchAll(/Response\.json\(\s*shape\(/g)];
1328
+ expect(calls.length).toBe(1);
1329
+ // 定义处也算一处(`const shape = ...`),但它不是 Response.json 包裹,所以上面的正则不会数到
1330
+ expect((src.match(/const shape = /g) || []).length).toBe(1);
1331
+ });
1332
+
1333
+ // 2026-10-31 —— **同一 body 里的两个时钟源**(外部复核:
1334
+ // 「要解耦两个读数,必须证明它们来自不同的源,而不是来自不同的字段名」)。
1335
+ // 这条同时证明两件事:
1336
+ // ① uptime 的来源是 process.uptime()(单调时钟),不是 Date.now()-startedAt;
1337
+ // ② startedAt 与 uptime 互相自洽(startedAt = now - uptime),所以它是「同一对的另一侧」。
1338
+ // 若哪天有人把 uptime 改成 Date.now()-startedAt,① 会红 —— 那时两个字段会同源、判别力归零。
1339
+ test("uptime comes from the monotonic clock (a separate source from served_at)", async () => {
1340
+ const { readFileSync } = await import("node:fs");
1341
+ const src = readFileSync(new URL("./server.ts", import.meta.url), "utf8");
1342
+ expect(src).toContain("uptime: Math.floor(process.uptime())");
1343
+ expect(src).not.toMatch(/uptime:\s*Math\.floor\(\(Date\.now\(\)\s*-/);
1344
+
1345
+ const body = await (await fetch(`${BASE}/health`)).json() as any;
1346
+ expect(Number.isInteger(body.uptime)).toBe(true);
1347
+ expect(body.uptime).toBeGreaterThanOrEqual(0);
1348
+ // 自洽:now - startedAt ≈ uptime(±5s 容差,覆盖处理时间与秒级取整)
1349
+ const derived = (Date.now() - Date.parse(body.startedAt)) / 1000;
1350
+ expect(Math.abs(derived - body.uptime)).toBeLessThanOrEqual(5);
1351
+ });
1352
+
1353
+ // 2026-10-31 —— **响应头也不能泄露指纹**(外部复核:「匿名 /health 响应头里不得出现
1354
+ // git / commit / build(sha|id) 类头;这两条不需要会话就能读 ⇒ 它们回答『我站在哪一层』,
1355
+ // 不是『我有没有登录』」)。
1356
+ // 为什么需要它:body 有白名单,**头没有**。将来有人把 build id 塞进 `X-Build-Id`,
1357
+ // body 侧断言全绿,而匿名读者已经拿到了指纹。
1358
+ test("anonymous /health exposes no fingerprint-bearing response header", async () => {
1359
+ const res = await fetch(`${BASE}/health`);
1360
+ expect(res.status).toBe(200);
1361
+ const names = [...res.headers.keys()].map((k) => k.toLowerCase());
1362
+ const forbidden = names.filter((n) => /git|commit|build[-_]?(sha|id)?/.test(n));
1363
+ if (forbidden.length) {
1364
+ throw new Error(`匿名 /health 出现了指纹类响应头:${forbidden.join(", ")}\n` +
1365
+ " ⇒ body 白名单不覆盖响应头;要么删掉这个头,要么它只在鉴权分支发。");
1366
+ }
1367
+ // 镜像:同一个端点在**鉴权**分支下可以有 X-* 头,但也不能有指纹 —— 迄今也没有;
1368
+ // 这条留作记录:若哪天加了,必须先在白名单测试里显式放行。
1369
+ expect(forbidden).toEqual([]);
1370
+ });
1371
+
1372
+ // 2026-10-31 —— **「谁写的」比「谁先谁后」更抗重构**(外部复核:头集合当主判据)。
1373
+ // 部署前面有 nginx/反代时,客户端拿到的错误页可能不是我们写的。
1374
+ // 判据不是「content-type 是 json」(那要求每个客户端都记得先看),
1375
+ // 而是一个**静态**产出者标记:有它 ⇒ 这段字节出自 hub;没有 ⇒ 出自它前面的某一层。
1376
+ // 必须是静态值:一旦它随进程/版本变化,它就变成了指纹(与 version_role 那条相冲突)。
1377
+ // 2026-10-31 —— **凡是差值字段,必须同时给出两个端点的原始值**
1378
+ // (外部复核:「任何 `a − b` 都会把『两字段一源』变成不可见;读者至少能看出可能同源,
1379
+ // 只剩一个数时他无法质疑两个端点」)。
1380
+ //
1381
+ // 谓词落在**名字**上而不是「源码里出现了减法」(外部复核:
1382
+ // 「`startedAt` / `lastSuccessAt` 也是减法算出来的但**稳**;只扫减法会漏掉无条件的那个」)。
1383
+ // 分母必须报出来:命中 0 个差值字段 ⇒ 这条断言是真空真。
1384
+ test("difference-shaped fields name both endpoints in the same payload (proves endpoints exist, not that the value is right)", async () => {
1385
+ const { HEALTH_FIELD_META } = await import("./server.js");
1386
+ const DIFFY = /(age|elapsed|uptime|remaining|ttl|delta|drift|lag)/i;
1387
+ const named = Object.keys(HEALTH_FIELD_META).filter((k) => DIFFY.test(k));
1388
+ expect(named.length).toBeGreaterThan(0); // 分母:按名字至少命中 1 个
1389
+
1390
+ const derived = named.filter((k) => (HEALTH_FIELD_META as any)[k].derived_from);
1391
+ // 本仓今天有 2 个真差值(epoch_delta_ms / clk_tck_delta);`uptime` 是**单调读数**不是差值,
1392
+ // 它显式不写 derived_from —— 所以这里要求的是「写了端点的必须两端齐全」,
1393
+ // 而不是「所有命中名字的都必须写」(后者会把这条规则变成填表)。
1394
+ expect(derived.length).toBeGreaterThanOrEqual(2);
1395
+
1396
+ const problems: string[] = [];
1397
+ for (const k of derived) {
1398
+ const ends = (HEALTH_FIELD_META as any)[k].derived_from as readonly string[];
1399
+ if (!Array.isArray(ends) || ends.length < 2) { problems.push(`${k}: 端点少于 2 个`); continue; }
1400
+ for (const e of ends) {
1401
+ if (!(e in HEALTH_FIELD_META)) problems.push(`${k}: 端点 ${e} 不是本载荷里的字段(拼错的端点等于没有端点)`);
1402
+ }
1403
+ }
1404
+ expect(problems).toEqual([]);
1405
+ // 镜像:非差值字段**不该**被要求给端点(否则「填表」会取代判据)——
1406
+ // 断言 uptime 没有 derived_from,并且它确实不是 now-startedAt 那种同源减法。
1407
+ expect((HEALTH_FIELD_META as any).uptime.derived_from).toBeUndefined();
1408
+ });
1409
+
1410
+ test("every hub response carries a constant producer marker (so a proxy page is distinguishable)", async () => {
1411
+ const paths = ["/health", "/api/definitely-not-a-route", "/"];
1412
+ const seen: (string | null)[] = [];
1413
+ for (const path of paths) {
1414
+ const res = await fetch(`${BASE}${path}`);
1415
+ seen.push(res.headers.get("X-CommHub"));
1416
+ }
1417
+ // 三个不同出口(健康检查 / 404 / 帮助页)都必须带,且值相同
1418
+ expect(seen).toEqual(["hub", "hub", "hub"]);
1419
+ // 静态性:同一路径两次读到的值必须一致(否则它是指纹,不是产出者标记)
1420
+ const again = await fetch(`${BASE}/health`);
1421
+ expect(again.headers.get("X-CommHub")).toBe("hub");
1422
+ // 与「匿名无指纹」那条不冲突:这个头不含 git/commit/build 类词
1423
+ expect(/git|commit|build[-_]?(sha|id)?/.test("x-commhub")).toBe(false);
1424
+ });
1425
+
1426
+ // 2026-10-31 —— **计数之间的守恒式**(外部复核:「human + worker + unassigned == 待办行数;
1427
+ // 不等 ⇒ RuntimeError。它防的是将来改坏分桶:漏一类左边小、重复计一类左边大」)。
1428
+ // 本仓这里的两个数是同一个量的两个名字:mcp_inflight(当前)与 mcp_inflight_peak(峰值)。
1429
+ // 守恒式:peak ≥ inflight(任何时刻都成立,与采样时机无关);
1430
+ // 反过来若有人把 peak 写成"本次采样值",两者会相等而看不出——所以还要一条
1431
+ // 「peak 只增不减」:在窗口内取三次,peak 序列必须单调不减。
1432
+ test("mcp_inflight_peak dominates the current value and never decreases", async () => {
1433
+ const samples: Array<{ now: number; peak: number }> = [];
1434
+ for (let i = 0; i < 3; i++) {
1435
+ const d = await (await fetch(`${BASE}/health`)).json() as any;
1436
+ samples.push({ now: Number(d.mcp_inflight), peak: Number(d.mcp_inflight_peak) });
1437
+ await new Promise((r) => setTimeout(r, 120));
1438
+ }
1439
+ for (const s of samples) {
1440
+ expect(Number.isFinite(s.now)).toBe(true);
1441
+ expect(Number.isFinite(s.peak)).toBe(true);
1442
+ expect(s.peak).toBeGreaterThanOrEqual(s.now); // 守恒式
1443
+ expect(s.now).toBeGreaterThanOrEqual(0);
1444
+ }
1445
+ // 单调:峰值不许下降(它不是一个采样值)
1446
+ for (let i = 1; i < samples.length; i++) {
1447
+ expect(samples[i].peak).toBeGreaterThanOrEqual(samples[i - 1].peak);
1448
+ }
1449
+ });
1450
+
1451
+ // 2026-10-31 —— **一致时零证据**(外部复核:「status / db / mineruProxy 三个字段是同一个位,
1452
+ // 一致时零证据」)。本仓的 status 与 status_reasons 由构造保证一致 ⇒
1453
+ // 「status=='ok' ⟺ reasons 为空」是恒真断言,保护不了任何东西。
1454
+ // ⇒ 改成断言**映射本身**:给一个理由就必须 degraded;且映射是纯函数、可被单独喂输入。
1455
+ test("status mapping is a pure function of the reasons list (one reason is enough to degrade)", async () => {
1456
+ const { statusFromReasons } = await import("./server.js");
1457
+ expect(statusFromReasons([])).toBe("ok");
1458
+ expect(statusFromReasons(["db_unreadable"])).toBe("degraded");
1459
+ expect(statusFromReasons(["license_unreadable"])).toBe("degraded");
1460
+ expect(statusFromReasons(["anything_at_all"])).toBe("degraded"); // 不认识的理由也不许吞
1461
+ // 且线上载荷与函数一致(不是两套逻辑)
1462
+ const live = await (await fetch(`${BASE}/health`)).json() as any;
1463
+ expect(live.status).toBe(statusFromReasons(live.status_reasons ?? []));
1464
+ });
1465
+
1466
+ test("no dead entries: every allow-listed key is actually served to anonymous callers", async () => {
1467
+ const { PUBLIC_HEALTH_KEYS } = await import("./server.js");
1468
+ const plain = await (await fetch(`${BASE}/health`)).json() as any;
1469
+ // 条件出现的键(只在带 X-Probe-Nonce 时出现)要在第二种请求里核对
1470
+ const probed = await (await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": "dead-entry-check" } })).json() as any;
1471
+ const seen = new Set([...Object.keys(plain), ...Object.keys(probed)]);
1472
+ const dead = [...PUBLIC_HEALTH_KEYS].filter((k) => !seen.has(k));
1473
+ // 2026-10-31 —— 失败时必须点名(外部复核 ③):只说 `toEqual([])` 的失败信息里
1474
+ // 没有「是哪几个键」,而修它需要的正是那几个名字。
1475
+ if (dead.length) {
1476
+ throw new Error(
1477
+ `白名单里有 ${dead.length} 个键在任何投影里都不出现(死条目):${dead.join(", ")}\n` +
1478
+ " ⇒ 要么从 PUBLIC_HEALTH_KEYS 删掉,要么让 body 真的产出它;" +
1479
+ "留着等于给未来的同名字段预授权。",
1480
+ );
1481
+ }
1482
+ expect(dead).toEqual([]);
1483
+ });
1484
+
1485
+ test("exposes stable upload limits anonymously without exposing topology", async () => {
1486
+ const res = await fetch(`${BASE}/health`);
1487
+ expect(res.status).toBe(200);
1488
+ const body = await res.json() as any;
1489
+ expect(body.limits).toEqual({
1490
+ max_upload_bytes: MAX_UPLOAD_BYTES,
1491
+ max_request_content_length: MAX_REQUEST_CONTENT_LENGTH,
1492
+ });
1493
+ expect(body.limits.max_request_content_length).toBeGreaterThan(body.limits.max_upload_bytes);
1494
+ });
1495
+
1496
+ // 2026-10-31 —— 「这一次」的判据。
1497
+ //
1498
+ // /health 恒 200,所以「200」不证明是这台机器、这个进程、更不证明是**这个请求**。
1499
+ // 缓存层 / 前面的代理 / 上一次运行留下的响应,都给同一个 200。
1500
+ // 请求方带随机 nonce ⇒ 回显 ⇔ 这个响应生成于收到这个请求之后。
1501
+ test("echoes a caller-supplied probe nonce so 'this very request' is provable", async () => {
1502
+ const nonce = `p-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
1503
+ const res = await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": nonce } });
1504
+ expect(res.status).toBe(200);
1505
+ expect(res.headers.get("cache-control")).toBe("no-store");
1506
+ const body = await res.json() as any;
1507
+ expect(body.probe_nonce).toBe(nonce);
1508
+ // 🔴 served_at 的断言只到「可解析」——它**不证明新鲜**,也不参与任何判据。
1509
+ // 真正证明“这一次”的是 probe_nonce(缓存不可能为它生成响应)。
1510
+ // 这里把它标清楚,否则它就会变成下一个 startedAt:看着像证据,却没有消费者。
1511
+ const servedAt = Date.parse(body.served_at);
1512
+ expect(Number.isFinite(servedAt)).toBe(true);
1513
+ expect(servedAt).toBeGreaterThan(0);
1514
+ });
1515
+
1516
+ // 三件套的第③件:nonce 必须也出现在**响应之外**(服务端日志)。
1517
+ // 判据:一次探针之后,日志里该 nonce 出现**恰好 1 次**。
1518
+ // == 1 ⇒ 这次请求真的到了这个进程(中间层伪造不了服务端日志)
1519
+ // == 0 ⇒ 缺日志
1520
+ // > 1 ⇒ 有人复用了同一个 nonce(重试没换)⇒ 那次读数不可信
1521
+ test("logs the probe nonce exactly once, outside the response", async () => {
1522
+ const nonce = `log-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
1523
+ const seen: string[] = [];
1524
+ const original = console.log;
1525
+ console.log = (...args: unknown[]) => {
1526
+ const line = args.map(String).join(" ");
1527
+ if (line.includes(nonce)) seen.push(line);
1528
+ original(...args);
1529
+ };
1530
+ try {
1531
+ const res = await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": nonce } });
1532
+ await res.json();
1533
+ } finally {
1534
+ console.log = original;
1535
+ }
1536
+ expect(seen.length).toBe(1);
1537
+ expect(seen[0]).toContain("[health] probe nonce=");
1538
+ });
1539
+
1540
+ // 2026-10-31 —— 上面那条 `== 1` 需要一个**镜像**,否则它只在「日志存在」时成立,
1541
+ // 而在「日志被去重」时同样成立 —— 而去重恰好会毁掉 ==1 判据的全部价值:
1542
+ // 判据里的 `> 1` 只有在「复用会被记两次」时才能被发现。
1543
+ // ⇒ 一个看起来无害的优化(同一 nonce 只打一行、或加个 seen 集合)会让复用永远读成「新鲜」。
1544
+ test("reusing the same nonce logs TWICE (so `>1` can actually fire)", async () => {
1545
+ const nonce = `reuse-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
1546
+ const seen: string[] = [];
1547
+ const original = console.log;
1548
+ console.log = (...args: unknown[]) => {
1549
+ const line = args.map(String).join(" ");
1550
+ if (line.includes(nonce)) seen.push(line);
1551
+ original(...args);
1552
+ };
1553
+ try {
1554
+ for (let i = 0; i < 2; i++) {
1555
+ const res = await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": nonce } });
1556
+ await res.json();
1557
+ }
1558
+ } finally {
1559
+ console.log = original;
1560
+ }
1561
+ expect(seen.length).toBe(2); // 去重实现会让这条红 —— 那是故意的
1562
+ });
1563
+
1564
+ test("two distinct nonces are each logged once (no cross-talk)", async () => {
1565
+ const mk = () => `pair-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
1566
+ const a = mk(); const b = mk();
1567
+ const seen: string[] = [];
1568
+ const original = console.log;
1569
+ console.log = (...args: unknown[]) => {
1570
+ const line = args.map(String).join(" ");
1571
+ if (line.includes("pair-")) seen.push(line);
1572
+ original(...args);
1573
+ };
1574
+ try {
1575
+ await (await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": a } })).json();
1576
+ await (await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": b } })).json();
1577
+ } finally {
1578
+ console.log = original;
1579
+ }
1580
+ expect(seen.filter(l => l.includes(a)).length).toBe(1);
1581
+ expect(seen.filter(l => l.includes(b)).length).toBe(1);
1582
+ });
1583
+
1584
+ // 2026-10-31 —— served_at 变成**常驻**:窗口的两端必须在同一个时钟域里。
1585
+ // 没有它,读者只能拿自己的钟去减 since ⇒ 偷偷假设两边时钟一致。
1586
+ // 而 probe_nonce 仍然只在带 X-Probe-Nonce 时出现(它是“这一次”的凭据)。
1587
+ test("default /health always carries served_at (same clock domain) but never probe_nonce", async () => {
1588
+ const res = await fetch(`${BASE}/health`);
1589
+ const body = await res.json() as any;
1590
+ expect("probe_nonce" in body).toBe(false);
1591
+ expect(typeof body.served_at).toBe("string");
1592
+ const served = Date.parse(body.served_at);
1593
+ expect(Number.isFinite(served)).toBe(true);
1594
+ // 同一时钟域:served_at 不早于进程起点,且两次读数单调不减。
1595
+ expect(served).toBeGreaterThanOrEqual(Date.parse(body.startedAt));
1596
+ const second = await (await fetch(`${BASE}/health`)).json() as any;
1597
+ expect(Date.parse(second.served_at)).toBeGreaterThanOrEqual(served);
1598
+ // 2026-10-31 修订:**一律 no-store**。原来只在带 nonce 时设,
1599
+ // 而 /health 每个字段都是「此刻的读数」——304 会冻结 startedAt 而 counters 照涨,
1600
+ // 那正是 flapping 的假阳性形状。断言方向随之从 null 改成必须存在。
1601
+ expect(res.headers.get("cache-control")).toBe("no-store");
1602
+ });
1603
+
1604
+ test("refuses a nonce it cannot echo verbatim instead of half-accepting it", async () => {
1605
+ // 注意:非 ASCII 那类(如「中文」)到不了这一层 —— fetch/undici 在**发送端**
1606
+ // 就拒绝非 token 的 header 值。所以这里只用能被发出去的非法值。
1607
+ for (const bad of ["has space", "semi;colon", "a".repeat(65)]) {
1608
+ const res = await fetch(`${BASE}/health`, { headers: { "X-Probe-Nonce": bad } });
1609
+ const body = await res.json() as any;
1610
+ // 半接受会造出「看起来回显了、其实被改过」的值 —— 比不回显更糟。
1611
+ expect("probe_nonce" in body).toBe(false);
1612
+ }
1613
+ });
1614
+
94
1615
  test("CLI count source stays truthful: health.sse_connections == /api/stats/sse total (no fake 0)", async () => {
95
1616
  // The CLI's `anet doctor` line reads health.sse_connections now
96
1617
  // (was Object.keys(sse_sessions).length). This pins that aggregate to
@@ -201,8 +1722,12 @@ describe("#473 GET /api/stats/sse — detail survives, behind ops auth", () => {
201
1722
  expect(res.status).toBe(200);
202
1723
  const body = await res.json() as any;
203
1724
  expect(body.ok).toBe(true);
204
- expect(typeof body.total).toBe("number");
1725
+ expect(Number.isInteger(body.total)).toBe(true);
1726
+ expect(body.total).toBeGreaterThanOrEqual(0); // 类型不是断言
205
1727
  expect(body.sessions[`${userNetworkId}:${userName}`]).toBeGreaterThanOrEqual(1);
1728
+ // 结构关系:total 必须等于各计数之和(否则「总数」与「明细」是两个读数)
1729
+ const detailSum = Object.values(body.sessions as Record<string, number>).reduce((a, b) => a + b, 0);
1730
+ expect(detailSum).toBe(body.total);
206
1731
  });
207
1732
 
208
1733
  test("legacy master token → 200 (ops path — restAuth null, isLegacyAuthToken)", () => {
@@ -357,7 +1882,8 @@ describe("f28a6c1b CR3 — network-scoped filter matrix (M1-M7)", () => {
357
1882
  mAliceNet = rAl.network_id;
358
1883
  db.run("UPDATE users SET role = 'user' WHERE username = ?1", [mAliceName]);
359
1884
  mAliceId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [mAliceName])!.user_id;
360
- const addAlice = addNetworkMember(mUserANet, mAliceId, "member", mUserAId);
1885
+ // 多用户 Agent 权限:新成员默认只看授权 Agent;本测试测的是「完全信任的成员」旧语义,显式 agent_access=all。
1886
+ const addAlice = addNetworkMember(mUserANet, mAliceId, "member", mUserAId, { agentAccess: "all" });
361
1887
  if (!addAlice.ok) throw new Error("addNetworkMember(alice→N_A) failed: " + addAlice.error);
362
1888
 
363
1889
  // carol — own network + will also be added to N_A, then revoked
@@ -369,7 +1895,7 @@ describe("f28a6c1b CR3 — network-scoped filter matrix (M1-M7)", () => {
369
1895
  mCarolNet = rC.network_id;
370
1896
  db.run("UPDATE users SET role = 'user' WHERE username = ?1", [mCarolName]);
371
1897
  mCarolId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [mCarolName])!.user_id;
372
- const addCarol = addNetworkMember(mUserANet, mCarolId, "member", mUserAId);
1898
+ const addCarol = addNetworkMember(mUserANet, mCarolId, "member", mUserAId, { agentAccess: "all" });
373
1899
  if (!addCarol.ok) throw new Error("addNetworkMember(carol→N_A) failed: " + addCarol.error);
374
1900
 
375
1901
  // Live SSE sessions — one per network — so the filter has real
@@ -623,3 +2149,46 @@ describe("#506 cross-network isolation of /health sse_sessions (same alias, two
623
2149
  expect(keys.some((k) => k.startsWith(`${aNet}:`))).toBe(false);
624
2150
  });
625
2151
  });
2152
+
2153
+ // #2149 —— 错误路径**不能回显凭据**。
2154
+ //
2155
+ // 背景:2026-10-23 TMA云鲸 对 CommHub MCP 做只读扫描时收到 502,代理生成的
2156
+ // 非 JSON 错误页把本次请求的鉴权相关头回显在正文里。那个 502 页很可能来自
2157
+ // 调用链上的代理(本仓没有 502 生成逻辑),但**这条防线必须在本仓也有**:
2158
+ // 任何 4xx/5xx 的响应体都不该把调用方递上来的 `Authorization` / `Cookie` /
2159
+ // query 里的 token 原样吐回去 —— 一旦有人写出这种错误文案,它就会进日志、
2160
+ // 进回执、进诊断归档。
2161
+ //
2162
+ // 做法是**注入一个形状像真凭据的 canary**,然后打一圈错误路径,断言响应正文
2163
+ // 里一次都不出现它。canary 用 `ntok_` 前缀,正是本仓 `redactTokens` 认得的形状。
2164
+ describe("#2149 error paths never echo credentials", () => {
2165
+ const CANARY = "ntok_LEAKCANARY_0123456789abcdef";
2166
+ const COOKIE = "session=COOKIELEAKCANARY0123456789";
2167
+
2168
+ const paths: Array<{ method: string; path: string; body?: string }> = [
2169
+ { method: "GET", path: "/api/nope-not-a-route" },
2170
+ { method: "GET", path: "/api/requirements" },
2171
+ { method: "GET", path: "/api/nodes" },
2172
+ { method: "POST", path: "/mcp", body: "{not json" },
2173
+ { method: "POST", path: "/api/auth/login", body: JSON.stringify({ username: "nobody", password: "wrong-password-Aa1!" }) },
2174
+ { method: "POST", path: "/api/auth/me/avatar/upload" },
2175
+ ];
2176
+
2177
+ test("no 4xx/5xx body contains the presented token, cookie or query secret", async () => {
2178
+ for (const c of paths) {
2179
+ const res = await fetch(`${BASE}${c.path}${c.path.includes("?") ? "&" : "?"}access_token=${CANARY}`, {
2180
+ method: c.method,
2181
+ headers: {
2182
+ authorization: `Bearer ${CANARY}`,
2183
+ cookie: COOKIE,
2184
+ "content-type": "application/json",
2185
+ },
2186
+ body: c.body,
2187
+ });
2188
+ const text = await res.text();
2189
+ expect(text.includes(CANARY)).toBe(false);
2190
+ expect(text.includes("LEAKCANARY")).toBe(false);
2191
+ expect(text.includes("COOKIELEAKCANARY")).toBe(false);
2192
+ }
2193
+ });
2194
+ });