@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
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The one place a person-channel actor is minted. A ledger row under `elicitation:` or `host-gated:` says a person
3
+ * decided in a form or a host's approval dialog; the server writes one only after its form gate passed, from the
4
+ * attested harness, never from a tool's input (F1-e.0d: risk_check recorded a forged `elicitation:claude-code`).
5
+ * The prefixes are spelled in this file only; a census holds every other spelling under src/holmes at zero.
6
+ *
7
+ * @implements A-SPEC-792.26 — a type brand on a string is erased at run time, so a ledger seam could not tell a minted
8
+ * `elicitation:claude` from an environment approval with the same text (F1-e.0e: reproduced). A minted actor is a
9
+ * frozen object this module registers; every ledger seam writes its actor through ledgerActor, which writes a
10
+ * registered object as its text and any string that claims a person channel as `unattested:<string>`.
11
+ */
12
+ declare const humanChannel: unique symbol;
13
+ /**
14
+ * A person-channel actor, minted only by humanChannelActor: a frozen String object, so string methods and
15
+ * interpolation read its text, while it is not a `string` and only a seam turns it into one.
16
+ */
17
+ export interface HumanChannelActor extends String {
18
+ readonly value: string;
19
+ readonly [humanChannel]: true;
20
+ }
21
+ /** What a ledger seam accepts as an actor. */
22
+ export type LedgerActor = string | HumanChannelActor;
23
+ declare const PREFIX: {
24
+ readonly elicitation: "elicitation:";
25
+ readonly 'host-gated': "host-gated:";
26
+ };
27
+ export declare function humanChannelActor(channel: keyof typeof PREFIX, harness: string): HumanChannelActor;
28
+ /** Whether a string claims a person channel, in any case, spacing or Unicode spelling. */
29
+ export declare function isHumanChannelActor(s: unknown): boolean;
30
+ /** Whether an actor value came from the mint. */
31
+ export declare function isMinted(a: unknown): a is HumanChannelActor;
32
+ /** The text a ledger seam writes for an actor: a minted one as is, a claimed person channel as unattested. */
33
+ export declare function ledgerActor(a: LedgerActor | unknown): string;
34
+ /** An authorization reference written beside an actor: one claiming a person channel stands only with a minted actor. */
35
+ export declare function ledgerAuthorization(authorization: string | undefined, actor: LedgerActor | unknown): string | undefined;
36
+ /** An actor that came in through a tool's input: recorded as such, never as a person. */
37
+ export declare function toolInputActor(s: LedgerActor | undefined): string;
38
+ export {};
@@ -0,0 +1,49 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.humanChannelActor = humanChannelActor;
4
+ exports.isHumanChannelActor = isHumanChannelActor;
5
+ exports.isMinted = isMinted;
6
+ exports.ledgerActor = ledgerActor;
7
+ exports.ledgerAuthorization = ledgerAuthorization;
8
+ exports.toolInputActor = toolInputActor;
9
+ const PREFIX = { elicitation: 'elicitation:', 'host-gated': 'host-gated:' };
10
+ const minted = new WeakSet();
11
+ function humanChannelActor(channel, harness) {
12
+ const value = `${PREFIX[channel]}${harness}`;
13
+ // a summary that interpolates the actor reads its text; that text handed back to a seam is unattested
14
+ const actor = Object.freeze(Object.assign(new String(value), { value }));
15
+ minted.add(actor);
16
+ return actor;
17
+ }
18
+ /** Folded as a reader would: NFKC, lower case, and nothing but `a-z`, `0-9` and `:` kept (`host‐gated`, ` Elicitation`). */
19
+ const fold = (s) => s.normalize('NFKC').toLowerCase().replace(/[^a-z0-9:]/g, '');
20
+ const FOLDED = Object.values(PREFIX).map(fold);
21
+ /** Whether a string claims a person channel, in any case, spacing or Unicode spelling. */
22
+ function isHumanChannelActor(s) {
23
+ return typeof s === 'string' && FOLDED.some((p) => fold(s).startsWith(p));
24
+ }
25
+ /** Whether an actor value came from the mint. */
26
+ function isMinted(a) {
27
+ return typeof a === 'object' && a !== null && minted.has(a);
28
+ }
29
+ /** The text a ledger seam writes for an actor: a minted one as is, a claimed person channel as unattested. */
30
+ function ledgerActor(a) {
31
+ if (isMinted(a))
32
+ return a.value;
33
+ const s = typeof a === 'string' ? a
34
+ : typeof a === 'object' && a !== null && typeof a.value === 'string' ? a.value
35
+ : String(a);
36
+ // @implements A-SPEC-792.27 — and anything outside printable ASCII: confusables (Cyrillic е, U+A789, a combining
37
+ // accent) slipped past the fold, and a closed rule ends that family; a non-ASCII OS user is over-marked, never a person
38
+ return isHumanChannelActor(s) || /[^\x20-\x7e]/.test(s) ? `unattested:${s}` : s;
39
+ }
40
+ /** An authorization reference written beside an actor: one claiming a person channel stands only with a minted actor. */
41
+ function ledgerAuthorization(authorization, actor) {
42
+ if (authorization === undefined || isMinted(actor) || !isHumanChannelActor(authorization))
43
+ return authorization;
44
+ return `unattested:${authorization}`;
45
+ }
46
+ /** An actor that came in through a tool's input: recorded as such, never as a person. */
47
+ function toolInputActor(s) {
48
+ return `tool-input:${s === undefined ? 'unknown' : String(s)}`;
49
+ }
@@ -0,0 +1,22 @@
1
+ export declare const INSTALL_MANIFEST: string;
2
+ export interface ManifestFile {
3
+ path: string;
4
+ sha256: string;
5
+ }
6
+ export interface ProductProblem {
7
+ path?: string;
8
+ why: 'manifest-missing' | 'manifest-invalid' | 'manifest-tampered' | 'missing' | 'changed' | 'staged' | 'in-index';
9
+ }
10
+ export declare function readInstallManifest(root: string): ManifestFile[] | null;
11
+ /**
12
+ * Records `paths` (absolute or target-relative) and every path the previous manifest listed that still exists, each with
13
+ * the sha256 of its content now; a path outside the target is never listed.
14
+ */
15
+ export declare function writeInstallManifest(target: string, paths: string[], version: string): void;
16
+ export declare function removeInstallManifest(target: string): void;
17
+ /**
18
+ * Each manifest file that is missing, changed against its digest, in `staged` (paths a command stages, target-relative)
19
+ * or staged in the index against HEAD; `manifest-missing` when there is no readable manifest.
20
+ */
21
+ export declare function productInstalledProblems(root: string, staged?: string[]): ProductProblem[];
22
+ export declare function describeProductInstalled(problems: ProductProblem[]): string;
@@ -0,0 +1,160 @@
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.INSTALL_MANIFEST = void 0;
37
+ exports.readInstallManifest = readInstallManifest;
38
+ exports.writeInstallManifest = writeInstallManifest;
39
+ exports.removeInstallManifest = removeInstallManifest;
40
+ exports.productInstalledProblems = productInstalledProblems;
41
+ exports.describeProductInstalled = describeProductInstalled;
42
+ // @implements A-SPEC-792.16, A-SPEC-222.10, A-SPEC-794.55, A-SPEC-794.57
43
+ /**
44
+ * The files the product installed in a target, by path and digest, as init recorded them. A self-approval must never
45
+ * cover one of them: a changed, staged or missing product file — or no record at all — is a reason to refuse.
46
+ */
47
+ const crypto = __importStar(require("node:crypto"));
48
+ const fs = __importStar(require("node:fs"));
49
+ const path = __importStar(require("node:path"));
50
+ const bounded_io_1 = require("../project/bounded-io");
51
+ exports.INSTALL_MANIFEST = path.join('.ax', 'state', 'install-manifest.json');
52
+ const MANIFEST_EVENT = 'install-manifest';
53
+ const digestOf = (abs) => {
54
+ try {
55
+ return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
56
+ }
57
+ catch {
58
+ return null;
59
+ }
60
+ };
61
+ const inside = (root, abs) => { const r = path.relative(root, abs); return r !== '' && !r.startsWith('..') && !path.isAbsolute(r); };
62
+ function readInstallManifest(root) {
63
+ const r = readManifestChecked(root);
64
+ return r === null ? null : r.files;
65
+ }
66
+ /** The manifest's entries, and whether any entry was malformed (dropped). Null when there is no readable manifest. */
67
+ function readManifestChecked(root) {
68
+ try {
69
+ const m = JSON.parse(fs.readFileSync(path.join(root, exports.INSTALL_MANIFEST), 'utf8'));
70
+ if (!Array.isArray(m.files))
71
+ return null;
72
+ const files = m.files.filter((f) => !!f && typeof f.path === 'string' && typeof f.sha256 === 'string');
73
+ return { files, malformed: files.length !== m.files.length };
74
+ }
75
+ catch {
76
+ return null;
77
+ }
78
+ }
79
+ /** @implements A-SPEC-792.18 — the digest the last init recorded for the manifest, or null when none is recorded. */
80
+ function recordedManifestDigest(root) {
81
+ try {
82
+ // @implements A-SPEC-222.10 — H-C (M-3): the recorded digest comes from trusted events (a forged event hid tampering)
83
+ const { TrustedLedgerStore } = require('./recorded-pairs');
84
+ const evs = new TrustedLedgerStore(path.join(root, '.ax', 'ledger')).loadAll();
85
+ for (let i = evs.length - 1; i >= 0; i--) {
86
+ if (evs[i].kind !== MANIFEST_EVENT)
87
+ continue;
88
+ const d = (evs[i].inputs ?? []).find((x) => x.startsWith('sha256:'));
89
+ return d ? d.slice(7) : null;
90
+ }
91
+ }
92
+ catch { /* unreadable ledger: nothing is recorded */ }
93
+ return null;
94
+ }
95
+ /**
96
+ * Records `paths` (absolute or target-relative) and every path the previous manifest listed that still exists, each with
97
+ * the sha256 of its content now; a path outside the target is never listed.
98
+ */
99
+ function writeInstallManifest(target, paths, version) {
100
+ const previous = (readInstallManifest(target) ?? []).map((f) => f.path);
101
+ const rels = [...new Set([...paths.map((p) => path.isAbsolute(p) ? p : path.join(target, p)), ...previous.map((p) => path.join(target, p))]
102
+ .filter((abs) => inside(target, abs)).map((abs) => path.relative(target, abs)))].sort();
103
+ const files = rels.map((rel) => ({ path: rel, sha256: digestOf(path.join(target, rel)) })).filter((f) => f.sha256 !== null);
104
+ const file = path.join(target, exports.INSTALL_MANIFEST);
105
+ fs.mkdirSync(path.dirname(file), { recursive: true });
106
+ const tmp = `${file}.${process.pid}.tmp`;
107
+ const text = `${JSON.stringify({ schema: 'install-manifest/1', holmes: version, files }, null, 2)}\n`;
108
+ fs.writeFileSync(tmp, text, { mode: 0o644 });
109
+ fs.renameSync(tmp, file);
110
+ // @implements A-SPEC-792.18 — the manifest's own digest, kept where the judgement can compare it
111
+ const { FileLedgerStore } = require('./ledger-store');
112
+ new FileLedgerStore(path.join(target, '.ax', 'ledger')).append({ ts: new Date().toISOString(), actor: 'holmes-kit init', kind: MANIFEST_EVENT,
113
+ summary: `install manifest of ${files.length} file(s)`, inputs: [`sha256:${crypto.createHash('sha256').update(text).digest('hex')}`] });
114
+ }
115
+ function removeInstallManifest(target) {
116
+ try {
117
+ fs.rmSync(path.join(target, exports.INSTALL_MANIFEST), { force: true });
118
+ }
119
+ catch { /* nothing to remove */ }
120
+ }
121
+ /**
122
+ * Each manifest file that is missing, changed against its digest, in `staged` (paths a command stages, target-relative)
123
+ * or staged in the index against HEAD; `manifest-missing` when there is no readable manifest.
124
+ */
125
+ function productInstalledProblems(root, staged = []) {
126
+ const checked = readManifestChecked(root);
127
+ if (checked === null)
128
+ return [{ why: 'manifest-missing' }];
129
+ const files = checked.files;
130
+ // @implements A-SPEC-792.18 — a manifest that cannot vouch for anything, or is not the one init recorded, is never clear
131
+ const head = [];
132
+ if (files.length === 0 || checked.malformed)
133
+ head.push({ why: 'manifest-invalid' });
134
+ const recorded = recordedManifestDigest(root);
135
+ if (recorded === null || digestOf(path.join(root, exports.INSTALL_MANIFEST)) !== recorded)
136
+ head.push({ why: 'manifest-tampered' });
137
+ const norm = (p) => path.normalize(p);
138
+ const stagedSet = new Set(staged.map(norm));
139
+ const r = (0, bounded_io_1.gitOnce)(root, ['-c', 'core.fsmonitor=false', 'diff', '--cached', '--name-only', '-z', '--no-renames'], 'repo');
140
+ const indexChanged = new Set(r.status === 0 ? String(r.stdout).split('\0').filter(Boolean).map(norm) : []);
141
+ const out = [...head];
142
+ for (const f of files) {
143
+ const now = digestOf(path.join(root, f.path));
144
+ if (now === null)
145
+ out.push({ path: f.path, why: 'missing' });
146
+ else if (now !== f.sha256)
147
+ out.push({ path: f.path, why: 'changed' });
148
+ // A-SPEC-794.57 — what the command stages, and what the index already holds, are told apart
149
+ if (stagedSet.has(norm(f.path)))
150
+ out.push({ path: f.path, why: 'staged' });
151
+ else if (indexChanged.has(norm(f.path)))
152
+ out.push({ path: f.path, why: 'in-index' });
153
+ }
154
+ return out;
155
+ }
156
+ function describeProductInstalled(problems) {
157
+ return problems.map((p) => p.why === 'manifest-missing' ? 'product-installed: no install manifest (run holmes-kit init)'
158
+ : p.path === undefined ? `product-installed: the install manifest is ${p.why === 'manifest-invalid' ? 'invalid' : 'not the one init recorded'} (${p.why})`
159
+ : `product-installed: ${p.path} (${p.why === 'in-index' ? 'already in the index' : p.why})`).join('; ');
160
+ }
@@ -104,6 +104,8 @@ function rechainLedger(mainline, working, key) {
104
104
  // Timestamp order, stable for ties (Array#sort is stable): the tail reads chronologically.
105
105
  orphans.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
106
106
  const events = [...mainline];
107
+ // @implements A-SPEC-792.27 — the seams' named limit: an orphan is re-chained VERBATIM. Its actor was judged when it
108
+ // was first written (ledgerActor), and judging the recorded text again would mark every person row unattested.
107
109
  for (const o of orphans)
108
110
  events.push((0, provenance_chain_1.chainNext)(events, bodyOf(o), key));
109
111
  return { events, orphanCount: orphans.length, alreadyVerified: false };
@@ -1,4 +1,4 @@
1
- import { LedgerStore } from './ledger-store';
1
+ import { LedgerStore, SpendLedger } from './ledger-store';
2
2
  /**
3
3
  * The ONE conformance suite every `LedgerStore` adapter must pass.
4
4
  *
@@ -9,3 +9,9 @@ import { LedgerStore } from './ledger-store';
9
9
  * implementation, and finding that now is the whole reason a second adapter exists.
10
10
  */
11
11
  export declare function ledgerStoreConformance(name: string, make: () => LedgerStore): void;
12
+ /**
13
+ * @implements A-SPEC-245.12 (X5) — the clauses every SpendLedger adapter must pass, against the contract only: a first
14
+ * spend is appended, a second of the same nonce is spent and writes nothing, another nonce is appended, and a spend
15
+ * row written before fingerprints (the raw nonce) still counts as spent.
16
+ */
17
+ export declare function spendLedgerConformance(name: string, make: () => SpendLedger & LedgerStore): void;
@@ -1,6 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.ledgerStoreConformance = ledgerStoreConformance;
4
+ exports.spendLedgerConformance = spendLedgerConformance;
4
5
  /**
5
6
  * The ONE conformance suite every `LedgerStore` adapter must pass.
6
7
  *
@@ -88,3 +89,68 @@ function ledgerStoreConformance(name, make) {
88
89
  });
89
90
  });
90
91
  }
92
+ /**
93
+ * @implements A-SPEC-245.12 (X5) — the clauses every SpendLedger adapter must pass, against the contract only: a first
94
+ * spend is appended, a second of the same nonce is spent and writes nothing, another nonce is appended, and a spend
95
+ * row written before fingerprints (the raw nonce) still counts as spent.
96
+ */
97
+ function spendLedgerConformance(name, make) {
98
+ const { nonceFingerprint } = require('./provenance-chain');
99
+ const spend = (nonce) => ({ nonce, row: { ts: '2026-10-27T00:00:00.000Z', actor: 'a', kind: 'nonce-consumed', summary: 's', inputs: [nonceFingerprint(nonce)], rationale: 'r' } });
100
+ const spentRows = (s) => s.loadAll().filter((e) => e.kind === 'nonce-consumed').length;
101
+ const far = () => Date.now() + 5000;
102
+ describe(`SpendLedger conformance — ${name} (A-SPEC-245.12)`, () => {
103
+ it('normal: a first spend is appended, a second of the same nonce is spent and writes nothing', () => {
104
+ const s = make();
105
+ expect(s.appendIfUnspent([spend('N-1')], far())).toBe('appended');
106
+ expect(s.appendIfUnspent([spend('N-1')], far())).toBe('spent');
107
+ expect(spentRows(s)).toBe(1);
108
+ });
109
+ it('corner: another nonce is appended beside a spent one', () => {
110
+ const s = make();
111
+ s.appendIfUnspent([spend('N-1')], far());
112
+ expect(s.appendIfUnspent([spend('N-2')], far())).toBe('appended');
113
+ expect(spentRows(s)).toBe(2);
114
+ });
115
+ it('boundary (A-SPEC-245.13, Y4): with the second of two nonces spent, the call is spent and writes nothing', () => {
116
+ const s = make();
117
+ s.appendIfUnspent([spend('N-2')], far());
118
+ expect(s.appendIfUnspent([spend('N-1'), spend('N-2')], far())).toBe('spent');
119
+ expect(s.loadAll().filter((e) => e.kind === 'nonce-consumed').map((e) => e.inputs)).toEqual([[nonceFingerprint('N-2')]]);
120
+ });
121
+ it('negative: a spend row that carries the raw nonce (written before fingerprints) counts as spent', () => {
122
+ const s = make();
123
+ s.append({ ts: '2026-10-27T00:00:00.000Z', actor: 'old', kind: 'nonce-consumed', summary: 's', inputs: ['N-raw'] });
124
+ expect(s.appendIfUnspent([spend('N-raw')], far())).toBe('spent');
125
+ });
126
+ // @implements A-SPEC-245.9 (1b-3, M-10) — the revocation operation, on both adapters
127
+ const revocation = (nonce) => ({ ts: '2026-10-27T00:00:00.000Z', actor: 'op', kind: 'nonce-revoked', summary: 'revoked', inputs: [nonceFingerprint(nonce)], rationale: 'r' });
128
+ // typed loosely, so an adapter without the operation is red as an assertion, not a type error
129
+ const revoke = (s, nonce) => s.appendRevocationIfUnspent?.(nonce, revocation(nonce), far());
130
+ const revokedRows = (s) => s.loadAll().filter((e) => e.kind === 'nonce-revoked').length;
131
+ it('normal (A-SPEC-245.9, M-10): an unspent nonce is revoked once; a second revocation is revoked-already and writes nothing', () => {
132
+ const s = make();
133
+ expect(revoke(s, 'R-1')).toBe('revoked');
134
+ expect(revoke(s, 'R-1')).toBe('revoked-already');
135
+ expect(revokedRows(s)).toBe(1);
136
+ });
137
+ it('negative (A-SPEC-245.9, M-10): a spent nonce is not revoked — the answer is spent and nothing is written', () => {
138
+ const s = make();
139
+ s.appendIfUnspent([spend('R-2')], far());
140
+ expect(revoke(s, 'R-2')).toBe('spent');
141
+ expect(revokedRows(s)).toBe(0);
142
+ });
143
+ it('negative (A-SPEC-245.16, item 1): a revoked nonce is not spent — the spend answers revoked and writes nothing', () => {
144
+ const s = make();
145
+ s.append(revocation('R-RV'));
146
+ expect(s.appendIfUnspent([spend('R-OK'), spend('R-RV')], far())).toBe('revoked');
147
+ expect(spentRows(s)).toBe(0);
148
+ });
149
+ it('corner (A-SPEC-245.9, M-10): a nonce spent by a row written before fingerprints is not revoked', () => {
150
+ const s = make();
151
+ s.append({ ts: '2026-10-27T00:00:00.000Z', actor: 'old', kind: 'nonce-consumed', summary: 's', inputs: ['R-raw'] });
152
+ expect(revoke(s, 'R-raw')).toBe('spent');
153
+ expect(revokedRows(s)).toBe(0);
154
+ });
155
+ });
156
+ }
@@ -1,5 +1,6 @@
1
- import { ProvenanceEvent } from './provenance-chain';
1
+ import { ProvenanceEvent, AppendBody } from './provenance-chain';
2
2
  import { LedgerEvent, DoubleSpend } from './provenance-ledger';
3
+ import { type SpendNamespace } from './spend-kinds';
3
4
  /**
4
5
  * The ledger as a PORT — ADR-001's deferred half, applied to the one store whose shape was derived
5
6
  * from real use rather than guessed at.
@@ -21,6 +22,8 @@ import { LedgerEvent, DoubleSpend } from './provenance-ledger';
21
22
  *
22
23
  * NOT DECLARED, and why: transactions, batching, pagination, RBAC. No caller needs them, they cannot
23
24
  * be verified by the two adapters, and an unverifiable contract clause is worth less than a comment.
25
+ * (A-SPEC-245.12: the one exclusive operation, spending, is the separate SpendLedger port below, with
26
+ * its own conformance clauses — not a transaction on this one.)
24
27
  * ADR-001 named speculative port design as the cost of deciding early; this is where that cost is
25
28
  * refused.
26
29
  */
@@ -28,7 +31,7 @@ import { LedgerEvent, DoubleSpend } from './provenance-ledger';
28
31
  export interface LedgerBroken {
29
32
  replicaId: string | null;
30
33
  detail?: string;
31
- kind?: 'chain' | 'double-spend';
34
+ kind?: 'chain' | 'double-spend' | 'revoked-and-consumed';
32
35
  nonce?: string;
33
36
  events?: DoubleSpend['events'];
34
37
  }
@@ -48,12 +51,48 @@ export interface LedgerStore {
48
51
  broken: LedgerBroken[];
49
52
  };
50
53
  /** Append to this writer's chain. Never modifies or removes an existing event. */
51
- append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
52
- /** Spent on ANY chain — see the interface note. */
53
- isNonceConsumed(nonce: string): boolean;
54
+ append(body: AppendBody): ProvenanceEvent;
55
+ /** Spent on ANY chain — see the interface note. A-SPEC-794.4: in the namespace `ns` (the grant namespace by default). */
56
+ isNonceConsumed(nonce: string, ns?: SpendNamespace): boolean;
54
57
  /** A-SPEC-642 — single-use nonces consumed more than once across chains and not yet reconciled. */
55
58
  doubleSpends(): DoubleSpend[];
56
59
  }
