@holmes-lab/holmes-kit 0.39.0 → 0.40.1

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 (325) hide show
  1. package/CHANGELOG.md +578 -6
  2. package/README.md +120 -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 +226 -442
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  67. package/dist/holmes/cli/interactive-prompt.js +98 -16
  68. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  69. package/dist/holmes/cli/lock-recover.js +126 -0
  70. package/dist/holmes/cli/mcp-processes.js +1 -1
  71. package/dist/holmes/cli/release-docs.js +1 -1
  72. package/dist/holmes/cli/run-exec.d.ts +141 -0
  73. package/dist/holmes/cli/run-exec.js +1435 -0
  74. package/dist/holmes/cli/run-provision.d.ts +3 -1
  75. package/dist/holmes/cli/run-provision.js +255 -44
  76. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  77. package/dist/holmes/cli/run-wiring.js +270 -0
  78. package/dist/holmes/cli/run.d.ts +21 -0
  79. package/dist/holmes/cli/run.js +341 -92
  80. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  81. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  82. package/dist/holmes/cli/screen-safe.js +18 -756
  83. package/dist/holmes/config/config.d.ts +19 -0
  84. package/dist/holmes/config/config.js +18 -3
  85. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  86. package/dist/holmes/cpg/import-resolver.js +1 -1
  87. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  88. package/dist/holmes/governance/approval-decisions.js +29 -0
  89. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  90. package/dist/holmes/governance/approval-grants.js +612 -33
  91. package/dist/holmes/governance/approval-queue.d.ts +26 -0
  92. package/dist/holmes/governance/approval-queue.js +109 -11
  93. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  94. package/dist/holmes/governance/approval-spend.js +191 -0
  95. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  96. package/dist/holmes/governance/autonomous-shell.js +332 -0
  97. package/dist/holmes/governance/autonomy.d.ts +12 -0
  98. package/dist/holmes/governance/autonomy.js +51 -15
  99. package/dist/holmes/governance/constitution.d.ts +5 -0
  100. package/dist/holmes/governance/constitution.js +32 -12
  101. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  102. package/dist/holmes/governance/full-autonomy.js +103 -7
  103. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  104. package/dist/holmes/governance/harness-catalog.js +348 -0
  105. package/dist/holmes/governance/human-channel.d.ts +38 -0
  106. package/dist/holmes/governance/human-channel.js +49 -0
  107. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  108. package/dist/holmes/governance/install-manifest.js +160 -0
  109. package/dist/holmes/governance/ledger-rechain.js +2 -0
  110. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  111. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  112. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  113. package/dist/holmes/governance/ledger-store.js +186 -8
  114. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  115. package/dist/holmes/governance/provenance-chain.js +19 -4
  116. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  117. package/dist/holmes/governance/provenance-ledger.js +53 -18
  118. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  119. package/dist/holmes/governance/push-gate-runner.js +50 -9
  120. package/dist/holmes/governance/push-gate.d.ts +13 -2
  121. package/dist/holmes/governance/push-gate.js +106 -14
  122. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  123. package/dist/holmes/governance/recorded-pairs.js +522 -0
  124. package/dist/holmes/governance/replica-id.d.ts +1 -1
  125. package/dist/holmes/governance/replica-id.js +1 -1
  126. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  127. package/dist/holmes/governance/spec-seam.js +587 -0
  128. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  129. package/dist/holmes/governance/spend-kinds.js +18 -0
  130. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  131. package/dist/holmes/guardrail/advisory-line.js +718 -0
  132. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  133. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  134. package/dist/holmes/guardrail/impact-gate.d.ts +7 -0
  135. package/dist/holmes/guardrail/impact-gate.js +33 -6
  136. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  137. package/dist/holmes/guardrail/line-continuation.js +39 -0
  138. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  139. package/dist/holmes/guardrail/operator-person.js +57 -11
  140. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  141. package/dist/holmes/guardrail/refusal-codes.js +64 -10
  142. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  143. package/dist/holmes/guardrail/risk-classifier.js +228 -16
  144. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  145. package/dist/holmes/guardrail/risk-gate.js +7 -34
  146. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  147. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  148. package/dist/holmes/guardrail/run-refusals.js +24 -8
  149. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  150. package/dist/holmes/guardrail/run-stages.js +25 -5
  151. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  152. package/dist/holmes/guardrail/shell-words.js +24 -3
  153. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  154. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  155. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  156. package/dist/holmes/guardrail/write-target.js +26 -5
  157. package/dist/holmes/hooks/pre-tool-use.d.ts +116 -1
  158. package/dist/holmes/hooks/pre-tool-use.js +1176 -170
  159. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  160. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  161. package/dist/holmes/hooks/session-start.js +17 -1
  162. package/dist/holmes/hooks/stop.d.ts +23 -0
  163. package/dist/holmes/hooks/stop.js +86 -33
  164. package/dist/holmes/mcp/approval-adapters.js +3 -1
  165. package/dist/holmes/mcp/approval-commit.js +3 -2
  166. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  167. package/dist/holmes/mcp/approval-policy.js +3 -1
  168. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  169. package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
  170. package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
  171. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  172. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  173. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  174. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  175. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  176. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  177. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  178. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  179. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  180. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  181. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  182. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  183. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  184. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  185. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  186. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  187. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  188. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  189. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  190. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  191. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  192. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  193. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  194. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  195. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  196. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  197. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  198. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  199. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  200. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  201. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  202. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  203. package/dist/holmes/mcp/handlers/test-execution.d.ts +471 -4
  204. package/dist/holmes/mcp/handlers/test-execution.js +199 -21
  205. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  206. package/dist/holmes/mcp/handlers.d.ts +557 -82
  207. package/dist/holmes/mcp/handlers.js +74 -23
  208. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  209. package/dist/holmes/mcp/harness-attestation.js +325 -53
  210. package/dist/holmes/mcp/maintenance-analyze.d.ts +6 -1
  211. package/dist/holmes/mcp/maintenance-analyze.js +13 -11
  212. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  213. package/dist/holmes/mcp/maintenance-evidence.js +35 -3
  214. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  215. package/dist/holmes/mcp/server-staleness.js +1 -1
  216. package/dist/holmes/mcp/server.js +9 -8
  217. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  218. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  219. package/dist/holmes/mcp/tool-schemas.js +42 -9
  220. package/dist/holmes/project/act-root.d.ts +19 -0
  221. package/dist/holmes/project/act-root.js +100 -0
  222. package/dist/holmes/project/baseline.d.ts +15 -2
  223. package/dist/holmes/project/baseline.js +14 -8
  224. package/dist/holmes/project/bounded-group.d.ts +47 -0
  225. package/dist/holmes/project/bounded-group.js +140 -0
  226. package/dist/holmes/project/bounded-io.d.ts +51 -2
  227. package/dist/holmes/project/bounded-io.js +140 -6
  228. package/dist/holmes/project/change-source.d.ts +4 -0
  229. package/dist/holmes/project/change-source.js +14 -6
  230. package/dist/holmes/project/instance-id.d.ts +10 -0
  231. package/dist/holmes/project/instance-id.js +233 -0
  232. package/dist/holmes/project/machine-identity.d.ts +25 -0
  233. package/dist/holmes/project/machine-identity.js +133 -0
  234. package/dist/holmes/project/owned-lock.d.ts +84 -0
  235. package/dist/holmes/project/owned-lock.js +263 -0
  236. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  237. package/dist/holmes/project/plain-lock-fs.js +126 -0
  238. package/dist/holmes/project/request-lock.d.ts +85 -0
  239. package/dist/holmes/project/request-lock.js +459 -0
  240. package/dist/holmes/project/root.d.ts +12 -4
  241. package/dist/holmes/project/root.js +29 -8
  242. package/dist/holmes/project/run-records.d.ts +19 -0
  243. package/dist/holmes/project/run-records.js +94 -12
  244. package/dist/holmes/project/screen-text.d.ts +94 -0
  245. package/dist/holmes/project/screen-text.js +763 -0
  246. package/dist/holmes/project/spend-lock.d.ts +82 -0
  247. package/dist/holmes/project/spend-lock.js +413 -0
  248. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  249. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  250. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  251. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  252. package/dist/holmes/review/confidence-calibration.js +1 -1
  253. package/dist/holmes/review/content-verify.js +1 -1
  254. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  255. package/dist/holmes/review/evidence-mode.js +33 -0
  256. package/dist/holmes/review/head-worktree.d.ts +55 -0
  257. package/dist/holmes/review/head-worktree.js +329 -0
  258. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  259. package/dist/holmes/review/hop-ablation.js +5 -5
  260. package/dist/holmes/review/mrp.js +13 -3
  261. package/dist/holmes/review/point-in-time-replay.js +12 -3
  262. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  263. package/dist/holmes/review/rank-diagnosis.js +1 -1
  264. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  265. package/dist/holmes/review/replay-corpus.js +25 -9
  266. package/dist/holmes/review/requirement-triage.js +2 -2
  267. package/dist/holmes/review/run-provenance.d.ts +45 -0
  268. package/dist/holmes/review/run-provenance.js +314 -0
  269. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  270. package/dist/holmes/review/semantic-arm.js +3 -3
  271. package/dist/holmes/review/test-evidence.d.ts +174 -0
  272. package/dist/holmes/review/test-evidence.js +330 -2
  273. package/dist/holmes/review/test-outcomes.js +3 -1
  274. package/dist/holmes/review/test-reports.d.ts +94 -0
  275. package/dist/holmes/review/test-reports.js +382 -0
  276. package/dist/holmes/review/test-runner.d.ts +180 -58
  277. package/dist/holmes/review/test-runner.js +560 -324
  278. package/dist/holmes/review/test-selection-breadth.js +2 -2
  279. package/dist/holmes/review/test-units.d.ts +159 -0
  280. package/dist/holmes/review/test-units.js +814 -0
  281. package/dist/holmes/review/verdicts.d.ts +105 -8
  282. package/dist/holmes/review/verdicts.js +640 -36
  283. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  284. package/dist/holmes/rtm/anchor-census.js +151 -0
  285. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  286. package/dist/holmes/rtm/anchor-ids.js +45 -2
  287. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  288. package/dist/holmes/rtm/comment-ranges.js +104 -0
  289. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  290. package/dist/holmes/rtm/counted-tests.js +63 -0
  291. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  292. package/dist/holmes/rtm/known-defects.js +1 -1
  293. package/dist/holmes/rtm/localize.js +1 -1
  294. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  295. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  296. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  297. package/dist/holmes/rtm/test-scope.js +166 -5
  298. package/dist/holmes/rtm/trace-gaps.js +1 -1
  299. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  300. package/dist/holmes/runtime/dispatch.js +12 -1
  301. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  302. package/dist/holmes/semantic/cloud-usage.js +1 -1
  303. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  304. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  305. package/dist/holmes/spec/approval-blockers.js +1 -1
  306. package/dist/holmes/spec/entity-store.d.ts +6 -1
  307. package/dist/holmes/spec/entity-store.js +16 -2
  308. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  309. package/dist/holmes/spec/entity-transaction.js +87 -170
  310. package/dist/holmes/spec/spec-store.d.ts +12 -6
  311. package/dist/holmes/spec/spec-store.js +4 -2
  312. package/dist/holmes/spec/spec-types.js +1 -1
  313. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  314. package/dist/holmes/spec/succession-guard.js +187 -0
  315. package/dist/holmes/spec/succession.d.ts +70 -0
  316. package/dist/holmes/spec/succession.js +171 -0
  317. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  318. package/docs/install-guide.md +9 -3
  319. package/docs/language-support.md +78 -0
  320. package/package.json +4 -3
  321. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  322. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  323. package/playbooks/publish/PLAYBOOK.md +47 -34
  324. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  325. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -0,0 +1,459 @@
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.PublishUnsupported = exports.PublishConflict = exports.FenceLost = exports.CLAIM_STALE_MS = exports.AGE_FACTOR = exports.REQUEST_LEAKS_FILE = exports.REQUEST_RETIRED_DIR = exports.REQUEST_CLAIMS_DIR = exports.REQUEST_LOCKS_DIR = void 0;
37
+ exports.requestLockLayout = requestLockLayout;
38
+ exports.withRequestLock = withRequestLock;
39
+ exports.requestLockHolders = requestLockHolders;
40
+ exports.recoverRequestLockAsOperator = recoverRequestLockAsOperator;
41
+ exports.nextLockEpoch = nextLockEpoch;
42
+ // @implements A-SPEC-794.2, A-SPEC-794.6
43
+ /**
44
+ * The request lock (design draft 4 §4.1, §4.4): one holder per approval request id, on the owned-lock protocol, and
45
+ * the fence a holder checks before every queue append and grant publish.
46
+ *
47
+ * - The lock lives at `.ax/state/request-locks/<id>`; its successor claims and retired generations sit beside the
48
+ * other locks' under `.ax/state`. The id is `req-<12 hex>` or nothing is touched.
49
+ * - Lock order (A-SPEC-245.7 extended by A-SPEC-794.6): entity-store → request → spend → chain. A spend holder never
50
+ * takes this lock; request-lock-order.test.ts holds that no spend-context module reaches it.
51
+ * - Acquisition never waits past its budget plus one pass. A certainly dead holder (spendVerdict's rules, the probe
52
+ * injectable) is recovered and the lock taken fresh. A holder whose liveness cannot be judged (another or an unknown
53
+ * host, an unknown boot, an earlier boot on darwin) is recovered once held longer than 4x its bound; a holder judged
54
+ * alive is never recovered by age; this process asking again for an id it holds is a leak. Past that, the operator
55
+ * runs `holmes-kit lock recover request <id>`.
56
+ * - The fence holds while the owner record carries this holder's token, the lock directory keeps the inode it had at
57
+ * acquisition, and no successor claim names the token; it reads through the LockFs, so a symlinked path is lost.
58
+ * - A publish links a private temp file to its name, so it never replaces a file.
59
+ *
60
+ * Limits: the fence narrows the window between check and write and does not close it — the no-clobber publish and
61
+ * lockEpoch carry the rest (tamper evidence, not prevention). Age-based recovery is a judgement, not a proof. A reused
62
+ * pid reads as alive. The wait is Atomics.wait, which blocks the event loop: an MCP path must keep its budget short.
63
+ */
64
+ const fs = __importStar(require("node:fs"));
65
+ const path = __importStar(require("node:path"));
66
+ const node_crypto_1 = require("node:crypto");
67
+ const owned_lock_1 = require("./owned-lock");
68
+ const spend_lock_1 = require("./spend-lock");
69
+ const plain_lock_fs_1 = require("./plain-lock-fs");
70
+ exports.REQUEST_LOCKS_DIR = '.ax/state/request-locks';
71
+ exports.REQUEST_CLAIMS_DIR = '.ax/state/request-lock-claims';
72
+ exports.REQUEST_RETIRED_DIR = '.ax/state/request-retired-locks';
73
+ exports.REQUEST_LEAKS_FILE = '.ax/state/request-lock-leaks.jsonl';
74
+ function requestLockLayout(id) { return { parent: exports.REQUEST_LOCKS_DIR, name: id, claims: exports.REQUEST_CLAIMS_DIR, retired: exports.REQUEST_RETIRED_DIR }; }
75
+ const REQUEST_ID = /^req-[0-9a-f]{12}$/;
76
+ const TRANSIENT = /^\.lock-[0-9a-f-]{36}\.tmp$/;
77
+ /** A holder whose liveness cannot be judged is recovered once held longer than this many times its bound. */
78
+ exports.AGE_FACTOR = 4;
79
+ /** A claim of a claimant whose liveness cannot be judged is recovered once older than this. */
80
+ exports.CLAIM_STALE_MS = 60_000;
81
+ const UNJUDGEABLE = new Set(['host', 'boot-unknown', 'case-1-off']);
82
+ const EPOCH_LIMIT = 2 ** 32;
83
+ /** The holder's lock was recovered, replaced or claimed by a successor: it must write nothing. */
84
+ class FenceLost extends Error {
85
+ holmesRefusal = true;
86
+ constructor(message) { super(message); this.name = 'FenceLost'; }
87
+ }
88
+ exports.FenceLost = FenceLost;
89
+ /** A publish found its name taken; the existing file is untouched. */
90
+ class PublishConflict extends Error {
91
+ holmesRefusal = true;
92
+ constructor(message) { super(message); this.name = 'PublishConflict'; }
93
+ }
94
+ exports.PublishConflict = PublishConflict;
95
+ /** The file system refused the hard link a publish needs; nothing is copied in its place. */
96
+ class PublishUnsupported extends Error {
97
+ holmesRefusal = true;
98
+ constructor(message) { super(message); this.name = 'PublishUnsupported'; }
99
+ }
100
+ exports.PublishUnsupported = PublishUnsupported;
101
+ const lockFsOf = (root) => (0, plain_lock_fs_1.plainLockFs)(root, (name) => TRANSIENT.test(name));
102
+ /** Tokens of request locks this copy of the module holds. */
103
+ const held = new Set();
104
+ function identityOf(given) {
105
+ if (given)
106
+ return given;
107
+ const m = require('./machine-identity');
108
+ return { host: m.hostId(), bootId: m.bootId() };
109
+ }
110
+ function validHolder(r, id) {
111
+ if (typeof r !== 'object' || r === null)
112
+ return false;
113
+ const o = r;
114
+ const keys = ['kind', 'token', 'pid', 'host', 'bootId', 'acquiredAt', 'boundMs', 'id'];
115
+ return Object.keys(o).every((k) => keys.includes(k)) && o.kind === 'request' && (0, owned_lock_1.isLockToken)(o.token)
116
+ && Number.isSafeInteger(o.pid) && o.pid > 0
117
+ && (o.host === null || typeof o.host === 'string') && (o.bootId === null || typeof o.bootId === 'string')
118
+ && typeof o.acquiredAt === 'string' && typeof o.boundMs === 'number' && o.boundMs > 0 && o.id === id;
119
+ }
120
+ function validClaim(r) {
121
+ if (typeof r !== 'object' || r === null)
122
+ return false;
123
+ const o = r;
124
+ const keys = ['kind', 'token', 'pid', 'host', 'bootId', 'claimedAt', 'recovers', 'released'];
125
+ return Object.keys(o).every((k) => keys.includes(k)) && o.kind === 'request-recovery' && (0, owned_lock_1.isLockToken)(o.token)
126
+ && Number.isSafeInteger(o.pid) && o.pid > 0
127
+ && (o.host === null || typeof o.host === 'string') && (o.bootId === null || typeof o.bootId === 'string')
128
+ && typeof o.claimedAt === 'string' && (0, owned_lock_1.isLockToken)(o.recovers) && (o.released === undefined || o.released === true);
129
+ }
130
+ /** This process's pid is never dead: its own token is a leak, any other is alive. Otherwise spendVerdict's rules. */
131
+ function verdictOf(r, me, platform, probe) {
132
+ if (r.pid === process.pid)
133
+ return { dead: false, reason: held.has(r.token) ? 'leak' : 'alive' };
134
+ const v = (0, spend_lock_1.spendVerdict)(r, me, platform, probe);
135
+ return v.dead ? { dead: true } : { dead: false, reason: v.reason };
136
+ }
137
+ const ageOf = (iso, now) => now - Date.parse(String(iso));
138
+ /** An unjudgeable holder held longer than AGE_FACTOR x its bound. */
139
+ const pastBound = (h, reason, now) => UNJUDGEABLE.has(reason) && ageOf(h.acquiredAt, now) > exports.AGE_FACTOR * h.boundMs;
140
+ function busyMessage(id, h, reason) {
141
+ const route = `if the holder is dead, the operator runs \`holmes-kit lock recover request ${id} --confirm-holder-dead\` from a terminal`;
142
+ return reason === 'alive' || reason === 'leak'
143
+ ? `The request lock of ${id} is held by pid ${h.pid}, which is running. Retry when it is released; ${route} once it is held longer than ${exports.AGE_FACTOR}x its bound.`
144
+ : `The request lock of ${id} is held by pid ${h.pid}, whose liveness cannot be judged here (${reason}). It is recovered automatically once held longer than ${exports.AGE_FACTOR}x its bound of ${(h.boundMs / 1000).toFixed(1)} s; sooner, ${route}.`;
145
+ }
146
+ function policyOf(id, me, platform, probe, force) {
147
+ return {
148
+ kind: 'request',
149
+ valid: (r, first) => (first ? validHolder(r, id) : validClaim(r)),
150
+ judgeDead: (r, first) => {
151
+ if (force !== undefined && first) {
152
+ if (r.token === force.token)
153
+ return;
154
+ throw new owned_lock_1.LockError('lock-busy', 'recover-live', `The request lock of ${id} changed hands after it was judged; it is not recovered. Judge it again.`);
155
+ }
156
+ const now = force?.now ?? Date.now();
157
+ const v = verdictOf(r, me, platform, probe);
158
+ if (v.dead)
159
+ return;
160
+ if (first) {
161
+ if (pastBound(r, v.reason, now))
162
+ return;
163
+ throw new owned_lock_1.LockError('lock-busy', 'recover-live', busyMessage(id, r, v.reason));
164
+ }
165
+ // a successor claim: a recoverer that published it and may have died
166
+ const age = ageOf(r.claimedAt, now);
167
+ if ((UNJUDGEABLE.has(v.reason) || force?.confirmClaims) && age > exports.CLAIM_STALE_MS)
168
+ return;
169
+ throw new owned_lock_1.LockError('lock-busy', 'recover-claim', `A recovery claim by pid ${r.pid} (${(Math.max(0, age) / 1000).toFixed(1)} s old, ${v.reason}) blocks the recovery of the request lock of ${id}.`);
170
+ },
171
+ claim: (recovers) => ({ kind: 'request-recovery', token: (0, node_crypto_1.randomUUID)(), pid: process.pid, host: me.host, bootId: me.bootId, claimedAt: new Date().toISOString(), recovers }),
172
+ };
173
+ }
174
+ const sleepSync = (ms) => { try {
175
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
176
+ }
177
+ catch { /* retry without waiting */ } };
178
+ const unwrapAct = (f) => { try {
179
+ return f();
180
+ }
181
+ catch (e) {
182
+ throw e instanceof owned_lock_1.ActError ? e.inner : e;
183
+ } };
184
+ function fenceOf(root, lfs, id, token, ownership) {
185
+ const lost = (why) => new FenceLost(`The request lock of ${id} ${why}; this holder writes nothing.`);
186
+ const check = () => {
187
+ let dir, claims;
188
+ try {
189
+ dir = path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id);
190
+ claims = lfs.directory(exports.REQUEST_CLAIMS_DIR);
191
+ }
192
+ catch {
193
+ throw lost('cannot be read through its locator');
194
+ }
195
+ let s, owner;
196
+ try {
197
+ s = lfs.stat(dir);
198
+ }
199
+ catch {
200
+ s = undefined;
201
+ }
202
+ if (!s || !s.isDirectory())
203
+ throw lost('is gone');
204
+ if (s.dev !== ownership.dev || s.ino !== ownership.ino)
205
+ throw lost('was replaced');
206
+ try {
207
+ owner = JSON.parse(lfs.readBytes(path.join(dir, 'owner.json'))?.toString('utf8') ?? 'null');
208
+ }
209
+ catch {
210
+ owner = null;
211
+ }
212
+ if (owner?.token !== token)
213
+ throw lost('has another holder');
214
+ for (const claim of [path.join(dir, `successor-${token}.json`), path.join(claims, `successor-${token}.json`)]) {
215
+ let c;
216
+ try {
217
+ c = lfs.stat(claim);
218
+ }
219
+ catch {
220
+ throw lost('cannot be read through its locator');
221
+ }
222
+ if (c)
223
+ throw lost('is claimed by a successor');
224
+ }
225
+ };
226
+ return {
227
+ check,
228
+ write: (fn) => { check(); return fn(); },
229
+ publish: (dirRel, name, bytes) => {
230
+ if (path.basename(name) !== name || name === '' || name.startsWith('.'))
231
+ throw new PublishConflict(`Not a publishable name: ${JSON.stringify(name)}.`);
232
+ check();
233
+ const target = lfs.directory(dirRel, true);
234
+ const temp = path.join(target, `.publishing.${(0, node_crypto_1.randomUUID)()}.tmp`);
235
+ fs.writeFileSync(temp, bytes, { flag: 'wx', mode: 0o600 });
236
+ try {
237
+ fs.linkSync(temp, path.join(target, name));
238
+ }
239
+ catch (e) {
240
+ const code = e.code;
241
+ if (code === 'EEXIST')
242
+ throw new PublishConflict(`${path.join(dirRel, name)} exists; it is not replaced.`);
243
+ if (code === 'EPERM' || code === 'ENOTSUP' || code === 'EXDEV' || code === 'ENOSYS')
244
+ throw new PublishUnsupported(`This file system refused the hard link a publish needs (${code}); ${path.join(dirRel, name)} is not written.`);
245
+ throw e;
246
+ }
247
+ finally {
248
+ try {
249
+ fs.unlinkSync(temp);
250
+ }
251
+ catch { /* a leftover temp file is read by reconcile */ }
252
+ }
253
+ },
254
+ };
255
+ }
256
+ function recordLeak(root, lfs, id, e) {
257
+ const message = e instanceof Error ? e.message : String(e);
258
+ try {
259
+ lfs.appendLine(path.join(root, exports.REQUEST_LEAKS_FILE), JSON.stringify({ at: new Date().toISOString(), pid: process.pid, id, error: message }));
260
+ }
261
+ catch { /* stderr still says it */ }
262
+ try {
263
+ process.stderr.write(`[Holmes-Kit] the request lock of ${id} was not released (${message}); it is recovered like a dead holder's, or by the operator.\n`);
264
+ }
265
+ catch { /* best effort */ }
266
+ }
267
+ /**
268
+ * Take the request lock of `id` within `opts.budgetMs`, run `act` with the fence, and release. Busy past the budget is
269
+ * `lock-busy`; this process's own hold of the id is `lock-leak`; an id outside `req-<12 hex>`, or a root without `.ax`,
270
+ * is refused before any file is touched. A release that fails after `act` returned does not hide the result; when
271
+ * `act` threw, its error is the one thrown.
272
+ */
273
+ function withRequestLock(root, id, opts, act) {
274
+ if (!REQUEST_ID.test(id))
275
+ throw new owned_lock_1.LockError('unknown-owner', 'acquire', `Not a request id: ${JSON.stringify(id)}.`);
276
+ let ax;
277
+ try {
278
+ ax = fs.lstatSync(path.join(root, '.ax'));
279
+ }
280
+ catch {
281
+ ax = undefined;
282
+ }
283
+ if (!ax?.isDirectory())
284
+ throw new owned_lock_1.LockError('unknown-owner', 'acquire', 'A request lock is taken only inside an existing .ax directory.');
285
+ const lfs = lockFsOf(root);
286
+ const layout = requestLockLayout(id);
287
+ const me = identityOf(opts.identity);
288
+ const platform = opts.platform ?? process.platform;
289
+ const record = { kind: 'request', token: (0, node_crypto_1.randomUUID)(), pid: process.pid, host: me.host, bootId: me.bootId,
290
+ acquiredAt: new Date().toISOString(), boundMs: opts.boundMs ?? 1000, id };
291
+ const deadline = Date.now() + opts.budgetMs;
292
+ let lastBusy = `The request lock of ${id} is held.`;
293
+ let orphan = false;
294
+ for (;;) {
295
+ let release;
296
+ try {
297
+ release = (0, owned_lock_1.acquireOwnedLock)(lfs, layout, record);
298
+ }
299
+ catch (e) {
300
+ if (!(e instanceof owned_lock_1.LockError) || e.code !== 'lock-busy')
301
+ throw e;
302
+ }
303
+ if (release) {
304
+ held.add(record.token);
305
+ let result, failure;
306
+ try {
307
+ const ownership = lfs.stat(path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id));
308
+ if (!ownership)
309
+ throw new FenceLost(`The request lock of ${id} vanished as it was taken; this holder writes nothing.`);
310
+ result = act(fenceOf(root, lfs, id, record.token, ownership));
311
+ }
312
+ catch (e) {
313
+ failure = { error: e };
314
+ }
315
+ try {
316
+ release();
317
+ }
318
+ catch (e) {
319
+ recordLeak(root, lfs, id, e);
320
+ }
321
+ finally {
322
+ held.delete(record.token);
323
+ }
324
+ if (failure)
325
+ throw failure.error;
326
+ return result;
327
+ }
328
+ const bytes = lfs.readBytes(path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id, 'owner.json'));
329
+ orphan = false;
330
+ if (bytes !== undefined) {
331
+ let raw;
332
+ try {
333
+ raw = JSON.parse(bytes.toString('utf8'));
334
+ }
335
+ catch {
336
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Malformed lock ownership must be preserved.');
337
+ }
338
+ if (!validHolder(raw, id))
339
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Invalid lock ownership must be preserved.');
340
+ const v = verdictOf(raw, me, platform, opts.probe);
341
+ if (!v.dead && v.reason === 'leak')
342
+ throw new owned_lock_1.LockError('lock-leak', 'acquire', `This process already holds the request lock of ${id}; a second acquisition is a leak.`);
343
+ if (v.dead || pastBound(raw, v.reason, Date.now())) {
344
+ try {
345
+ unwrapAct(() => (0, owned_lock_1.recoverOwnedLock)(lfs, layout, policyOf(id, me, platform, opts.probe), () => undefined, () => () => undefined));
346
+ }
347
+ catch (e) {
348
+ if (!(e instanceof owned_lock_1.LockError) || e.code !== 'lock-busy')
349
+ throw e;
350
+ lastBusy = e.message;
351
+ }
352
+ if (Date.now() < deadline)
353
+ continue;
354
+ }
355
+ else
356
+ lastBusy = busyMessage(id, raw, v.reason);
357
+ }
358
+ else if (lfs.stat(path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id))) {
359
+ // a directory between its rename and its owner read, or one left without a record: read again on the next pass
360
+ orphan = true;
361
+ lastBusy = `The request lock of ${id} has no holder record yet.`;
362
+ }
363
+ if (Date.now() >= deadline) {
364
+ if (orphan)
365
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'A request lock without a holder record is preserved for inspection.');
366
+ throw new owned_lock_1.LockError('lock-busy', 'acquire', lastBusy);
367
+ }
368
+ sleepSync(Math.min(15, Math.max(1, deadline - Date.now())));
369
+ }
370
+ }
371
+ /** The held request locks with a readable holder, for doctor. */
372
+ function requestLockHolders(root) {
373
+ const lfs = lockFsOf(root);
374
+ let dir, names;
375
+ try {
376
+ dir = lfs.directory(exports.REQUEST_LOCKS_DIR);
377
+ names = lfs.list(dir);
378
+ }
379
+ catch {
380
+ return [];
381
+ }
382
+ const out = [];
383
+ for (const name of names) {
384
+ if (!REQUEST_ID.test(name))
385
+ continue;
386
+ try {
387
+ const r = JSON.parse(lfs.readBytes(path.join(dir, name, 'owner.json'))?.toString('utf8') ?? 'null');
388
+ if (validHolder(r, name))
389
+ out.push(r);
390
+ }
391
+ catch { /* unreadable: doctor says nothing it cannot read */ }
392
+ }
393
+ return out;
394
+ }
395
+ /**
396
+ * The operator's recovery of one request lock, by `recoverSpendLockAsOperator`'s rules: a dead holder is recovered;
397
+ * an unjudgeable one needs `confirmHolderDead`; an answering one needs it and a hold longer than 4x its bound; this
398
+ * process's own hold is refused; a lock that changed hands since it was read is refused.
399
+ */
400
+ function recoverRequestLockAsOperator(root, id, opts) {
401
+ if (!REQUEST_ID.test(id))
402
+ return { refused: `Not a request id: ${JSON.stringify(id)}.` };
403
+ const lfs = lockFsOf(root);
404
+ let holder = null, present = false;
405
+ try {
406
+ const dir = path.join(lfs.directory(exports.REQUEST_LOCKS_DIR), id);
407
+ present = lfs.stat(dir) !== undefined;
408
+ const r = JSON.parse(lfs.readBytes(path.join(dir, 'owner.json'))?.toString('utf8') ?? 'null');
409
+ holder = validHolder(r, id) ? r : null;
410
+ }
411
+ catch {
412
+ holder = null;
413
+ }
414
+ if (!holder)
415
+ return present ? { refused: `The request lock of ${id} has no readable holder record; it is preserved for inspection.` } : { nothing: true };
416
+ if (opts.expectToken !== undefined && holder.token !== opts.expectToken)
417
+ return { refused: `The request lock of ${id} changed hands after it was read; run again to judge the current holder.` };
418
+ const me = identityOf(opts.identity);
419
+ const platform = opts.platform ?? process.platform;
420
+ const now = (opts.now ?? Date.now)();
421
+ const v = verdictOf(holder, me, platform, opts.probe);
422
+ let reason;
423
+ if (v.dead)
424
+ reason = 'the holder is dead';
425
+ else if (v.reason === 'leak')
426
+ return { refused: `This process holds the request lock of ${id}; it is released when its act ends.` };
427
+ else if (v.reason === 'alive') {
428
+ if (!opts.confirmHolderDead)
429
+ return { refused: `The request lock's holder, pid ${holder.pid}, answers on this host; if that pid is not the holder (reused) and the holder is dead, run again with --confirm-holder-dead once it has been held longer than ${exports.AGE_FACTOR}x its bound.` };
430
+ if (!(ageOf(holder.acquiredAt, now) > exports.AGE_FACTOR * holder.boundMs))
431
+ return { refused: `The request lock's holder, pid ${holder.pid}, answers and has not been held longer than ${exports.AGE_FACTOR}x its bound; it is not recovered.` };
432
+ reason = `confirmed dead by the operator: pid ${holder.pid} answers, held past ${exports.AGE_FACTOR}x its bound`;
433
+ }
434
+ else {
435
+ if (!opts.confirmHolderDead)
436
+ return { refused: `The request lock's holder, pid ${holder.pid}, cannot be judged dead here (${v.reason}); if it is dead, run again with --confirm-holder-dead.` };
437
+ reason = `confirmed dead by the operator (${v.reason})`;
438
+ }
439
+ const force = { token: holder.token, confirmClaims: opts.confirmHolderDead, now };
440
+ try {
441
+ unwrapAct(() => (0, owned_lock_1.recoverOwnedLock)(lfs, requestLockLayout(id), policyOf(id, me, platform, opts.probe, force), () => undefined, () => () => undefined));
442
+ }
443
+ catch (e) {
444
+ if (e instanceof owned_lock_1.LockError && e.code === 'lock-busy')
445
+ return { refused: e.message };
446
+ throw e;
447
+ }
448
+ return { recovered: holder, reason };
449
+ }
450
+ /** 1 + the largest `lockEpoch` among the events of `id` that is a safe integer in [0, 2^32), or 1 when there is none. */
451
+ function nextLockEpoch(events, id) {
452
+ let max = 0;
453
+ for (const e of events) {
454
+ const n = e.lockEpoch;
455
+ if (e.id === id && typeof n === 'number' && Number.isSafeInteger(n) && n >= 0 && n < EPOCH_LIMIT && n > max)
456
+ max = n;
457
+ }
458
+ return max + 1;
459
+ }
@@ -32,14 +32,22 @@ export interface ProjectRoot {
32
32
  }
