@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,48 @@
1
+ /**
2
+ * The ports of the admission core (A-SPEC-792.50): git objects and graph through `ObjectPort`, time through `Clock`.
3
+ * The core receives bytes and graph answers only through these; it imports no file system, process or network module.
4
+ */
5
+ /** One tree entry of a commit, recursive, trees included (so an ancestor's type is visible). */
6
+ export interface TreeEntry {
7
+ path: string;
8
+ mode: string;
9
+ type: 'blob' | 'tree' | 'commit';
10
+ oid: string;
11
+ }
12
+ export interface ObjectPort {
13
+ /** Every entry of the commit's tree, recursive, trees included. */
14
+ entries(commit: string): TreeEntry[];
15
+ size(oid: string): number;
16
+ /** The blob's bytes, or null when it is larger than `max`. */
17
+ bytes(oid: string, max: number): Buffer | null;
18
+ /** Many blobs in one read (each null when larger than `max`): the head's spec documents for the frontmatter-id index. */
19
+ bytesMany(oids: readonly string[], max: number): Map<string, Buffer | null>;
20
+ /** sha256 hex of the blob's first `length` bytes, read in chunks. */
21
+ prefixSha256(oid: string, length: number): string;
22
+ /** The blob's last byte, or null when it is empty. */
23
+ lastByte(oid: string): number | null;
24
+ /** Short hashes of the blob's lines, in order, or null above `maxLines` lines. */
25
+ lineHashes(oid: string, maxLines: number): string[] | null;
26
+ isAncestor(a: string, b: string): boolean;
27
+ mergeBases(a: string, b: string): string[];
28
+ exists(commit: string): boolean;
29
+ shallow(): boolean;
30
+ }
31
+ export interface Clock {
32
+ now(): number;
33
+ }
34
+ export type Axis = 'single' | 'introduction' | 'rollback';
35
+ export interface PushEvent {
36
+ event: 'push';
37
+ ref: string;
38
+ before: string;
39
+ after: string;
40
+ }
41
+ export interface PullRequestEvent {
42
+ event: 'pull_request_target';
43
+ base: string;
44
+ head: string;
45
+ }
46
+ export type AdmissionEvent = PushEvent | PullRequestEvent;
47
+ /** A zero object id (a branch creation's `before`, a deletion's `after`), SHA-1 or SHA-256. */
48
+ export declare const isZero: (oid: string) => boolean;
@@ -0,0 +1,11 @@
1
+ "use strict";
2
+ // @implements A-SPEC-792.50
3
+ /**
4
+ * The ports of the admission core (A-SPEC-792.50): git objects and graph through `ObjectPort`, time through `Clock`.
5
+ * The core receives bytes and graph answers only through these; it imports no file system, process or network module.
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.isZero = void 0;
9
+ /** A zero object id (a branch creation's `before`, a deletion's `after`), SHA-1 or SHA-256. */
10
+ const isZero = (oid) => /^(?:0{40}|0{64})$/.test(oid);
11
+ exports.isZero = isZero;
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The range of an event (A-SPEC-792.37 §5). A push is a fast-forward, a force push (with or without one merge base), a
3
+ * branch creation or a deletion; a pull request is `merge-base(base, head)..head`. A range that cannot be judged as an
4
+ * ordinary range — both sides zero, a missing object, a shallow repository, a deletion — is the event's `incomplete`
5
+ * with `rangeUndefined`. No single merge base is a force push judged on its rollback axis alone, also `rangeUndefined`.
6
+ */
7
+ import { AdmissionEvent, ObjectPort } from './ports';
8
+ import { EventIncomplete } from './bounded-reader';
9
+ export type Range = {
10
+ kind: 'fast-forward';
11
+ before: string;
12
+ after: string;
13
+ } | {
14
+ kind: 'force';
15
+ before: string;
16
+ after: string;
17
+ mergeBase: string | null;
18
+ } | {
19
+ kind: 'create';
20
+ after: string;
21
+ } | {
22
+ kind: 'pr';
23
+ base: string;
24
+ head: string;
25
+ mergeBase: string;
26
+ };
27
+ /** The range, or throws EventIncomplete. A deletion throws with its `before` for the listing. */
28
+ export declare class DeletedBranch extends EventIncomplete {
29
+ readonly before: string;
30
+ constructor(before: string);
31
+ }
32
+ export declare function resolveRange(event: AdmissionEvent, port: ObjectPort): Range;
@@ -0,0 +1,51 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.DeletedBranch = void 0;
4
+ exports.resolveRange = resolveRange;
5
+ // @implements A-SPEC-792.50
6
+ /**
7
+ * The range of an event (A-SPEC-792.37 §5). A push is a fast-forward, a force push (with or without one merge base), a
8
+ * branch creation or a deletion; a pull request is `merge-base(base, head)..head`. A range that cannot be judged as an
9
+ * ordinary range — both sides zero, a missing object, a shallow repository, a deletion — is the event's `incomplete`
10
+ * with `rangeUndefined`. No single merge base is a force push judged on its rollback axis alone, also `rangeUndefined`.
11
+ */
12
+ const ports_1 = require("./ports");
13
+ const bounded_reader_1 = require("./bounded-reader");
14
+ /** The range, or throws EventIncomplete. A deletion throws with its `before` for the listing. */
15
+ class DeletedBranch extends bounded_reader_1.EventIncomplete {
16
+ before;
17
+ constructor(before) {
18
+ super('branch deleted', true);
19
+ this.before = before;
20
+ }
21
+ }
22
+ exports.DeletedBranch = DeletedBranch;
23
+ function resolveRange(event, port) {
24
+ if (port.shallow())
25
+ throw new bounded_reader_1.EventIncomplete('shallow repository', true);
26
+ if (event.event === 'pull_request_target') {
27
+ for (const c of [event.base, event.head])
28
+ if (!port.exists(c))
29
+ throw new bounded_reader_1.EventIncomplete('missing object', true);
30
+ const mbs = port.mergeBases(event.base, event.head);
31
+ if (mbs.length !== 1)
32
+ throw new bounded_reader_1.EventIncomplete('range undefined: no single merge base', true);
33
+ return { kind: 'pr', base: event.base, head: event.head, mergeBase: mbs[0] };
34
+ }
35
+ const { before, after } = event;
36
+ if ((0, ports_1.isZero)(before) && (0, ports_1.isZero)(after))
37
+ throw new bounded_reader_1.EventIncomplete('zero on both sides', true);
38
+ if ((0, ports_1.isZero)(after)) {
39
+ if (!port.exists(before))
40
+ throw new bounded_reader_1.EventIncomplete('missing object', true);
41
+ throw new DeletedBranch(before);
42
+ }
43
+ if (!port.exists(after) || (!(0, ports_1.isZero)(before) && !port.exists(before)))
44
+ throw new bounded_reader_1.EventIncomplete('missing object', true);
45
+ if ((0, ports_1.isZero)(before))
46
+ return { kind: 'create', after };
47
+ if (port.isAncestor(before, after))
48
+ return { kind: 'fast-forward', before, after };
49
+ const mbs = port.mergeBases(before, after);
50
+ return { kind: 'force', before, after, mergeBase: mbs.length === 1 ? mbs[0] : null };
51
+ }
@@ -0,0 +1 @@
1
+ export declare function selfContainmentFindings(bytes: Buffer): string[];
@@ -0,0 +1,125 @@
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.selfContainmentFindings = selfContainmentFindings;
37
+ // @implements A-SPEC-792.50
38
+ /**
39
+ * Self-containment of the two detector workflows (A-SPEC-792.37 §3, M-1): facts only, no verdict.
40
+ *
41
+ * - `uses:` at step or job level (a reusable workflow) is a finding when local (`./…`) or not pinned to a 40-hex commit.
42
+ * - `run:` is a closed form (review B-M1): every non-empty line must be on the allowlist below, so a repository script,
43
+ * `npm run`, `npx`, `pnpm`, `yarn` or any interpreter is a finding without being named. Until slice 1c defines the
44
+ * detector's own run statement, the allowlist is a plain `echo` of literal words.
45
+ * - The keys are a closed set too (review 08:37, H1 and N-M1): a `run:` allowlist means nothing beside a step `shell:`,
46
+ * an `env` that sets `BASH_ENV`, `defaults.run`, or an unpinned `container` or `services` image, each of which runs
47
+ * something the workflow does not show. Every key outside the sets below is a finding; `container` and `services`
48
+ * images must be pinned by digest; an `env` map may set only the token keys (an allow list, review 11:19).
49
+ * The YAML forms are the classifier's pre-checks; other workflows are not read here.
50
+ */
51
+ const yaml = __importStar(require("js-yaml"));
52
+ const PINNED = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.\/-]+@[0-9a-f]{40}$/;
53
+ const ALLOWED_RUN_LINES = [/^echo [A-Za-z0-9 _.,:=-]*$/];
54
+ const TOP_KEYS = new Set(['name', 'run-name', 'on', 'permissions', 'concurrency', 'env', 'jobs']);
55
+ const JOB_KEYS = new Set(['name', 'runs-on', 'permissions', 'if', 'needs', 'timeout-minutes', 'concurrency', 'env', 'steps', 'container', 'services', 'uses']);
56
+ const STEP_KEYS = new Set(['name', 'id', 'if', 'uses', 'with', 'env', 'run']);
57
+ /**
58
+ * The env keys a detector workflow may set: the token 1b passes, nothing else (review 11:19 H-1). A deny list cannot be
59
+ * closed — bash runs `BASH_FUNC_echo%%`, `SHELLOPTS` with `PS4`, `PROMPT_COMMAND` and more around a plain `echo`.
60
+ */
61
+ const ENV_ALLOWED = new Set(['GH_TOKEN', 'GITHUB_TOKEN']);
62
+ const DIGEST_IMAGE = /@sha256:[0-9a-f]{64}$/;
63
+ function usesFinding(where, uses) {
64
+ if (typeof uses !== 'string')
65
+ return null;
66
+ if (uses.startsWith('./'))
67
+ return `${where}: a local uses (${uses})`;
68
+ if (!PINNED.test(uses))
69
+ return `${where}: an action or workflow not pinned to a 40-hex commit (${uses})`;
70
+ return null;
71
+ }
72
+ const isMap = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
73
+ function keysFindings(where, v, allowed) {
74
+ return isMap(v) ? Object.keys(v).filter((k) => !allowed.has(k)).map((k) => `${where}: the key ${k} is outside the detector's closed set`) : [];
75
+ }
76
+ function envFindings(where, env) {
77
+ if (env === undefined)
78
+ return [];
79
+ if (!isMap(env))
80
+ return [`${where}.env: not a map`];
81
+ return Object.keys(env).filter((k) => !ENV_ALLOWED.has(k)).map((k) => `${where}.env: sets ${k}`);
82
+ }
83
+ function imageFindings(where, container) {
84
+ const image = typeof container === 'string' ? container : isMap(container) ? container.image : undefined;
85
+ return typeof image === 'string' && DIGEST_IMAGE.test(image) ? [] : [`${where}: an image not pinned by digest (${String(image)})`];
86
+ }
87
+ function selfContainmentFindings(bytes) {
88
+ let doc;
89
+ try {
90
+ doc = yaml.load(bytes.toString('utf8'), { schema: yaml.CORE_SCHEMA });
91
+ }
92
+ catch {
93
+ return [];
94
+ }
95
+ const findings = [...keysFindings('workflow', doc, TOP_KEYS), ...(isMap(doc) ? envFindings('workflow', doc.env) : [])];
96
+ const jobs = doc?.jobs ?? {};
97
+ for (const [job, def] of Object.entries(jobs)) {
98
+ findings.push(...keysFindings(job, def, JOB_KEYS), ...envFindings(job, def?.env));
99
+ const j = usesFinding(`${job}`, def?.uses);
100
+ if (j)
101
+ findings.push(j);
102
+ if (def?.container !== undefined)
103
+ findings.push(...imageFindings(`${job}.container`, def.container));
104
+ if (def?.services !== undefined) {
105
+ if (!isMap(def.services))
106
+ findings.push(`${job}.services: not a map`);
107
+ else
108
+ for (const [name, svc] of Object.entries(def.services))
109
+ findings.push(...imageFindings(`${job}.services.${name}`, svc));
110
+ }
111
+ for (const [i, step] of (Array.isArray(def?.steps) ? def.steps : []).entries()) {
112
+ const s = (step ?? {});
113
+ findings.push(...keysFindings(`${job}.steps[${i}]`, step, STEP_KEYS), ...envFindings(`${job}.steps[${i}]`, s.env));
114
+ const u = usesFinding(`${job}.steps[${i}]`, s.uses);
115
+ if (u)
116
+ findings.push(u);
117
+ if (s.run !== undefined) {
118
+ const lines = String(s.run).split('\n').map((l) => l.trim()).filter(Boolean);
119
+ if (lines.some((l) => !ALLOWED_RUN_LINES.some((re) => re.test(l))))
120
+ findings.push(`${job}.steps[${i}]: a run outside the allowed statements`);
121
+ }
122
+ }
123
+ }
124
+ return findings;
125
+ }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The signature source (A-SPEC-792.37 §8): empty in 0.40.0. No signature is recognised, so no entry's basis is
3
+ * `signature`; pull-request approvals as signatures are a later slice, not scheduled.
4
+ */
5
+ export interface Signature {
6
+ path: string;
7
+ kind: string;
8
+ }
9
+ export declare function emptySignatures(): Signature[];
@@ -0,0 +1,4 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.emptySignatures = emptySignatures;
4
+ function emptySignatures() { return []; }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The tree pairs an event is judged on (A-SPEC-792.37 §5, §8): one pair for a fast-forward, a creation (over the empty
3
+ * tree, with no configuration) or a pull request; two for a force push — the introduction axis
4
+ * (`merge-base..after`, configuration at the merge base) and the rollback axis (`before` → `after`, configuration at
5
+ * `before`) — or the rollback axis alone when there is no single merge base.
6
+ */
7
+ import { Axis } from './ports';
8
+ import { Range } from './range-resolver';
9
+ export interface TreePair {
10
+ axis: Axis;
11
+ base: string | null;
12
+ head: string;
13
+ configAt: string | null;
14
+ }
15
+ export declare function planTransitions(range: Range): TreePair[];
@@ -0,0 +1,14 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.planTransitions = planTransitions;
4
+ function planTransitions(range) {
5
+ switch (range.kind) {
6
+ case 'fast-forward': return [{ axis: 'single', base: range.before, head: range.after, configAt: range.before }];
7
+ case 'create': return [{ axis: 'single', base: null, head: range.after, configAt: null }];
8
+ case 'pr': return [{ axis: 'single', base: range.mergeBase, head: range.head, configAt: range.base }];
9
+ case 'force': return range.mergeBase === null
10
+ ? [{ axis: 'rollback', base: range.before, head: range.after, configAt: range.before }]
11
+ : [{ axis: 'introduction', base: range.mergeBase, head: range.after, configAt: range.mergeBase },
12
+ { axis: 'rollback', base: range.before, head: range.after, configAt: range.before }];
13
+ }
14
+ }
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The verdict lattice of the admission detector (A-SPEC-792.37 §2, §8): `refused` > `incomplete` > `needs-signature`
3
+ * > `admit`. Every entry carries the stricter verdict of all its levels and axes, the contribution that decided it
4
+ * (its level, its table row when a row decided, and its reason), and every contribution. The conclusion of a report is
5
+ * always `neutral` in 0.40.0.
6
+ */
7
+ import { Axis } from './ports';
8
+ export type Verdict = 'admit' | 'needs-signature' | 'refused' | 'incomplete';
9
+ export declare const CONCLUSION: "neutral";
10
+ export type Level = 'key' | 'path' | 'finding' | 'table' | 'parents';
11
+ export interface Contribution {
12
+ level: Level;
13
+ axis?: Axis;
14
+ row?: number;
15
+ verdict: Verdict;
16
+ reason: string;
17
+ }
18
+ export interface Entry {
19
+ path: string;
20
+ kind: string;
21
+ verdict: Verdict;
22
+ /** The table row of the contribution that decided the verdict, when a row decided it. */
23
+ row?: number;
24
+ /** What decided the verdict: its level, its row when a row decided, and its reason (Behavior 4; review B-M3). */
25
+ decision: {
26
+ level: Level;
27
+ row?: number;
28
+ reason: string;
29
+ };
30
+ contributing: Contribution[];
31
+ /** Row 3: a change to the detection definition (an alarm whatever its verdict). */
32
+ definition: boolean;
33
+ basis: 'policy' | 'none';
34
+ }
35
+ /** The stricter of two verdicts. */
36
+ export declare function stricter(a: Verdict, b: Verdict): Verdict;
37
+ /** The deciding contribution: the strictest, and among equals the first given. */
38
+ export declare function decide(contributions: readonly Contribution[]): Contribution;
@@ -0,0 +1,17 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CONCLUSION = void 0;
4
+ exports.stricter = stricter;
5
+ exports.decide = decide;
6
+ exports.CONCLUSION = 'neutral';
7
+ const RANK = { admit: 0, 'needs-signature': 1, incomplete: 2, refused: 3 };
8
+ /** The stricter of two verdicts. */
9
+ function stricter(a, b) { return RANK[b] > RANK[a] ? b : a; }
10
+ /** The deciding contribution: the strictest, and among equals the first given. */
11
+ function decide(contributions) {
12
+ let best = contributions[0];
13
+ for (const c of contributions.slice(1))
14
+ if (RANK[c.verdict] > RANK[best.verdict])
15
+ best = c;
16
+ return best;
17
+ }
@@ -0,0 +1,44 @@
1
+ export type WiringAnswer = {
2
+ ok: true;
3
+ } | {
4
+ ok: false;
5
+ breach: string;
6
+ };
7
+ export interface WiringContext {
8
+ /** The development form `bin/holmes-mcp.js` is allowed: the head's package.json names @holmes-lab/holmes-kit. */
9
+ devForm: boolean;
10
+ }
11
+ /** The package path: absolute, ending in @holmes-lab/holmes-kit, no special character, no `..` segment. */
12
+ export declare function validPackagePath(p: string): boolean;
13
+ export declare function canonicalHookCommand(command: string): boolean;
14
+ /** One key path a TOML document defines, and whether any of its segments was quoted. */
15
+ export interface TomlKey {
16
+ path: string[];
17
+ quoted: boolean;
18
+ }
19
+ /** @implements A-SPEC-792.50 (review N-C1) — a key with the line it is defined on (0-based), and every string value with its path. */
20
+ export interface TomlRead {
21
+ keys: Array<TomlKey & {
22
+ line: number;
23
+ }>;
24
+ strings: Array<{
25
+ path: string[];
26
+ value: string;
27
+ }>;
28
+ }
29
+ /**
30
+ * Every key path a TOML document defines — table headers, array-of-tables headers, dotted keys and inline-table keys —
31
+ * by a small tokenizer that keeps no values. Strings (basic, literal, multi-line) are read so that their contents are
32
+ * never taken for keys. Throws SyntaxError on anything it cannot read.
33
+ */
34
+ export declare function tomlKeys(text: string): TomlKey[];
35
+ /** The tokenizer's whole reading: keys with their lines, and string values with the path they are the value of. */
36
+ export declare function tomlRead(text: string): TomlRead;
37
+ /**
38
+ * @implements A-SPEC-792.50 (review N-C1) — the second reading's judgement, given the tokenizer's reading and the lines
39
+ * the line reading put in the holmes block. Each check here also has a line-reading counterpart, so through
40
+ * `canonicalWiring` it answers only what the first reading missed; it is exported so each check is tested on its own.
41
+ */
42
+ export declare function tomlStructureBreach(read: TomlRead, holmesLines: ReadonlySet<number>): string | null;
43
+ /** Whether a wiring file's bytes are canonical. */
44
+ export declare function canonicalWiring(path: string, bytes: Buffer, ctx: WiringContext): WiringAnswer;