@holmes-lab/holmes-kit 0.38.0 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (308) hide show
  1. package/CHANGELOG.md +370 -6
  2. package/README.md +58 -40
  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 +50 -13
  47. package/dist/holmes/cli/approve.js +260 -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 +45 -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 +206 -424
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  67. package/dist/holmes/cli/lock-recover.js +126 -0
  68. package/dist/holmes/cli/mcp-processes.d.ts +32 -0
  69. package/dist/holmes/cli/mcp-processes.js +132 -0
  70. package/dist/holmes/cli/release-docs.js +1 -1
  71. package/dist/holmes/cli/run-exec.d.ts +141 -0
  72. package/dist/holmes/cli/run-exec.js +1435 -0
  73. package/dist/holmes/cli/run-provision.d.ts +8 -0
  74. package/dist/holmes/cli/run-provision.js +325 -0
  75. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  76. package/dist/holmes/cli/run-wiring.js +270 -0
  77. package/dist/holmes/cli/run.d.ts +26 -0
  78. package/dist/holmes/cli/run.js +364 -83
  79. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  80. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  81. package/dist/holmes/cli/screen-safe.js +18 -756
  82. package/dist/holmes/config/config.d.ts +2 -0
  83. package/dist/holmes/config/config.js +5 -2
  84. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  85. package/dist/holmes/cpg/import-resolver.js +1 -1
  86. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  87. package/dist/holmes/governance/approval-decisions.js +29 -0
  88. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  89. package/dist/holmes/governance/approval-grants.js +612 -33
  90. package/dist/holmes/governance/approval-queue.d.ts +31 -0
  91. package/dist/holmes/governance/approval-queue.js +122 -11
  92. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  93. package/dist/holmes/governance/approval-spend.js +191 -0
  94. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  95. package/dist/holmes/governance/autonomous-shell.js +332 -0
  96. package/dist/holmes/governance/autonomy.d.ts +5 -0
  97. package/dist/holmes/governance/autonomy.js +16 -11
  98. package/dist/holmes/governance/constitution.d.ts +5 -0
  99. package/dist/holmes/governance/constitution.js +32 -12
  100. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  101. package/dist/holmes/governance/full-autonomy.js +103 -7
  102. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  103. package/dist/holmes/governance/harness-catalog.js +348 -0
  104. package/dist/holmes/governance/human-channel.d.ts +38 -0
  105. package/dist/holmes/governance/human-channel.js +49 -0
  106. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  107. package/dist/holmes/governance/install-manifest.js +160 -0
  108. package/dist/holmes/governance/ledger-rechain.js +2 -0
  109. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  110. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  111. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  112. package/dist/holmes/governance/ledger-store.js +186 -8
  113. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  114. package/dist/holmes/governance/provenance-chain.js +19 -4
  115. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  116. package/dist/holmes/governance/provenance-ledger.js +53 -18
  117. package/dist/holmes/governance/push-gate-runner.js +11 -7
  118. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  119. package/dist/holmes/governance/recorded-pairs.js +522 -0
  120. package/dist/holmes/governance/replica-id.d.ts +1 -1
  121. package/dist/holmes/governance/replica-id.js +1 -1
  122. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  123. package/dist/holmes/governance/spec-seam.js +587 -0
  124. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  125. package/dist/holmes/governance/spend-kinds.js +18 -0
  126. package/dist/holmes/governance/tool-actions.js +2 -0
  127. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  128. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  129. package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
  130. package/dist/holmes/guardrail/impact-gate.js +1 -1
  131. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  132. package/dist/holmes/guardrail/line-continuation.js +39 -0
  133. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  134. package/dist/holmes/guardrail/operator-person.js +57 -11
  135. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  136. package/dist/holmes/guardrail/refusal-codes.js +70 -10
  137. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  138. package/dist/holmes/guardrail/risk-classifier.js +245 -15
  139. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  140. package/dist/holmes/guardrail/risk-gate.js +7 -34
  141. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  142. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  143. package/dist/holmes/guardrail/run-refusals.d.ts +6 -1
  144. package/dist/holmes/guardrail/run-refusals.js +36 -14
  145. package/dist/holmes/guardrail/run-stages.d.ts +10 -0
  146. package/dist/holmes/guardrail/run-stages.js +46 -6
  147. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  148. package/dist/holmes/guardrail/shell-words.js +24 -3
  149. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  150. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  151. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  152. package/dist/holmes/guardrail/write-target.js +26 -5
  153. package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
  154. package/dist/holmes/hooks/pre-tool-use.js +1167 -168
  155. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  156. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  157. package/dist/holmes/hooks/session-start.d.ts +5 -0
  158. package/dist/holmes/hooks/session-start.js +29 -1
  159. package/dist/holmes/hooks/stop.d.ts +23 -0
  160. package/dist/holmes/hooks/stop.js +88 -33
  161. package/dist/holmes/mcp/approval-adapters.js +3 -1
  162. package/dist/holmes/mcp/approval-commit.js +3 -2
  163. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  164. package/dist/holmes/mcp/approval-policy.js +3 -1
  165. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  166. package/dist/holmes/mcp/handlers/approval-ask.d.ts +14 -0
  167. package/dist/holmes/mcp/handlers/approval-ask.js +31 -6
  168. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  169. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  170. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  171. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  172. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  173. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  174. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  175. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  176. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  177. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  178. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  179. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  180. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  181. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  182. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  183. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  184. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  185. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  186. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  187. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  188. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  189. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  190. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  191. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  192. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  193. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  194. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  195. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  196. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  197. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  198. package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
  199. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +5 -0
  200. package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
  201. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  202. package/dist/holmes/mcp/handlers.d.ts +99 -79
  203. package/dist/holmes/mcp/handlers.js +93 -25
  204. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  205. package/dist/holmes/mcp/harness-attestation.js +325 -53
  206. package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
  207. package/dist/holmes/mcp/maintenance-analyze.js +9 -9
  208. package/dist/holmes/mcp/maintenance-evidence.js +31 -2
  209. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  210. package/dist/holmes/mcp/server-staleness.d.ts +43 -0
  211. package/dist/holmes/mcp/server-staleness.js +158 -0
  212. package/dist/holmes/mcp/server.js +34 -9
  213. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  214. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  215. package/dist/holmes/mcp/tool-schemas.js +42 -2
  216. package/dist/holmes/project/act-root.d.ts +19 -0
  217. package/dist/holmes/project/act-root.js +100 -0
  218. package/dist/holmes/project/baseline.js +4 -3
  219. package/dist/holmes/project/bounded-group.d.ts +47 -0
  220. package/dist/holmes/project/bounded-group.js +140 -0
  221. package/dist/holmes/project/bounded-io.d.ts +50 -2
  222. package/dist/holmes/project/bounded-io.js +138 -6
  223. package/dist/holmes/project/change-source.js +2 -2
  224. package/dist/holmes/project/instance-id.d.ts +10 -0
  225. package/dist/holmes/project/instance-id.js +233 -0
  226. package/dist/holmes/project/machine-identity.d.ts +25 -0
  227. package/dist/holmes/project/machine-identity.js +133 -0
  228. package/dist/holmes/project/owned-lock.d.ts +84 -0
  229. package/dist/holmes/project/owned-lock.js +263 -0
  230. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  231. package/dist/holmes/project/plain-lock-fs.js +126 -0
  232. package/dist/holmes/project/request-lock.d.ts +85 -0
  233. package/dist/holmes/project/request-lock.js +459 -0
  234. package/dist/holmes/project/root.d.ts +12 -4
  235. package/dist/holmes/project/root.js +26 -7
  236. package/dist/holmes/project/run-records.d.ts +19 -0
  237. package/dist/holmes/project/run-records.js +94 -12
  238. package/dist/holmes/project/screen-text.d.ts +94 -0
  239. package/dist/holmes/project/screen-text.js +763 -0
  240. package/dist/holmes/project/spend-lock.d.ts +82 -0
  241. package/dist/holmes/project/spend-lock.js +413 -0
  242. package/dist/holmes/project/workspace-preflight.d.ts +5 -0
  243. package/dist/holmes/project/workspace-preflight.js +24 -1
  244. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  245. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  246. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  247. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  248. package/dist/holmes/review/confidence-calibration.js +1 -1
  249. package/dist/holmes/review/content-verify.js +1 -1
  250. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  251. package/dist/holmes/review/hop-ablation.js +5 -5
  252. package/dist/holmes/review/point-in-time-replay.js +12 -3
  253. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  254. package/dist/holmes/review/rank-diagnosis.js +1 -1
  255. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  256. package/dist/holmes/review/replay-corpus.js +25 -9
  257. package/dist/holmes/review/requirement-triage.js +2 -2
  258. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  259. package/dist/holmes/review/semantic-arm.js +3 -3
  260. package/dist/holmes/review/test-outcomes.js +3 -1
  261. package/dist/holmes/review/test-runner.d.ts +11 -0
  262. package/dist/holmes/review/test-runner.js +31 -10
  263. package/dist/holmes/review/test-selection-breadth.js +2 -2
  264. package/dist/holmes/review/verdicts.d.ts +109 -7
  265. package/dist/holmes/review/verdicts.js +653 -34
  266. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  267. package/dist/holmes/rtm/anchor-census.js +151 -0
  268. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  269. package/dist/holmes/rtm/anchor-ids.js +45 -2
  270. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  271. package/dist/holmes/rtm/comment-ranges.js +104 -0
  272. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  273. package/dist/holmes/rtm/counted-tests.js +63 -0
  274. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  275. package/dist/holmes/rtm/known-defects.js +1 -1
  276. package/dist/holmes/rtm/localize.js +1 -1
  277. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  278. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  279. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  280. package/dist/holmes/rtm/test-scope.js +166 -5
  281. package/dist/holmes/rtm/trace-gaps.js +1 -1
  282. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  283. package/dist/holmes/runtime/dispatch.js +12 -1
  284. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  285. package/dist/holmes/semantic/cloud-usage.js +1 -1
  286. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  287. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  288. package/dist/holmes/spec/approval-blockers.js +1 -1
  289. package/dist/holmes/spec/entity-store.d.ts +6 -1
  290. package/dist/holmes/spec/entity-store.js +16 -2
  291. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  292. package/dist/holmes/spec/entity-transaction.js +87 -170
  293. package/dist/holmes/spec/spec-store.d.ts +12 -6
  294. package/dist/holmes/spec/spec-store.js +4 -2
  295. package/dist/holmes/spec/spec-types.js +1 -1
  296. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  297. package/dist/holmes/spec/succession-guard.js +187 -0
  298. package/dist/holmes/spec/succession.d.ts +70 -0
  299. package/dist/holmes/spec/succession.js +171 -0
  300. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  301. package/docs/install-guide.md +9 -3
  302. package/docs/language-support.md +78 -0
  303. package/package.json +4 -3
  304. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  305. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  306. package/playbooks/publish/PLAYBOOK.md +45 -33
  307. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  308. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -51,8 +51,10 @@ export interface AxConfig {
51
51
  * The owner's ceiling on automatic approval (autonomous and delegated seals). It only narrows the grader; `default`
52
52
  * when absent, `off` when malformed — a ceiling must never fail toward wider.
53
53
  */
54
+ /** @implements A-SPEC-792.28 — `shellStaging`: autonomous approval of governance staging; `on` when absent, `off` when malformed. */
54
55
  autonomy: {
55
56
  ceiling: AutonomyCeiling;
57
+ shellStaging: 'on' | 'off';
56
58
  };
57
59
  /**
58
60
  * @implements A-SPEC-778
@@ -156,7 +156,7 @@ exports.DEFAULT_CONFIG = {
156
156
  storage: { specStore: 'local-markdown' },
157
157
  architecture: { cycleIgnore: [] },
158
158
  classification: { strict: false, testDirs: [] },
159
- autonomy: { ceiling: 'default' },
159
+ autonomy: { ceiling: 'default', shellStaging: 'on' },
160
160
  run: { refusalRepeatLimit: exports.RUN_REFUSAL_LIMIT_DEFAULT, approvalWaitMinutes: exports.RUN_APPROVAL_WAIT_DEFAULT },
161
161
  stages: structuredClone(exports.DEFAULT_STAGES),
162
162
  };
@@ -199,8 +199,11 @@ function loadConfig(root) {
199
199
  // not a known value, including a non-object `autonomy`, is `off`.
200
200
  const auto = merged.autonomy;
201
201
  const declaredCeiling = auto !== null && typeof auto === 'object' ? auto.ceiling : undefined;
202
+ const declaredStaging = auto !== null && typeof auto === 'object' ? auto.shellStaging : undefined;
202
203
  merged.autonomy = {
203
204
  ceiling: CEILINGS.includes(declaredCeiling) ? declaredCeiling : 'off',
205
+ // @implements A-SPEC-792.28 — absent is on; anything present but "on" is off (never fails toward wider)
206
+ shellStaging: declaredStaging === undefined || declaredStaging === 'on' ? 'on' : 'off',
204
207
  };
205
208
  // @implements A-SPEC-778 — only an integer from 1 to 1000 is a limit.
206
209
  const runCfg = merged.run;
@@ -225,6 +228,6 @@ function loadConfig(root) {
225
228
  catch {
226
229
  // @implements A-SPEC-476.3 — the defaults carry the widest ceiling, so a broken file raised it; it reads `off`, as a
227
230
  // malformed ceiling already does (A-SPEC-532.6: a ceiling never fails toward wider).
228
- return { ...structuredClone(exports.DEFAULT_CONFIG), autonomy: { ceiling: 'off' } };
231
+ return { ...structuredClone(exports.DEFAULT_CONFIG), autonomy: { ceiling: 'off', shellStaging: 'off' } };
229
232
  }
230
233
  }
@@ -4,7 +4,7 @@ exports.CORPUS_EVIDENCE = exports.MATRIX_LANGUAGES = exports.LAYERS = void 0;
4
4
  exports.languageMatrix = languageMatrix;
5
5
  exports.renderLanguageSupport = renderLanguageSupport;
6
6
  exports.renderReadmeLanguageTable = renderReadmeLanguageTable;
7
- // @implements A-SPEC-510.6
7
+ // @implements A-SPEC-510.6, A-SPEC-794.57
8
8
  /**
9
9
  * The layer × language support matrix — what "officially supported" MEANS, made checkable.
10
10
  *
@@ -163,7 +163,7 @@ function renderLanguageSupport() {
163
163
  */
164
164
  exports.CORPUS_EVIDENCE = {
165
165
  typescript: { fns: '10,929', corpus: 'this repository' },
166
- python: { fns: '1,209', corpus: 'jarvis' },
166
+ python: { fns: '1,209', corpus: 'a private consumer workspace' },
167
167
  csharp: { fns: '9,184', corpus: 'Newtonsoft.Json + RestSharp', note: '4.4% of files refuse at L1 (preprocessor across syntax)' },
168
168
  java: { fns: '8,376', corpus: 'gson + junit4' },
169
169
  go: { fns: '2,637', corpus: 'gin + cobra' },
@@ -205,7 +205,7 @@ function createImportResolver(scanned, opts) {
205
205
  // A specifier without a leading dot used to be refused outright, on the ground that it names an
206
206
  // external package. That holds for `node:fs` and `js-yaml`; it does NOT hold for Python, which
207
207
  // writes intra-repository modules absolutely — `from src.core.memory_audit import X`. Measured
208
- // on the jarvis corpus: 1060 specifiers, 0 relative, 542 naming a file the scan already had, and
208
+ // on the consumer corpus: 1060 specifiers, 0 relative, 542 naming a file the scan already had, and
209
209
  // 0 import edges in the graph. The whole import layer was missing for that language because the
210
210
  // resolver's shape was JS's.
211
211
  //
@@ -0,0 +1,47 @@
1
+ /**
2
+ * The decision functions of the approval queue (design draft 4 §4, §5, §7). This skeleton holds the reconcile
3
+ * judgement; the decision functions that take the request lock join it once S1's cycles are in the fold.
4
+ */
5
+ /** The facts reconcile reads for one `granted` event (design §5, A-SPEC-794.6). */
6
+ export interface ReconcileInput {
7
+ granted: {
8
+ id: string;
9
+ gen?: string | null;
10
+ nonce: string;
11
+ instance?: string;
12
+ };
13
+ thisInstance: string;
14
+ /** A separate `satisfied` event closed the cycle inline. */
15
+ satisfied: boolean;
16
+ /** The cycle is terminal in the fold. */
17
+ terminal: boolean;
18
+ /** The ledger holds a revocation of the granted nonce. */
19
+ nonceRevoked: boolean;
20
+ /** Each witness by the nonce it names, so a file of another nonce witnesses nothing. */
21
+ witnesses: {
22
+ /** The nonce in `${id}.${gen}.json`, or null when there is no such file. */
23
+ grantFileNonce: string | null;
24
+ /** The nonce in a claimed copy `.claimed.*.${id}.${gen}.json`, or null. */
25
+ claimedCopyNonce: string | null;
26
+ /** The nonce of the queue's `consumed(id, gen)` event, or null. */
27
+ consumedEventNonce: string | null;
28
+ /** The ledger holds a `nonce-consumed` row for the granted nonce. */
29
+ nonceConsumed: boolean;
30
+ };
31
+ /** The publish temp file, parsed; `'unparsable'` when it exists and does not parse; null when there is none. */
32
+ temp: {
33
+ request?: unknown;
34
+ gen?: unknown;
35
+ nonce?: unknown;
36
+ } | 'unparsable' | null;
37
+ }
38
+ export type ReconcileAnswer = 'excluded' | 'complete' | 'settled' | 'finish-publish' | 'revoke';
39
+ /**
40
+ * What reconcile does with one grant:
41
+ * - `excluded`: a legacy grant (no, null or empty gen), an inline `satisfied` event, or another instance's grant;
42
+ * - `complete`: a witness names the granted nonce;
43
+ * - `settled`: the cycle is terminal or the nonce revoked — nothing is repaired, and no publish is finished;
44
+ * - `finish-publish`: the temp file names the same request, gen and nonce;
45
+ * - `revoke`: otherwise; the nonce is revoked and `repair-revoked` closes the cycle.
46
+ */
47
+ export declare function reconcileJudgement(input: ReconcileInput): ReconcileAnswer;
@@ -0,0 +1,29 @@
1
+ "use strict";
2
+ // @implements A-SPEC-794.2, A-SPEC-794.6
3
+ /**
4
+ * The decision functions of the approval queue (design draft 4 §4, §5, §7). This skeleton holds the reconcile
5
+ * judgement; the decision functions that take the request lock join it once S1's cycles are in the fold.
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.reconcileJudgement = reconcileJudgement;
9
+ /**
10
+ * What reconcile does with one grant:
11
+ * - `excluded`: a legacy grant (no, null or empty gen), an inline `satisfied` event, or another instance's grant;
12
+ * - `complete`: a witness names the granted nonce;
13
+ * - `settled`: the cycle is terminal or the nonce revoked — nothing is repaired, and no publish is finished;
14
+ * - `finish-publish`: the temp file names the same request, gen and nonce;
15
+ * - `revoke`: otherwise; the nonce is revoked and `repair-revoked` closes the cycle.
16
+ */
17
+ function reconcileJudgement(input) {
18
+ const g = input.granted, w = input.witnesses;
19
+ if (typeof g.gen !== 'string' || g.gen === '' || input.satisfied || g.instance !== input.thisInstance)
20
+ return 'excluded';
21
+ if (w.grantFileNonce === g.nonce || w.claimedCopyNonce === g.nonce || w.consumedEventNonce === g.nonce || w.nonceConsumed)
22
+ return 'complete';
23
+ if (input.terminal || input.nonceRevoked)
24
+ return 'settled';
25
+ const t = input.temp;
26
+ if (t !== null && t !== 'unparsable' && t.request === g.id && t.gen === g.gen && t.nonce === g.nonce)
27
+ return 'finish-publish';
28
+ return 'revoke';
29
+ }
@@ -1,4 +1,6 @@
1
1
  import { Approval } from '../guardrail/risk-gate';
2
+ import { type SpendResult } from './approval-spend';
3
+ import { type SpendNamespace } from './spend-kinds';
2
4
  /**
3
5
  * The grant file channel — approval delivery with no file editing and no reconnect.
4
6
  *
@@ -32,6 +34,35 @@ export declare const GRANTS_RELDIR: string;
32
34
  export declare function readGrants(root: string): {
33
35
  grants: Approval[];
34
36
  ignored: number;
37
+ refused?: Array<{
38
+ nonce: string;
39
+ reason: 'spent' | 'revoked';
40
+ }>;
41
+ unusable?: string;
42
+ };
43
+ /**
44
+ * @implements A-SPEC-245.9 (H-5, N11), A-SPEC-245.15 (item 2) — the ledger facts the usable-grant judgement reads: whether
45
+ * every chain verifies (chain integrity only: an open double spend is the conflict policy's, and ledger_reconcile's own
46
+ * grant must stay usable while one is open), and which nonces are spent or revoked on any chain. One verification costs
47
+ * about 340 ms on a 40,000-event ledger (M-11), so the facts are cached in `.ax/state/ledger-facts.json`, keyed by each
48
+ * chain file's name, size and mtime; a chain that changes invalidates them. Named limit: a chain rewritten to the same
49
+ * size with its mtime set back is read from the cache. (Here, not in ledger-store: the store's adapter writes only
50
+ * through the chain, REQ-141.)
51
+ */
52
+ export interface LedgerSpendFacts {
53
+ ok: boolean;
54
+ reason?: string;
55
+ spent: (nonce: string) => boolean;
56
+ revoked: (nonce: string) => boolean;
57
+ }
58
+ export declare function ledgerSpendFacts(root: string, ns?: SpendNamespace): LedgerSpendFacts;
59
+ /**
60
+ * The grant files as they are on disk, judged only by their shape — for a path that removes the files of grants it has
61
+ * already spent (the usable judgement would hide them from it).
62
+ */
63
+ export declare function readGrantFiles(root: string): {
64
+ grants: Approval[];
65
+ ignored: number;
35
66
  };
36
67
  /**
37
68
  * @implements A-SPEC-649
@@ -77,7 +108,7 @@ export declare function resolveApproval(root: string, envApproval: Approval | un
77
108
  kind: string;
78
109
  target: string;
79
110
  subject?: string;
80
- }, now: string): {
111
+ }, now: string, spentByThisAct?: readonly Approval[]): {
81
112
  approval: Approval;
82
113
  source: 'env' | 'grant';
83
114
  } | undefined;
@@ -90,3 +121,191 @@ export declare function resolveApproval(root: string, envApproval: Approval | un
90
121
  * The nonce is flattened to a basename so a traversal-shaped nonce cannot reach outside the dir.
91
122
  */
92
123
  export declare function consumeGrantFile(root: string, nonce: string): void;
124
+ /**
125
+ * @implements A-SPEC-245.2 — a grant's lifetime has one seam. A claim moves the grant's file aside by an exclusive rename
126
+ * (one claimant wins; `readGrants` never reads a claimed file, so a claimed grant covers nothing else), then the act
127
+ * either commits it (removed) or releases it (renamed back). "Spend after success" had been repeated at 18 sites, and
128
+ * an `.ax/roles` Write spent its grant at one branch and was denied by the next (measured).
129
+ */
130
+ export declare const CLAIM_PREFIX = ".claimed.";
131
+ export interface GrantClaim {
132
+ readonly nonce: string;
133
+ commit(): void;
134
+ release(): void;
135
+ }
136
+ /**
137
+ * Claim every grant file holding `nonce`, or null when there is none to claim (another claimant won, or none exists).
138
+ * @implements A-SPEC-596 — by the nonce INSIDE the file, never by a path built from it: a grant whose filename differed
139
+ * from its nonce was honoured yet never spent, and no nonce becomes a path, so none can point out of the directory.
140
+ */
141
+ export declare function claimGrant(root: string, nonce: string): GrantClaim | null;
142
+ /** @implements A-SPEC-245.4 (M3) — the claimed copies of the grant file `name` (`<id>.json`), for revocation. */
143
+ export declare function claimedCopiesOf(root: string, name: string): string[];
144
+ /**
145
+ * @implements A-SPEC-245.2, A-SPEC-794.35 — the grant files the store reads: every `*.json` in the grant directory that is
146
+ * not a claimed copy (a claimed grant is in an act's hands and covers nothing else). One set, so a grant that covers its
147
+ * act is also one the screens list and `--revoke` reaches.
148
+ */
149
+ export declare function grantFileNames(root: string): string[];
150
+ /**
151
+ * @implements A-SPEC-794.34, A-SPEC-794.35 — the grant name a file in the grant directory carries: a name in
152
+ * `grantFileNames` without `.json`, or a claimed copy's own name without it; null for anything else.
153
+ */
154
+ export declare function grantFileIdOf(fileName: string): string | null;
155
+ /** A grant field that names request `id`: the id itself or a re-grant `id.r<n>`. */
156
+ export declare function namesRequest(value: unknown, id: string): boolean;
157
+ export type RequestGrantState = {
158
+ state: 'covers';
159
+ grant: string;
160
+ } | {
161
+ state: 'claimed';
162
+ } | {
163
+ state: 'none';
164
+ staleClaim?: true;
165
+ };
166
+ /**
167
+ * @implements A-SPEC-794.35, A-SPEC-794.37 — the one judgement of a granted request's grant: `covers` when `resolveApproval`
168
+ * would authorise its act now (naming the covering file), `claimed` when a live process holds its grant, else `none` (and
169
+ * `staleClaim` when a dead process left its claim, which `doctor` names). A request the fold does not name (a refusal-log
170
+ * one) is judged on every exact act its own grants name. Judged without a subject: `spec_approve` compares it on consumption.
171
+ */
172
+ export declare function requestGrantState(root: string, id: string, act: {
173
+ kind: string;
174
+ target: string;
175
+ } | undefined, now: string): RequestGrantState;
176
+ export type GrantedState = 'live' | 'claimed' | 'consumed' | 'expired' | 'unusable';
177
+ /**
178
+ * @implements A-SPEC-794.37 — the one order of a granted request's state, for `approval_status` and `--status`. A row whose
179
+ * expiry is past, empty or no date is not live whatever a file says (A-SPEC-245.18); a usable grant is live whatever a
180
+ * `consumed` row says (A-SPEC-794.33).
181
+ */
182
+ export declare function grantedStateOf(g: {
183
+ covers: boolean;
184
+ claimed: boolean;
185
+ consumedTs?: string;
186
+ expires?: string;
187
+ }, nowMs: number): GrantedState;
188
+ /**
189
+ * @implements A-SPEC-794.37 — what each file the store reads holds, for the screens: its first scope, and whether it covers
190
+ * now (usable on the ledger, unexpired, not bound to another workspace).
191
+ */
192
+ export declare function grantFileFacts(root: string, now: string): Array<{
193
+ file: string;
194
+ kind: string;
195
+ pattern: string;
196
+ exact: boolean;
197
+ covers: boolean;
198
+ }>;
199
+ /**
200
+ * @implements A-SPEC-245.4 — the grants one decision resolved, settled once when that decision is final. Each branch
201
+ * that resolves a grant holds it here; `settle(true)` claims every held grant (one lost claim returns the rest and
202
+ * answers 'lost') and commits them, `settle(false)` spends nothing. A counterfactual settlement never spends: the
203
+ * hook's audit re-asks its question with no approval, and that reading is not a decision.
204
+ */
205
+ export declare class GrantSettlement {
206
+ readonly spends: boolean;
207
+ private readonly held;
208
+ private readonly envHeld;
209
+ private readonly spent;
210
+ private outcome;
211
+ private why;
212
+ constructor(spends?: boolean);
213
+ static counterfactual(): GrantSettlement;
214
+ hold(root: string, nonce: string, approval?: Approval): void;
215
+ /** @implements A-SPEC-245.9 (1b-2) — an environment single-use approval, spent with the grants when the decision is final. */
216
+ holdEnv(root: string, nonce: string, approval: Approval, summary: string): void;
217
+ /** The approvals of the grants this settlement spent. */
218
+ get committed(): readonly Approval[];
219
+ /** Why the spend refused (outcome `refused`). */
220
+ get refusal(): string | undefined;
221
+ /** @implements A-SPEC-245.9 (1b-2) — what a final allow would spend, as data another thread can settle. */
222
+ pending(): GrantSettlementPending;
223
+ static fromPending(p: GrantSettlementPending): GrantSettlement;
224
+ /** @implements A-SPEC-245.9 (1b-2) — take the outcome another thread settled for this settlement's pending spends. */
225
+ adopt(r: GrantSettlementResult): 'settled' | 'lost' | 'refused';
226
+ /**
227
+ * @implements A-SPEC-245.4, A-SPEC-245.9 (1b-2) — on a final allow: claim every held grant (one lost claim returns the
228
+ * rest: `lost`), write every spend row — the grants' and the environment nonces' — in one spendApprovals call per root
229
+ * under the workspace spend lock (not ok: the claims are returned, `refused`), then commit the claims.
230
+ */
231
+ settle(allowed: boolean): 'settled' | 'lost' | 'refused';
232
+ }
233
+ export interface GrantSettlementPending {
234
+ held: Array<{
235
+ root: string;
236
+ nonce: string;
237
+ approval?: Approval;
238
+ }>;
239
+ env: Array<{
240
+ root: string;
241
+ nonce: string;
242
+ approval: Approval;
243
+ summary: string;
244
+ }>;
245
+ }
246
+ export interface GrantSettlementResult {
247
+ outcome: 'settled' | 'lost' | 'refused';
248
+ committed: Approval[];
249
+ refusal?: string;
250
+ }
251
+ /**
252
+ * @implements A-SPEC-245.2 — the act inside a claim: committed when `succeeded` says so, released on a refusal or a throw.
253
+ * A claim lost to another act answers `lost()`; an act with no grant (an env approval) runs as it is.
254
+ */
255
+ export declare function withGrant<T>(root: string, resolved: {
256
+ source: string;
257
+ approval: {
258
+ nonce?: string;
259
+ };
260
+ } | undefined, act: () => Promise<T> | T, succeeded: (result: T) => boolean, lost: () => T, onThrow?: () => 'commit' | 'release'): Promise<T>;
261
+ /**
262
+ * @implements A-SPEC-245.4 — `withGrant` for an act that runs synchronously under a lock, so the claim is settled before
263
+ * the lock is released. `onThrow` says whether a throw comes after the act already did what the grant authorized.
264
+ */
265
+ export declare function withGrantSync<T>(root: string, resolved: {
266
+ source: string;
267
+ approval: {
268
+ nonce?: string;
269
+ };
270
+ } | undefined, act: () => T, succeeded: (result: T) => boolean, lost: () => T, onThrow?: () => 'commit' | 'release'): T;
271
+ /**
272
+ * @implements A-SPEC-245.2 — claim and commit, for a path that acted under its own lock (entity store, review evidence,
273
+ * runtime binding, the CLI's one-shot acts). A grant with nothing to claim is reported, as before.
274
+ */
275
+ export declare function spendGrants(root: string, nonces: Iterable<string>): void;
276
+ /**
277
+ * @implements A-SPEC-245.9 (1b-1) — an act that a spend refused: `spent` is a replay; `conflict` and `unconfirmed` name
278
+ * the spend-conflict-detected row; `error` is a spend lock or chain lock not obtained in its budget. Nothing acted.
279
+ */
280
+ export declare class GrantSpendRefusal extends Error {
281
+ readonly result: Exclude<SpendResult, {
282
+ ok: true;
283
+ }> | 'error';
284
+ readonly holmesRefusal = true;
285
+ constructor(result: Exclude<SpendResult, {
286
+ ok: true;
287
+ }> | 'error');
288
+ }
289
+ /**
290
+ * @implements A-SPEC-245.9 (1b-1) — spend grant approvals once across every replica chain: one nonce-consumed row per
291
+ * nonce under the workspace spend lock (spendApprovals), written where the act's first byte is about to be written and
292
+ * after every refusal that precedes it. `rationale` carries an entity operation's id, so its recovery can tell its own
293
+ * spend. Throws GrantSpendRefusal when the spend does not answer ok. The grant files stay with their claim or with
294
+ * `spendGrants`, which removes them after the act.
295
+ */
296
+ export declare function spendGrantApprovals(root: string, approvals: readonly Approval[], what: string, rationale?: string): void;
297
+ /**
298
+ * @implements A-SPEC-245.9 (1b-1) — the store's beforePublish (A-SPEC-245.14) for an act a grant authorized: undefined
299
+ * when no grant authorized it (an env approval runs as before).
300
+ */
301
+ export declare function grantSpend(resolved: {
302
+ source: string;
303
+ approval: Approval;
304
+ root?: string;
305
+ } | undefined, what: string, onSpent?: () => void): (() => undefined) | undefined;
306
+ /** @implements A-SPEC-245.2 — claimed files whose process is gone: a crash between claim and settle, for `doctor`. */
307
+ export declare function staleClaims(root: string): Array<{
308
+ file: string;
309
+ pid: number;
310
+ at: string;
311
+ }>;