60
+ /**
61
+ * @implements A-SPEC-245.12 (X5) — the spend port: one operation, apart from the general LedgerStore its many readers
62
+ * use. `appendIfUnspent` appends each spend's row when none of the nonces is spent on any chain, excluding every other
63
+ * writer it can until the deadline; it answers
64
+ * - `appended`;
65
+ * - `spent`: a nonce was already spent, nothing written;
66
+ * - `conflict`: after the append, a spend of the same approval appeared on a chain begun after the store's last look;
67
+ * - `unconfirmed`: such a chain could not be read, so the spend is not confirmed single.
68
+ * The last two record `spend-conflict-detected`, in words that tell them apart.
69
+ */
70
+ export interface SpendLedger {
71
+ /** @implements A-SPEC-794.4 — `ns` names the namespace the nonces are judged in (the grant namespace by default). */
72
+ appendIfUnspent(spends: Array<{
73
+ nonce: string;
74
+ row: AppendBody;
75
+ }>, deadline: number, ns?: SpendNamespace): SpendAppend;
76
+ /** @implements A-SPEC-245.9 (1b-3, M-10) — append a revocation row unless the nonce is spent or already revoked. */
77
+ appendRevocationIfUnspent(nonce: string, row: AppendBody, deadline: number, ns?: SpendNamespace): RevocationAppend;
78
+ }
79
+ /** `revoked` (A-SPEC-245.16): a nonce of the call was revoked on some chain — nothing written, like `spent`. */
80
+ export type SpendAppend = 'appended' | 'spent' | 'revoked' | 'conflict' | 'unconfirmed';
81
+ export type RevocationAppend = 'revoked' | 'spent' | 'revoked-already';
82
+ /** The ledger kind of a revocation (A-SPEC-245.9, H-2), in the grant namespace (A-SPEC-794.4). */
83
+ export declare const NONCE_REVOKED: string;
84
+ /**
85
+ * @implements A-SPEC-794.5 — the port binds a row's kind to the namespace it judges: a spend judged in one namespace
86
+ * and written under another kind would be invisible to that namespace's readers, so it is refused before anything is
87
+ * written.
88
+ */
89
+ export declare class SpendKindMismatch extends Error {
90
+ readonly expected: string;
91
+ readonly actual: string;
92
+ constructor(expected: string, actual: string);
93
+ }
94
+ /** The least time a late chain gets to be read, even when the spend's budget is spent (reviewer A, L1). */
95
+ export declare const LATE_CHAIN_READ_MS = 500;
57
96
  /**
58
97
  * @implements A-SPEC-643
59
98
  * The chain file THIS process writes: `provenance.<replica>.jsonl`, resolved exactly as every other
@@ -87,7 +126,7 @@ export declare function ledgerConflictReason(dir: string): string | null;
87
126
  * wrote files itself would satisfy every conformance test while silently dropping all three, and
88
127
  * nothing in this suite would notice — which is why a structural test pins the delegation too.
89
128
  */
