@holmes-lab/holmes-kit 0.39.0 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (298) hide show
  1. package/CHANGELOG.md +344 -6
  2. package/README.md +54 -41
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/admission/core/admission-policy.d.ts +37 -0
  5. package/dist/holmes/admission/core/admission-policy.js +147 -0
  6. package/dist/holmes/admission/core/bounded-reader.d.ts +56 -0
  7. package/dist/holmes/admission/core/bounded-reader.js +135 -0
  8. package/dist/holmes/admission/core/change-classifier.d.ts +34 -0
  9. package/dist/holmes/admission/core/change-classifier.js +278 -0
  10. package/dist/holmes/admission/core/config-loader.d.ts +30 -0
  11. package/dist/holmes/admission/core/config-loader.js +145 -0
  12. package/dist/holmes/admission/core/event-judgement.d.ts +37 -0
  13. package/dist/holmes/admission/core/event-judgement.js +251 -0
  14. package/dist/holmes/admission/core/path-rules.d.ts +35 -0
  15. package/dist/holmes/admission/core/path-rules.js +88 -0
  16. package/dist/holmes/admission/core/pin.d.ts +7 -0
  17. package/dist/holmes/admission/core/pin.js +29 -0
  18. package/dist/holmes/admission/core/ports.d.ts +48 -0
  19. package/dist/holmes/admission/core/ports.js +11 -0
  20. package/dist/holmes/admission/core/range-resolver.d.ts +32 -0
  21. package/dist/holmes/admission/core/range-resolver.js +51 -0
  22. package/dist/holmes/admission/core/self-containment.d.ts +1 -0
  23. package/dist/holmes/admission/core/self-containment.js +125 -0
  24. package/dist/holmes/admission/core/signature-source.d.ts +9 -0
  25. package/dist/holmes/admission/core/signature-source.js +4 -0
  26. package/dist/holmes/admission/core/transition-planner.d.ts +15 -0
  27. package/dist/holmes/admission/core/transition-planner.js +14 -0
  28. package/dist/holmes/admission/core/verdict.d.ts +38 -0
  29. package/dist/holmes/admission/core/verdict.js +17 -0
  30. package/dist/holmes/admission/core/wiring.d.ts +44 -0
  31. package/dist/holmes/admission/core/wiring.js +618 -0
  32. package/dist/holmes/admission/forge/git-object-port.d.ts +4 -0
  33. package/dist/holmes/admission/forge/git-object-port.js +132 -0
  34. package/dist/holmes/assoc/assoc-arm.d.ts +1 -1
  35. package/dist/holmes/assoc/assoc-arm.js +1 -1
  36. package/dist/holmes/cli/agents.d.ts +8 -0
  37. package/dist/holmes/cli/agents.js +9 -5
  38. package/dist/holmes/cli/approve-cli.d.ts +2 -0
  39. package/dist/holmes/cli/approve-cli.js +392 -0
  40. package/dist/holmes/cli/approve-ref.d.ts +13 -7
  41. package/dist/holmes/cli/approve-ref.js +30 -10
  42. package/dist/holmes/cli/approve-status.d.ts +26 -2
  43. package/dist/holmes/cli/approve-status.js +98 -18
  44. package/dist/holmes/cli/approve-watch.d.ts +5 -0
  45. package/dist/holmes/cli/approve-watch.js +10 -5
  46. package/dist/holmes/cli/approve.d.ts +49 -13
  47. package/dist/holmes/cli/approve.js +249 -67
  48. package/dist/holmes/cli/attest.js +2 -1
  49. package/dist/holmes/cli/autonomy.d.ts +4 -1
  50. package/dist/holmes/cli/autonomy.js +17 -10
  51. package/dist/holmes/cli/codex-oracle.d.ts +11 -0
  52. package/dist/holmes/cli/codex-oracle.js +5 -1
  53. package/dist/holmes/cli/codex-toml.d.ts +10 -0
  54. package/dist/holmes/cli/codex-toml.js +36 -2
  55. package/dist/holmes/cli/doctor-boundary.d.ts +76 -0
  56. package/dist/holmes/cli/doctor-boundary.js +308 -0
  57. package/dist/holmes/cli/doctor-locks.d.ts +15 -0
  58. package/dist/holmes/cli/doctor-locks.js +119 -0
  59. package/dist/holmes/cli/doctor.d.ts +2 -0
  60. package/dist/holmes/cli/doctor.js +34 -5
  61. package/dist/holmes/cli/flags.d.ts +23 -0
  62. package/dist/holmes/cli/flags.js +89 -0
  63. package/dist/holmes/cli/index.d.ts +5 -1
  64. package/dist/holmes/cli/index.js +202 -424
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  67. package/dist/holmes/cli/lock-recover.js +126 -0
  68. package/dist/holmes/cli/mcp-processes.js +1 -1
  69. package/dist/holmes/cli/release-docs.js +1 -1
  70. package/dist/holmes/cli/run-exec.d.ts +141 -0
  71. package/dist/holmes/cli/run-exec.js +1435 -0
  72. package/dist/holmes/cli/run-provision.d.ts +3 -1
  73. package/dist/holmes/cli/run-provision.js +255 -44
  74. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  75. package/dist/holmes/cli/run-wiring.js +270 -0
  76. package/dist/holmes/cli/run.d.ts +21 -0
  77. package/dist/holmes/cli/run.js +341 -92
  78. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  79. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  80. package/dist/holmes/cli/screen-safe.js +18 -756
  81. package/dist/holmes/config/config.d.ts +2 -0
  82. package/dist/holmes/config/config.js +5 -2
  83. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  84. package/dist/holmes/cpg/import-resolver.js +1 -1
  85. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  86. package/dist/holmes/governance/approval-decisions.js +29 -0
  87. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  88. package/dist/holmes/governance/approval-grants.js +612 -33
  89. package/dist/holmes/governance/approval-queue.d.ts +26 -0
  90. package/dist/holmes/governance/approval-queue.js +109 -11
  91. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  92. package/dist/holmes/governance/approval-spend.js +191 -0
  93. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  94. package/dist/holmes/governance/autonomous-shell.js +332 -0
  95. package/dist/holmes/governance/autonomy.d.ts +5 -0
  96. package/dist/holmes/governance/autonomy.js +16 -11
  97. package/dist/holmes/governance/constitution.d.ts +5 -0
  98. package/dist/holmes/governance/constitution.js +32 -12
  99. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  100. package/dist/holmes/governance/full-autonomy.js +103 -7
  101. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  102. package/dist/holmes/governance/harness-catalog.js +348 -0
  103. package/dist/holmes/governance/human-channel.d.ts +38 -0
  104. package/dist/holmes/governance/human-channel.js +49 -0
  105. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  106. package/dist/holmes/governance/install-manifest.js +160 -0
  107. package/dist/holmes/governance/ledger-rechain.js +2 -0
  108. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  109. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  110. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  111. package/dist/holmes/governance/ledger-store.js +186 -8
  112. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  113. package/dist/holmes/governance/provenance-chain.js +19 -4
  114. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  115. package/dist/holmes/governance/provenance-ledger.js +53 -18
  116. package/dist/holmes/governance/push-gate-runner.js +11 -7
  117. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  118. package/dist/holmes/governance/recorded-pairs.js +522 -0
  119. package/dist/holmes/governance/replica-id.d.ts +1 -1
  120. package/dist/holmes/governance/replica-id.js +1 -1
  121. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  122. package/dist/holmes/governance/spec-seam.js +587 -0
  123. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  124. package/dist/holmes/governance/spend-kinds.js +18 -0
  125. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  126. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  127. package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
  128. package/dist/holmes/guardrail/impact-gate.js +1 -1
  129. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  130. package/dist/holmes/guardrail/line-continuation.js +39 -0
  131. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  132. package/dist/holmes/guardrail/operator-person.js +57 -11
  133. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  134. package/dist/holmes/guardrail/refusal-codes.js +64 -10
  135. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  136. package/dist/holmes/guardrail/risk-classifier.js +228 -16
  137. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  138. package/dist/holmes/guardrail/risk-gate.js +7 -34
  139. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  140. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  141. package/dist/holmes/guardrail/run-refusals.js +24 -8
  142. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  143. package/dist/holmes/guardrail/run-stages.js +25 -5
  144. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  145. package/dist/holmes/guardrail/shell-words.js +24 -3
  146. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  147. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  148. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  149. package/dist/holmes/guardrail/write-target.js +26 -5
  150. package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
  151. package/dist/holmes/hooks/pre-tool-use.js +1134 -167
  152. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  153. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  154. package/dist/holmes/hooks/stop.d.ts +23 -0
  155. package/dist/holmes/hooks/stop.js +86 -33
  156. package/dist/holmes/mcp/approval-adapters.js +3 -1
  157. package/dist/holmes/mcp/approval-commit.js +3 -2
  158. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  159. package/dist/holmes/mcp/approval-policy.js +3 -1
  160. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  161. package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
  162. package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
  163. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  164. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  165. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  166. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  167. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  168. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  169. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  170. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  171. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  172. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  173. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  174. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  175. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  176. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  177. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  178. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  179. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  180. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  181. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  182. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  183. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  184. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  185. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  186. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  187. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  188. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  189. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  190. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  191. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  192. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  193. package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
  194. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  195. package/dist/holmes/mcp/handlers.d.ts +89 -79
  196. package/dist/holmes/mcp/handlers.js +69 -22
  197. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  198. package/dist/holmes/mcp/harness-attestation.js +325 -53
  199. package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
  200. package/dist/holmes/mcp/maintenance-analyze.js +9 -9
  201. package/dist/holmes/mcp/maintenance-evidence.js +31 -2
  202. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  203. package/dist/holmes/mcp/server-staleness.js +1 -1
  204. package/dist/holmes/mcp/server.js +9 -8
  205. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  206. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  207. package/dist/holmes/mcp/tool-schemas.js +29 -2
  208. package/dist/holmes/project/act-root.d.ts +19 -0
  209. package/dist/holmes/project/act-root.js +100 -0
  210. package/dist/holmes/project/baseline.js +4 -3
  211. package/dist/holmes/project/bounded-group.d.ts +47 -0
  212. package/dist/holmes/project/bounded-group.js +140 -0
  213. package/dist/holmes/project/bounded-io.d.ts +50 -2
  214. package/dist/holmes/project/bounded-io.js +138 -6
  215. package/dist/holmes/project/change-source.js +2 -2
  216. package/dist/holmes/project/instance-id.d.ts +10 -0
  217. package/dist/holmes/project/instance-id.js +233 -0
  218. package/dist/holmes/project/machine-identity.d.ts +25 -0
  219. package/dist/holmes/project/machine-identity.js +133 -0
  220. package/dist/holmes/project/owned-lock.d.ts +84 -0
  221. package/dist/holmes/project/owned-lock.js +263 -0
  222. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  223. package/dist/holmes/project/plain-lock-fs.js +126 -0
  224. package/dist/holmes/project/request-lock.d.ts +85 -0
  225. package/dist/holmes/project/request-lock.js +459 -0
  226. package/dist/holmes/project/root.d.ts +12 -4
  227. package/dist/holmes/project/root.js +26 -7
  228. package/dist/holmes/project/run-records.d.ts +19 -0
  229. package/dist/holmes/project/run-records.js +94 -12
  230. package/dist/holmes/project/screen-text.d.ts +94 -0
  231. package/dist/holmes/project/screen-text.js +763 -0
  232. package/dist/holmes/project/spend-lock.d.ts +82 -0
  233. package/dist/holmes/project/spend-lock.js +413 -0
  234. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  235. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  236. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  237. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  238. package/dist/holmes/review/confidence-calibration.js +1 -1
  239. package/dist/holmes/review/content-verify.js +1 -1
  240. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  241. package/dist/holmes/review/hop-ablation.js +5 -5
  242. package/dist/holmes/review/point-in-time-replay.js +12 -3
  243. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  244. package/dist/holmes/review/rank-diagnosis.js +1 -1
  245. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  246. package/dist/holmes/review/replay-corpus.js +25 -9
  247. package/dist/holmes/review/requirement-triage.js +2 -2
  248. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  249. package/dist/holmes/review/semantic-arm.js +3 -3
  250. package/dist/holmes/review/test-outcomes.js +3 -1
  251. package/dist/holmes/review/test-runner.d.ts +11 -0
  252. package/dist/holmes/review/test-runner.js +31 -10
  253. package/dist/holmes/review/test-selection-breadth.js +2 -2
  254. package/dist/holmes/review/verdicts.d.ts +105 -8
  255. package/dist/holmes/review/verdicts.js +640 -36
  256. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  257. package/dist/holmes/rtm/anchor-census.js +151 -0
  258. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  259. package/dist/holmes/rtm/anchor-ids.js +45 -2
  260. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  261. package/dist/holmes/rtm/comment-ranges.js +104 -0
  262. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  263. package/dist/holmes/rtm/counted-tests.js +63 -0
  264. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  265. package/dist/holmes/rtm/known-defects.js +1 -1
  266. package/dist/holmes/rtm/localize.js +1 -1
  267. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  268. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  269. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  270. package/dist/holmes/rtm/test-scope.js +166 -5
  271. package/dist/holmes/rtm/trace-gaps.js +1 -1
  272. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  273. package/dist/holmes/runtime/dispatch.js +12 -1
  274. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  275. package/dist/holmes/semantic/cloud-usage.js +1 -1
  276. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  277. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  278. package/dist/holmes/spec/approval-blockers.js +1 -1
  279. package/dist/holmes/spec/entity-store.d.ts +6 -1
  280. package/dist/holmes/spec/entity-store.js +16 -2
  281. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  282. package/dist/holmes/spec/entity-transaction.js +87 -170
  283. package/dist/holmes/spec/spec-store.d.ts +12 -6
  284. package/dist/holmes/spec/spec-store.js +4 -2
  285. package/dist/holmes/spec/spec-types.js +1 -1
  286. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  287. package/dist/holmes/spec/succession-guard.js +187 -0
  288. package/dist/holmes/spec/succession.d.ts +70 -0
  289. package/dist/holmes/spec/succession.js +171 -0
  290. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  291. package/docs/install-guide.md +9 -3
  292. package/docs/language-support.md +78 -0
  293. package/package.json +4 -3
  294. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  295. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  296. package/playbooks/publish/PLAYBOOK.md +45 -33
  297. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  298. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -42,7 +42,7 @@ exports.everSealedInLedger = everSealedInLedger;
