@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,522 @@
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.TrustedLedgerStore = exports.CommittedReadError = exports.TOOL_ACTORS = void 0;
37
+ exports.headRefOf = headRefOf;
38
+ exports.headCommitOf = headCommitOf;
39
+ exports.committedLedgerTexts = committedLedgerTexts;
40
+ exports.trustedActor = trustedActor;
41
+ exports.trustedLedgerEvents = trustedLedgerEvents;
42
+ exports.ownLedgerShortened = ownLedgerShortened;
43
+ exports.approvedSeals = approvedSeals;
44
+ exports.recordedPairsPort = recordedPairsPort;
45
+ exports.describeIgnored = describeIgnored;
46
+ // @implements A-SPEC-222.9, A-SPEC-222.10, A-SPEC-222.12, A-SPEC-222.13
47
+ /**
48
+ * The ledger events a successor, a seal or a provenance proof may be taken from (H1 of the 2026-10-25 review, SD1
49
+ * finding 2; A-SPEC-222.10 H-A, H-C, M-1): one port for every reader that needs trust, so none opens the ledger itself.
50
+ * It reads through the ledger store (A-SPEC-150), never past it. An event counts only when all three hold:
51
+ * - it is in this writer's own replica file, or it stands in the `HEAD:` blob of another replica's file (the worktree
52
+ * and the index of another replica are never read: a staged file, or a row appended after the commit, is not HEAD);
53
+ * - its chain verifies (this writer's file in the worktree, another's as committed); a chain that does not is ignored
54
+ * whole;
55
+ * - its actor is a tool, or its authorization is exactly `<its actor>:<12 hex>` as authorizationRef writes it; an
56
+ * `unattested:` actor or authorization never counts.
57
+ * Everything else is ignored and named, so the refusal that follows can say why. Residual risk, stated in the spec:
58
+ * without an out-of-band secret, code running as the same user can append a well-formed row to this writer's own file,
59
+ * and a commit (an act an agent can take) puts a forged replica into HEAD.
60
+ */
61
+ const fs = __importStar(require("node:fs"));
62
+ const path = __importStar(require("node:path"));
63
+ const ledger_store_1 = require("./ledger-store");
64
+ const provenance_chain_1 = require("./provenance-chain");
65
+ const bounded_io_1 = require("../project/bounded-io");
66
+ const succession_1 = require("../spec/succession");
67
+ /** Every literal actor production code appends as a tool (the reader census holds the list to the code). */
68
+ exports.TOOL_ACTORS = ['holmes-kit', 'holmes-kit init', 'holmes-spec-seam', 'spec_renumber', 'spec_reconcile'];
69
+ const TOOL_ACTOR = new RegExp(`^(?:${exports.TOOL_ACTORS.map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')}|full-autonomy:.+)$`);
70
+ const SUCCESSION_KINDS = new Set(['spec-retired', 'spec-superseded']);
71
+ const fileName = (replicaId) => (replicaId === null ? 'provenance.jsonl' : `provenance.${replicaId}.jsonl`);
72
+ /** The project root a ledger directory belongs to: `<root>/.ax/ledger` gives `<root>`, any other directory itself. */
73
+ function rootOfLedger(dir) {
74
+ const abs = path.resolve(dir);
75
+ return path.basename(abs) === 'ledger' && path.basename(path.dirname(abs)) === '.ax' ? path.resolve(abs, '..', '..') : abs;
76
+ }
77
+ const OID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
78
+ /**
79
+ * @implements A-SPEC-222.12 (M1) — the commit HEAD names, read from the git directory's own files with no child: a
80
+ * `.git` directory or a linked worktree's `.git` file (`gitdir:`), the worktree's `commondir`, and a loose ref or
81
+ * `packed-refs`. Only at a root that holds `.git` (the paths are then the repository's own); null otherwise.
82
+ */
83
+ /** @implements A-SPEC-222.14 — the worktree's git directory, its common directory and the HEAD line, read once. */
84
+ function gitDirsOf(root) {
85
+ try {
86
+ const dotGit = path.join(root, '.git');
87
+ const st = fs.lstatSync(dotGit);
88
+ let gitDir;
89
+ if (st.isDirectory())
90
+ gitDir = dotGit;
91
+ else if (st.isFile()) {
92
+ const m = /^gitdir: (.+)$/m.exec(fs.readFileSync(dotGit, 'utf8'));
93
+ if (!m)
94
+ return null;
95
+ gitDir = path.resolve(root, m[1].trim());
96
+ }
97
+ else
98
+ return null;
99
+ let common = gitDir;
100
+ try {
101
+ common = path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim());
102
+ }
103
+ catch { /* not a linked worktree */ }
104
+ return { gitDir, common, head: fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim() };
105
+ }
106
+ catch {
107
+ return null;
108
+ }
109
+ }
110
+ /** @implements A-SPEC-222.14 — the ref HEAD names (`refs/heads/feat`), `detached` for a commit, null with no `.git` here. */
111
+ function headRefOf(root) {
112
+ const dirs = gitDirsOf(root);
113
+ if (dirs === null)
114
+ return null;
115
+ const m = /^ref: (refs\/[^\s]+)$/.exec(dirs.head);
116
+ return m ? m[1] : 'detached';
117
+ }
118
+ function headCommitOf(root) {
119
+ try {
120
+ const dirs = gitDirsOf(root);
121
+ if (dirs === null)
122
+ return null;
123
+ const { gitDir, common, head } = dirs;
124
+ if (OID.test(head))
125
+ return head;
126
+ const m = /^ref: (refs\/[^\s]+)$/.exec(head);
127
+ if (!m || m[1].split('/').some((s) => s === '..' || s === ''))
128
+ return null;
129
+ for (const dir of [gitDir, common]) {
130
+ try {
131
+ const id = fs.readFileSync(path.join(dir, ...m[1].split('/')), 'utf8').trim();
132
+ if (OID.test(id))
133
+ return id;
134
+ }
135
+ catch { /* not loose here */ }
136
+ }
137
+ const packed = fs.readFileSync(path.join(common, 'packed-refs'), 'utf8');
138
+ for (const line of packed.split('\n')) {
139
+ const [id, ref] = line.trim().split(' ');
140
+ if (ref === m[1] && OID.test(id ?? ''))
141
+ return id;
142
+ }
143
+ return null;
144
+ }
145
+ catch {
146
+ return null;
147
+ }
148
+ }
149
+ /**
150
+ * @implements A-SPEC-222.12 (M1) — the text of ledger files as they stand in HEAD (`rels` from the root), read with one
151
+ * `git cat-file --batch` for all of them and memoised per process by the commit; null for a file HEAD does not hold. The
152
+ * Stop hook's rollback check and the trusted-events port share it (one git child per new commit, not one per replica).
153
+ * A root that holds no `.git`, or a HEAD its files do not name, is read per file and not memoised.
154
+ */
155
+ const headMemo = new Map();
156
+ /** @implements A-SPEC-222.13 — HEAD could not be read: never "absent", so every reader fails closed on it. */
157
+ class CommittedReadError extends Error {
158
+ constructor(m) { super(m); this.name = 'CommittedReadError'; }
159
+ }
160
+ exports.CommittedReadError = CommittedReadError;
161
+ function committedLedgerTexts(root, rels) {
162
+ const commit = headCommitOf(root);
163
+ const out = new Map();
164
+ // @implements A-SPEC-222.13 (low d) — git names the paths NFC under core.precomposeunicode
165
+ const asked = (rel) => rel.normalize('NFC');
166
+ if (commit === null) {
167
+ for (const rel of rels) {
168
+ const r = (0, bounded_io_1.gitOnceBuffer)(root, ['-c', 'core.fsmonitor=false', 'cat-file', '-p', `HEAD:./${asked(rel)}`], 'repo', { pinned: (0, bounded_io_1.judgmentPins)() });
169
+ if (r.error !== undefined || r.status === null)
170
+ throw new CommittedReadError(`git could not read HEAD:${rel}`);
171
+ // a path HEAD does not hold (or no HEAD) answers 128 with nothing on stdout: absent, not unread
172
+ out.set(rel, r.status === 0 ? r.stdout.toString('utf8') : null);
173
+ }
174
+ return out;
175
+ }
176
+ const key = `${root}\u0000${commit}`;
177
+ const memo = headMemo.get(key) ?? new Map();
178
+ // one batch per commit: a miss also fetches every chain file the ledger directory holds, since the port, the seam and
179
+ // the Stop rollback check each ask for a different subset (A-SPEC-222.13 low a)
180
+ let missing = rels.filter((r) => !memo.has(r));
181
+ if (missing.length > 0) {
182
+ try {
183
+ const ledgerDir = path.join(root, '.ax', 'ledger');
184
+ const all = fs.readdirSync(ledgerDir).filter((n) => /^provenance(?:\.[^/]+)?\.jsonl$/.test(n)).map((n) => `.ax/ledger/${n}`);
185
+ // this writer's own file too, though the worktree no longer holds it: a deleted ledger is what the seam asks about
186
+ try {
187
+ all.push(`.ax/ledger/${fileName(new ledger_store_1.FileLedgerStore(ledgerDir).replicaId())}`);
188
+ }
189
+ catch { /* no replica id */ }
190
+ missing = [...new Set([...missing, ...all.filter((r) => !memo.has(r))])];
191
+ }
192
+ catch { /* no ledger directory: only what was asked */ }
193
+ }
194
+ if (missing.length > 0) {
195
+ const r = (0, bounded_io_1.gitOnceBuffer)(root, ['-c', 'core.fsmonitor=false', 'cat-file', '--batch'], 'repo', { pinned: (0, bounded_io_1.judgmentPins)(), input: missing.map((m) => `${commit}:${asked(m)}`).join('\n') + '\n' });
196
+ if (r.status !== 0 || r.error !== undefined)
197
+ throw new CommittedReadError(`git cat-file could not read the ledger at ${commit.slice(0, 12)}`);
198
+ // @implements A-SPEC-222.13 — cut at byte offsets of the bytes git wrote; a header that does not parse is a read
199
+ // failure, and nothing of a failed read is memoised
200
+ const buf = r.stdout;
201
+ const read = new Map();
202
+ let at = 0;
203
+ for (const rel of missing) {
204
+ const nl = buf.indexOf(10, at);
205
+ if (nl < 0)
206
+ throw new CommittedReadError(`git cat-file answered short for ${rel}`);
207
+ const header = buf.subarray(at, nl).toString('utf8').split(' ');
208
+ at = nl + 1;
209
+ if (header.length === 2 && header[1] === 'missing') {
210
+ read.set(rel, null);
211
+ continue;
212
+ }
213
+ if (header.length !== 3 || header[1] !== 'blob' || !/^\d+$/.test(header[2]))
214
+ throw new CommittedReadError(`git cat-file answered an unexpected header for ${rel}`);
215
+ const size = Number(header[2]);
216
+ if (at + size > buf.length)
217
+ throw new CommittedReadError(`git cat-file answered short for ${rel}`);
218
+ read.set(rel, buf.subarray(at, at + size).toString('utf8'));
219
+ at += size + 1;
220
+ }
221
+ for (const [rel, text] of read)
222
+ memo.set(rel, text);
223
+ if (headMemo.size > 64)
224
+ headMemo.clear();
225
+ headMemo.set(key, memo);
226
+ }
227
+ for (const rel of rels)
228
+ out.set(rel, memo.get(rel) ?? null);
229
+ return out;
230
+ }
231
+ function realTrustDeps(root, ledgerDir = path.join(root, '.ax', 'ledger'), givenId) {
232
+ const store = new ledger_store_1.FileLedgerStore(ledgerDir, givenId);
233
+ return {
234
+ chains: () => store.chains().map((c) => c.replicaId),
235
+ ownReplica: () => { try {
236
+ return store.replicaId();
237
+ }
238
+ catch {
239
+ return null;
240
+ } },
241
+ heads: (rels) => {
242
+ const out = new Map();
243
+ for (const [rel, text] of committedLedgerTexts(root, rels)) {
244
+ let events = null;
245
+ if (text !== null) {
246
+ try {
247
+ events = (0, provenance_chain_1.parseLedgerLines)(text, rel, { throwOnCorruption: false });
248
+ }
249
+ catch {
250
+ events = null;
251
+ }
252
+ }
253
+ out.set(rel, events);
254
+ }
255
+ return out;
256
+ },
257
+ broken: () => new Set(store.verifyAll().broken.filter((b) => (b.kind ?? 'chain') === 'chain').map((b) => b.replicaId)),
258
+ events: () => store.loadAll(),
259
+ key: () => process.env.HOLMES_LEDGER_KEY || undefined,
260
+ };
261
+ }
262
+ /** Whether a row's actor and authorization are a tool's or a well-formed person's (M-1). */
263
+ function trustedActor(e) {
264
+ const actor = String(e.actor ?? '');
265
+ if (actor.startsWith('unattested:'))
266
+ return false;
267
+ if (TOOL_ACTOR.test(actor))
268
+ return true;
269
+ const a = typeof e.authorization === 'string' ? e.authorization : '';
270
+ return a.startsWith(`${actor}:`) && /^[0-9a-f]{12}$/.test(a.slice(actor.length + 1)) && !/(?:^|:)unattested:/.test(a);
271
+ }
272
+ /** Every trusted event across the ledger's chains, and every event or chain that was ignored with its reason. */
273
+ function trustedLedgerEvents(root, deps = realTrustDeps(root)) {
274
+ const ignored = [];
275
+ const events = [];
276
+ let chains;
277
+ try {
278
+ chains = deps.chains();
279
+ }
280
+ catch {
281
+ return { events, ignored: [{ file: '.ax/ledger', why: 'the ledger directory cannot be read' }] };
282
+ }
283
+ if (chains.length === 0)
284
+ return { events, ignored };
285
+ const own = deps.ownReplica();
286
+ const ledgerRel = path.relative(root, path.join(root, '.ax', 'ledger')).split(path.sep).join('/');
287
+ const keep = (e, file) => {
288
+ if (trustedActor(e))
289
+ return true;
290
+ ignored.push({ file, seq: e.seq, kind: e.kind, why: `its actor ${JSON.stringify(String(e.actor).slice(0, 40))} is neither a tool nor authorized` });
291
+ return false;
292
+ };
293
+ // A-SPEC-222.12 (M1): every other replica's HEAD blob in one read
294
+ const others = chains.filter((id) => !(id !== null && id === own)).map((id) => `${ledgerRel}/${fileName(id)}`);
295
+ let heads = new Map();
296
+ let headUnread = false;
297
+ if (others.length > 0) {
298
+ try {
299
+ heads = deps.heads(others);
300
+ }
301
+ catch {
302
+ headUnread = true;
303
+ }
304
+ }
305
+ for (const id of chains) {
306
+ const file = `${ledgerRel}/${fileName(id)}`;
307
+ if (id !== null && id === own) {
308
+ // this writer's own file, in the worktree
309
+ let broken;
310
+ try {
311
+ broken = deps.broken();
312
+ }
313
+ catch {
314
+ broken = new Set([id]);
315
+ }
316
+ if (broken.has(id)) {
317
+ ignored.push({ file, why: 'its chain does not verify' });
318
+ continue;
319
+ }
320
+ let all;
321
+ try {
322
+ all = deps.events();
323
+ }
324
+ catch {
325
+ ignored.push({ file, why: 'it cannot be read' });
326
+ continue;
327
+ }
328
+ for (const e of all)
329
+ if (e.replicaId === id && keep(e, file))
330
+ events.push(e);
331
+ continue;
332
+ }
333
+ // A-SPEC-222.10 (H-A a): another replica, as committed
334
+ // A-SPEC-222.13 — a HEAD that could not be read is not "absent": the replica is ignored with that reason
335
+ if (headUnread) {
336
+ ignored.push({ file, why: 'not this writer\'s replica, and HEAD could not be read' });
337
+ continue;
338
+ }
339
+ const committed = heads.get(file) ?? null;
340
+ if (committed === null) {
341
+ ignored.push({ file, why: 'not this writer\'s replica, and HEAD does not hold it' });
342
+ continue;
343
+ }
344
+ if (!(0, provenance_chain_1.verifyChain)(committed, deps.key?.()).ok) {
345
+ ignored.push({ file, why: 'its chain in HEAD does not verify' });
346
+ continue;
347
+ }
348
+ for (const e of committed)
349
+ if (keep(e, file))
350
+ events.push({ ...e, replicaId: id });
351
+ }
352
+ const order = (e) => `${e.ts} ${e.replicaId ?? ''} ${String(e.seq).padStart(12, '0')}`;
353
+ events.sort((a, b) => (order(a) < order(b) ? -1 : order(a) > order(b) ? 1 : 0));
354
+ return { events, ignored };
355
+ }
356
+ /**
357
+ * @implements A-SPEC-222.13 — whether this writer's ledger is no longer an extension of its file in HEAD (cut to a
358
+ * prefix, emptied or deleted): the judgement the Stop hook's rollback check makes, for the spec seam too. A file HEAD
359
+ * does not hold cannot be shortened against it.
360
+ * @implements A-SPEC-222.14 — a HEAD that cannot be read is not "shortened": its CommittedReadError reaches the caller,
361
+ * which says retry (restoring from git on that advice dropped uncommitted rows). The verdict is memoised by the commit
362
+ * and the own file's size and mtime (it parsed both texts again on every read).
363
+ */
364
+ const shortenedMemo = new Map();
365
+ function ownLedgerShortened(root, ledgerDir = path.join(root, '.ax', 'ledger')) {
366
+ let own;
367
+ try {
368
+ own = new ledger_store_1.FileLedgerStore(ledgerDir).replicaId();
369
+ }
370
+ catch {
371
+ return true;
372
+ }
373
+ const file = path.join(ledgerDir, fileName(own));
374
+ const rel = path.relative(root, file).split(path.sep).join('/');
375
+ let stamp = 'absent';
376
+ try {
377
+ const st = fs.statSync(file);
378
+ stamp = `${st.size}:${st.mtimeMs}:${st.ino}`;
379
+ }
380
+ catch { /* deleted */ }
381
+ const commit = headCommitOf(root);
382
+ const key = commit === null ? null : `${root}\u0000${commit}\u0000${rel}\u0000${stamp}`;
383
+ if (key !== null && shortenedMemo.has(key))
384
+ return shortenedMemo.get(key);
385
+ const committed = committedLedgerTexts(root, [rel]).get(rel) ?? null; // CommittedReadError: the caller's retry
386
+ let verdict = false;
387
+ if (committed !== null) {
388
+ let working = '';
389
+ try {
390
+ working = fs.readFileSync(file, 'utf8');
391
+ }
392
+ catch {
393
+ working = '';
394
+ }
395
+ const { mainlineIsPrefix } = require('./ledger-rechain');
396
+ const parse = (t) => (0, provenance_chain_1.parseLedgerLines)(t, rel, { throwOnCorruption: false });
397
+ verdict = !mainlineIsPrefix(parse(committed), parse(working));
398
+ }
399
+ if (key !== null) {
400
+ if (shortenedMemo.size > 64)
401
+ shortenedMemo.clear();
402
+ shortenedMemo.set(key, verdict);
403
+ }
404
+ return verdict;
405
+ }
406
+ /** A-SPEC-222.10 (H-B) — the seals a trusted `spec-approved` event recorded, as `[id, digest]`. */
407
+ function approvedSeals(events) {
408
+ const seals = new Set();
409
+ for (const e of events) {
410
+ if (e.kind !== 'spec-approved' || !Array.isArray(e.inputs))
411
+ continue;
412
+ const [id, digest] = e.inputs.map(String);
413
+ if (id && digest)
414
+ seals.add(`${id}\u0000${digest}`);
415
+ }
416
+ return (id, digest) => seals.has(`${id}\u0000${digest}`);
417
+ }
418
+ /**
419
+ * The successor pairs and seals the trusted events record, and the ignored rows or chains that could have recorded
420
+ * one: a chain ignored whole could hold any record, so it is named; an ignored row is named when it is of a succession
421
+ * kind or a seal.
422
+ */
423
+ function recordedPairsPort(root, deps) {
424
+ const { events, ignored } = trustedLedgerEvents(root, deps);
425
+ return { recorded: (0, succession_1.recordedPairs)(events), approved: approvedSeals(events),
426
+ ignored: ignored.filter((i) => i.kind === undefined || SUCCESSION_KINDS.has(i.kind) || i.kind === 'spec-approved') };
427
+ }
428
+ /**
429
+ * A-SPEC-222.10 (H-C) — a ledger store whose reads are the trusted events only; appends and every other operation are
430
+ * the file store's. Readers that need trust construct this instead of FileLedgerStore (the reader census holds it).
431
+ */
432
+ class TrustedLedgerStore extends ledger_store_1.FileLedgerStore {
433
+ ledgerDir;
434
+ id;
435
+ memo = null;
436
+ constructor(dir, givenId) { super(dir, givenId); this.ledgerDir = dir; this.id = givenId; }
437
+ /**
438
+ * @implements A-SPEC-222.12 (low a, b) — the trusted read, memoised per instance until a chain file's size or mtime or
439
+ * HEAD changes (untrusted() and repeated audits reuse it); the store it reads carries this instance's replica id.
440
+ */
441
+ read() {
442
+ const root = rootOfLedger(this.ledgerDir);
443
+ let key;
444
+ try {
445
+ key = [headCommitOf(root) ?? 'no-head', ...fs.readdirSync(this.ledgerDir).filter((n) => /^provenance(?:\.[^/]+)?\.jsonl$/.test(n)).sort()
446
+ .map((n) => { const st = fs.statSync(path.join(this.ledgerDir, n)); return `${n}:${st.size}:${st.mtimeMs}`; })].join('|');
447
+ }
448
+ catch {
449
+ key = `unkeyed:${Date.now()}:${Math.random()}`;
450
+ }
451
+ if (this.memo?.key !== key)
452
+ this.memo = { key, read: trustedLedgerEvents(root, realTrustDeps(root, this.ledgerDir, this.id)) };
453
+ return this.memo.read;
454
+ }
455
+ loadAll() { return this.read().events; }
456
+ /**
457
+ * @implements A-SPEC-222.12 (H1) — whether this writer's own chain was ignored as not verifying: a reader that would
458
+ * otherwise take "no trusted events" for "nothing recorded yet" fails closed on it.
459
+ */
460
+ ownChainBroken() {
461
+ let own = null;
462
+ try {
463
+ own = this.replicaId();
464
+ }
465
+ catch {
466
+ own = null;
467
+ }
468
+ if (own === null)
469
+ return true;
470
+ return this.read().ignored.some((i) => i.seq === undefined && i.file.endsWith(`/provenance.${own}.jsonl`) && /does not verify|cannot be read/.test(i.why));
471
+ }
472
+ /**
473
+ * Every row, trusted or not, for a check that only refuses: a conflicting row, even an untrusted one, stops an act
474
+ * (fail-closed), while what an act takes as granted or already done comes from `loadAll()` only.
475
+ */
476
+ loadAllRaw() { return super.loadAll(); }
477
+ /** The rows among `rows` (read with loadAllRaw) that are not trusted: for an audit, each one is a conflict. */
478
+ untrusted(rows) {
479
+ const key = (e) => `${e.replicaId ?? ''}\u0000${e.seq}\u0000${e.hash}`;
480
+ const trusted = new Set(this.loadAll().map(key));
481
+ return rows.filter((e) => !trusted.has(key(e)));
482
+ }
483
+ /**
484
+ * @implements A-SPEC-222.12 (L1) — an audit refusal that names the replica files holding the untrusted rows and the
485
+ * way out, so one row is not a refusal with no recovery: commit that replica's file (a person stages another replica),
486
+ * or, for an old replica of this machine whose hostname changed, commit or remove it.
487
+ */
488
+ untrustedReason(rows) {
489
+ // @implements A-SPEC-222.13 — by reason, from what the trusted read ignored: never tell a writer to remove its own file
490
+ const bad = this.untrusted(rows);
491
+ if (bad.length === 0)
492
+ return '';
493
+ const ignored = this.read().ignored;
494
+ const parts = new Set();
495
+ for (const e of bad) {
496
+ const name = e.replicaId === null ? 'provenance.jsonl' : `provenance.${e.replicaId}.jsonl`;
497
+ const row = ignored.find((i) => i.seq === e.seq && i.file.endsWith(`/${name}`));
498
+ const chain = ignored.find((i) => i.seq === undefined && i.file.endsWith(`/${name}`));
499
+ if (row)
500
+ parts.add(`${name}#${e.seq}: its actor is neither a tool nor authorized, so the row cannot count — redo the act through the tool`);
501
+ else if (chain && /HEAD could not be read/.test(chain.why))
502
+ parts.add(`${name}: HEAD could not be read — retry when git answers`);
503
+ else if (chain && /in HEAD does not verify/.test(chain.why))
504
+ parts.add(`${name}: its chain in HEAD does not verify — that replica's owner repairs it with \`holmes-kit ledger rechain\``);
505
+ else if (chain && /does not verify|cannot be read/.test(chain.why))
506
+ parts.add(`${name}: this writer's chain does not verify — repair it from a terminal with \`holmes-kit ledger rechain\` (an uncommitted ledger is re-chained whole: review it first)`);
507
+ else if (chain)
508
+ parts.add(`${name}: another replica that HEAD does not hold as written — a person stages and commits it`);
509
+ else
510
+ parts.add(`${name}#${e.seq}: not trusted`);
511
+ }
512
+ return ` (A-SPEC-222.13: ${[...parts].join('; ')}; then retry.)`;
513
+ }
514
+ }
515
+ exports.TrustedLedgerStore = TrustedLedgerStore;
516
+ /** One line naming ignored ledger entries, for a refusal or an unproven reason (at most three named). */
517
+ function describeIgnored(ignored) {
518
+ if (ignored.length === 0)
519
+ return '';
520
+ const named = ignored.slice(0, 3).map((i) => `${i.file}${i.seq !== undefined ? `#${i.seq}` : ''}: ${i.why}`).join('; ');
521
+ return `${ignored.length} ledger entr${ignored.length === 1 ? 'y was' : 'ies were'} ignored (${named}${ignored.length > 3 ? '; …' : ''})`;
522
+ }
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * DOTS ARE THE POINT. macOS hostnames end in `.local`, and the schema rule reads
5
5
  * `provenance.<segment>.jsonl` with `<segment>` containing no dot — an unsanitised
6
- * `SungNamui-MacStudio.local` would produce `provenance.SungNamui-MacStudio.local.jsonl`, which the
6
+ * `my-host.local` would produce `provenance.my-host.local.jsonl`, which the
7
7
  * schema check would not recognise as a replica chain at all. Two rules disagreeing about the same
8
8
  * file is worse than either rule being wrong.
9
9
  */
@@ -56,7 +56,7 @@ const STORE = path.join('.ax', 'state', 'replica-id');
56
56
  *
57
57
  * DOTS ARE THE POINT. macOS hostnames end in `.local`, and the schema rule reads
58
58
  * `provenance.<segment>.jsonl` with `<segment>` containing no dot — an unsanitised
59
- * `SungNamui-MacStudio.local` would produce `provenance.SungNamui-MacStudio.local.jsonl`, which the
59
+ * `my-host.local` would produce `provenance.my-host.local.jsonl`, which the
60
60
  * schema check would not recognise as a replica chain at all. Two rules disagreeing about the same
61
61
  * file is worse than either rule being wrong.
62
62
  */
@@ -0,0 +1,59 @@
1
+ export interface SeamGrant {
2
+ path: string;
3
+ blob: string | null;
4
+ }
5
+ export interface SeamState {
6
+ tips: string[];
7
+ granted: SeamGrant[];
8
+ accepted: SeamGrant[];
9
+ history: Record<string, unknown> | null;
10
+ }
11
+ export interface Unexplained {
12
+ where: 'index' | 'commit' | 'scan';
13
+ path?: string;
14
+ commit?: string;
15
+ detail?: string;
16
+ }
17
+ /** At most this many commits new since the recorded tips are read; more is itself unexplained. */
18
+ export declare const SEAM_MAX_COMMITS = 200;
19
+ /**
20
+ * The spec-store changes no granted staging act accounts for: in the index, in the commits new since the recorded tips,
21
+ * and any history file that moved since the baseline. A ledger with no baseline is initialised and explains nothing.
22
+ */
23
+ export declare function unexplainedSpecChanges(root: string, specsDir: string): Unexplained[];
24
+ /** Records a baseline of the tips now and the granted pairs still staged, when either differs from the last one. */
25
+ export declare function advanceSpecSeam(root: string, specsDir: string): void;
26
+ /**
27
+ * @implements A-SPEC-792.32 — the one calculator of what a staging approval approved: git's object id of these bytes
28
+ * (`sha1("blob <len>\0" + bytes)`), computed in process, so no clean filter or attribute of the work tree runs.
29
+ */
30
+ export declare function blobOf(bytes: Buffer, format?: 'sha1' | 'sha256'): string;
31
+ /** The repository's object format (a SHA-256 repository names its blobs by SHA-256). */
32
+ export declare function objectFormatOf(root: string): 'sha1' | 'sha256';
33
+ /** @implements A-SPEC-792.32 — the bytes a grant may name: a regular file without an execute bit (git mode 100644). */
34
+ export declare function grantableBytes(abs: string): Buffer | null;
35
+ export interface WorktreeChange {
36
+ path: string;
37
+ deleted: boolean;
38
+ untracked: boolean;
39
+ }
40
+ /**
41
+ * @implements A-SPEC-792.32 — what `git add` of these root-relative prefixes (every path when null) would change,
42
+ * without `git status`: a racily clean entry makes status re-hash the file through its clean filter, which ran the
43
+ * agent's filter command inside the hook (measured 2026-10-26). The index is read as recorded and each tracked file is
44
+ * compared by `blobOf` of its bytes and its mode; an untracked file is listed by `ls-files -o`. A filter, autocrlf or a
45
+ * mode the comparison does not follow reads as a change, which fails closed.
46
+ */
47
+ export declare function worktreeChanges(root: string, prefixes: string[] | null): WorktreeChange[];
48
+ /** @implements A-SPEC-792.32 — writes exactly these (path, blob) pairs of the spec store as a grant, nothing else. */
49
+ export declare function recordProvenGrant(root: string, specsDir: string, proven: Array<{
50
+ path: string;
51
+ blob: string | null;
52
+ }>): void;
53
+ /**
54
+ * A granted spec-staging act (the person path): the path and blob of each changed spec file the command's `git add` or
55
+ * `git stage` segments name. @implements A-SPEC-792.32 — a command that names no spec path grants none (the
56
+ * every-changed-spec fallback is gone), and the blob is `blobOf` over a regular non-executable file, never a hash
57
+ * through git.
58
+ */
59
+ export declare function recordGrantedStaging(root: string, specsDir: string, command: string, cwd: string): void;