@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
@@ -45,6 +45,7 @@ const entity_integration_transaction_1 = require("../../spec/entity-integration-
45
45
  const approval_grants_1 = require("../../governance/approval-grants");
46
46
  const approval_queue_1 = require("../../governance/approval-queue");
47
47
  const ledger_store_1 = require("../../governance/ledger-store");
48
+ const recorded_pairs_1 = require("../../governance/recorded-pairs"); // A-SPEC-222.10 H-C: audit bindings from trusted rows
48
49
  const provenance_chain_1 = require("../../governance/provenance-chain");
49
50
  const spec_parser_1 = require("../../spec/spec-parser");
50
51
  const spec_digest_1 = require("../../spec/spec-digest");
@@ -183,11 +184,15 @@ function createEntityIntegrationHandlers(context) {
183
184
  };
184
185
  requireAuthority();
185
186
  const audit = (operation, outcome) => {
186
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
187
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
187
188
  if (!ledger.verifyAll().ok)
188
189
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Abandonment audit cannot extend an invalid ledger.');
189
190
  const ref = 'entity-operation:' + operation.operationId;
190
- if (ledger.loadAll().some(event => event.kind === 'entity-integration-abandoned' && event.inputs?.includes(ref)))
191
+ // A-SPEC-222.10 H-C: an untrusted abandonment row is a conflict, never "already recorded"
192
+ const abandoned = ledger.loadAllRaw().filter(event => event.kind === 'entity-integration-abandoned' && event.inputs?.includes(ref));
193
+ if (ledger.untrusted(abandoned).length > 0)
194
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Abandonment audit record is not a trusted ledger row.' + ledger.untrustedReason(abandoned)); // A-SPEC-222.12 L1
195
+ if (abandoned.length > 0)
191
196
  return;
192
197
  ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-integration-abandoned', summary: 'Abandoned Git entity integration ' + operation.operationId,
193
198
  inputs: [ref, (0, entity_integration_transaction_1.entityIntegrationTarget)(operation), 'workspace:' + operation.workspaceId, 'store:' + operation.storeId, recovery.journalVersion, target,
@@ -215,10 +220,11 @@ function createEntityIntegrationHandlers(context) {
215
220
  env = undefined;
216
221
  }
217
222
  const grants = new Set(), authorities = new Set(), usedGrantRefs = new Set();
223
+ const spentHere = []; // A-SPEC-245.15 (item 2): the grants this act spent still authorize its later steps
218
224
  const grantRef = (approval) => 'grant-use:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify({ actor: approval.actor, token: approval.token, nonce: approval.nonce, scope: approval.scope, expires: approval.expires }));
219
225
  const requireAuthority = (specId) => {
220
226
  const action = { kind: specId ? 'spec-approve' : 'config-write', target: specId ?? target };
221
- const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
227
+ const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString(), spentHere);
222
228
  if (!resolved)
223
229
  throw new entity_store_1.EntityStoreError(specId ? 'spec-approval-required' : 'approval-required', 'Current authority is required for this integration.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Integrate the exact Git inputs while preserving entity identity and official seal transitions.' }));
224
230
  if (resolved.source === 'grant' && resolved.approval.nonce)
@@ -234,7 +240,11 @@ function createEntityIntegrationHandlers(context) {
234
240
  if (!ledger.verifyAll().ok)
235
241
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration cannot rely on an invalid ledger.');
236
242
  const binding = bindingFor(operation), refs = new Set();
237
- for (const event of ledger.loadAll().filter(event => event.kind === 'entity-integration-grant-used' && event.inputs?.includes(binding[0]))) {
243
+ // A-SPEC-222.10 H-C: a forged prior use would leave a real grant unspent, so an untrusted usage row is a conflict
244
+ const rows = ledger.loadAllRaw().filter(event => event.kind === 'entity-integration-grant-used' && event.inputs?.includes(binding[0]));
245
+ if (ledger.untrusted(rows).length > 0)
246
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Grant usage record is not a trusted ledger row.' + ledger.untrustedReason(rows)); // A-SPEC-222.12 L1
247
+ for (const event of rows) {
238
248
  const usages = (event.inputs ?? []).filter(ref => ref.startsWith('grant-use:'));
239
249
  if (binding.some(ref => !event.inputs?.includes(ref)) || usages.length === 0 || usages.some(ref => !/^grant-use:sha256:[0-9a-f]{64}$/.test(ref) || refs.has(ref)))
240
250
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration grant usage has conflicting bindings.');
@@ -244,21 +254,28 @@ function createEntityIntegrationHandlers(context) {
244
254
  return refs;
245
255
  };
246
256
  const recordGrantUse = (operation) => {
247
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
257
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
248
258
  const prior = priorGrantUses(ledger, operation), additional = [...usedGrantRefs].filter(ref => !prior.has(ref));
249
259
  for (const ref of prior)
250
260
  usedGrantRefs.add(ref);
251
261
  if (!additional.length)
252
262
  return;
263
+ // @implements A-SPEC-245.9 (1b-1) — the grants are spent once across replicas in the transaction's
264
+ // beforePublish, the op id in rationale; a recovery finds the reservation below and does not spend again
265
+ const spending = (0, approval_grants_1.readGrants)(bound.root).grants.filter(g => additional.includes(grantRef(g)));
266
+ (0, approval_grants_1.spendGrantApprovals)(bound.root, spending, 'entity-integration ' + operation.operationId, 'entity-operation:' + operation.operationId);
267
+ spentHere.push(...spending);
253
268
  ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-integration-grant-used', summary: 'Recorded grant usage for integration ' + operation.operationId,
254
269
  inputs: [...bindingFor(operation), target, ...additional, ...authorities], rationale: authority.approval.rationale, authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
255
270
  };
256
271
  const audit = (operation, verifyOnly = false, renumbered = []) => {
257
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
272
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
258
273
  const binding = bindingFor(operation);
259
274
  for (const ref of priorGrantUses(ledger, operation))
260
275
  usedGrantRefs.add(ref);
261
- const events = ledger.loadAll(), existing = events.filter(event => event.kind === 'entity-integrated' && event.inputs?.includes(binding[0]));
276
+ const events = ledger.loadAllRaw(), existing = events.filter(event => event.kind === 'entity-integrated' && event.inputs?.includes(binding[0]));
277
+ if (ledger.untrusted(existing).length > 0)
278
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration completion audit record is not a trusted ledger row.' + ledger.untrustedReason(existing)); // A-SPEC-222.12 L1
262
279
  if (existing.length) {
263
280
  if (existing.length !== 1 || binding.some(ref => !existing[0].inputs?.includes(ref)))
264
281
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration completion audit has conflicting bindings.');
@@ -296,11 +313,10 @@ function createEntityIntegrationHandlers(context) {
296
313
  requireAuthority();
297
314
  const result = recovery ? await (0, entity_integration_transaction_1.recoverEntityIntegration)(bound.root, recovery, requireAuthority, audit, recordGrantUse)
298
315
  : await (0, entity_integration_transaction_1.applyEntityIntegration)(bound.root, plan, requireAuthority, audit, recordGrantUse);
299
- for (const grant of (0, approval_grants_1.readGrants)(bound.root).grants)
316
+ for (const grant of (0, approval_grants_1.readGrantFiles)(bound.root).grants)
300
317
  if (grant.nonce && usedGrantRefs.has(grantRef(grant)))
301
- grants.add(grant.nonce);
302
- for (const nonce of grants)
303
- (0, approval_grants_1.consumeGrantFile)(bound.root, nonce);
318
+ grants.add(grant.nonce); // A-SPEC-245.15: spent ones too
319
+ (0, approval_grants_1.spendGrants)(bound.root, grants); // A-SPEC-245.2 — acted under the entity-store lock
304
320
  return result;
305
321
  }
306
322
  if (a.operation !== undefined && a.operation !== 'plan')
@@ -314,6 +330,8 @@ function createEntityIntegrationHandlers(context) {
314
330
  catch (error) {
315
331
  if (error instanceof entity_store_1.EntityStoreError)
316
332
  return { ok: false, code: error.code, reason: error.message };
333
+ if (error instanceof approval_grants_1.GrantSpendRefusal)
334
+ return { ok: false, code: 'grant-spend-refused', reason: 'Nothing was integrated: ' + error.message };
317
335
  throw error;
318
336
  }
319
337
  },
@@ -23,7 +23,7 @@ export declare function createEntityRenumberHandlers(context: {
23
23
  ok: boolean;
24
24
  plan: import("../../spec/entity-renumber-transaction").EntityRenumberRecoveryPlan;
25
25
  code?: undefined;
26
- reason?: undefined;
26
+ readonly reason?: undefined;
27
27
  conflicts?: undefined;
28
28
  ids?: undefined;
29
29
  executable?: undefined;
@@ -48,7 +48,7 @@ export declare function createEntityRenumberHandlers(context: {
48
48
  code: string;
49
49
  conflicts: string[];
50
50
  plan?: undefined;
51
- reason?: undefined;
51
+ readonly reason?: undefined;
52
52
  ids?: undefined;
53
53
  executable?: undefined;
54
54
  blockers?: undefined;
@@ -96,7 +96,7 @@ export declare function createEntityRenumberHandlers(context: {
96
96
  };
97
97
  plan?: undefined;
98
98
  code?: undefined;
99
- reason?: undefined;
99
+ readonly reason?: undefined;
100
100
  conflicts?: undefined;
101
101
  ids?: undefined;
102
102
  recoveryAvailable?: undefined;
@@ -130,7 +130,7 @@ export declare function createEntityRenumberHandlers(context: {
130
130
  schema: string;
131
131
  };
132
132
  code?: undefined;
133
- reason?: undefined;
133
+ readonly reason?: undefined;
134
134
  conflicts?: undefined;
135
135
  ids?: undefined;
136
136
  }>;
@@ -44,6 +44,7 @@ const entity_renumber_transaction_1 = require("../../spec/entity-renumber-transa
44
44
  const approval_grants_1 = require("../../governance/approval-grants");
45
45
  const approval_queue_1 = require("../../governance/approval-queue");
46
46
  const ledger_store_1 = require("../../governance/ledger-store");
47
+ const recorded_pairs_1 = require("../../governance/recorded-pairs"); // A-SPEC-222.10 H-C: audit bindings from trusted rows
47
48
  const provenance_chain_1 = require("../../governance/provenance-chain");
48
49
  function createEntityRenumberHandlers(context) {
49
50
  return {
@@ -88,11 +89,15 @@ function createEntityRenumberHandlers(context) {
88
89
  };
89
90
  requireAuthority();
90
91
  const audit = (operation, outcome) => {
91
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
92
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
92
93
  if (!ledger.verifyAll().ok)
93
94
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Abandonment audit cannot extend an invalid ledger.');
94
95
  const ref = 'entity-operation:' + operation.operationId;
95
- if (ledger.loadAll().some(event => event.kind === 'entity-renumber-abandoned' && event.inputs?.includes(ref)))
96
+ // A-SPEC-222.10 H-C: an untrusted abandonment row is a conflict, never "already recorded"
97
+ const abandoned = ledger.loadAllRaw().filter(event => event.kind === 'entity-renumber-abandoned' && event.inputs?.includes(ref));
98
+ if (ledger.untrusted(abandoned).length > 0)
99
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Abandonment audit record is not a trusted ledger row.' + ledger.untrustedReason(abandoned)); // A-SPEC-222.12 L1
100
+ if (abandoned.length > 0)
96
101
  return;
97
102
  ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-renumber-abandoned', summary: 'Abandoned entity renumbering ' + operation.operationId,
98
103
  inputs: [ref, (0, entity_renumber_transaction_1.entityRenumberTarget)(operation), 'workspace:' + operation.snapshot.workspaceId, 'store:' + operation.snapshot.storeId, recovery.journalVersion, target,
@@ -113,10 +118,11 @@ function createEntityRenumberHandlers(context) {
113
118
  }
114
119
  const grants = new Set(), authorities = new Set();
115
120
  const usedGrantRefs = new Set();
121
+ const spentHere = []; // A-SPEC-245.15 (item 2): the grants this act spent still authorize its later steps
116
122
  const grantRef = (approval) => 'grant-use:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify({ actor: approval.actor, token: approval.token, nonce: approval.nonce, scope: approval.scope, expires: approval.expires }));
117
123
  const requireAuthority = (specId) => {
118
124
  const action = { kind: specId ? 'spec-approve' : 'config-write', target: specId ?? target };
119
- const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
125
+ const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString(), spentHere);
120
126
  if (!resolved)
121
127
  throw new entity_store_1.EntityStoreError(specId ? 'spec-approval-required' : 'approval-required', 'Current authority is required for this renumber operation.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Preserve UUIDs and the official approval closure while renumbering.' }));
122
128
  if (resolved.source === 'grant' && resolved.approval.nonce)
@@ -132,7 +138,11 @@ function createEntityRenumberHandlers(context) {
132
138
  if (!ledger.verifyAll().ok)
133
139
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Grant usage cannot rely on an invalid ledger.');
134
140
  const binding = bindingFor(operation), refs = new Set();
135
- for (const event of ledger.loadAll().filter(event => event.kind === 'entity-renumber-grant-used' && event.inputs?.includes(binding[0]))) {
141
+ // A-SPEC-222.10 H-C: a forged prior use would leave a real grant unspent, so an untrusted usage row is a conflict
142
+ const rows = ledger.loadAllRaw().filter(event => event.kind === 'entity-renumber-grant-used' && event.inputs?.includes(binding[0]));
143
+ if (ledger.untrusted(rows).length > 0)
144
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Grant usage record is not a trusted ledger row.' + ledger.untrustedReason(rows)); // A-SPEC-222.12 L1
145
+ for (const event of rows) {
136
146
  const usages = (event.inputs ?? []).filter(ref => ref.startsWith('grant-use:'));
137
147
  if (binding.some(ref => !event.inputs?.includes(ref)) || usages.length === 0 || usages.some(ref => !/^grant-use:sha256:[0-9a-f]{64}$/.test(ref) || refs.has(ref)))
138
148
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Grant usage has conflicting operation or plan bindings.');
@@ -142,27 +152,34 @@ function createEntityRenumberHandlers(context) {
142
152
  return refs;
143
153
  };
144
154
  const recordGrantUse = (operation) => {
145
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
155
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
146
156
  const prior = priorGrantUses(ledger, operation);
147
157
  const additional = [...usedGrantRefs].filter(ref => !prior.has(ref));
148
158
  for (const ref of prior)
149
159
  usedGrantRefs.add(ref);
150
160
  if (additional.length === 0)
151
161
  return;
162
+ // @implements A-SPEC-245.9 (1b-1) — the grants are spent once across replicas in the transaction's
163
+ // beforePublish, the op id in rationale; a recovery finds the reservation above and does not spend again
164
+ const spending = (0, approval_grants_1.readGrants)(bound.root).grants.filter(g => additional.includes(grantRef(g)));
165
+ (0, approval_grants_1.spendGrantApprovals)(bound.root, spending, 'entity-renumber ' + operation.operationId, 'entity-operation:' + operation.operationId);
166
+ spentHere.push(...spending);
152
167
  ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-renumber-grant-used',
153
168
  summary: 'Reserved grant usage before renumber publication ' + operation.operationId,
154
169
  inputs: [...bindingFor(operation), target, ...additional, ...authorities], rationale: authority.approval.rationale,
155
170
  authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
156
171
  };
157
172
  const audit = (completed, verifyOnly = false) => {
158
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
173
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
159
174
  if (!ledger.verifyAll().ok)
160
175
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Renumber completion cannot extend an invalid ledger.');
161
176
  const operation = 'entity-operation:' + completed.operationId;
162
177
  const binding = bindingFor(completed);
163
178
  for (const ref of priorGrantUses(ledger, completed))
164
179
  usedGrantRefs.add(ref);
165
- const existing = ledger.loadAll().filter(event => event.kind === 'entity-renumbered' && event.inputs?.includes(operation));
180
+ const existing = ledger.loadAllRaw().filter(event => event.kind === 'entity-renumbered' && event.inputs?.includes(operation));
181
+ if (ledger.untrusted(existing).length > 0)
182
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Renumber audit record is not a trusted ledger row.' + ledger.untrustedReason(existing)); // A-SPEC-222.12 L1
166
183
  if (existing.length) {
167
184
  if (existing.length !== 1 || binding.some(ref => !existing[0].inputs?.includes(ref)))
168
185
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Renumber audit has conflicting completion bindings.');
@@ -182,11 +199,10 @@ function createEntityRenumberHandlers(context) {
182
199
  const result = recovery
183
200
  ? await (0, entity_renumber_transaction_1.recoverEntityRenumber)(context.storeRoot, recovery, requireAuthority, audit, recordGrantUse)
184
201
  : await (0, entity_renumber_transaction_1.applyEntityRenumber)(context.storeRoot, plan, requireAuthority, verifyOnly => audit(plan, verifyOnly), recordGrantUse);
185
- for (const grant of (0, approval_grants_1.readGrants)(bound.root).grants)
202
+ for (const grant of (0, approval_grants_1.readGrantFiles)(bound.root).grants)
186
203
  if (grant.nonce && usedGrantRefs.has(grantRef(grant)))
187
- grants.add(grant.nonce);
188
- for (const nonce of grants)
189
- (0, approval_grants_1.consumeGrantFile)(bound.root, nonce);
204
+ grants.add(grant.nonce); // A-SPEC-245.15: spent ones too
205
+ (0, approval_grants_1.spendGrants)(bound.root, grants); // A-SPEC-245.2 — acted under the entity-store lock
190
206
  return result;
191
207
  }
192
208
  if (a.operation !== undefined && a.operation !== 'plan')
@@ -220,6 +236,8 @@ function createEntityRenumberHandlers(context) {
220
236
  catch (error) {
221
237
  if (error instanceof entity_store_1.EntityStoreError)
222
238
  return { ok: false, code: error.code, reason: error.message };
239
+ if (error instanceof approval_grants_1.GrantSpendRefusal)
240
+ return { ok: false, code: 'grant-spend-refused', reason: 'Nothing was renumbered: ' + error.message };
223
241
  throw error;
224
242
  }
225
243
  },
@@ -19,7 +19,7 @@ export declare function createEntityStoreHandlers(context: {
19
19
  ok: boolean;
20
20
  plan: import("../../spec/entity-store").EntityAdoptionPlan;
21
21
  code?: undefined;
22
- reason?: undefined;
22
+ readonly reason?: undefined;
23
23
  } | {
24
24
  ok: boolean;
25
25
  plan: {
@@ -68,7 +68,7 @@ export declare function createEntityStoreHandlers(context: {
68
68
  })[];
69
69
  };
70
70
  code?: undefined;
71
- reason?: undefined;
71
+ readonly reason?: undefined;
72
72
  } | {
73
73
  ok: boolean;
74
74
  code: string;
@@ -34,8 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createEntityStoreHandlers = createEntityStoreHandlers;
37
- // @implements A-SPEC-627, A-SPEC-627.1
38
- // @implements A-SPEC-642
37
+ // @implements A-SPEC-627, A-SPEC-627.1, A-SPEC-222.10, A-SPEC-222.12
38
+ // @implements A-SPEC-642, A-SPEC-245.9, A-SPEC-245.15
39
39
  // @implements A-SPEC-641
40
40
  // @implements A-SPEC-638
41
41
  // @implements A-SPEC-634
@@ -45,6 +45,7 @@ const node_util_1 = require("node:util");
45
45
  const transition_policy_1 = require("../../spec/transition-policy");
46
46
  const spec_parser_1 = require("../../spec/spec-parser");
47
47
  const ledger_store_1 = require("../../governance/ledger-store");
48
+ const recorded_pairs_1 = require("../../governance/recorded-pairs"); // A-SPEC-222.10 H-C: audit bindings from trusted rows
48
49
  const provenance_chain_1 = require("../../governance/provenance-chain");
49
50
  const entity_transaction_1 = require("../../spec/entity-transaction");
50
51
  const entity_store_1 = require("../../spec/entity-store");
@@ -87,6 +88,25 @@ function createEntityStoreHandlers(context) {
87
88
  const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
88
89
  if (!resolved)
89
90
  return { ok: false, code: 'approval-required', reason: 'Recovery requires approval for this exact inspected plan.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Recover the interrupted entity operation while preserving external changes.' }) };
91
+ // @implements A-SPEC-245.9 (1b-1) — the recovery's grants are spent once across replicas before anything is
92
+ // recovered, keyed by the plan's target, so a retry of the same recovery does not spend again
93
+ const spendKey = 'entity-recovery:' + action.target;
94
+ // @implements A-SPEC-245.15 (6a) — the recovery grant is held by its claim while the recovery acts; once spent it
95
+ // is committed whatever follows, and it still authorizes this recovery's later steps (spentHere)
96
+ const claim = resolved.source === 'grant' && resolved.approval.nonce ? (0, approval_grants_1.claimGrant)(bound.root, String(resolved.approval.nonce)) : undefined;
97
+ if (claim === null)
98
+ return { ok: false, code: 'grant-in-use', reason: 'The recovery grant is in use by another act — nothing was recovered; retry.' };
99
+ const spentHere = [];
100
+ if (claim) {
101
+ try {
102
+ (0, approval_grants_1.spendGrantApprovals)(bound.root, [resolved.approval], 'entity-recover', spendKey);
103
+ }
104
+ catch (e) {
105
+ claim.release();
106
+ throw e;
107
+ }
108
+ spentHere.push(resolved.approval);
109
+ }
90
110
  const specGrants = new Set();
91
111
  const specAuthorizations = new Set();
92
112
  const usedGrantRefs = new Set();
@@ -94,20 +114,24 @@ function createEntityStoreHandlers(context) {
94
114
  const auditRecovery = () => {
95
115
  // @implements A-SPEC-634 — an aborted operation binds journal:none; a lock-only release binds no operation.
96
116
  const op = plan.operations[0] ?? { operationId: 'lock-only', storeId: 'none', journalVersion: null, targets: [] }, operationRef = 'entity-operation:' + op.operationId;
97
- const ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
117
+ const ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger')); // A-SPEC-222.10 H-C
98
118
  if (!ledger.verifyAll().ok)
99
119
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Recovery audit cannot extend an invalid ledger.');
100
120
  const binding = [operationRef, 'workspace:' + plan.workspaceId, 'store:' + (op.storeId ?? 'legacy'), 'store-locator:' + plan.storeLocator, op.journalVersion ?? 'journal:none'];
101
- const existing = ledger.loadAll().filter(event => event.kind === 'entity-recovered' && event.inputs?.includes(operationRef));
121
+ // A-SPEC-222.10 H-C: every matching row is read (a conflict refuses), and an untrusted one is a conflict too — a
122
+ // forged record would otherwise end the audit here, before the approval below is asked
123
+ const existing = ledger.loadAllRaw().filter(event => event.kind === 'entity-recovered' && event.inputs?.includes(operationRef));
102
124
  if (existing.length) {
103
125
  if (existing.length !== 1 || binding.some(ref => !existing[0].inputs?.includes(ref)))
104
126
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Recovery audit has conflicting operation bindings.');
127
+ if (ledger.untrusted(existing).length > 0)
128
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Recovery audit record is not a trusted ledger row.' + ledger.untrustedReason(existing)); // A-SPEC-222.12 L1
105
129
  for (const ref of existing[0].inputs ?? [])
106
130
  if (ref.startsWith('grant-use:'))
107
131
  usedGrantRefs.add(ref);
108
132
  return;
109
133
  }
110
- const authority = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
134
+ const authority = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString(), spentHere);
111
135
  if (!authority)
112
136
  throw new entity_store_1.EntityStoreError('approval-required', 'Recovery approval expired before audit completion.');
113
137
  if (authority.source === 'grant')
@@ -122,64 +146,89 @@ function createEntityStoreHandlers(context) {
122
146
  inputs: [...binding, ...ids, (0, entity_store_1.entityRecoveryTarget)(plan), ...specAuthorizations, ...usedGrantRefs], rationale: authority.approval.rationale,
123
147
  authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
124
148
  };
125
- const result = (0, entity_store_1.recoverEntityStore)(context.storeRoot, plan, (before, after, inventory) => {
126
- const specAction = { kind: 'spec-approve', target: after.id };
127
- const requireAuthority = () => {
128
- const authority = (0, approval_grants_1.resolveApproval)(bound.root, env, specAction, new Date().toISOString());
129
- if (!authority)
130
- throw new entity_store_1.EntityStoreError('spec-approval-required', 'This recovery also requires current spec transition authority.' + (0, approval_queue_1.queueHint)(bound.root, { ...specAction, why: 'Recover the interrupted specification transition.' }));
131
- return authority;
132
- };
133
- requireAuthority();
134
- if (!before || !['approved', 'draft', 'outdated'].includes(after.status))
135
- throw new entity_store_1.EntityStoreError('unsupported-recovery', 'Unsupported specification transition.');
136
- const files = new Map();
137
- const readFile = (relative) => {
138
- let text;
139
- try {
140
- text = fs.readFileSync(path.join(bound.root, relative), 'utf8');
141
- }
142
- catch {
143
- text = null;
144
- }
145
- files.set(relative, text);
146
- return text;
147
- };
148
- const prepared = after.status === 'approved'
149
- ? (0, transition_policy_1.prepareApprovedSpec)(before, inventory, specs => id => specs.find(s => s.id === id) ?? null, readFile)
150
- : (0, transition_policy_1.prepareLifecycleSpec)(before, inventory, after.status === 'draft' ? 'unseal' : 'retire', typeof after.frontmatter.retired_reason === 'string' ? after.frontmatter.retired_reason : undefined);
151
- if (!prepared.ok)
152
- throw new entity_store_1.EntityStoreError('spec-policy-refused', after.id + ': ' + prepared.reason); // A-SPEC-641
153
- if (!(0, node_util_1.isDeepStrictEqual)((0, spec_parser_1.parseSpec)((0, spec_parser_1.serializeSpec)(prepared.candidate)), after))
154
- throw new entity_store_1.EntityStoreError('spec-policy-refused', 'The journal differs from the canonical approved transition.');
155
- return () => {
156
- for (const [relative, expected] of files) {
157
- let actual;
149
+ let result;
150
+ try {
151
+ result = (0, entity_store_1.recoverEntityStore)(context.storeRoot, plan, (before, after, inventory) => {
152
+ const specAction = { kind: 'spec-approve', target: after.id };
153
+ const requireAuthority = () => {
154
+ const authority = (0, approval_grants_1.resolveApproval)(bound.root, env, specAction, new Date().toISOString(), spentHere);
155
+ if (!authority)
156
+ throw new entity_store_1.EntityStoreError('spec-approval-required', 'This recovery also requires current spec transition authority.' + (0, approval_queue_1.queueHint)(bound.root, { ...specAction, why: 'Recover the interrupted specification transition.' }));
157
+ return authority;
158
+ };
159
+ requireAuthority();
160
+ if (!before || !['approved', 'draft', 'outdated'].includes(after.status))
161
+ throw new entity_store_1.EntityStoreError('unsupported-recovery', 'Unsupported specification transition.');
162
+ const files = new Map();
163
+ const readFile = (relative) => {
164
+ let text;
158
165
  try {
159
- actual = fs.readFileSync(path.join(bound.root, relative), 'utf8');
166
+ text = fs.readFileSync(path.join(bound.root, relative), 'utf8');
160
167
  }
161
168
  catch {
162
- actual = null;
169
+ text = null;
163
170
  }
164
- if (actual !== expected)
165
- throw new entity_store_1.EntityStoreError('plan-changed', 'Compatibility policy inputs changed before recovery publication.');
171
+ files.set(relative, text);
172
+ return text;
173
+ };
174
+ const prepared = after.status === 'approved'
175
+ ? (0, transition_policy_1.prepareApprovedSpec)(before, inventory, specs => id => specs.find(s => s.id === id) ?? null, readFile)
176
+ : (0, transition_policy_1.prepareLifecycleSpec)(before, inventory, after.status === 'draft' ? 'unseal' : 'retire', typeof after.frontmatter.retired_reason === 'string' ? after.frontmatter.retired_reason : undefined);
177
+ if (!prepared.ok)
178
+ throw new entity_store_1.EntityStoreError('spec-policy-refused', after.id + ': ' + prepared.reason); // A-SPEC-641
179
+ if (!(0, node_util_1.isDeepStrictEqual)((0, spec_parser_1.parseSpec)((0, spec_parser_1.serializeSpec)(prepared.candidate)), after))
180
+ throw new entity_store_1.EntityStoreError('spec-policy-refused', 'The journal differs from the canonical approved transition.');
181
+ return () => {
182
+ for (const [relative, expected] of files) {
183
+ let actual;
184
+ try {
185
+ actual = fs.readFileSync(path.join(bound.root, relative), 'utf8');
186
+ }
187
+ catch {
188
+ actual = null;
189
+ }
190
+ if (actual !== expected)
191
+ throw new entity_store_1.EntityStoreError('plan-changed', 'Compatibility policy inputs changed before recovery publication.');
192
+ }
193
+ const authority = requireAuthority();
194
+ specAuthorizations.add('spec-authorization:' + (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token));
195
+ if (authority.source === 'grant')
196
+ usedGrantRefs.add(grantRef(authority.approval));
197
+ if (authority.source === 'grant' && authority.approval.nonce) {
198
+ (0, approval_grants_1.spendGrantApprovals)(bound.root, [authority.approval], 'entity-recover ' + after.id, spendKey); // A-SPEC-245.9, before publication
199
+ spentHere.push(authority.approval);
200
+ specGrants.add(authority.approval.nonce);
201
+ }
202
+ };
203
+ }, auditRecovery);
204
+ }
205
+ catch (e) {
206
+ // the recovery grant was spent before the recovery: used, so committed whatever failed after
207
+ if (claim) {
208
+ try {
209
+ claim.commit();
166
210
  }
167
- const authority = requireAuthority();
168
- specAuthorizations.add('spec-authorization:' + (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token));
169
- if (authority.source === 'grant')
170
- usedGrantRefs.add(grantRef(authority.approval));
171
- if (authority.source === 'grant' && authority.approval.nonce)
172
- specGrants.add(authority.approval.nonce);
173
- };
174
- }, auditRecovery);
211
+ catch (c) {
212
+ process.stderr.write(`[Holmes-Kit] ${c.message}\n`);
213
+ }
214
+ }
215
+ throw e;
216
+ }
175
217
  const consumed = new Set(specGrants);
176
- if (resolved.source === 'grant' && resolved.approval.nonce)
177
- consumed.add(resolved.approval.nonce);
178
- for (const grant of (0, approval_grants_1.readGrants)(bound.root).grants)
218
+ for (const grant of (0, approval_grants_1.readGrantFiles)(bound.root).grants)
179
219
  if (grant.nonce && usedGrantRefs.has(grantRef(grant)))
180
220
  consumed.add(grant.nonce);
181
- for (const nonce of consumed)
182
- (0, approval_grants_1.consumeGrantFile)(bound.root, nonce);
221
+ if (claim)
222
+ consumed.delete(String(resolved.approval.nonce)); // its file is the claim's, committed below
223
+ (0, approval_grants_1.spendGrants)(bound.root, consumed); // A-SPEC-245.2 — acted under the entity-store lock
224
+ if (claim) {
225
+ try {
226
+ claim.commit();
227
+ }
228
+ catch (c) {
229
+ process.stderr.write(`[Holmes-Kit] ${c.message}\n`);
230
+ }
231
+ }
183
232
  return result;
184
233
  }
185
234
  if (a.operation === 'adopt') {
@@ -195,16 +244,41 @@ function createEntityStoreHandlers(context) {
195
244
  const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
196
245
  if (!resolved)
197
246
  return { ok: false, code: 'approval-required', reason: 'Entity adoption requires approval for this exact plan.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Adopt the configured spec store without changing sealed documents.' }) };
198
- const result = (0, entity_store_1.adoptEntityStore)(context.storeRoot, plan);
199
- if (resolved.source === 'grant' && resolved.approval.nonce)
200
- (0, approval_grants_1.consumeGrantFile)(bound.root, resolved.approval.nonce);
201
- return result;
247
+ // @implements A-SPEC-245.9 (1b-1) — spent once across replicas before the adoption, keyed by its plan
248
+ // @implements A-SPEC-245.15 (6a) — held by its claim while the adoption acts, committed once spent
249
+ const claim = resolved.source === 'grant' && resolved.approval.nonce ? (0, approval_grants_1.claimGrant)(bound.root, String(resolved.approval.nonce)) : undefined;
250
+ if (claim === null)
251
+ return { ok: false, code: 'grant-in-use', reason: 'The adoption grant is in use by another act — nothing was adopted; retry.' };
252
+ if (claim) {
253
+ try {
254
+ (0, approval_grants_1.spendGrantApprovals)(bound.root, [resolved.approval], 'entity-adopt', 'entity-adoption:' + action.target);
255
+ }
256
+ catch (e) {
257
+ claim.release();
258
+ throw e;
259
+ }
260
+ }
261
+ try {
262
+ return (0, entity_store_1.adoptEntityStore)(context.storeRoot, plan);
263
+ }
264
+ finally {
265
+ if (claim) {
266
+ try {
267
+ claim.commit();
268
+ }
269
+ catch (c) {
270
+ process.stderr.write(`[Holmes-Kit] ${c.message}\n`);
271
+ }
272
+ }
273
+ }
202
274
  }
203
275
  throw new entity_store_1.EntityStoreError('unsupported-operation', 'Use status, plan-adoption, recovery-plan or explicitly authorized adopt/recover.');
204
276
  }
205
277
  catch (e) {
206
278
  if (e instanceof entity_store_1.EntityStoreError || e instanceof workspace_identity_1.WorkspaceIdentityError)
207
279
  return { ok: false, code: e.code, reason: e.message };
280
+ if (e instanceof approval_grants_1.GrantSpendRefusal)
281
+ return { ok: false, code: 'grant-spend-refused', reason: 'Nothing was changed: ' + e.message };
208
282
  throw e;
209
283
  }
210
284
  },
@@ -6,9 +6,13 @@ import type { ApprovalStatus } from '../../spec/approval-status';
6
6
  export interface ApprovalRequestState {
7
7
  id: string;
8
8
  /** @implements A-SPEC-779.3 — `withdrawn`: the run that filed it closed it; no operator decided it. */
9
- state: 'pending' | 'held' | 'granted' | 'consumed' | 'denied' | 'revoked' | 'withdrawn';
9
+ /** @implements A-SPEC-794.33 — `unusable`: granted, unspent and unexpired, but no grant file is left to cover the act. */
10
+ /** @implements A-SPEC-794.35 — `claimed`: an act holds the grant now. */
11
+ state: 'pending' | 'held' | 'granted' | 'unusable' | 'claimed' | 'expired' | 'consumed' | 'denied' | 'revoked' | 'withdrawn';
10
12
  question?: string;
11
13
  reason?: string;
14
+ /** @implements A-SPEC-245.9 (1b-6) — for a live grant: "single use, until <time>" or "single use, no time limit". */
15
+ validity?: string;
12
16
  ts?: string;
13
17
  }
14
18
  /**
@@ -106,7 +110,7 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
106
110
  blockers: string[];
107
111
  resealBlockers: string[];
108
112
  ok: boolean;
109
- reason?: undefined;
113
+ readonly reason?: undefined;
110
114
  }>;
111
115
  /**
112
116
  * @implements A-SPEC-538.3
@@ -126,7 +130,7 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
126
130
  } | {
127
131
  ok: boolean;
128
132
  events: import("../../governance/ledger-timeline").TimelineEntry[];
129
- reason?: undefined;
133
+ readonly reason?: undefined;
130
134
  }>;
131
135
  /**
132
136
  * @implements A-SPEC-642
@@ -179,7 +183,7 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
179
183
  ts: string;
180
184
  }[];
181
185
  remaining: string[];
182
- reason?: undefined;
186
+ readonly reason?: undefined;
183
187
  pending?: undefined;
184
188
  code?: undefined;
185
189
  }>;
@@ -217,6 +221,6 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
217
221
  retiredCount: number;
218
222
  findingsScanned: boolean;
219
223
  };
220
- reason?: undefined;
224
+ readonly reason?: undefined;
221
225
  }>;
222
226
  };