@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
@@ -54,6 +54,8 @@ export interface RefusalRecord {
54
54
  reasonBytes?: number;
55
55
  /** @implements A-SPEC-779.2 — the run that filed it; absent outside a run. */
56
56
  requester_run?: string;
57
+ /** @implements A-SPEC-779.7 — the MCP server instance that filed it; absent for hooks and the CLI. */
58
+ requester_server?: string;
57
59
  }
58
60
  export declare function refusalsFilename(replica: string): string;
59
61
  /** Born split: there is no legacy single `refusals.jsonl` — the file did not exist before replicas did. */
@@ -92,7 +94,10 @@ export interface PendingRequest {
92
94
  title?: string;
93
95
  /** @implements A-SPEC-779.2 — the run that filed it, the only one that may withdraw it; absent outside a run. */
94
96
  requesterRun?: string;
97
+ /** @implements A-SPEC-779.7 — the MCP server instance that filed it (`<pid>:<startedAt>`), which may withdraw it. */
98
+ requesterServer?: string;
95
99
  }
100
+ export declare function setRequesterServer(instance: string | undefined): void;
96
101
  export interface QueueState {
97
102
  pending: PendingRequest[];
98
103
  /**
@@ -146,6 +151,17 @@ export interface QueueState {
146
151
  ts: string;
147
152
  execution?: ExecutionContext;
148
153
  }>;
154
+ /**
155
+ * @implements A-SPEC-794.31
156
+ * Requests an unreleased 0.40 development build filed (their rows carry `gen`) and left open there. They are not
157
+ * pending and are not decided here; present only when non-empty, so the empty-state pins keep their shape.
158
+ */
159
+ devFiled?: Record<string, {
160
+ kind: string;
161
+ target: string;
162
+ requesterRun?: string;
163
+ requesterServer?: string;
164
+ }>;
149
165
  }
150
166
  /**
151
167
  * Deterministic request id from the action's identity.
@@ -157,6 +173,21 @@ export interface QueueState {
157
173
  * The timestamp rides on the EVENT, never in the id.
158
174
  */
159
175
  export declare function approvalRequestId(kind: string, target: string): string;