33
33
  /** The marker directory that makes a directory a Holmes-Kit project. */
34
34
  export declare const MARKER = ".ax";
35
+ /**
36
+ * @implements A-SPEC-102.31 — the one rule of what a project is: `dir/.ax` is a directory, a link to one included. The
37
+ * file system's own case rule applies (macOS answers `.AX` for `.ax`). A regular file named `.ax` is no project: it made a
38
+ * new catalog boundary (A, N5). resolveProjectRoot and the autonomy scope search both ask this.
39
+ */
40
+ export declare function isProjectDir(dir: string, opts?: {
41
+ strict?: boolean;
42
+ }): boolean;
35
43
  /**
36
44
  * The one canonical spelling of an existing path.
37
45
  *
38
46
  * `fs.realpathSync.native`, not `fs.realpathSync`. The JS implementation resolves symlinks only;
39
- * on Windows it leaves 8.3 short-name aliases (`C:\Users\SUNGNA~1`, which is what `%TEMP%` and
47
+ * on Windows it leaves 8.3 short-name aliases (`C:\Users\FIRSTL~1`, which is what `%TEMP%` and
40
48
  * `os.tmpdir()` hand out) exactly as spelled, while `git rev-parse --show-toplevel` prints the
41
- * long name. Measured 2026-08-23: `resolveProjectRoot('C:/AI_PRO~1/AX-COD~1')` reported
42
- * `root: C:\AI_PRO~1\AX-COD~1` beside `git.topLevel: C:\ai_project\AX-Coding-Project` for ONE
49
+ * long name. Measured 2026-08-23: `resolveProjectRoot('C:/WORKSP~1/MYPROJ~1')` reported
50
+ * `root: C:\WORKSP~1\MYPROJ~1` beside `git.topLevel: C:\workspace\my-project` for ONE
43
51
  * directory, and GitChangeSource refused it as a mismatch. The native call expands both symlinks
44
52
  * and 8.3 names (a strict superset, same ENOENT behaviour), so `root` keeps the promise its type
45
53
  * makes: one spelling per directory, the spelling every path key is built from.
@@ -51,7 +59,7 @@ export declare const canonicalPath: (p: string) => string;
51
59
  * so 8.3 aliases and symlinks collapse); a path that does not exist compares by its resolved spelling.
52
60
  * `realpath` is injectable so the 8.3 scenario runs on every OS in the tests. Measured 2026-09-14
53
61
  * (WIN0200-20260914-SHORTPATH): `entityStoreBinding` compared JS `fs.realpathSync` output against a
54
- * native-canonical root, so a workspace entered as `C:\Users\SUNGNA~1\…` was refused as foreign.
62
+ * native-canonical root, so a workspace entered as `C:\Users\FIRSTL~1\…` was refused as foreign.
55
63
  */
