@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,263 @@
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.ActError = exports.LOCK_STAGING_STALE_MS = exports.LOCK_HELD_MESSAGE = exports.LockError = void 0;
37
+ exports.isLockToken = isLockToken;
38
+ exports.acquireOwnedLock = acquireOwnedLock;
39
+ exports.recoverOwnedLock = recoverOwnedLock;
40
+ // @implements A-SPEC-245.8, A-SPEC-245.10, A-SPEC-245.11
41
+ /**
42
+ * An owned lock (A-SPEC-633, A-SPEC-638) behind a locator: the protocol the entity store lock and the workspace spend
43
+ * lock share. The spend lock's policy is spend-lock.ts; the entity store's is in entity-transaction.ts.
44
+ *
45
+ * - Acquire: the owner record is written inside a private staging directory that is renamed into the lock path, so a
46
+ * contender sees no lock or a complete one. An existing directory is busy whatever it holds.
47
+ * - Release: only by the holder whose token is in the owner record and whose directory inode is unchanged; the
48
+ * directory is renamed into the retired namespace and its known contents removed.
49
+ * - Recovery: a successor-generation claim published by exclusive create retires a dead generation. A live holder is
50
+ * never touched.
51
+ *
52
+ * Every file operation goes through the LockFs port, and the RecoveryPolicy is one validator and one liveness
53
+ * judgement per kind. Errors are LockError with a code and a site and a neutral message; a store translates them.
54
+ *
55
+ * Limits: one host and a local file system; no fsync, so visibility to concurrent processes is guaranteed and ordering
56
+ * across a power loss is not.
57
+ */
58
+ const path = __importStar(require("node:path"));
59
+ const node_crypto_1 = require("node:crypto");
60
+ class LockError extends Error {
61
+ code;
62
+ site;
63
+ holmesRefusal = true;
64
+ constructor(code, site, message) {
65
+ super(message);
66
+ this.code = code;
67
+ this.site = site;
68
+ this.name = 'LockError';
69
+ }
70
+ }
71
+ exports.LockError = LockError;
72
+ /** The neutral busy message of acquisition; a store may say it in its own words. */
73
+ exports.LOCK_HELD_MESSAGE = 'The lock is held by another or an interrupted operation.';
74
+ /** Age after which a `.staging-*` entry beside the locks is treated as abandoned by a publisher that died before its rename (A-SPEC-633). */
75
+ exports.LOCK_STAGING_STALE_MS = 10 * 60_000;
76
+ const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
77
+ function isLockToken(t) { return typeof t === 'string' && UUID_V4.test(t); }
78
+ /** Remove `.staging-*` entries older than the bound: a publisher that died before its rename. Younger entries may belong to a live acquirer; lock directories are never touched. */
79
+ function sweepAbandonedStaging(lfs, locks) {
80
+ let names;
81
+ try {
82
+ names = lfs.list(locks);
83
+ }
84
+ catch {
85
+ return;
86
+ }
87
+ for (const name of names) {
88
+ if (!name.startsWith('.staging-'))
89
+ continue;
90
+ const entry = path.join(locks, name);
91
+ try {
92
+ const s = lfs.stat(entry);
93
+ if (s && Date.now() - s.mtimeMs > exports.LOCK_STAGING_STALE_MS)
94
+ lfs.removeTree(entry);
95
+ }
96
+ catch { /* raced with its owner or already gone */ }
97
+ }
98
+ }
99
+ function retire(lfs, layout, dir, expected, owned) {
100
+ const current = lfs.stat(dir);
101
+ if (current?.dev !== expected.dev || current?.ino !== expected.ino)
102
+ throw new LockError('unknown-owner', 'retire', 'Lock directory changed before retirement.');
103
+ for (const name of lfs.list(dir))
104
+ if (!owned.has(path.join(dir, name)))
105
+ throw new LockError('cleanup-conflict', 'retire', 'Unknown lock contents must be preserved.');
106
+ const retired = lfs.directory(layout.retired, true);
107
+ const destination = path.join(retired, (0, node_crypto_1.randomUUID)());
108
+ if (lfs.stat(destination))
109
+ throw new LockError('retirement-conflict', 'retire', 'Lock retirement destination is occupied.');
110
+ // Release the active pathname in one step, retaining owner evidence until then.
111
+ lfs.rename(dir, destination);
112
+ for (const file of owned)
113
+ lfs.unlink(path.join(destination, path.basename(file)));
114
+ lfs.removeDir(destination);
115
+ }
116
+ /**
117
+ * Take the lock once, without waiting: busy (`lock-busy`, site `acquire`) when it exists in any form. Returns the
118
+ * release function, which retires the lock only while it is still this holder's generation.
119
+ */
120
+ function acquireOwnedLock(lfs, layout, record) {
121
+ const locks = lfs.directory(layout.parent, true);
122
+ const dir = path.join(locks, layout.name);
123
+ sweepAbandonedStaging(lfs, locks);
124
+ // An existing directory is busy whatever it holds: rename(2) would silently REPLACE an empty one, and an empty lock
125
+ // directory is exactly the legacy/foreign state that must be preserved for explicit recovery.
126
+ if (lfs.stat(dir))
127
+ throw new LockError('lock-busy', 'acquire', exports.LOCK_HELD_MESSAGE);
128
+ const staging = path.join(locks, '.staging-' + (0, node_crypto_1.randomUUID)());
129
+ lfs.makeDir(staging);
130
+ try {
131
+ // No fsync: the guarantee is atomic visibility to concurrent processes (the rename), not durability across power
132
+ // loss; measured 2026-09-13, an fsync per acquisition cut throughput from thousands to ~76 per second.
133
+ lfs.writeNew(path.join(staging, 'owner.json'), JSON.stringify(record));
134
+ lfs.renameNew(staging, dir);
135
+ }
136
+ catch (e) {
137
+ try {
138
+ lfs.removeTree(staging);
139
+ }
140
+ catch { /* best effort */ }
141
+ const code = e.code;
142
+ if (code === 'EEXIST' || code === 'ENOTEMPTY' || code === 'EPERM')
143
+ throw new LockError('lock-busy', 'acquire', exports.LOCK_HELD_MESSAGE);
144
+ throw e;
145
+ }
146
+ const ownership = lfs.stat(dir);
147
+ return () => {
148
+ const current = lfs.stat(dir);
149
+ if (current?.dev === ownership.dev && current?.ino === ownership.ino) {
150
+ const ownerFile = path.join(dir, 'owner.json');
151
+ const owner = lfs.readBytes(ownerFile);
152
+ if (owner && JSON.parse(owner.toString('utf8')).token === record.token)
153
+ retire(lfs, layout, dir, ownership, new Set([ownerFile]));
154
+ }
155
+ };
156
+ }
157
+ /** An error `act` threw, carried through the protocol's own error handling untouched. */
158
+ class ActError extends Error {
159
+ inner;
160
+ constructor(inner) {
161
+ super('act failed');
162
+ this.inner = inner;
163
+ }
164
+ }
165
+ exports.ActError = ActError;
166
+ /**
167
+ * Claim a dead owner's immutable generation without deleting or replacing its lock, run `act`, and retire the lock.
168
+ * Without a lock, `act` runs under a fresh acquisition (`fresh`). An error `act` throws arrives as ActError, so the
169
+ * caller can tell it from the protocol's own.
170
+ */
171
+ function recoverOwnedLock(lfs, layout, policy, act, fresh) {
172
+ const run = () => { try {
173
+ return act();
174
+ }
175
+ catch (e) {
176
+ throw new ActError(e);
177
+ } };
178
+ const dir = lfs.directory(path.join(layout.parent, layout.name));
179
+ if (!lfs.stat(dir)) {
180
+ const release = fresh();
181
+ try {
182
+ return run();
183
+ }
184
+ finally {
185
+ release();
186
+ }
187
+ }
188
+ const directory = lfs.stat(dir), records = [], tokens = new Set();
189
+ let file = path.join(dir, 'owner.json');
190
+ for (let depth = 0; depth < 128; depth++) {
191
+ const bytes = lfs.readBytes(file);
192
+ let owner;
193
+ try {
194
+ owner = JSON.parse(bytes?.toString('utf8') ?? 'null');
195
+ }
196
+ catch {
197
+ throw new LockError('unknown-owner', 'inspect', 'Malformed lock ownership must be preserved.');
198
+ }
199
+ const first = records.length === 0;
200
+ if (!policy.valid(owner, first) || (first && owner.released) || tokens.has(owner.token)) {
201
+ throw new LockError('unknown-owner', 'inspect', 'Invalid or cyclic lock ownership must be preserved.');
202
+ }
203
+ tokens.add(owner.token);
204
+ records.push(file);
205
+ if (!owner.released)
206
+ policy.judgeDead(owner, first);
207
+ const legacySuccessor = path.join(dir, 'successor-' + owner.token + '.json');
208
+ const claims = lfs.directory(layout.claims, true);
209
+ const externalSuccessor = path.join(claims, 'successor-' + owner.token + '.json');
210
+ if (lfs.stat(legacySuccessor) && lfs.stat(externalSuccessor))
211
+ throw new LockError('unknown-owner', 'inspect', 'Conflicting ownership generations must be preserved.');
212
+ const successor = lfs.stat(legacySuccessor) ? legacySuccessor : externalSuccessor;
213
+ if (lfs.stat(successor)) {
214
+ file = successor;
215
+ continue;
216
+ }
217
+ const claim = policy.claim(owner.token);
218
+ const claimText = JSON.stringify(claim);
219
+ const successorRelative = path.relative(lfs.directory('.'), successor);
220
+ try {
221
+ lfs.publish(successorRelative, claimText);
222
+ }
223
+ catch (e) {
224
+ if (e.code === 'EEXIST')
225
+ throw new LockError('lock-busy', 'recover-claim', 'Another recovery owns this generation.');
226
+ throw e;
227
+ }
228
+ records.push(successor);
229
+ try {
230
+ const current = lfs.stat(dir);
231
+ if (current?.dev !== directory.dev || current?.ino !== directory.ino)
232
+ throw new LockError('unknown-owner', 'inspect', 'Lock directory changed during recovery claim.');
233
+ // Only known generation files and their same-inode publication hardlinks belong to us. External generation
234
+ // claims survive retirement so delayed contenders cannot claim an old token against a newer directory at the
235
+ // reused active path.
236
+ const localRecords = records.filter(r => path.dirname(r) === dir);
237
+ const owned = new Set(localRecords);
238
+ const inodes = localRecords.map(r => lfs.stat(r));
239
+ for (const name of lfs.list(dir)) {
240
+ const candidate = path.join(dir, name);
241
+ if (owned.has(candidate))
242
+ continue;
243
+ const s = lfs.stat(candidate);
244
+ if (s && lfs.isOwnTransient(name) && s.isFile() && !s.isSymbolicLink() && inodes.some(i => i.dev === s.dev && i.ino === s.ino))
245
+ owned.add(candidate);
246
+ else
247
+ throw new LockError('cleanup-conflict', 'retire', 'Unknown lock contents are preserved for inspection.');
248
+ }
249
+ const result = run();
250
+ retire(lfs, layout, dir, directory, owned);
251
+ return result;
252
+ }
253
+ catch (e) {
254
+ // A failed live recovery must not strand its PID as an active owner forever. Mark only our generation released;
255
+ // another claimant appends a new generation.
256
+ const now = lfs.readBytes(successor);
257
+ if (now?.toString('utf8') === claimText)
258
+ lfs.replace(successorRelative, claimText, JSON.stringify({ ...claim, released: true }));
259
+ throw e;
260
+ }
261
+ }
262
+ throw new LockError('unknown-owner', 'inspect', 'Recovery ownership chain exceeds the supported inspection bound.');
263
+ }
@@ -0,0 +1,2 @@
1
+ import { LockFs } from './owned-lock';
2
+ export declare function plainLockFs(root: string, isOwnTransient: (name: string) => boolean): LockFs;
@@ -0,0 +1,126 @@
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.plainLockFs = plainLockFs;
37
+ // @implements A-SPEC-794.6
38
+ /**
39
+ * The plain LockFs of the owned-lock protocol under one root (moved out of request-lock.ts by A-SPEC-794.6): canonical
40
+ * relative locators, no symlinked directories, regular files only, exclusive publication. spend-lock.ts keeps its own
41
+ * copy until A-SPEC-245.x is next amended (backlog).
42
+ */
43
+ const fs = __importStar(require("node:fs"));
44
+ const path = __importStar(require("node:path"));
45
+ const node_crypto_1 = require("node:crypto");
46
+ const owned_lock_1 = require("./owned-lock");
47
+ function plainLockFs(root, isOwnTransient) {
48
+ const stat = (file) => {
49
+ try {
50
+ return fs.lstatSync(file);
51
+ }
52
+ catch (e) {
53
+ if (e.code === 'ENOENT')
54
+ return undefined;
55
+ throw e;
56
+ }
57
+ };
58
+ const directory = (relative, create = false) => {
59
+ let current = root;
60
+ for (const part of relative.replace(/\\/g, '/').split('/').filter((p) => p !== '' && p !== '.')) {
61
+ if (part === '..')
62
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock paths must be canonical relative locators.');
63
+ current = path.join(current, part);
64
+ if (create && !stat(current)) {
65
+ try {
66
+ fs.mkdirSync(current);
67
+ }
68
+ catch (e) {
69
+ if (e.code !== 'EEXIST')
70
+ throw e;
71
+ }
72
+ }
73
+ const s = stat(current);
74
+ if (s && (!s.isDirectory() || s.isSymbolicLink()))
75
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock directories must not be symlinks or non-directories.');
76
+ }
77
+ return current;
78
+ };
79
+ const readBytes = (file) => {
80
+ const s = stat(file);
81
+ if (!s)
82
+ return undefined;
83
+ if (!s.isFile())
84
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock records must be regular files.');
85
+ try {
86
+ return fs.readFileSync(file);
87
+ }
88
+ catch (e) {
89
+ if (e.code === 'ENOENT')
90
+ return undefined;
91
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', `A lock record that cannot be read (${e.code ?? 'error'}) is preserved for inspection.`);
92
+ }
93
+ };
94
+ return {
95
+ stat, directory, readBytes,
96
+ publish: (relative, bytes) => {
97
+ const dir = directory(path.dirname(relative), true);
98
+ const temp = path.join(dir, `.lock-${(0, node_crypto_1.randomUUID)()}.tmp`);
99
+ fs.writeFileSync(temp, bytes, { flag: 'wx', mode: 0o600 });
100
+ try {
101
+ fs.linkSync(temp, path.join(dir, path.basename(relative)));
102
+ }
103
+ finally {
104
+ fs.unlinkSync(temp);
105
+ }
106
+ },
107
+ rename: (from, to) => fs.renameSync(from, to),
108
+ renameNew: (from, to) => fs.renameSync(from, to),
109
+ appendLine: (file, line) => { directory(path.relative(root, path.dirname(file)), true); fs.appendFileSync(file, line + '\n'); },
110
+ replace: (relative, before, after) => {
111
+ const file = path.join(root, relative);
112
+ if (fs.readFileSync(file, 'utf8') !== before)
113
+ return;
114
+ const temp = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
115
+ fs.writeFileSync(temp, after, { flag: 'wx', mode: 0o600 });
116
+ fs.renameSync(temp, file);
117
+ },
118
+ list: (dir) => fs.readdirSync(dir),
119
+ makeDir: (dir) => fs.mkdirSync(dir),
120
+ writeNew: (file, bytes) => fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 }),
121
+ unlink: (file) => fs.unlinkSync(file),
122
+ removeDir: (dir) => fs.rmdirSync(dir),
123
+ removeTree: (dir) => fs.rmSync(dir, { recursive: true, force: true }),
124
+ isOwnTransient,
125
+ };
126
+ }
@@ -0,0 +1,85 @@
1
+ import { LockLayout } from './owned-lock';
2
+ import { SpendIdentity } from './spend-lock';
3
+ export declare const REQUEST_LOCKS_DIR = ".ax/state/request-locks";
4
+ export declare const REQUEST_CLAIMS_DIR = ".ax/state/request-lock-claims";
5
+ export declare const REQUEST_RETIRED_DIR = ".ax/state/request-retired-locks";
6
+ export declare const REQUEST_LEAKS_FILE = ".ax/state/request-lock-leaks.jsonl";
7
+ export declare function requestLockLayout(id: string): LockLayout;
8
+ /** A holder whose liveness cannot be judged is recovered once held longer than this many times its bound. */
9
+ export declare const AGE_FACTOR = 4;
10
+ /** A claim of a claimant whose liveness cannot be judged is recovered once older than this. */
11
+ export declare const CLAIM_STALE_MS = 60000;
12
+ /** The holder's lock was recovered, replaced or claimed by a successor: it must write nothing. */
13
+ export declare class FenceLost extends Error {
14
+ readonly holmesRefusal = true;
15
+ constructor(message: string);
16
+ }
17
+ /** A publish found its name taken; the existing file is untouched. */
18
+ export declare class PublishConflict extends Error {
19
+ readonly holmesRefusal = true;
20
+ constructor(message: string);
21
+ }
22
+ /** The file system refused the hard link a publish needs; nothing is copied in its place. */
23
+ export declare class PublishUnsupported extends Error {
24
+ readonly holmesRefusal = true;
25
+ constructor(message: string);
26
+ }
27
+ export interface Fence {
28
+ /** Throws FenceLost unless this holder still owns the lock. */
29
+ check(): void;
30
+ /** check(), then `fn`. */
31
+ write<T>(fn: () => T): T;
32
+ /** check(), then publish `bytes` at `dirRel/name` without replacing an existing file. */
33
+ publish(dirRel: string, name: string, bytes: string): void;
34
+ }
35
+ export interface RequestLockOptions {
36
+ budgetMs: number;
37
+ /** The step bound of the work held under the lock. */
38
+ boundMs?: number;
39
+ identity?: SpendIdentity;
40
+ platform?: NodeJS.Platform;
41
+ /** Liveness of another pid; injected by tests. */
42
+ probe?: (pid: number) => 'dead' | 'alive';
43
+ }
44
+ export interface RequestHolder {
45
+ kind: 'request';
46
+ token: string;
47
+ pid: number;
48
+ host: string | null;
49
+ bootId: string | null;
50
+ acquiredAt: string;
51
+ boundMs: number;
52
+ id: string;
53
+ }
54
+ /**
55
+ * Take the request lock of `id` within `opts.budgetMs`, run `act` with the fence, and release. Busy past the budget is
56
+ * `lock-busy`; this process's own hold of the id is `lock-leak`; an id outside `req-<12 hex>`, or a root without `.ax`,
57
+ * is refused before any file is touched. A release that fails after `act` returned does not hide the result; when
58
+ * `act` threw, its error is the one thrown.
59
+ */
60
+ export declare function withRequestLock<T>(root: string, id: string, opts: RequestLockOptions, act: (fence: Fence) => T): T;
61
+ /** The held request locks with a readable holder, for doctor. */
62
+ export declare function requestLockHolders(root: string): RequestHolder[];
63
+ export type RequestOperatorRecovery = {
64
+ recovered: RequestHolder;
65
+ reason: string;
66
+ } | {
67
+ refused: string;
68
+ } | {
69
+ nothing: true;
70
+ };
71
+ /**
72
+ * The operator's recovery of one request lock, by `recoverSpendLockAsOperator`'s rules: a dead holder is recovered;
73
+ * an unjudgeable one needs `confirmHolderDead`; an answering one needs it and a hold longer than 4x its bound; this
74
+ * process's own hold is refused; a lock that changed hands since it was read is refused.
75
+ */
76
+ export declare function recoverRequestLockAsOperator(root: string, id: string, opts: {
77
+ confirmHolderDead: boolean;
78
+ expectToken?: string | null;
79
+ identity?: SpendIdentity;
80
+ platform?: NodeJS.Platform;
81
+ now?: () => number;
82
+ probe?: (pid: number) => 'dead' | 'alive';
83
+ }): RequestOperatorRecovery;
84
+ /** 1 + the largest `lockEpoch` among the events of `id` that is a safe integer in [0, 2^32), or 1 when there is none. */
85
+ export declare function nextLockEpoch(events: ReadonlyArray<Record<string, unknown>>, id: string): number;