176
+ /**
177
+ * @implements A-SPEC-794.32 — the keys only S1's writers put on a queue row (measured on 9028712a's own output, and no
178
+ * writer of this version writes one): a row with any of them, whatever its value, is a development-build row.
179
+ */
180
+ export declare const DEV_KEYS: readonly string[];
181
+ /** @implements A-SPEC-794.31 — the line a screen ends with while development-build requests are left; null when none. */
182
+ export declare function devFiledNote(state: QueueState): string | null;
183
+ /**
184
+ * @implements A-SPEC-794.31 — the refusal a decision gets when its reference names a development-build request (its
185
+ * id or a unique prefix); null otherwise. A-SPEC-794.32 — called only after the resolver found nothing, so a reference
186
+ * that names a decidable request is never refused here, and a list number is the resolver's to answer.
187
+ * A-SPEC-794.33 — one match is named with its subject, several are each listed (L8); `exact` takes the whole id only, as
188
+ * approval_ask and approval_withdraw name a request (B-2).
189
+ */
190
+ export declare function devFiledRefusal(state: QueueState, ref: string, exact?: boolean): string | null;
160
191
  /**
161
192
  * Fold queue events into the current pending list. Pure.
162
193
  *
@@ -33,14 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.DECISION_KINDS = exports.QUEUE_RELPATH = void 0;
36
+ exports.DEV_KEYS = exports.DECISION_KINDS = exports.QUEUE_RELPATH = void 0;
37
37
  exports.requestLabel = requestLabel;
38
38
  exports.pendingRequestLine = pendingRequestLine;
39
39
  exports.approvalAskLine = approvalAskLine;
40
40
  exports.refusalsFilename = refusalsFilename;
41
41
  exports.isRefusalsFilename = isRefusalsFilename;
42
42
  exports.readRefusals = readRefusals;
43
+ exports.setRequesterServer = setRequesterServer;
43
44
  exports.approvalRequestId = approvalRequestId;
45
+ exports.devFiledNote = devFiledNote;
46
+ exports.devFiledRefusal = devFiledRefusal;
44
47
  exports.foldQueue = foldQueue;
45
48
  exports.enqueueApprovalRequest = enqueueApprovalRequest;
46
49
  exports.enqueueApprovalRequestDetailed = enqueueApprovalRequestDetailed;
@@ -51,15 +54,17 @@ exports.refusalsOutsideInbox = refusalsOutsideInbox;
51
54
  exports.grantableRequests = grantableRequests;
52
55
  exports.openOccurrences = openOccurrences;
53
56
  exports.asPendingRequest = asPendingRequest;
54
- // @implements A-SPEC-134.2, A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.12, A-SPEC-779.2
57
+ // @implements A-SPEC-134.2, A-SPEC-794.31, A-SPEC-794.32, A-SPEC-794.33, A-SPEC-794.34,A-SPEC-244,A-SPEC-626, A-SPEC-752, A-SPEC-754, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.12, A-SPEC-779.2
55
58
  const execution_context_1 = require("../project/execution-context");
56
59
  const run_mode_1 = require("./run-mode");
57
60
  const root_1 = require("../project/root");
58
61
  const node_crypto_1 = require("node:crypto");
59
62
  const fs = __importStar(require("node:fs"));
60
63
  const path = __importStar(require("node:path"));
61
- const screen_safe_1 = require("../cli/screen-safe");
64
+ // @implements A-SPEC-794.4 — the text renderer from the project layer, so governance imports no cli
65
+ const screen_text_1 = require("../project/screen-text");
62
66
  const replica_id_1 = require("./replica-id");
67
+ const human_channel_1 = require("./human-channel");
63
68
  /**
64
69
  * The approval request queue — the review list a human batches decisions over.
65
70
  *
@@ -106,7 +111,7 @@ exports.DECISION_KINDS = new Set([
106
111
  function requestLabel(kind, target, title) {
107
112
  if (typeof title !== 'string' || title.trim() === '')
108
113
  return '';
109
- const f = (s, max) => (0, screen_safe_1.flattenField)(s, max).replace(/[\]「」]/g, ' ').trim();
114
+ const f = (s, max) => (0, screen_text_1.flattenField)(s, max).replace(/[\]「」]/g, ' ').trim();
110
115
  return ` · ${f(kind ?? '', 40)} ${f(target ?? '', 60)} 「${f(title, 80)}」`;
111
116
  }
112
117
  /**
@@ -171,6 +176,15 @@ function readRefusals(root) {
171
176
  }
172
177
  return out.sort((a, b) => (a.r.ts < b.r.ts ? -1 : a.r.ts > b.r.ts ? 1 : a.i - b.i)).map((e) => e.r);
173
178
  }
179
+ /**
180
+ * @implements A-SPEC-779.7 — the requester key of a filing made inside the MCP server: its instance id, set once at
181
+ * server start. Process-global on purpose: a request is filed deep inside handlers that never see the server. Hooks and
182
+ * the CLI never set it, so their filings carry no `requester_server`.
183
+ */
184
+ let requesterServer;
185
+ function setRequesterServer(instance) {
186
+ requesterServer = typeof instance === 'string' && instance !== '' ? instance.slice(0, 120) : undefined;
187
+ }
174
188
  /**
175
189
  * Deterministic request id from the action's identity.
176
190
  *
@@ -183,6 +197,44 @@ function readRefusals(root) {
183
197
  function approvalRequestId(kind, target) {
184
198
  return 'req-' + (0, node_crypto_1.createHash)('sha256').update(`${kind}:${target}`).digest('hex').slice(0, 12);
185
199
  }
200
+ /** @implements A-SPEC-794.31 — the decision rows: a development build's are applied, and any of them ends its record. */
201
+ const DEV_CLOSING = new Set(['granted', 'denied', 'revoked', 'withdrawn', 'consumed']);
202
+ /**
203
+ * @implements A-SPEC-794.32 — the keys only S1's writers put on a queue row (measured on 9028712a's own output, and no
204
+ * writer of this version writes one): a row with any of them, whatever its value, is a development-build row.
205
+ */
206
+ exports.DEV_KEYS = ['gen', 'hv', 'instance', 'prev', 'prevCause', 'cause', 'legacy'];
207
+ /** @implements A-SPEC-794.31 — the line a screen ends with while development-build requests are left; null when none. */
208
+ function devFiledNote(state) {
209
+ const n = Object.keys(state.devFiled ?? {}).length;
210
+ return n === 0 ? null
211
+ // A-SPEC-794.34 — "cannot be decided" contradicted the deny words (B-3): they cannot be granted, a person may deny one
212
+ : `◆ ${n} request(s) filed by an unreleased 0.40 development build are not listed and cannot be granted — a person may deny one by its id; the agent's next attempt files each again`;
213
+ }
214
+ /**
215
+ * @implements A-SPEC-794.31 — the refusal a decision gets when its reference names a development-build request (its
216
+ * id or a unique prefix); null otherwise. A-SPEC-794.32 — called only after the resolver found nothing, so a reference
217
+ * that names a decidable request is never refused here, and a list number is the resolver's to answer.
218
+ * A-SPEC-794.33 — one match is named with its subject, several are each listed (L8); `exact` takes the whole id only, as
219
+ * approval_ask and approval_withdraw name a request (B-2).
220
+ */
221
+ function devFiledRefusal(state, ref, exact = false) {
222
+ const r = String(ref ?? '').trim();
223
+ if (r === '' || /^\d+$/.test(r))
224
+ return null;
225
+ const dev = state.devFiled ?? {};
226
+ const ids = Object.keys(dev);
227
+ const hit = ids.includes(r) ? [r] : exact ? [] : ids.filter((id) => id.startsWith(r));
228
+ if (hit.length === 1) {
229
+ const d = dev[hit[0]];
230
+ return `${hit[0]} (${(0, screen_text_1.flattenField)(d.kind, 24)} ${(0, screen_text_1.flattenField)(d.target, 60)}) was filed by an unreleased 0.40 development build; 0.40.0 does not grant it — a person may deny it by its id, and the agent's next attempt files it again as a new request`;
231
+ }
232
+ if (hit.length > 1) {
233
+ return [`'${(0, screen_text_1.flattenField)(r, 30)}' matches ${hit.length} requests filed by an unreleased 0.40 development build; 0.40.0 grants none of them — give one full id to deny it:`,
234
+ ...hit.map((id) => ` ${id}`)].join('\n');
235
+ }
236
+ return null;
237
+ }
186
238
  /**
187
239
  * Fold queue events into the current pending list. Pure.
188
240
  *
@@ -195,6 +247,7 @@ function foldQueue(lines, opts) {
195
247
  const decisions = {};
196
248
  const holds = {};
197
249
  const subjects = {};
250
+ const devFiled = {};
198
251
  let malformedLines = 0;
199
252
  for (const raw of Array.isArray(lines) ? lines : []) {
200
253
  const line = String(raw ?? '').trim();
@@ -224,6 +277,35 @@ function foldQueue(lines, opts) {
224
277
  }
225
278
  }
226
279
  const id = typeof e.id === 'string' ? e.id : undefined;
280
+ // @implements A-SPEC-794.31, A-SPEC-794.32 — a row carrying any S1 key was written by an unreleased 0.40 development
281
+ // build (S1, reverted by A-SPEC-794.30; every row its final code wrote carries hv and instance, its legacy closing no
282
+ // gen). Its request is not pending: it is remembered as development-filed. Its decisions are a person's and are
283
+ // applied as plain ones (a grant must stay visible and revocable, a denial must reach the hint); its legacy closing
284
+ // closes the plain request it superseded; its holds and its own cycle closings change nothing.
285
+ if (exports.DEV_KEYS.some((k) => k in e)) {
286
+ // A-SPEC-794.33 — the latest row's requester, so the run or server that filed it can withdraw it (L3)
287
+ if (id && e.event === 'requested') {
288
+ devFiled[id] = {
289
+ kind: String(e.kind ?? ''), target: String(e.target ?? ''),
290
+ ...(typeof e.requester_run === 'string' && e.requester_run !== '' ? { requesterRun: e.requester_run } : {}),
291
+ ...(typeof e.requester_server === 'string' && e.requester_server !== '' ? { requesterServer: e.requester_server } : {}),
292
+ };
293
+ continue;
294
+ }
295
+ // A-SPEC-794.33 — the legacy closing leaves a trace: the request it closed is development-filed, named and deniable
296
+ if (id && e.event === 'superseded' && e.legacy === true) {
297
+ const closed = pending.get(id);
298
+ if (closed && !devFiled[id])
299
+ devFiled[id] = { kind: closed.kind, target: closed.target };
300
+ pending.delete(id);
301
+ continue;
302
+ }
303
+ if (!id || !DEV_CLOSING.has(String(e.event)))
304
+ continue;
305
+ }
306
+ // A-SPEC-794.32 — a request or a decision of the id ends the development record; a hold does not
307
+ if (id && (e.event === 'requested' || DEV_CLOSING.has(String(e.event))))
308
+ delete devFiled[id];
227
309
  switch (e.event) {
228
310
  case 'requested': {
229
311
  if (!id) {
@@ -268,6 +350,7 @@ function foldQueue(lines, opts) {
268
350
  ...(typeof e.risk === 'string' && e.risk !== '' ? { risk: e.risk } : {}),
269
351
  ...(typeof e.title === 'string' && e.title !== '' ? { title: e.title } : {}), // @implements A-SPEC-770.12
270
352
  ...(typeof e.requester_run === 'string' && e.requester_run !== '' ? { requesterRun: e.requester_run } : {}), // @implements A-SPEC-779.2
353
+ ...(typeof e.requester_server === 'string' && e.requester_server !== '' ? { requesterServer: e.requester_server } : {}), // @implements A-SPEC-779.7
271
354
  });
272
355
  }
273
356
  break;
@@ -338,10 +421,26 @@ function foldQueue(lines, opts) {
338
421
  break;
339
422
  }
340
423
  }
424
+ // @implements A-SPEC-794.32 — a listed id is not counted as development-filed (a union merge can put its plain request
425
+ // first). A-SPEC-794.33 — a person's hold is no longer erased here: queueHint files a held request again when nothing
426
+ // is pending, so a hold cannot deadlock (A-M3)
427
+ for (const id of Object.keys(devFiled))
428
+ if (pending.has(id))
429
+ delete devFiled[id];
430
+ // @implements A-SPEC-794.33 — a hold lasts until a decision, whatever the row order: a request filed after the hold
431
+ // carries it, so the list, the hint and approval_status say the same (A-M4, the hold that flipped back)
432
+ for (const [id, h] of Object.entries(holds)) {
433
+ const entry = pending.get(id);
434
+ if (entry && !entry.hold) {
435
+ entry.hold = true;
436
+ if (h.question !== undefined)
437
+ entry.question = h.question;
438
+ }
439
+ }
341
440
  const all = [...pending.values()];
342
441
  const ttl = typeof opts?.ttlMs === 'number' && typeof opts?.now === 'number'
343
442
  ? { ttlMs: opts.ttlMs, now: opts.now } : null;
344
- const withSubjects = Object.keys(subjects).length > 0 ? { subjects } : {};
443
+ const withSubjects = { ...(Object.keys(subjects).length > 0 ? { subjects } : {}), ...(Object.keys(devFiled).length > 0 ? { devFiled } : {}) };
345
444
  if (ttl === null)
346
445
  return { pending: all, expired: [], malformedLines, decisions, holds, ...withSubjects };
347
446
  // @implements A-SPEC-507.1 — strict excess only, and an unparseable lastTs stays ACTIVE: a
@@ -424,8 +523,9 @@ function enqueueApprovalRequestDetailed(root, req) {
424
523
  ...(execution ? { execution } : {}),
425
524
  ...(typeof req.subject === 'string' && req.subject !== '' ? { subject: req.subject } : {}),
426
525
  ...(typeof req.risk === 'string' && req.risk !== '' ? { risk: req.risk } : {}),
427
- ...(typeof req.title === 'string' && req.title.trim() !== '' ? { title: (0, screen_safe_1.flattenField)(req.title, 200) } : {}), // @implements A-SPEC-770.12
526
+ ...(typeof req.title === 'string' && req.title.trim() !== '' ? { title: (0, screen_text_1.flattenField)(req.title, 200) } : {}), // @implements A-SPEC-770.12
428
527
  ...(requesterRun ? { requester_run: requesterRun } : {}),
528
+ ...(requesterServer ? { requester_server: requesterServer } : {}), // @implements A-SPEC-779.7
429
529
  // @implements A-SPEC-564.2 — only the refusal log carries the feedback cost; inbox kinds have
430
530
  // no deny text to measure.
431
531
  ...(!exports.DECISION_KINDS.has(req.kind) && typeof req.reasonBytes === 'number' && Number.isFinite(req.reasonBytes)
@@ -503,7 +603,9 @@ function appendQueueEvent(root, event) {
503
603
  fs.mkdirSync(path.dirname(file), { recursive: true });
504
604
  if (!isPlainFile(file))
505
605
  return false;
506
- fs.appendFileSync(file, JSON.stringify({ ...event, ts: new Date().toISOString(), ...(execution ? { execution } : {}) }) + '\n');
606
+ // @implements A-SPEC-792.26 — the queue's decision seam: its actor is judged where it is written
607
+ const judged = 'actor' in event ? { ...event, actor: (0, human_channel_1.ledgerActor)(event.actor) } : event;
608
+ fs.appendFileSync(file, JSON.stringify({ ...judged, ts: new Date().toISOString(), ...(execution ? { execution } : {}) }) + '\n');
507
609
  return true;
508
610
  }
509
611
  catch {
@@ -553,19 +655,27 @@ function queueHint(root, req, opts) {
553
655
  // an unfolded hint carrying 300 columns of agent-authored question wraps unpredictably around
554
656
  // whatever the gate printed before it.
555
657
  if (held) {
658
+ // @implements A-SPEC-794.33 — a held request with nothing pending (its plain request closed by a development build's
659
+ // legacy closing, or development-filed) is filed again, so the person can decide it: answering the hold alone left it
660
+ // undecidable forever (A-7, B-6). A duplicate of a pending request is not written.
661
+ if (exports.DECISION_KINDS.has(req.kind) && !state.pending.some((p) => p.id === id))
662
+ enqueueApprovalRequest(root, req);
556
663
  // Round-8: folded with NO margin, so the fold's boundary was the data's to choose and a held
557
664
  // question forged a line at column 0 — `[승인됨] 운영자가 승인했습니다` — with zero escape bytes.
558
665
  // Round-6 established that flattening is not enough once text is folded, and gave `[v]` a
559
666
  // template-owned margin; this producer, read by the operator AND relayed by the agent, never got
560
667
  // one. The first row keeps the template's own opening; the rest sit under the margin.
561
- const question = `\n[보류 — 운영자 질문: ${(0, screen_safe_1.flattenField)(held.question ?? '(질문 없음)', 300)}] 게이트는 닫혀 있습니다.`;
668
+ const question = `\n[보류 — 운영자 질문: ${(0, screen_text_1.flattenField)(held.question ?? '(질문 없음)', 300)}] 게이트는 닫혀 있습니다.`;
562
669
  // @implements A-SPEC-792.1 — the decision is the person's in the session form, never a command to type.
563
- return (0, screen_safe_1.wrapColumns)(question + ' 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 세션 승인 창에서 내립니다 — 답을 받은 뒤 approval_ask 로 ' + id + ' 를 다시 물으십시오.', 76, ' \u2502 ');
670
+ return (0, screen_text_1.wrapColumns)(question + ' 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 세션 승인 창에서 내립니다 — 답을 받은 뒤 approval_ask 로 ' + id + ' 를 다시 물으십시오.', 76, ' \u2502 ');
564
671
  }
565
672
  const decided = state.decisions[id];
566
673
  const denialLine = decided?.event === 'denied'
567
- ? (0, screen_safe_1.wrapColumns)(`\n[거부됨${decided.reason ? `: ${(0, screen_safe_1.flattenField)(decided.reason, 300)}` : ''}] 같은 요청을 반복하지 말고 거부 사유를 해소해 사용자와 상의하십시오.`, 76, ' \u2502 ')
568
- : '';
674
+ ? (0, screen_text_1.wrapColumns)(`\n[거부됨${decided.reason ? `: ${(0, screen_text_1.flattenField)(decided.reason, 300)}` : ''}] 같은 요청을 반복하지 말고 거부 사유를 해소해 사용자와 상의하십시오.`, 76, ' \u2502 ')
675
+ : decided?.event === 'granted'
676
+ // @implements A-SPEC-792.17 — asked again for the same act: say the earlier grant was single use and is spent
677
+ ? (0, screen_text_1.wrapColumns)(`\n[이전 승인 소진: ${(0, screen_text_1.flattenField)(decided.consumedTs || decided.ts || '이전', 40)}의 승인은 1회용이었고 첫 사용에 소진됐습니다 — 같은 행위를 다시 하려면 새 결정이 필요합니다]`, 76, ' │ ')
678
+ : '';
569
679
  // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
570
680
  // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
571
681
  // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
@@ -669,5 +779,6 @@ function asPendingRequest(id, occurrences) {
669
779
  lastTs: latest.ts,
670
780
  ...(latest.replica ? { replica: latest.replica } : {}),
671
781
  ...(latest.requester_run ? { requesterRun: latest.requester_run } : {}), // @implements A-SPEC-779.2
782
+ ...(latest.requester_server ? { requesterServer: latest.requester_server } : {}), // @implements A-SPEC-779.7
672
783
  };
673
784
  }
@@ -0,0 +1,95 @@
1
+ import { type LedgerStore, type SpendLedger, type RevocationAppend } from './ledger-store';
2
+ import { type SpendNamespace } from './spend-kinds';
3
+ import type { LedgerActor } from './human-channel';
4
+ /** `actor` is written through the chain's ledgerActor, so a person-channel actor keeps its registration. */
5
+ export interface SpendApproval {
6
+ nonce: string;
7
+ actor: LedgerActor;
8
+ summary: string;
9
+ rationale: string;
10
+ authorization?: string;
11
+ }
12
+ /** The closed set of commit kinds in 1a. */
13
+ export type SpendCommit = {
14
+ readonly kind: 'rename';
15
+ readonly from: string;
16
+ readonly to: string;
17
+ } | {
18
+ readonly kind: 'profile';
19
+ readonly from: string;
20
+ readonly to: string;
21
+ };
22
+ export declare const renameCommit: (from: string, to: string) => SpendCommit;
23
+ export declare const profileCommit: (from: string, to: string) => SpendCommit;
24
+ /**
25
+ * `conflict`: a spend of the same approval appeared on a chain this spend could not exclude (A-SPEC-245.11);
26
+ * `unconfirmed`: such a chain could not be read (A-SPEC-245.12). Either way no commit ran, and the approval is used.
27
+ */
28
+ export type SpendResult = {
29
+ ok: true;
30
+ } | {
31
+ ok: false;
32
+ reason: 'spent' | 'revoked' | 'conflict' | 'unconfirmed';
33
+ };
34
+ /** The commit failed after its spend rows were written: the approvals are spent and nothing changed. */
35
+ export declare class SpendCommitError extends Error {
36
+ readonly cause: unknown;
37
+ readonly code = "commit-failed";
38
+ readonly holmesRefusal = true;
39
+ constructor(cause: unknown);
40
+ }
41
+ /**
42
+ * @implements A-SPEC-245.9 (H-2, M-10) — revoke a single-use nonce once across every replica chain, under the workspace
43
+ * spend lock and through the SpendLedger port: `spent` (on any chain; nothing written), `revoked-already`, or `revoked`
44
+ * (one nonce-revoked row). A lock not obtained within the budget throws (the acquire timeout).
45
+ */
46
+ export declare function revokeNonce(root: string, nonce: string, by: {
47
+ actor: LedgerActor;
48
+ reason: string;
49
+ }, opts?: {
50
+ budgetMs?: number;
51
+ ledger?: SpendLedger & LedgerStore;
52
+ }): RevocationAppend;
53
+ /** The project root of a writer chain file `<root>/.ax/ledger/<chain>` (A-SPEC-245.9, 1b-1). */
54
+ export declare function projectRootOfChain(chainFile: string): string;
55
+ /**
56
+ * Why an act path refuses after a spend that did not answer ok (A-SPEC-245.9, 1b-1); `error` is a spend that threw
57
+ * (the spend lock or a chain lock not obtained in its budget) — nothing was spent and nothing acted.
58
+ */
59
+ export declare function spendRefusalReason(r: Exclude<SpendResult, {
60
+ ok: true;
61
+ }> | 'error'): string;
62
+ /**
63
+ * The canonical fingerprint of a spend row, for double-spend grouping only (NH-2): its first input that is a
64
+ * fingerprint, else the fingerprint of its first input (a row written before fingerprints). Null without inputs.
65
+ */
66
+ export declare function canonicalNonceOf(row: {
67
+ inputs?: string[];
68
+ }): string | null;
69
+ /**
70
+ * @param opts.ledger the SpendLedger to spend through (A-SPEC-245.12, X5); the workspace's file ledger by default.
71
+ */
72
+ /** The most nonces one request id walks: the id and `.r1` … `.r1000`. */
73
+ export declare const NONCE_WALK_BOUND = 1000;
74
+ /**
75
+ * @implements A-SPEC-794.5 — the one walk over a request id's nonces, the way the CLI issues them: the id, then `.r1`,
76
+ * `.r2`, …, passing over a nonce that was spent or revoked. `fresh` is the first nonce neither (null past the bound);
77
+ * `spent` says whether a nonce passed over was spent. The ledger is read once, and both the raw nonce and its
78
+ * fingerprint count, as isNonceConsumed counts them.
79
+ */
80
+ export declare function nonceWalk(ledger: LedgerStore, id: string, ns?: SpendNamespace): {
81
+ fresh: string | null;
82
+ spent: boolean;
83
+ };
84
+ /**
85
+ * @implements A-SPEC-794.4 — whether a request id was ever spent: under the id itself or under an `.rN` nonce. A caller
86
+ * that asked the id alone missed a spent `.r1` grant whose first nonce had been revoked. A-SPEC-794.5: the walk is
87
+ * `nonceWalk`, shared with the CLI's fresh nonce.
88
+ */
89
+ export declare function requestEverSpent(ledger: LedgerStore, id: string, ns?: SpendNamespace): boolean;
90
+ export declare function spendApprovals(root: string, approvals: SpendApproval[], step: {
91
+ commit?: SpendCommit;
92
+ }, opts?: {
93
+ budgetMs?: number;
94
+ ledger?: SpendLedger & LedgerStore;
95
+ }): SpendResult;
@@ -0,0 +1,191 @@
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.NONCE_WALK_BOUND = exports.SpendCommitError = exports.profileCommit = exports.renameCommit = void 0;
37
+ exports.revokeNonce = revokeNonce;
38
+ exports.projectRootOfChain = projectRootOfChain;
39
+ exports.spendRefusalReason = spendRefusalReason;
40
+ exports.canonicalNonceOf = canonicalNonceOf;
41
+ exports.nonceWalk = nonceWalk;
42
+ exports.requestEverSpent = requestEverSpent;
43
+ exports.spendApprovals = spendApprovals;
44
+ // @implements A-SPEC-245.8, A-SPEC-245.10, A-SPEC-245.11, A-SPEC-245.12, A-SPEC-245.9, A-SPEC-245.16, A-SPEC-794.4, A-SPEC-794.5, A-SPEC-794.46
45
+ /**
46
+ * Spending approvals once across replica chains (A-SPEC-245.7, its callers moved here by A-SPEC-245.9).
47
+ *
48
+ * `spendApprovals(root, approvals, step)`, under the workspace spend lock:
49
+ * 1. re-checks every nonce against the merged ledger, inside every replica chain's append lock (the file adapter
50
+ * takes them), so an older writer that takes one chain lock is excluded too;
51
+ * 2. appends one spend row per approval, its one input the nonce's fingerprint and its context in `rationale`;
52
+ * 3. runs the step's commit, one of a closed set of kinds built by their constructors.
53
+ * The row is written before the commit (A-SPEC-245.10, correction of A-SPEC-245.8 item 6): a crash between them leaves
54
+ * the approval spent and nothing changed. A commit that fails records `spend-commit-failed` and throws `commit-failed`.
55
+ *
56
+ * One budget covers the spend lock and all the chain locks together.
57
+ */
58
+ const fs = __importStar(require("node:fs"));
59
+ const path = __importStar(require("node:path"));
60
+ const spend_lock_1 = require("../project/spend-lock");
61
+ const provenance_chain_1 = require("./provenance-chain");
62
+ const ledger_store_1 = require("./ledger-store");
63
+ const spend_kinds_1 = require("./spend-kinds");
64
+ const renameCommit = (from, to) => ({ kind: 'rename', from, to });
65
+ exports.renameCommit = renameCommit;
66
+ const profileCommit = (from, to) => ({ kind: 'profile', from, to });
67
+ exports.profileCommit = profileCommit;
68
+ /** Each kind's measured worst case, the bound doctor's alarm multiplies by four. */
69
+ const COMMIT_BOUND_MS = { rename: 1000, profile: 1000 };
70
+ /** The commit failed after its spend rows were written: the approvals are spent and nothing changed. */
71
+ class SpendCommitError extends Error {
72
+ cause;
73
+ code = 'commit-failed';
74
+ holmesRefusal = true;
75
+ constructor(cause) {
76
+ super(`the spend was recorded and its commit failed: ${cause?.message ?? String(cause)}`);
77
+ this.cause = cause;
78
+ }
79
+ }
80
+ exports.SpendCommitError = SpendCommitError;
81
+ /**
82
+ * @implements A-SPEC-245.9 (H-2, M-10) — revoke a single-use nonce once across every replica chain, under the workspace
83
+ * spend lock and through the SpendLedger port: `spent` (on any chain; nothing written), `revoked-already`, or `revoked`
84
+ * (one nonce-revoked row). A lock not obtained within the budget throws (the acquire timeout).
85
+ */
86
+ function revokeNonce(root, nonce, by, opts = {}) {
87
+ const budgetMs = opts.budgetMs ?? 5000;
88
+ const deadline = Date.now() + budgetMs;
89
+ const ledger = opts.ledger ?? new ledger_store_1.FileLedgerStore(path.join(root, '.ax', 'ledger'));
90
+ return (0, spend_lock_1.withSpendLock)(root, { budgetMs, nonces: [(0, provenance_chain_1.nonceFingerprint)(nonce)], boundMs: budgetMs + 1000 }, () => ledger.appendRevocationIfUnspent(nonce, { ts: new Date().toISOString(), actor: by.actor, kind: ledger_store_1.NONCE_REVOKED,
91
+ summary: 'revoked single-use approval', inputs: [(0, provenance_chain_1.nonceFingerprint)(nonce)], rationale: by.reason }, deadline));
92
+ }
93
+ /** The project root of a writer chain file `<root>/.ax/ledger/<chain>` (A-SPEC-245.9, 1b-1). */
94
+ function projectRootOfChain(chainFile) {
95
+ return path.dirname(path.dirname(path.dirname(chainFile)));
96
+ }
97
+ /**
98
+ * Why an act path refuses after a spend that did not answer ok (A-SPEC-245.9, 1b-1); `error` is a spend that threw
99
+ * (the spend lock or a chain lock not obtained in its budget) — nothing was spent and nothing acted.
100
+ */
101
+ function spendRefusalReason(r) {
102
+ // A-SPEC-141: a contention refusal is worded apart from a replay (could not obtain exclusive access, not "consumed")
103
+ if (r === 'error')
104
+ return 'could not obtain exclusive ledger access to spend the single-use approval (spend lock or a chain lock not obtained in its budget) — nothing was spent and nothing was done; retry';
105
+ if (r.reason === 'spent')
106
+ return '단일 사용 승인(nonce)이 이미 소비되었습니다 — 재사용은 부재와 같이 거부됩니다';
107
+ // A-SPEC-245.16 (item 1): refused like a spent approval — nothing spent, nothing done
108
+ if (r.reason === 'revoked')
109
+ return '단일 사용 승인(nonce)이 철회되었습니다 — 철회된 승인은 아무것도 허용하지 않습니다. 아무것도 소비·실행되지 않았습니다';
110
+ return `단일 사용 승인(nonce)의 1회 소비를 확정하지 못했습니다(${r.reason}: spend-conflict-detected 행이 그 승인을 지목합니다) — 실행하지 않았고 승인은 사용된 것으로 봅니다. 새 승인을 받으십시오`;
111
+ }
112
+ const FINGERPRINT = /^nonce:[0-9a-f]{12}$/;
113
+ /**
114
+ * The canonical fingerprint of a spend row, for double-spend grouping only (NH-2): its first input that is a
115
+ * fingerprint, else the fingerprint of its first input (a row written before fingerprints). Null without inputs.
116
+ */
117
+ function canonicalNonceOf(row) {
118
+ const inputs = row.inputs ?? [];
119
+ const fp = inputs.find((i) => FINGERPRINT.test(i));
120
+ if (fp)
121
+ return fp;
122
+ return inputs.length > 0 && typeof inputs[0] === 'string' ? (0, provenance_chain_1.nonceFingerprint)(inputs[0]) : null;
123
+ }
124
+ function runCommit(commit) {
125
+ fs.mkdirSync(path.dirname(commit.to), { recursive: true });
126
+ fs.renameSync(commit.from, commit.to);
127
+ }
128
+ /**
129
+ * @param opts.ledger the SpendLedger to spend through (A-SPEC-245.12, X5); the workspace's file ledger by default.
130
+ */
131
+ /** The most nonces one request id walks: the id and `.r1` … `.r1000`. */
132
+ exports.NONCE_WALK_BOUND = 1000;
133
+ /**
134
+ * @implements A-SPEC-794.5 — the one walk over a request id's nonces, the way the CLI issues them: the id, then `.r1`,
135
+ * `.r2`, …, passing over a nonce that was spent or revoked. `fresh` is the first nonce neither (null past the bound);
136
+ * `spent` says whether a nonce passed over was spent. The ledger is read once, and both the raw nonce and its
137
+ * fingerprint count, as isNonceConsumed counts them.
138
+ */
139
+ function nonceWalk(ledger, id, ns = 'grant') {
140
+ const events = ledger.loadAll();
141
+ const inputsOf = (kind) => new Set(events.filter((e) => e.kind === kind).flatMap((e) => e.inputs ?? []));
142
+ const spentInputs = inputsOf((0, spend_kinds_1.spendKind)(ns));
143
+ const revokedInputs = inputsOf((0, spend_kinds_1.revokeKind)(ns));
144
+ const has = (set, nonce) => set.has(nonce) || set.has((0, provenance_chain_1.nonceFingerprint)(nonce));
145
+ let spent = false;
146
+ for (let n = 0; n <= exports.NONCE_WALK_BOUND; n++) {
147
+ const nonce = n === 0 ? id : `${id}.r${n}`;
148
+ const wasSpent = has(spentInputs, nonce);
149
+ if (!wasSpent && !has(revokedInputs, nonce))
150
+ return { fresh: nonce, spent };
151
+ spent = spent || wasSpent;
152
+ }
153
+ return { fresh: null, spent };
154
+ }
155
+ /**
156
+ * @implements A-SPEC-794.4 — whether a request id was ever spent: under the id itself or under an `.rN` nonce. A caller
157
+ * that asked the id alone missed a spent `.r1` grant whose first nonce had been revoked. A-SPEC-794.5: the walk is
158
+ * `nonceWalk`, shared with the CLI's fresh nonce.
159
+ */
160
+ function requestEverSpent(ledger, id, ns = 'grant') {
161
+ return nonceWalk(ledger, id, ns).spent;
162
+ }
163
+ function spendApprovals(root, approvals, step, opts = {}) {
164
+ const budgetMs = opts.budgetMs ?? 5000;
165
+ const deadline = Date.now() + budgetMs;
166
+ const unique = [...new Map(approvals.map((a) => [a.nonce, a])).values()];
167
+ const nonces = unique.map((a) => (0, provenance_chain_1.nonceFingerprint)(a.nonce));
168
+ const ledger = opts.ledger ?? new ledger_store_1.FileLedgerStore(path.join(root, '.ax', 'ledger'));
169
+ // W4: the hold covers the wait for the chain locks as well as the commit, so 4x the bound outlasts any live holder
170
+ const boundMs = budgetMs + (step.commit ? COMMIT_BOUND_MS[step.commit.kind] : 1000);
171
+ return (0, spend_lock_1.withSpendLock)(root, { budgetMs, nonces, boundMs }, () => {
172
+ const ts = new Date().toISOString();
173
+ const spends = unique.map((a) => ({ nonce: a.nonce, row: { ts, actor: a.actor, kind: (0, spend_kinds_1.spendKind)('grant'), summary: a.summary, inputs: [(0, provenance_chain_1.nonceFingerprint)(a.nonce)],
174
+ rationale: a.rationale, ...(a.authorization !== undefined ? { authorization: a.authorization } : {}) } }));
175
+ const appended = ledger.appendIfUnspent(spends, deadline);
176
+ if (appended !== 'appended')
177
+ return { ok: false, reason: appended };
178
+ if (step.commit) {
179
+ try {
180
+ runCommit(step.commit);
181
+ }
182
+ catch (e) {
183
+ ledger.append({ ts: new Date().toISOString(), actor: 'holmes-kit', kind: 'spend-commit-failed',
184
+ summary: `the ${step.commit.kind} commit failed after its spend was recorded`, inputs: nonces,
185
+ rationale: e?.message ?? String(e) });
186
+ throw new SpendCommitError(e);
187
+ }
188
+ }
189
+ return { ok: true };
190
+ });
191
+ }
@@ -0,0 +1,61 @@
1
+ export type ShellVerdict = {
2
+ ok: true;
3
+ paths: string[];
4
+ proven: Array<{
5
+ path: string;
6
+ blob: string;
7
+ }>;
8
+ conditions: Record<string, string>;
9
+ } | {
10
+ ok: false;
11
+ failed: string;
12
+ detail: string;
13
+ };
14
+ export interface LedgerEventLike {
15
+ kind?: string;
16
+ inputs?: unknown;
17
+ ts?: string;
18
+ actor?: unknown;
19
+ summary?: string;
20
+ }
21
+ export interface ShellDeps {
22
+ /** What the add would stage, as `git status --porcelain -z` names it; null when git cannot answer. */
23
+ statusPaths(pathspecs: string[] | null): Array<{
24
+ path: string;
25
+ deleted: boolean;
26
+ }> | null;
27
+ ledgerEvents(): LedgerEventLike[];
28
+ /** @implements A-SPEC-222.9 — the entries `ledgerEvents` left out, described for an unproven reason ('' when none). */
29
+ ignoredEvents?(): string;
30
+ /** @implements A-SPEC-222.10 — this writer's own ledger file, as git names it from the root (`.ax/ledger/provenance.<id>.jsonl`). */
31
+ ownLedgerFile?(): string | null;
32
+ chainsVerify(): boolean;
33
+ queueMalformed(): number;
34
+ /** A description of the product-installed problems for these staged paths, or null when there are none. */
35
+ productProblems(staged: string[]): string | null;
36
+ /** @implements A-SPEC-792.32 — the bytes of a regular, non-executable file (git mode 100644), else null. */
37
+ readBytes(rel: string): Buffer | null;
38
+ /** The repository's object format, which names its blobs (SHA-1 when absent). */
39
+ objectFormat?(): 'sha1' | 'sha256';
40
+ }
41
+ export declare function governanceStagingOnly(reasons: readonly string[]): boolean;
42
+ /** 1. Grammar: `git add|stage` (-A, --all or literal paths), then `&& git status …` with an optional counted pipe. */
43
+ export declare function stagingGrammar(command: string): {
44
+ ok: true;
45
+ pathspecs: string[] | null;
46
+ } | {
47
+ ok: false;
48
+ detail: string;
49
+ };
50
+ export declare function autonomousShellVerdict(input: {
51
+ command: string;
52
+ root: string;
53
+ shellStaging: 'on' | 'off';
54
+ specsRel?: string;
55
+ base?: string;
56
+ specStaging?: boolean;
57
+ }, deps: ShellDeps): ShellVerdict;
58
+ /** The real readers: git in the workspace, its provenance ledger, its queue and its install manifest. */
59
+ export declare function realShellDeps(root: string): ShellDeps;
60
+ /** For approve --list: the last autonomous shell approvals (time, command digest, path count). */
61
+ export declare function renderAutonomousApprovals(events: LedgerEventLike[], limit?: number): string;