90
- export declare class FileLedgerStore implements LedgerStore {
129
+ export declare class FileLedgerStore implements LedgerStore, SpendLedger {
91
130
  private readonly dir;
92
131
  private readonly givenId?;
93
132
  private readonly inner;
@@ -111,10 +150,41 @@ export declare class FileLedgerStore implements LedgerStore {
111
150
  ok: boolean;
112
151
  broken: LedgerBroken[];
113
152
  };
114
- append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
115
- isNonceConsumed(nonce: string): boolean;
153
+ append(body: AppendBody): ProvenanceEvent;
154
+ isNonceConsumed(nonce: string, ns?: SpendNamespace): boolean;
116
155
  doubleSpends(): DoubleSpend[];
156
+ /**
157
+ * @implements A-SPEC-245.10, A-SPEC-245.11, A-SPEC-245.12 — the spend port on files: append the spend rows to this
158
+ * writer's chain while holding every replica chain's append lock, taken in sorted path order within the deadline.
159
+ * The chains are enumerated with their lock directories (M-a): a chain whose first append is in progress has a lock
160
+ * and no file yet, and is waited for. This writer's own chain is included even when absent. If a chain appears
161
+ * while the locks are taken, they are released and taken again. The spent check runs inside all the locks. After
162
+ * the append, still holding them, chains begun since are waited for (at least LATE_CHAIN_READ_MS) and read (W2).
163
+ * Throws the lock layer's error when the deadline passes before the append.
164
+ */
165
+ appendIfUnspent(spends: Array<{
166
+ nonce: string;
167
+ row: AppendBody;
168
+ }>, deadline: number, ns?: SpendNamespace): SpendAppend;
169
+ /**
170
+ * @implements A-SPEC-245.9 (1b-3, M-10) — revocation on files: under every replica chain's append lock, a nonce
171
+ * spent on any chain answers `spent`, one already revoked answers `revoked-already`, and otherwise the revocation row
172
+ * is appended (`revoked`). A spend that appears later on a chain begun after the enumeration is N10's report.
173
+ */
174
+ appendRevocationIfUnspent(nonce: string, row: AppendBody, deadline: number, ns?: SpendNamespace): RevocationAppend;
175
+ /**
176
+ * Run `body` holding every replica chain's append lock, taken in sorted path order within `deadline` (A-SPEC-245.10,
177
+ * 245.11): the chains are enumerated with their lock directories, this writer's own chain is included even when
178
+ * absent, and a chain that appears while the locks are taken starts the round again. Throws the lock layer's error
179
+ * when the deadline passes first.
180
+ */
181
+ private underEveryChainLock;
117
182
  }
183
+ /** @implements A-SPEC-245.9 (1b-3) — whether a ledger holds a revocation of `nonce` (its fingerprint, or the raw value). */
184
+ export declare function nonceRevokedIn(events: Array<{
185
+ kind: string;
186
+ inputs?: string[];
187
+ }>, nonce: string, ns?: SpendNamespace): boolean;
118
188
  /**
119
189
  * In-memory adapter — the instrument that makes the contract testable.
120
190
  *
@@ -122,7 +192,7 @@ export declare class FileLedgerStore implements LedgerStore {
122
192
  * adapter in disguise and would prove nothing about coupling. It reuses the pure chain functions
123
193
  * (`chainNext`, `verifyChain`) because those are the format, not the storage.
124
194
  */
125
- export declare class MemoryLedgerStore implements LedgerStore {
195
+ export declare class MemoryLedgerStore implements LedgerStore, SpendLedger {
126
196
  private readonly id;
127
197
  private readonly byReplica;
128
198
  constructor(id?: string);
@@ -136,9 +206,16 @@ export declare class MemoryLedgerStore implements LedgerStore {
136
206
  ok: boolean;
137
207
  broken: LedgerBroken[];
138
208
  };
139
- append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
140
- isNonceConsumed(nonce: string): boolean;
209
+ append(body: AppendBody): ProvenanceEvent;
210
+ isNonceConsumed(nonce: string, ns?: SpendNamespace): boolean;
141
211
  doubleSpends(): DoubleSpend[];
212
+ /** One process, no other writer to exclude: check, then append (A-SPEC-245.12, the spend port's in-memory form). */
213
+ appendIfUnspent(spends: Array<{
214
+ nonce: string;
215
+ row: AppendBody;
216
+ }>, _deadline: number, ns?: SpendNamespace): SpendAppend;
217
+ /** @implements A-SPEC-245.9 (1b-3, M-10) — the revocation port's in-memory form: check, then append. */
218
+ appendRevocationIfUnspent(nonce: string, row: AppendBody, _deadline: number, ns?: SpendNamespace): RevocationAppend;
142
219
  }
143
220
  /**
144
221
  * The cross-replica nonce check, bound to one ledger file, ready to hand to