56
64
  export declare function sameCanonicalDirectory(a: string, b: string, realpath?: (p: string) => string): boolean;
57
65
  export declare function resolveProjectRoot(dir: string, opts?: {
@@ -36,9 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.canonicalPath = exports.MARKER = void 0;
37
37
  exports.cleanSubprocessEnv = cleanSubprocessEnv;
38
38
  exports.cleanTestEnv = cleanTestEnv;
39
+ exports.isProjectDir = isProjectDir;
39
40
  exports.sameCanonicalDirectory = sameCanonicalDirectory;
40
41
  exports.resolveProjectRoot = resolveProjectRoot;
41
- // @implements A-SPEC-205, A-SPEC-627, A-SPEC-734
42
+ // @implements A-SPEC-205, A-SPEC-627, A-SPEC-734, A-SPEC-102.31, A-SPEC-102.32, A-SPEC-794.47, A-SPEC-794.57, A-SPEC-794.58
42
43
  // @implements A-SPEC-128
43
44
  const fs = __importStar(require("node:fs"));
44
45
  const path = __importStar(require("node:path"));
@@ -97,7 +98,7 @@ function cleanSubprocessEnv(env = process.env) {
97
98
  // under test; an evidence run must judge the same in an autonomous workspace and a human-gated one.
98
99
  // @implements A-SPEC-695
99
100
  // `NPM_CONFIG_DRY_RUN` is the fourth of the same family and the first that is not ours. Measured
100
- // 2026-09-20: `npm publish --dry-run` — the command the publish playbook itself prescribes — exports
101
+ // 2026-09-20: `npm publish --dry-run` — which the publish playbook prescribed until A-SPEC-794.46 — exports
101
102
  // `npm_config_dry_run=true` to `prepublishOnly`; the release gate handed it to jest; and the
102
103
  // mcp-launcher suite's own `npx -p <tarball>` then installed NOTHING, so the handshake returned null
103
104
  // and the gate refused a green tree twice with "this source is not publishable". Load was suspected
@@ -105,7 +106,9 @@ function cleanSubprocessEnv(env = process.env) {
105
106
  // "Do nothing" is the one npm setting that contradicts what an evidence run is for. It is named, not
106
107
  // swept: a `/^npm_config_/` sweep would take the registry, the cache and the proxy with it, and a
107
108
  // suite behind a private registry would go red for a reason that has nothing to do with the tree.
108
- const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL', 'NPM_CONFIG_DRY_RUN']);
109
+ // @implements A-SPEC-128.14 — V1: `PYTEST_ADDOPTS` narrowed a full run (`-k`, reviewer B M1); a test runner never takes it.
110
+ // @implements A-SPEC-128.15 — P3: nor `PYTEST_PLUGINS`, which loads a plugin the project did not declare.
111
+ const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL', 'NPM_CONFIG_DRY_RUN', 'PYTEST_ADDOPTS', 'PYTEST_PLUGINS']);
109
112
  function cleanTestEnv(env = process.env) {
110
113
  const cleaned = cleanSubprocessEnv(env);
111
114
  for (const k of Object.keys(cleaned)) {
@@ -116,14 +119,32 @@ function cleanTestEnv(env = process.env) {
116
119
  }
117
120
  /** The marker directory that makes a directory a Holmes-Kit project. */
118
121
  exports.MARKER = '.ax';
122
+ /**
123
+ * @implements A-SPEC-102.31 — the one rule of what a project is: `dir/.ax` is a directory, a link to one included. The
124
+ * file system's own case rule applies (macOS answers `.AX` for `.ax`). A regular file named `.ax` is no project: it made a
125
+ * new catalog boundary (A, N5). resolveProjectRoot and the autonomy scope search both ask this.
126
+ */
127
+ function isProjectDir(dir, opts = {}) {
128
+ try {
129
+ return fs.statSync(path.join(dir, exports.MARKER)).isDirectory();
130
+ }
131
+ catch (e) {
132
+ // @implements A-SPEC-102.32 — strict (the catalog union): only an absent `.ax` is no project; one that cannot be
133
+ // stat'ed (a parent closed with chmod 000) dropped its additions silently while doctor said PASS (A, low 4)
134
+ const code = e.code;
135
+ if (opts.strict === true && code !== 'ENOENT' && code !== 'ENOTDIR')
136
+ throw e;
137
+ return false;
138
+ }
139
+ }
119
140
  /**
120
141
  * The one canonical spelling of an existing path.
121
142
  *
122
143
  * `fs.realpathSync.native`, not `fs.realpathSync`. The JS implementation resolves symlinks only;
123
- * on Windows it leaves 8.3 short-name aliases (`C:\Users\SUNGNA~1`, which is what `%TEMP%` and
144
+ * on Windows it leaves 8.3 short-name aliases (`C:\Users\FIRSTL~1`, which is what `%TEMP%` and
124
145
  * `os.tmpdir()` hand out) exactly as spelled, while `git rev-parse --show-toplevel` prints the
125
- * long name. Measured 2026-08-23: `resolveProjectRoot('C:/AI_PRO~1/AX-COD~1')` reported
126
- * `root: C:\AI_PRO~1\AX-COD~1` beside `git.topLevel: C:\ai_project\AX-Coding-Project` for ONE
146
+ * long name. Measured 2026-08-23: `resolveProjectRoot('C:/WORKSP~1/MYPROJ~1')` reported
147
+ * `root: C:\WORKSP~1\MYPROJ~1` beside `git.topLevel: C:\workspace\my-project` for ONE
127
148
  * directory, and GitChangeSource refused it as a mismatch. The native call expands both symlinks
128
149
  * and 8.3 names (a strict superset, same ENOENT behaviour), so `root` keeps the promise its type
129
150
  * makes: one spelling per directory, the spelling every path key is built from.
@@ -137,7 +158,7 @@ const canonical = exports.canonicalPath;
137
158
  * so 8.3 aliases and symlinks collapse); a path that does not exist compares by its resolved spelling.
138
159
  * `realpath` is injectable so the 8.3 scenario runs on every OS in the tests. Measured 2026-09-14
139
160
  * (WIN0200-20260914-SHORTPATH): `entityStoreBinding` compared JS `fs.realpathSync` output against a
140
- * native-canonical root, so a workspace entered as `C:\Users\SUNGNA~1\…` was refused as foreign.
161
+ * native-canonical root, so a workspace entered as `C:\Users\FIRSTL~1\…` was refused as foreign.
141
162
  */
142
163
  function sameCanonicalDirectory(a, b, realpath = exports.canonicalPath) {
143
164
  const spell = (p) => { try {
@@ -199,7 +220,7 @@ function resolveProjectRoot(dir, opts = {}) {
199
220
  const insideAx = (p) => p.split(path.sep).some((seg) => seg.toLowerCase() === exports.MARKER.toLowerCase());
200
221
  let found;
201
222
  for (let cur = start;; cur = path.dirname(cur)) {
202
- if (!insideAx(cur) && fs.existsSync(path.join(cur, exports.MARKER))) {
223
+ if (!insideAx(cur) && isProjectDir(cur)) {
203
224
  found = cur;
204
225
  break;
205
226
  }
@@ -9,6 +9,25 @@ export interface RunRecord {
9
9
  export declare const runsDir: (main: string) => string;
10
10
  /** The main checkout behind `dir`: a linked worktree's `.git` pointer leads to the common git directory's parent. */
11
11
  export declare function mainCheckoutOf(dir: string): string;
12
+ /**
13
+ * The checkout holding `dir` (`top`, the first directory upward with a `.git` entry; `dir` itself when none) and its
14
+ * main checkout. @implements A-SPEC-102.29 — the commondir is read only as a regular file of at most 4 KiB (a FIFO held
15
+ * the read open). @implements A-SPEC-102.30 (item 8) — the `.git` pointer and the commondir are each read on one
16
+ * descriptor, non-blocking and checked by fstat. `strict` (the harness catalog's root): a pointer or a commondir that
17
+ * exists but cannot be read so throws, naming the path. @implements A-SPEC-102.32 — non-strict (the runs' reading) is
18
+ * that of before 102.30, and it is not "not a worktree" in every case: a pointer it cannot open throws (EACCES), a
19
+ * pointer it reads but cannot follow, or a commondir it cannot read (a link), answers the worktree as its own main.
20
+ * Neither reading tells a forged checkout from a real one (the Limits of A-SPEC-102.32 name eight forms).
21
+ * @implements A-SPEC-102.33 — and a pointer `gitdir: <any directory>/.git` with no commondir makes that directory, the
22
+ * one the agent chose, the main checkout: its runs, config and ledgers are read and written (the reading of before
23
+ * 102.30; the fix waits for the owner's decision 1-c).
24
+ */
25
+ export declare function checkoutOf(dir: string, opts?: {
26
+ strict?: boolean;
27
+ }): {
28
+ top: string;
29
+ main: string;
30
+ };
12
31
  export declare const newRunId: (now: Date, rand: () => string) => string;
13
32
  export declare const keyHash: (key: string) => string;
14
33
  export declare function writeRun(main: string, rec: RunRecord): string;