42
42
  exports.validateTriageArtifact = validateTriageArtifact;
43
43
  exports.intakeHead = intakeHead;
44
44
  exports.validateRequirementIntake = validateRequirementIntake;
45
- // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734, A-SPEC-719.6
45
+ // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734, A-SPEC-719.6, A-SPEC-245.9, A-SPEC-222.10, A-SPEC-794.4
46
46
  // @implements A-SPEC-713
47
47
  /** Content-addressed, isolated persistence for advisory requirement triage results. */
48
48
  const crypto = __importStar(require("node:crypto"));
@@ -50,7 +50,9 @@ const fs = __importStar(require("node:fs"));
50
50
  const path = __importStar(require("node:path"));
51
51
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
52
52
  const ledger_store_1 = require("../governance/ledger-store");
53
+ const recorded_pairs_1 = require("../governance/recorded-pairs");
53
54
  const provenance_chain_1 = require("../governance/provenance-chain");
55
+ const spend_kinds_1 = require("../governance/spend-kinds");
54
56
  const ledger_lock_1 = require("../governance/ledger-lock");
55
57
  const display_id_aliases_1 = require("../governance/display-id-aliases");
56
58
  const bounded_io_1 = require("../project/bounded-io");
@@ -124,17 +126,19 @@ function issueRequirementTriageEvidence(root, artifact) {
124
126
  * unobtainable lock is a refusal, never a silent pass.
125
127
  */
126
128
  function consumeRequirementTriageEvidence(root, digest, reqId) {
127
- const ledgerFile = (0, ledger_store_1.writerChainFile)(ledgerDirOf(root));
128
129
  const key = spendKeyOf(digest);
129
130
  try {
130
- const won = (0, provenance_chain_1.consumeNonceExclusively)(key, ledgerFile, {
131
- ts: new Date().toISOString(), actor: 'holmes-kit', kind: 'nonce-consumed',
132
- summary: `requirement triage evidence spent on ${reqId}`, inputs: [(0, provenance_chain_1.nonceFingerprint)(key)],
133
- }, { isNonceConsumed: (0, ledger_store_1.nonceConsumedIn)(ledgerFile) });
134
- return won ? { ok: true } : { ok: false, reason: SPENT };
131
+ // @implements A-SPEC-245.9 (1b-1) — spent under the workspace spend lock, across every replica chain
132
+ const { spendApprovals } = require('../governance/approval-spend');
133
+ const r = spendApprovals(root, [{ nonce: key, actor: 'holmes-kit', summary: `requirement triage evidence spent on ${reqId}`, rationale: reqId }], {});
134
+ if (r.ok)
135
+ return { ok: true };
136
+ return { ok: false, reason: r.reason === 'spent' ? SPENT
137
+ : r.reason === 'revoked' ? '새 REQ triage evidence was revoked — it admits nothing; re-run requirement_triage.' // A-SPEC-245.16
138
+ : `새 REQ triage evidence could not be confirmed as spent once (${r.reason}: a spend-conflict-detected row names it) — re-run requirement_triage.` };
135
139
  }
136
140
  catch (e) {
137
- const busy = e instanceof ledger_lock_1.LedgerLockError;
141
+ const busy = e instanceof ledger_lock_1.LedgerLockError || e?.code === 'lock-busy';
138
142
  return { ok: false, reason: busy
139
143
  ? `새 REQ triage evidence could not be spent (ledger busy: ${e.message}) — 다시 시도하십시오.`
140
144
  : `새 REQ triage evidence could not be spent (${e instanceof Error ? e.message : String(e)}) — the ledger could not record it; check it with holmes-kit doctor.` };
@@ -149,10 +153,10 @@ function hasRequirementIntakeRecord(root, reqId, digest) {
149
153
  if (typeof digest !== 'string' || !DIGEST.test(digest))
150
154
  return false;
151
155
  try {
152
- const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
156
+ const store = new recorded_pairs_1.TrustedLedgerStore(ledgerDirOf(root)); // A-SPEC-222.10 H-C: a proof, from trusted events
153
157
  const broken = new Set(store.verifyAll().broken.map((b) => b.replicaId));
154
158
  const fp = (0, provenance_chain_1.nonceFingerprint)(spendKeyOf(digest));
155
- return store.loadAll().some((e) => e.kind === 'nonce-consumed' && !broken.has(e.replicaId)
159
+ return store.loadAll().some((e) => e.kind === (0, spend_kinds_1.spendKind)('grant') && !broken.has(e.replicaId)
156
160
  && (e.inputs ?? []).includes(fp) && e.summary === `requirement triage evidence spent on ${reqId}`);
157
161
  }
158
162
  catch {
@@ -165,7 +169,7 @@ function hasRequirementIntakeRecord(root, reqId, digest) {
165
169
  */
166
170
  function everSealedInLedger(root, specId) {
167
171
  try {
168
- const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
172
+ const store = new recorded_pairs_1.TrustedLedgerStore(ledgerDirOf(root)); // A-SPEC-222.10 H-C: a proof, from trusted events
169
173
  const broken = new Set(store.verifyAll().broken.map((b) => b.replicaId));
170
174
  // @implements A-SPEC-729 (round 7) — the mark follows RECORDED renames, in ledger order: a sealed
171
175
  // REQ renumbered away freed its id, and an untriaged REQ renumbered onto it read as "sealed
@@ -279,12 +283,17 @@ function validateRequirementIntake(root, triageEvidence) {
279
283
  // must not have been spent on another REQ yet (the spend itself happens at the write).
280
284
  // Only a chain that VERIFIES counts (round 1: a planted `provenance.<x>.jsonl` minted issuance). With
281
285
  // HOLMES_LEDGER_KEY set, verification checks signatures, so a forged chain cannot pass.
286
+ // A-SPEC-222.10 H-C: issuance is a proof, so it is accepted only from trusted events; the raw rows only say where an
287
+ // untrusted record sits, so the refusal can name the repair (round 2 below)
282
288
  const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
283
289
  let issuedOn = [];
290
+ let trustedOn = new Set();
284
291
  let broken = new Map();
285
292
  let own = null;
286
293
  try {
287
- issuedOn = store.loadAll().filter((e) => e.kind === 'triage-issued' && (e.inputs ?? []).includes(evidence.digest)).map((e) => e.replicaId);
294
+ const issued = (e) => e.kind === 'triage-issued' && (e.inputs ?? []).includes(evidence.digest);
295
+ issuedOn = store.loadAll().filter(issued).map((e) => e.replicaId);
296
+ trustedOn = new Set(new recorded_pairs_1.TrustedLedgerStore(ledgerDirOf(root)).loadAll().filter(issued).map((e) => e.replicaId));
288
297
  broken = new Map(store.verifyAll().broken.map((b) => [b.replicaId, b.detail]));
289
298
  }
290
299
  catch (e) {
@@ -299,7 +308,7 @@ function validateRequirementIntake(root, triageEvidence) {
299
308
  catch {
300
309
  own = null;
301
310
  }
302
- const verified = issuedOn.filter((r) => !broken.has(r));
311
+ const verified = issuedOn.filter((r) => !broken.has(r) && trustedOn.has(r));
303
312
  if (verified.length === 0) {
304
313
  // Round 2: when the broken chain is this writer's OWN, re-triage would land on the same chain —
305
314
  // the only recovery is repairing the ledger, so the refusal says that instead.
@@ -43,7 +43,7 @@ exports.readMcpHeartbeats = readMcpHeartbeats;
43
43
  /**
44
44
  * Whether the install a running MCP server was loaded from has changed under it, and the server's heartbeat.
45
45
  *
46
- * Measured 2026-10-23 (D1): the jarvis session's holmes-kit MCP served v0.36.0 while the global install its `.mcp.json`
46
+ * Measured 2026-10-23 (D1): a consumer workspace session's holmes-kit MCP served v0.36.0 while the global install its `.mcp.json`
47
47
  * names was 0.38.0 — the process had started before the install was upgraded in place — so `approval_ask`,
48
48
  * `review_verdict` and `phase_check` were missing and nothing said so. A-SPEC-251.2 compares the WIRING with the CLI
49
49
  * (they matched); A-SPEC-156's basis compares the loaded build with the WORKSPACE's dist (a consumer has none).
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.HOOK_ENFORCED_TOOLS = void 0;
4
- // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1, A-SPEC-732, A-SPEC-734, A-SPEC-751.3, A-SPEC-251.4, A-SPEC-779.7
4
+ // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1, A-SPEC-732, A-SPEC-734, A-SPEC-751.3, A-SPEC-251.4, A-SPEC-779.7, A-SPEC-732.4
5
5
  const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
6
6
  const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
7
7
  const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
@@ -51,15 +51,15 @@ const elicit = async (req) => {
51
51
  }
52
52
  };
53
53
  // @implements A-SPEC-732 (round 2) — who launched this server, asked once, on first need.
54
- const { attestHarness, systemProcLookup, dispatcherVerifier } = require('./harness-attestation');
55
54
  // @implements A-SPEC-751.3 — the operator runtime registry's dispatcher is a launcher (it sits between the harness and
56
- // this server on a registered machine); the path is the registry's fixed default, never taken from the request.
57
- const runtimeRegistryPath = require('node:path').join(require('node:os').homedir(), '.holmes', 'runtime', 'bindings.json');
55
+ // this server on a registered machine); its path is the registry's fixed default under this home.
56
+ // @implements A-SPEC-732.4 — built in one entry (serverAttestation), which the tests reach with their own home and env
57
+ const { serverAttestation } = require('./harness-attestation');
58
58
  let attested;
59
59
  const harnessAttestation = () => {
60
60
  if (attested === undefined) {
61
61
  try {
62
- attested = attestHarness(process.ppid, systemProcLookup(), 8, dispatcherVerifier(runtimeRegistryPath));
62
+ attested = serverAttestation(process.ppid, { env: process.env, home: require('node:os').homedir() });
63
63
  }
64
64
  catch {
65
65
  attested = { attested: false, chain: [], reason: 'the process table could not be read' };
@@ -171,8 +171,8 @@ const fullProfile = process.env.HOLMES_MCP_PROFILE === 'full';
171
171
  // clients can marshal complex (array/object) arguments; fall back to a
172
172
  // permissive stub only if a handler somehow lacks a schema (tool-schemas.test.ts
173
173
  // pins full 1:1 coverage, so the fallback should never fire in practice).
174
- const TOOLS = Object.keys(handlers)
175
- .filter((name) => fullProfile || !tool_schemas_1.HOOK_ENFORCED_TOOLS.has(name))
174
+ const wire = (0, tool_schemas_1.wireDispatch)(handlers, fullProfile); // @implements A-SPEC-792.25, A-SPEC-792.26
175
+ const TOOLS = wire.names
176
176
  .map((name) => {
177
177
  const def = tool_schemas_1.TOOL_SCHEMAS[name];
178
178
  return def
@@ -191,7 +191,8 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
191
191
  // the prototype chain to a truthy non-handler and crash the new validation path (round-2 probe) —
192
192
  // pre-enforcement it silently "succeeded" by invoking Object. Both are wrong; unknown tool is true.
193
193
  const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined;
194
- const fn = own(handlers, req.params.name);
194
+ // @implements A-SPEC-792.25 — the same set ListTools serves: a hidden tool is an unknown tool on the wire
195
+ const fn = wire.handlerFor(req.params.name);
195
196
  const def = own(tool_schemas_1.TOOL_SCHEMAS, req.params.name);
196
197
  const args = req.params.arguments ?? {};
197
198
  const check = fn && def ? (0, validate_args_1.validateArgs)(req.params.name, def.inputSchema, args) : { ok: true };
@@ -27,7 +27,7 @@ const spec_id_2 = require("../spec/spec-id");
27
27
  * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
28
28
  */
29
29
  /** The id's number SPACE. @implements A-SPEC-571.1 — ADR keeps its own sequence so a decision
30
- * (jarvis's ADR-0001) neither blocks nor is blocked by the functional chain's max. Everything
30
+ * (a consumer workspace's ADR-0001) neither blocks nor is blocked by the functional chain's max. Everything
31
31
  * else shares one space, exactly as before. */
32
32
  function idSpaceOf(id) {
33
33
  return /^ADR-/.test(id.trim()) ? 'ADR' : 'functional';
@@ -17,4 +17,17 @@ export interface ToolSchema {
17
17
  };
18
18
  }
19
19
  export declare const HOOK_ENFORCED_TOOLS: Set<string>;
20
+ /**
21
+ * @implements A-SPEC-792.25 — the one set the wire serves: ListTools advertises it and CallTool dispatches it, so a
22
+ * hidden tool is an unknown tool on the wire (risk_check answered there while ListTools hid it, F1-e.0d).
23
+ */
24
+ export declare function isWireTool(name: string, fullProfile: boolean): boolean;
25
+ /**
26
+ * @implements A-SPEC-792.26 — the wire's one tool set: ListTools serves `names` and CallTool resolves through
27
+ * `handlerFor`, an exact own-property match within that set, so a hidden tool or a respelling of one is unknown to both.
28
+ */
29
+ export declare function wireDispatch<T>(handlers: Record<string, T>, fullProfile: boolean): {
30
+ names: string[];
31
+ handlerFor(name: string): T | undefined;
32
+ };
20
33
  export declare const TOOL_SCHEMAS: Record<string, ToolSchema>;
@@ -1,6 +1,8 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
4
+ exports.isWireTool = isWireTool;
5
+ exports.wireDispatch = wireDispatch;
4
6
  // @implements A-SPEC-743, A-SPEC-736, A-SPEC-735, A-SPEC-729, A-SPEC-719, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713, A-SPEC-774.25, A-SPEC-255.1
5
7
  // @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
6
8
  // consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
@@ -37,6 +39,22 @@ const ROOT_ANY = str('Absolute path to the project root. Version control is opti
37
39
  // at module scope, so anything importing it for this constant attaches to stdio. This module holds
38
40
  // the rest of the tool metadata and has no import side effects.
39
41
  exports.HOOK_ENFORCED_TOOLS = new Set(['phase_check', 'risk_check', 'rtm_check', 'spec_validate']);
42
+ /**
43
+ * @implements A-SPEC-792.25 — the one set the wire serves: ListTools advertises it and CallTool dispatches it, so a
44
+ * hidden tool is an unknown tool on the wire (risk_check answered there while ListTools hid it, F1-e.0d).
45
+ */
46
+ function isWireTool(name, fullProfile) {
47
+ return fullProfile || !exports.HOOK_ENFORCED_TOOLS.has(name);
48
+ }
49
+ /**
50
+ * @implements A-SPEC-792.26 — the wire's one tool set: ListTools serves `names` and CallTool resolves through
51
+ * `handlerFor`, an exact own-property match within that set, so a hidden tool or a respelling of one is unknown to both.
52
+ */
53
+ function wireDispatch(handlers, fullProfile) {
54
+ const names = Object.keys(handlers).filter((name) => isWireTool(name, fullProfile));
55
+ const set = new Set(names);
56
+ return { names, handlerFor: (name) => (set.has(name) && Object.prototype.hasOwnProperty.call(handlers, name) ? handlers[name] : undefined) };
57
+ }
40
58
  exports.TOOL_SCHEMAS = {
41
59
  approval_commit: {
42
60
  description: 'Complete a server-issued, one-use in-session approval continuation. This sensitive annotation asks the host to show its native tool confirmation; the server records arrival only as a host-gated continuation, never proof of a human response. Send the unmodified approvalIntent returned by the original refused action, then retry that original action. The server verifies challenge, kind, target, subject digest, workspace, session run and expiry; this tool never reads HOLMES_APPROVAL or writes configuration.',
@@ -170,6 +188,15 @@ exports.TOOL_SCHEMAS = {
170
188
  properties: {
171
189
  id: str('Id of the spec to retire.'),
172
190
  reason: str('Why it is being retired. Omitted from the document when blank; not required when the spec already carries superseded_by.'),
191
+ // @implements A-SPEC-222.4
192
+ supersededBy: str('On an ALREADY-outdated spec with no superseded_by: record this approved spec of the same kind as its successor (records spec-superseded), so an anchor can move to it. Refused, writing nothing, for a draft, another kind, or a spec that already names a different successor.'),
193
+ // @implements A-SPEC-222.5
194
+ directive: str('With supersededBy on a SEALED spec under an active full autonomy profile: the supervisor directive this retirement follows (a section title or message id). It is recorded; when every machine condition holds (sealed same-kind successor; an A-SPEC anchored nowhere or a T-SPEC whose successor is tested; no approved dependent outside the chain; not graded for a person; the successor covers what it covered) the spec is retired without an approval. Otherwise the refusal is today\'s, with autonomousRefused naming the failed condition.'),
195
+ also: {
196
+ type: 'array',
197
+ description: 'Further { id, supersededBy } pairs retired in the same autonomous act (a chain, e.g. the T-SPEC over the retired A-SPEC).',
198
+ items: { type: 'object', properties: { id: str('Id of the spec to retire.'), supersededBy: str('Its sealed successor.') }, required: ['id', 'supersededBy'] },
199
+ },
173
200
  root: str('Optional when the server is bound to a file store — the ledger location is derived from the store itself; if supplied it must resolve to the SAME project.'),
174
201
  },
175
202
  required: ['id'],
@@ -225,7 +252,7 @@ exports.TOOL_SCHEMAS = {
225
252
  },
226
253
  // @implements A-SPEC-718.4
227
254
  approval_ask: {
228
- description: "Ask the person to decide ONE pending approval request in this session's approval form — the id a refusal named (`[승인 대기 req-…]`), from the approval inbox or this machine's refusal log. The person chooses approve / deny / question; the answer is recorded exactly as the operator's grant, deny or question is recorded (actor `elicitation:<client>`), so after `granted` retry the refused act once. Returns { ok, id, kind, decision: granted|denied|held|undecided, nextAction }. Nothing is recorded without the person's answer: silence leaves the request pending. A request a run awaits is asked here too, from the interactive session (the run resumes on the grant). Refuses, recording nothing, from a run's own server, when the session cannot show a form (HOLMES_ELICIT=off, a server no harness launched, a client without forms), and for a shell/config/code-write request on a client not yet measured to wait for a person (only claude-code today).",
255
+ description: "Ask the person to decide ONE pending approval request in this session's approval form — the id a refusal named (`[승인 대기 req-…]`), from the approval inbox or this machine's refusal log. The person chooses approve / deny / question; the answer is recorded exactly as the operator's grant, deny or question is recorded (under the session's elicitation channel actor), so after `granted` retry the refused act once. Returns { ok, id, kind, decision: granted|denied|held|undecided, nextAction }. Nothing is recorded without the person's answer: silence leaves the request pending. A request a run awaits is asked here too, from the interactive session (the run resumes on the grant). Refuses, recording nothing, from a run's own server, when the session cannot show a form (HOLMES_ELICIT=off, a server no harness launched, a client without forms), and for a shell/config/code-write request on a client not yet measured to wait for a person (only claude-code today).",
229
256
  inputSchema: {
230
257
  type: 'object',
231
258
  properties: {
@@ -250,7 +277,7 @@ exports.TOOL_SCHEMAS = {
250
277
  },
251
278
  // @implements A-SPEC-102.9
252
279
  review_verdict: {
253
- description: "Ask the person for an independent review verdict on base..head in this session's approval form. approve records pass, deny records fail with the person's reason as the finding; the verdict is recorded as the person's (reviewer.person true, channel elicitation:<client>, independent true), so it satisfies the review gate without a separate terminal. Returns { ok, decision: pass|fail|undecided, independent? }. Silence, a question and an automatic decline record nothing. Refuses, recording nothing, inside a run, when the session cannot show a form, and on a client not yet measured to wait for a person (only claude-code today).",
280
+ description: "Ask the person for an independent review verdict on base..head in this session's approval form. approve records pass, deny records fail with the person's reason as the finding; the verdict is recorded as the person's (reviewer.person true, the elicitation channel, independent true), so it satisfies the review gate without a separate terminal. Returns { ok, decision: pass|fail|undecided, independent? }. Silence, a question and an automatic decline record nothing. Refuses, recording nothing, inside a run, when the session cannot show a form, and on a client not yet measured to wait for a person (only claude-code today).",
254
281
  inputSchema: {
255
282
  type: 'object',
256
283
  properties: {
@@ -0,0 +1,19 @@
1
+ /** `--target` when given, else `cwd`; the `.ax` project it belongs to, or the path itself when it belongs to none.
2
+ * @implements A-SPEC-102.31 (W7) — a `--target` that does not exist is returned resolved, never thrown: the act reports
3
+ * it as before, and the catalog of a root that cannot be resolved refuses the guarded acts. */
4
+ export declare function actRoot(flags: Record<string, string | boolean | undefined>, cwd?: string): string;
5
+ /** The search for projects under an autonomy scope: its depth and the directories it may read. */
6
+ export declare const SCOPE_SEARCH_LIMITS: {
7
+ readonly maxDepth: 16;
8
+ readonly maxDirs: 10000;
9
+ };
10
+ /**
11
+ * Every `.ax` project under `scope` (the scope's own included). autonomy full covers the whole subtree, so each project
12
+ * there is judged by its additions (A-SPEC-102.30, medium 2). Links are not followed, and `.git`, `node_modules` and
13
+ * `.ax` are not entered. A search past either limit, or a directory it cannot read, throws: the union could not be
14
+ * known, and the act is refused.
15
+ */
16
+ export declare function projectsUnder(scope: string, limits?: {
17
+ maxDepth: number;
18
+ maxDirs: number;
19
+ }): string[];
@@ -0,0 +1,100 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.SCOPE_SEARCH_LIMITS = void 0;
37
+ exports.actRoot = actRoot;
38
+ exports.projectsUnder = projectsUnder;
39
+ // @implements A-SPEC-102.30, A-SPEC-102.31
40
+ /**
41
+ * The project an operator act works on, decided once. approve and lock recover act on the working directory when no
42
+ * `--target` is given (their usage says so); the guard was handed no root there, so `approve --grant` from inside a
43
+ * project judged without the project's additions while the queue it wrote was that project's (A and B, reproduced).
44
+ * The queue and the guard now take this one value.
45
+ */
46
+ const fs = __importStar(require("node:fs"));
47
+ const path = __importStar(require("node:path"));
48
+ const root_1 = require("./root");
49
+ /** `--target` when given, else `cwd`; the `.ax` project it belongs to, or the path itself when it belongs to none.
50
+ * @implements A-SPEC-102.31 (W7) — a `--target` that does not exist is returned resolved, never thrown: the act reports
51
+ * it as before, and the catalog of a root that cannot be resolved refuses the guarded acts. */
52
+ function actRoot(flags, cwd = process.cwd()) {
53
+ const dir = path.resolve(cwd, typeof flags.target === 'string' ? flags.target : '.');
54
+ try {
55
+ return (0, root_1.resolveProjectRoot)(dir, { includeGit: false }).root; // the `.ax` project, or the path itself, canonical
56
+ }
57
+ catch {
58
+ return dir;
59
+ }
60
+ }
61
+ /** The search for projects under an autonomy scope: its depth and the directories it may read. */
62
+ exports.SCOPE_SEARCH_LIMITS = { maxDepth: 16, maxDirs: 10_000 };
63
+ const NOT_ENTERED = new Set(['.git', 'node_modules', '.ax']);
64
+ /**
65
+ * Every `.ax` project under `scope` (the scope's own included). autonomy full covers the whole subtree, so each project
66
+ * there is judged by its additions (A-SPEC-102.30, medium 2). Links are not followed, and `.git`, `node_modules` and
67
+ * `.ax` are not entered. A search past either limit, or a directory it cannot read, throws: the union could not be
68
+ * known, and the act is refused.
69
+ */
70
+ function projectsUnder(scope, limits = exports.SCOPE_SEARCH_LIMITS) {
71
+ const found = [];
72
+ let read = 0;
73
+ const stack = [[path.resolve(scope), 0]];
74
+ while (stack.length > 0) {
75
+ const [dir, depth] = stack.pop();
76
+ if (++read > limits.maxDirs)
77
+ throw new Error(`more than ${limits.maxDirs} directories under ${scope}`);
78
+ let entries;
79
+ try {
80
+ entries = fs.readdirSync(dir, { withFileTypes: true });
81
+ }
82
+ catch (e) {
83
+ throw new Error(`${dir} cannot be read (${e.code ?? 'error'})`);
84
+ }
85
+ // @implements A-SPEC-102.31 — resolveProjectRoot's rule (a `.ax` directory, a link to one, the file system's case
86
+ // rule); the name compare missed `.AX` and a linked `.ax`. The search itself follows no link and enters no `.ax`
87
+ if ((0, root_1.isProjectDir)(dir))
88
+ found.push(dir);
89
+ for (const e of entries) {
90
+ if (!e.isDirectory())
91
+ continue;
92
+ if (NOT_ENTERED.has(e.name.toLowerCase()))
93
+ continue;
94
+ if (depth + 1 > limits.maxDepth)
95
+ throw new Error(`a search depth of ${limits.maxDepth} is passed under ${scope}`);
96
+ stack.push([path.join(dir, e.name), depth + 1]);
97
+ }
98
+ }
99
+ return found;
100
+ }
@@ -40,7 +40,7 @@ exports.isBaselineTrusted = isBaselineTrusted;
40
40
  exports.readBaseline = readBaseline;
41
41
  exports.shouldRecordBaseline = shouldRecordBaseline;
42
42
  exports.listBaselines = listBaselines;
43
- // @implements A-SPEC-128
43
+ // @implements A-SPEC-128, A-SPEC-222.10
44
44
  const fs = __importStar(require("node:fs"));
45
45
  const path = __importStar(require("node:path"));
46
46
  const node_crypto_1 = require("node:crypto");
@@ -129,8 +129,9 @@ function isBaselineTrusted(root, label, ledgerFile) {
129
129
  // so scanning only the legacy file would fail to find an anchor this very process just wrote.
130
130
  let events;
131
131
  try {
132
- const { FileLedgerStore } = require('../governance/ledger-store');
133
- events = new FileLedgerStore(path.dirname(ledgerFile)).loadAll();
132
+ // @implements A-SPEC-222.10 — H-C: a trusted anchor only (it narrows the test scope)
133
+ const { TrustedLedgerStore } = require('../governance/recorded-pairs');
134
+ events = new TrustedLedgerStore(path.dirname(ledgerFile)).loadAll();
134
135
  }
135
136
  catch {
136
137
  return false;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * A bounded child that outlives no one. On POSIX the child is a small watch shim, spawned detached so it leads a new
3
+ * process group, and the shim runs the real command inside that group:
4
+ * - when the shim's parent goes (the caller was signalled, or died otherwise), the shim ends its whole group: a
5
+ * detached group no longer receives the caller's group signals, and no JavaScript handler runs while spawnSync waits;
6
+ * - when the shim itself is signalled, it ends its group the same way;
7
+ * - when the command exits, the shim exits the same way (its code, or its signal raised on itself).
8
+ * After the call returns, the caller ends the group on the bound, a buffer overflow or a signal, and after a normal exit
9
+ * only when a probe finds members left (they are ended and reported).
10
+ *
11
+ * The group id is the pid of the child this call spawned; ending it right after the call returns makes hitting another
12
+ * process unlikely, not impossible. A grandchild that leaves the group with setsid escapes (a named limit). Windows has
13
+ * no groups: the child alone is stopped there, as before. Node's own modules only, so a test can run it as built.
14
+ */
15
+ import { type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from 'node:child_process';
16
+ /** @implements A-SPEC-734.6 — how long the shim keeps relaying after its runner exits (late output a worker writes). */
17
+ export declare const SHIM_DRAIN_MS = 300;
18
+ /** @implements A-SPEC-734.6 — how often the shim compares its parent with the caller after the first line. */
19
+ export declare const SHIM_WATCH_MS = 100;
20
+ /**
21
+ * The shim's program (`node -e SHIM -- HEAD cmd ...args`, HEAD the JSON `{caller, nodeOptions, drainMs, watchMs}`). A spawn error's code is
22
+ * written to descriptor 3 and the shim exits 127.
23
+ * @implements A-SPEC-734.5 — the parent is compared with the caller's pid from the first line (a caller that died while
24
+ * the shim started left it re-parented and the runner unbounded); the runner's output is relayed through the shim's pipes
25
+ * with a short drain at its exit (a worker holding the inherited pipes kept the call until the bound); the shim runs
26
+ * without the caller's NODE_OPTIONS and hands it to the runner.
27
+ */
28
+ export declare const SHIM = "const { spawn } = require('child_process');\nconst fs = require('fs');\nconst [head, cmd, ...args] = process.argv.slice(1);\nconst { caller, nodeOptions, drainMs, watchMs } = JSON.parse(head);\nconst end = () => { try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(137); } };\nif (process.ppid !== caller) end();\nconst sigs = ['SIGINT', 'SIGTERM', 'SIGHUP'];\nfor (const s of sigs) process.on(s, end);\nconst watch = setInterval(() => { if (process.ppid !== caller) end(); }, watchMs);\nconst env = { ...process.env };\nif (nodeOptions === null) delete env.NODE_OPTIONS; else env.NODE_OPTIONS = nodeOptions;\nconst c = spawn(cmd, args, { stdio: ['inherit', 'pipe', 'pipe'], env });\nc.stdout.pipe(process.stdout, { end: false });\nc.stderr.pipe(process.stderr, { end: false });\nc.on('error', (e) => {\n clearInterval(watch);\n try { fs.writeSync(3, String((e && e.code) || 'ERROR')); } catch {}\n process.stderr.write(String(e && e.message) + '\\n');\n process.exit(127);\n});\nlet open = 2, exited = null, finished = false;\nconst finish = () => {\n if (finished || exited === null || open > 0) return;\n finished = true;\n c.stdout.unpipe(); c.stderr.unpipe();\n let n = 2;\n const go = () => {\n if (--n > 0) return;\n const [code, sig] = exited;\n if (sig) { for (const s of sigs) process.removeAllListeners(s); process.kill(process.pid, sig); setTimeout(() => process.exit(128), 1000); }\n else process.exit(code === null ? 1 : code);\n };\n process.stdout.write('', go);\n process.stderr.write('', go);\n};\nc.stdout.on('end', () => { open--; finish(); });\nc.stderr.on('end', () => { open--; finish(); });\nc.on('exit', (code, sig) => {\n clearInterval(watch);\n exited = [code, sig];\n // a worker still holding the runner's pipes does not hold the call: a short drain, then out\n setTimeout(() => { open = 0; finish(); }, drainMs);\n finish();\n});\n";
29
+ export interface BoundedGroupResult {
30
+ result: SpawnSyncReturns<string>;
31
+ stopped: boolean;
32
+ leftovers: boolean;
33
+ }
34
+ export interface BoundedGroupDeps {
35
+ kill?: (pid: number, sig: NodeJS.Signals | 0) => void;
36
+ callerPid?: number;
37
+ /** @implements A-SPEC-734.7 — the shim's timing, through its head (DIP); defaults SHIM_DRAIN_MS and SHIM_WATCH_MS. */
38
+ drainMs?: number;
39
+ watchMs?: number;
40
+ }
41
+ /** @implements A-SPEC-734.7 — the shim's head, without the caller's NODE_OPTIONS (added by the caller). */
42
+ export declare function shimHead(deps: BoundedGroupDeps): {
43
+ caller: number;
44
+ drainMs: number;
45
+ watchMs: number;
46
+ };
47
+ export declare function boundedGroupSpawnSync(cmd: string, args: string[], opts: SpawnSyncOptionsWithStringEncoding, timeoutMs: number, deps?: BoundedGroupDeps): BoundedGroupResult;
@@ -0,0 +1,140 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SHIM = exports.SHIM_WATCH_MS = exports.SHIM_DRAIN_MS = void 0;
4
+ exports.shimHead = shimHead;
5
+ exports.boundedGroupSpawnSync = boundedGroupSpawnSync;
6
+ // @implements A-SPEC-734.4, A-SPEC-734.5, A-SPEC-734.6, A-SPEC-734.7
7
+ /**
8
+ * A bounded child that outlives no one. On POSIX the child is a small watch shim, spawned detached so it leads a new
9
+ * process group, and the shim runs the real command inside that group:
10
+ * - when the shim's parent goes (the caller was signalled, or died otherwise), the shim ends its whole group: a
11
+ * detached group no longer receives the caller's group signals, and no JavaScript handler runs while spawnSync waits;
12
+ * - when the shim itself is signalled, it ends its group the same way;
13
+ * - when the command exits, the shim exits the same way (its code, or its signal raised on itself).
14
+ * After the call returns, the caller ends the group on the bound, a buffer overflow or a signal, and after a normal exit
15
+ * only when a probe finds members left (they are ended and reported).
16
+ *
17
+ * The group id is the pid of the child this call spawned; ending it right after the call returns makes hitting another
18
+ * process unlikely, not impossible. A grandchild that leaves the group with setsid escapes (a named limit). Windows has
19
+ * no groups: the child alone is stopped there, as before. Node's own modules only, so a test can run it as built.
20
+ */
21
+ const node_child_process_1 = require("node:child_process");
22
+ /** @implements A-SPEC-734.6 — how long the shim keeps relaying after its runner exits (late output a worker writes). */
23
+ exports.SHIM_DRAIN_MS = 300;
24
+ /** @implements A-SPEC-734.6 — how often the shim compares its parent with the caller after the first line. */
25
+ exports.SHIM_WATCH_MS = 100;
26
+ /**
27
+ * The shim's program (`node -e SHIM -- HEAD cmd ...args`, HEAD the JSON `{caller, nodeOptions, drainMs, watchMs}`). A spawn error's code is
28
+ * written to descriptor 3 and the shim exits 127.
29
+ * @implements A-SPEC-734.5 — the parent is compared with the caller's pid from the first line (a caller that died while
30
+ * the shim started left it re-parented and the runner unbounded); the runner's output is relayed through the shim's pipes
31
+ * with a short drain at its exit (a worker holding the inherited pipes kept the call until the bound); the shim runs
32
+ * without the caller's NODE_OPTIONS and hands it to the runner.
33
+ */
34
+ exports.SHIM = `const { spawn } = require('child_process');
35
+ const fs = require('fs');
36
+ const [head, cmd, ...args] = process.argv.slice(1);
37
+ const { caller, nodeOptions, drainMs, watchMs } = JSON.parse(head);
38
+ const end = () => { try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(137); } };
39
+ if (process.ppid !== caller) end();
40
+ const sigs = ['SIGINT', 'SIGTERM', 'SIGHUP'];
41
+ for (const s of sigs) process.on(s, end);
42
+ const watch = setInterval(() => { if (process.ppid !== caller) end(); }, watchMs);
43
+ const env = { ...process.env };
44
+ if (nodeOptions === null) delete env.NODE_OPTIONS; else env.NODE_OPTIONS = nodeOptions;
45
+ const c = spawn(cmd, args, { stdio: ['inherit', 'pipe', 'pipe'], env });
46
+ c.stdout.pipe(process.stdout, { end: false });
47
+ c.stderr.pipe(process.stderr, { end: false });
48
+ c.on('error', (e) => {
49
+ clearInterval(watch);
50
+ try { fs.writeSync(3, String((e && e.code) || 'ERROR')); } catch {}
51
+ process.stderr.write(String(e && e.message) + '\\n');
52
+ process.exit(127);
53
+ });
54
+ let open = 2, exited = null, finished = false;
55
+ const finish = () => {
56
+ if (finished || exited === null || open > 0) return;
57
+ finished = true;
58
+ c.stdout.unpipe(); c.stderr.unpipe();
59
+ let n = 2;
60
+ const go = () => {
61
+ if (--n > 0) return;
62
+ const [code, sig] = exited;
63
+ if (sig) { for (const s of sigs) process.removeAllListeners(s); process.kill(process.pid, sig); setTimeout(() => process.exit(128), 1000); }
64
+ else process.exit(code === null ? 1 : code);
65
+ };
66
+ process.stdout.write('', go);
67
+ process.stderr.write('', go);
68
+ };
69
+ c.stdout.on('end', () => { open--; finish(); });
70
+ c.stderr.on('end', () => { open--; finish(); });
71
+ c.on('exit', (code, sig) => {
72
+ clearInterval(watch);
73
+ exited = [code, sig];
74
+ // a worker still holding the runner's pipes does not hold the call: a short drain, then out
75
+ setTimeout(() => { open = 0; finish(); }, drainMs);
76
+ finish();
77
+ });
78
+ `;
79
+ /** @implements A-SPEC-734.7 — the shim's head, without the caller's NODE_OPTIONS (added by the caller). */
80
+ function shimHead(deps) {
81
+ return { caller: deps.callerPid ?? process.pid, drainMs: deps.drainMs ?? exports.SHIM_DRAIN_MS, watchMs: deps.watchMs ?? exports.SHIM_WATCH_MS };
82
+ }
83
+ function boundedGroupSpawnSync(cmd, args, opts, timeoutMs, deps = {}) {
84
+ const kill = deps.kill ?? ((pid, sig) => { process.kill(pid, sig); });
85
+ if (process.platform === 'win32') {
86
+ const result = (0, node_child_process_1.spawnSync)(cmd, args, { ...opts, timeout: timeoutMs, killSignal: 'SIGKILL' });
87
+ return { result, stopped: result.error?.code === 'ETIMEDOUT', leftovers: false };
88
+ }
89
+ // `detached` is honoured by spawnSync (libuv's setsid) though its option type leaves it out
90
+ // A-SPEC-734.5: the caller's NODE_OPTIONS goes to the runner, not to the shim; descriptor 3 carries a spawn error's code
91
+ const env = { ...(opts.env ?? process.env) };
92
+ const nodeOptions = env.NODE_OPTIONS ?? null;
93
+ delete env.NODE_OPTIONS;
94
+ const given = opts.stdio;
95
+ const stdio = Array.isArray(given) ? [...given] : [given ?? 'pipe', given ?? 'pipe', given ?? 'pipe'];
96
+ while (stdio.length < 3)
97
+ stdio.push('pipe');
98
+ stdio.length = 3;
99
+ stdio.push('pipe');
100
+ const groupOpts = { ...opts, env, stdio, timeout: timeoutMs, killSignal: 'SIGKILL', detached: true };
101
+ const head = JSON.stringify({ ...shimHead(deps), nodeOptions });
102
+ const result = (0, node_child_process_1.spawnSync)(process.execPath, ['-e', exports.SHIM, '--', head, cmd, ...args], groupOpts);
103
+ const errno = String(result.output?.[3] ?? '').trim();
104
+ if (result.output)
105
+ result.output = result.output.slice(0, 3);
106
+ const code = result.error?.code;
107
+ const stopped = code === 'ETIMEDOUT';
108
+ let leftovers = false;
109
+ const pid = result.pid;
110
+ if (pid) {
111
+ if (result.error || result.signal !== null) {
112
+ try {
113
+ kill(-pid, 'SIGKILL');
114
+ }
115
+ catch { /* the group already ended */ }
116
+ }
117
+ else {
118
+ let members = false;
119
+ try {
120
+ kill(-pid, 0);
121
+ members = true;
122
+ }
123
+ catch {
124
+ members = false;
125
+ }
126
+ if (members) {
127
+ leftovers = true;
128
+ try {
129
+ kill(-pid, 'SIGKILL');
130
+ }
131
+ catch { /* ended meanwhile */ }
132
+ }
133
+ }
134
+ }
135
+ // a spawn error keeps execFileSync's shape and its own code (ENOENT, EACCES, …)
136
+ if (!result.error && result.status === 127 && /^E[A-Z0-9]+$/.test(errno)) {
137
+ result.error = Object.assign(new Error(`spawnSync ${cmd} ${errno}`), { code: errno, ...(errno === 'ENOENT' ? { errno: -2 } : {}), syscall: `spawnSync ${cmd}`, path: cmd });
138
+ }
139
+ return { result, stopped, leftovers };
140
+ }