@cbartens/bkit 6.1.0 → 6.2.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 (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -10,6 +10,7 @@
10
10
  // everything already in the index, not nothing.
11
11
 
12
12
  import { spawnSync } from "node:child_process";
13
+ import { createHash } from "node:crypto";
13
14
  import * as fs from "node:fs";
14
15
  import * as os from "node:os";
15
16
  import * as path from "node:path";
@@ -22,6 +23,7 @@ import {
22
23
  UNJUSTIFIED_REASON,
23
24
  gitEnv,
24
25
  parse,
26
+ queryLedger,
25
27
  mintTs,
26
28
  resolveRepoSlug,
27
29
  validate,
@@ -30,17 +32,43 @@ import {
30
32
  type AppendLedger,
31
33
  } from "../../ledgers/telemetry.js";
32
34
  import { COMPACT_LEDGERS, compactLedgers, type CompactLedger } from "../../ledgers/compact.js";
35
+ import {
36
+ CORRECTION_REJECTED_ROW,
37
+ CORRECTION_SUCCEEDED_ROW,
38
+ actionHash,
39
+ appendHeld,
40
+ appendLine,
41
+ correctionScope,
42
+ ledgerIntent,
43
+ ledgerOperation,
44
+ ledgerOperationsFile,
45
+ pendingLedgerIntentsFor,
46
+ recordLedgerIntent,
47
+ recordLedgerOperation,
48
+ statusTimestamp,
49
+ withTargetLock,
50
+ writePrepared,
51
+ type AppendCheckpoint,
52
+ } from "../../ledgers/status.js";
33
53
  import {
34
54
  CommandError,
55
+ CorrectionExhausted,
35
56
  EXIT,
57
+ INVOCATION_FLAG,
58
+ invocationDir,
36
59
  isIgnoredPath,
37
60
  isSharedBranch,
61
+ NoWriteRejection,
38
62
  parseJson,
63
+ UncertainEffect,
64
+ wholeNumber,
39
65
  type CommandSpec,
40
66
  type FlagSpec,
67
+ type Invocation,
41
68
  type RunContext,
42
69
  } from "../lib.js";
43
- import { str } from "./status.js";
70
+ import { CORRECTION_LIMIT, spendCorrection, type CorrectionSpend } from "./counters.js";
71
+ import { readStatusRows, str } from "./status.js";
44
72
  import {
45
73
  NO_MARKERS_REASON,
46
74
  outOfScope,
@@ -62,6 +90,9 @@ export const EXIT_NOT_BOOKKEEPING = 7;
62
90
  /** append: a row was refused (supplied `ts`, wrong kind, invalid, unlisted writer). */
63
91
  export const EXIT_ROW_REFUSED = 8;
64
92
 
93
+ /** Rows per `ledgers query` page unless --limit says otherwise. */
94
+ const QUERY_PAGE = 200;
95
+
65
96
  const SCOPES = ["core", "full", "pr"] as const;
66
97
  export type Scope = (typeof SCOPES)[number];
67
98
  const MODES = ["stage", "commit", "commit-allow-empty"];
@@ -135,7 +166,7 @@ interface GitResult {
135
166
  }
136
167
 
137
168
  /** `git <args>` in `cwd`, never throwing and never trimming (NUL-delimited output). */
138
- function gitRaw(
169
+ export function gitRaw(
139
170
  cwd: string,
140
171
  args: string[],
141
172
  env: NodeJS.ProcessEnv = {},
@@ -250,6 +281,8 @@ export interface SharedCheckoutRecord {
250
281
  }
251
282
 
252
283
  const RECORD_DIR = "bkit/shared-checkout";
284
+ /** Where a stopped run's commit list is parked: a directory the record listing never reads. */
285
+ const PARKED_DIR = "bkit/shared-checkout-parked";
253
286
  const RECORD_FID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
254
287
 
255
288
  /** The checkout's top: git status and pathspecs are relative to it, whatever `cwd` is. */
@@ -368,6 +401,120 @@ export function removeRecord(cwd: string, fid: string): boolean {
368
401
  return true;
369
402
  }
370
403
 
404
+ /** `$(git rev-parse --git-path bkit/shared-checkout-parked/{fid}.json)`, absolute; null for a bad FID or outside a repo. */
405
+ function parkedFile(cwd: string, fid: string): string | null {
406
+ if (!RECORD_FID.test(fid) || fid.includes("..")) return null;
407
+ const res = gitRaw(cwd, ["rev-parse", "--git-path", `${PARKED_DIR}/${fid}.json`]);
408
+ return res.status === 0 && res.stdout.trim() !== "" ? path.resolve(cwd, res.stdout.trim()) : null;
409
+ }
410
+
411
+ /**
412
+ * Park `rec`'s start, commits and pushed list for `workflow` in this clone's git dir, so a
413
+ * resume of a run that stays open can rebuild its record without any remote.
414
+ */
415
+ export function writeParkedCommits(cwd: string, workflow: string, rec: SharedCheckoutRecord): void {
416
+ const file = parkedFile(cwd, rec.fid);
417
+ if (file === null) throw new CommandError(EXIT_ROOT, `cannot park commits for "${rec.fid}"`);
418
+ fs.mkdirSync(path.dirname(file), { recursive: true });
419
+ const parked = {
420
+ workflow,
421
+ at: statusTimestamp(),
422
+ startSha: rec.startSha,
423
+ commits: rec.commits,
424
+ pushed: rec.pushed ?? [],
425
+ };
426
+ fs.writeFileSync(file, `${JSON.stringify(parked, null, 2)}\n`);
427
+ }
428
+
429
+ /** The FID's parked commit list for `workflow`; null when absent, unreadable or parked for another workflow. */
430
+ export function readParkedCommits(cwd: string, fid: string, workflow: string): RunCommits | null {
431
+ const file = parkedFile(cwd, fid);
432
+ if (file === null || !fs.existsSync(file)) return null;
433
+ const parsed = parseJson(fs.readFileSync(file, "utf-8"));
434
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") return null;
435
+ const p = parsed.value as Record<string, unknown>;
436
+ if (p["workflow"] !== workflow) return null;
437
+ const ids = (v: unknown) =>
438
+ Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
439
+ return {
440
+ startSha: typeof p["startSha"] === "string" ? p["startSha"] : "",
441
+ commits: ids(p["commits"]),
442
+ pushed: ids(p["pushed"]),
443
+ };
444
+ }
445
+
446
+ /** Remove the FID's parked commit list; false when there was none. */
447
+ export function removeParkedCommits(cwd: string, fid: string): boolean {
448
+ const file = parkedFile(cwd, fid);
449
+ if (file === null || !fs.existsSync(file)) return false;
450
+ fs.rmSync(file, { force: true });
451
+ return true;
452
+ }
453
+
454
+ /** The status row type that carries a run's commit list across the removal of its record. */
455
+ export const RUN_COMMITS_ROW = "run-commits";
456
+
457
+ /** What a `run-commits` row holds: the record fields a resumed run rebuilds its record from. */
458
+ export interface RunCommits {
459
+ startSha: string;
460
+ commits: string[];
461
+ pushed: string[];
462
+ }
463
+
464
+ /** Append a `run-commits` row for `rec` to the status log `file`. */
465
+ export function appendRunCommits(file: string, workflow: string, rec: SharedCheckoutRecord): void {
466
+ fs.appendFileSync(
467
+ file,
468
+ appendLine({
469
+ type: RUN_COMMITS_ROW,
470
+ workflow,
471
+ at: statusTimestamp(),
472
+ startSha: rec.startSha,
473
+ commits: rec.commits,
474
+ pushed: rec.pushed ?? [],
475
+ }),
476
+ );
477
+ }
478
+
479
+ /**
480
+ * The newest `run-commits` row of `workflow`'s open run in the status log `file`. Null
481
+ * when the log or the row is missing.
482
+ */
483
+ export function readRunCommits(file: string, workflow: string): RunCommits | null {
484
+ if (!fs.existsSync(file)) return null;
485
+ return runCommitsIn(fs.readFileSync(file, "utf-8"), workflow);
486
+ }
487
+
488
+ /**
489
+ * The newest `run-commits` row of `workflow` in the status log `text`, among the rows after
490
+ * the last `workflow-started` row of that workflow, in file order. Null when there is none;
491
+ * a line that is not a JSON object is skipped.
492
+ */
493
+ export function runCommitsIn(text: string, workflow: string): RunCommits | null {
494
+ const rows = text
495
+ .split("\n")
496
+ .flatMap((line) => {
497
+ const parsed = parseJson(line);
498
+ return parsed.ok && parsed.value !== null && typeof parsed.value === "object"
499
+ ? [parsed.value as Record<string, unknown>]
500
+ : [];
501
+ })
502
+ .filter((row) => row["workflow"] === workflow);
503
+ const opened = rows.map((row) => row["type"]).lastIndexOf("workflow-started");
504
+ const row = rows
505
+ .slice(opened + 1)
506
+ .filter((r) => r["type"] === RUN_COMMITS_ROW)
507
+ .at(-1);
508
+ if (row === undefined) return null;
509
+ const ids = (v: unknown) =>
510
+ Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
511
+ return {
512
+ startSha: typeof row["startSha"] === "string" ? row["startSha"] : "",
513
+ commits: ids(row["commits"]),
514
+ pushed: ids(row["pushed"]),
515
+ };
516
+ }
517
+
371
518
  /** The FID's record, only while its branch is still the one checked out. */
372
519
  export function activeRecord(cwd: string, fid: string): SharedCheckoutRecord | null {
373
520
  const rec = readRecord(cwd, fid);
@@ -806,20 +953,82 @@ export const ledgersCommand: CommandSpec = {
806
953
  required: true,
807
954
  help: "file holding a JSON array of rows without schema, ts or bkit, or - for stdin",
808
955
  },
956
+ {
957
+ ...INVOCATION_FLAG,
958
+ help: `${INVOCATION_FLAG.help}; fills each row's by block (workflow, step, subagent, model, provenance) and refuses a row whose own by disagrees`,
959
+ },
960
+ {
961
+ name: "operation",
962
+ type: "string",
963
+ help: "operation id naming this request: the same id and rows replay the original receipt without writing; the same id with other rows is refused; a new id is a deliberate later update",
964
+ },
965
+ {
966
+ name: "issue-operation",
967
+ type: "boolean",
968
+ help: "let the engine issue the operation id from --invocation and the request, so a retried call after a lost response replays instead of appending again; exclusive with --operation",
969
+ },
970
+ {
971
+ name: "correction-of",
972
+ type: "string",
973
+ help: "the operation of an earlier guaranteed no-write rejection of this ledger append in this step: this call is its corrected retry (two per scope), under its own fresh --operation or --issue-operation",
974
+ },
809
975
  ],
810
976
  output: {
811
977
  ledger: "the ledger appended to",
812
978
  file: "its path, relative to --root",
813
979
  appended: "rows written",
814
980
  keys: "each row's key, in order (null when a row has none)",
981
+ receipt:
982
+ "with --operation: {operation, ledger, file, offset, bytes, rows[{key, ts}], replayed}; replayed is true when the original effect is returned",
983
+ correction:
984
+ "with --correction-of: {scope, operation, of, used, limit, substep, verified}; verified is true when the rows landed (or the original receipt was returned)",
815
985
  },
816
986
  exitCodes: {
817
- [EXIT_STAGE]: "mkdir or append failed",
987
+ [EXIT_STAGE]:
988
+ "mkdir or append failed, the ledger is locked by another writer, or a prior attempt left an uncertain partial write",
818
989
  [EXIT_ROW_REFUSED]:
819
990
  "a row carries ts, has the wrong kind, fails validation, or names a writer not listed for its kind — nothing written",
820
991
  },
821
992
  run: (ctx) => append(ctx),
822
993
  },
994
+ query: {
995
+ summary:
996
+ "Read one ledger's canonical winners (filtered after the fold), paged, with line diagnostics and coverage. Writes nothing.",
997
+ use: "by-hand",
998
+ flags: [
999
+ { name: "root", type: "string", help: "checkout whose ledger to read (default: cwd)" },
1000
+ {
1001
+ name: "ledger",
1002
+ type: "string",
1003
+ required: true,
1004
+ help: Object.keys(APPEND_LEDGERS).join(" | "),
1005
+ },
1006
+ { name: "key", type: "string", help: "only the winner with this key" },
1007
+ { name: "status", type: "string", help: "only winners whose status is this (e.g. ACTIVE)" },
1008
+ {
1009
+ name: "limit",
1010
+ type: "string",
1011
+ help: `rows per page (default ${QUERY_PAGE}, at least 1)`,
1012
+ },
1013
+ {
1014
+ name: "cursor",
1015
+ type: "string",
1016
+ help: "nextCursor of the previous page; refused when the ledger or the filter changed",
1017
+ },
1018
+ ],
1019
+ output: {
1020
+ ledger: "the ledger read",
1021
+ file: "its path, relative to --root",
1022
+ rows: "this page of fold winners, oldest ts first (equal ts by identity)",
1023
+ nextCursor: "pass as --cursor for the next page, or null on the last page",
1024
+ snapshot: "digest of the bytes read; every page of one scan shares it",
1025
+ total: "winners that pass the filter, across all pages",
1026
+ diagnostics: "each unreadable line: {line, reason}; on every page",
1027
+ coverage:
1028
+ "{status: clean|incomplete|partial|missing|unreadable, clean, malformedLines, lines}; clean is true only for a finished scan (nextCursor null) with no unreadable line, so a page with a nextCursor is incomplete",
1029
+ },
1030
+ run: (ctx) => query(ctx),
1031
+ },
823
1032
  triage: {
824
1033
  summary:
825
1034
  "Bucket each deferral row the FID declared by the four Deferral Reason tests, and write the unjustified ones.",
@@ -1221,14 +1430,23 @@ export function unionLedgers(src: string, dst: string): string[] {
1221
1430
  const made = mkdirp(path.dirname(to));
1222
1431
  if (made) throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(to)}: ${made}`);
1223
1432
  if (fs.existsSync(to) && fs.statSync(to).isFile()) {
1224
- const existing = fs.readFileSync(to, "utf-8");
1225
- const have = new Set(fileLines(existing));
1226
- const fresh = fileLines(fs.readFileSync(from, "utf-8")).filter((l) => !have.has(l));
1227
- const block = fresh.join("\n").replace(/\n+$/, "");
1228
- // A destination missing its final newline would glue the first new row
1229
- // onto its last one, leaving a line that is not JSON.
1230
- const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
1231
- if (block !== "") fs.appendFileSync(to, `${sep}${block}\n`);
1433
+ // Under the destination's target lock, so a pending ledger operation's bytes are never reordered.
1434
+ withTargetLock(to, () => {
1435
+ const pending = pendingLedgerIntentsFor(dst, rel);
1436
+ if (pending.length > 0)
1437
+ throw new CommandError(
1438
+ EXIT_STAGE,
1439
+ `${rel} has ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them first`,
1440
+ );
1441
+ const existing = fs.readFileSync(to, "utf-8");
1442
+ const have = new Set(fileLines(existing));
1443
+ const fresh = fileLines(fs.readFileSync(from, "utf-8")).filter((l) => !have.has(l));
1444
+ const block = fresh.join("\n").replace(/\n+$/, "");
1445
+ // A destination missing its final newline would glue the first new row
1446
+ // onto its last one, leaving a line that is not JSON.
1447
+ const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
1448
+ if (block !== "") fs.appendFileSync(to, `${sep}${block}\n`);
1449
+ });
1232
1450
  } else {
1233
1451
  const copied = copy(from, to);
1234
1452
  if (copied) throw new CommandError(EXIT_STAGE, `copy failed for ${rel}: ${copied}`);
@@ -1252,6 +1470,8 @@ export interface AppendResult {
1252
1470
  file: string;
1253
1471
  appended: number;
1254
1472
  keys: Array<string | null>;
1473
+ /** Present when the call named an `operation`. */
1474
+ receipt?: LedgerReceipt;
1255
1475
  }
1256
1476
 
1257
1477
  /** The top section in its written order, then the row's own fields. */
@@ -1268,16 +1488,201 @@ const TOP_ORDER = [
1268
1488
  "references",
1269
1489
  ];
1270
1490
 
1491
+ /** A row's `by` block when it is an object, else an empty one. */
1492
+ const byOfRow = (row: Record<string, unknown>): Record<string, unknown> =>
1493
+ row["by"] !== null && typeof row["by"] === "object" && !Array.isArray(row["by"])
1494
+ ? (row["by"] as Record<string, unknown>)
1495
+ : {};
1496
+
1497
+ /** The `by` fields an invocation owns; a row may repeat them but never disagree. */
1498
+ const INVOCATION_BY_KEYS = [
1499
+ "workflow",
1500
+ "step",
1501
+ "subagent",
1502
+ "model",
1503
+ "modelSource",
1504
+ "configuredModel",
1505
+ "host",
1506
+ ] as const;
1507
+
1508
+ /**
1509
+ * `row` with its `by` block completed from the verified invocation. A field the row
1510
+ * asserts that differs from the invocation's, or that the invocation cannot vouch for,
1511
+ * is refused rather than overwritten. A configured pin is recorded as `configuredModel`
1512
+ * only, never as the model that ran.
1513
+ */
1514
+ function withInvocationBy(
1515
+ row: Record<string, unknown>,
1516
+ inv: Invocation,
1517
+ refuse: (why: string) => CommandError,
1518
+ ): Record<string, unknown> {
1519
+ const unavailable = inv.observedModel === "unavailable";
1520
+ const expected: Record<string, string | undefined> = {
1521
+ workflow: inv.workflow ?? inv.standalone ?? undefined,
1522
+ step: inv.step ?? inv.declaredStep ?? undefined,
1523
+ subagent: inv.agent ?? undefined,
1524
+ model:
1525
+ inv.agent !== null && inv.observedModel !== null && !unavailable
1526
+ ? inv.observedModel
1527
+ : undefined,
1528
+ modelSource:
1529
+ inv.agent === null || inv.observedModel === null
1530
+ ? undefined
1531
+ : unavailable
1532
+ ? "unavailable"
1533
+ : "observed",
1534
+ configuredModel: inv.agent !== null ? (inv.configuredModel ?? undefined) : undefined,
1535
+ host: inv.agent !== null ? (inv.host ?? undefined) : undefined,
1536
+ };
1537
+ const asserted = row["by"];
1538
+ if (
1539
+ asserted !== undefined &&
1540
+ (asserted === null || typeof asserted !== "object" || Array.isArray(asserted))
1541
+ )
1542
+ throw refuse("by must be an object");
1543
+ const by: Record<string, unknown> = { ...(asserted as Record<string, unknown> | undefined) };
1544
+ for (const key of INVOCATION_BY_KEYS) {
1545
+ if (by[key] !== undefined && by[key] !== expected[key]) {
1546
+ throw refuse(
1547
+ `conflict: by.${key}=${JSON.stringify(by[key])} disagrees with invocation ${inv.id} (${expected[key] === undefined ? "none" : JSON.stringify(expected[key])})`,
1548
+ );
1549
+ }
1550
+ if (by[key] === undefined && expected[key] !== undefined) by[key] = expected[key];
1551
+ }
1552
+ return { ...row, by };
1553
+ }
1554
+
1555
+ export interface LedgerReceipt {
1556
+ operation: string;
1557
+ ledger: string;
1558
+ file: string;
1559
+ offset: number;
1560
+ bytes: number;
1561
+ rows: Array<{ key: string | null; ts: number }>;
1562
+ replayed: boolean;
1563
+ }
1564
+
1565
+ export interface AppendOptions {
1566
+ /** Names the request: the same id and rows replay the original effect, never a second write. */
1567
+ operation?: string;
1568
+ /** The engine issues the operation id from the invocation and the request; exclusive with `operation`. */
1569
+ issueOperation?: boolean;
1570
+ /** Test seam: called at each durable checkpoint; a throw there simulates a lost response. */
1571
+ checkpoint?: AppendCheckpoint;
1572
+ }
1573
+
1574
+ /** `JSON.stringify` with object keys sorted at every depth: equal requests serialize equally. */
1575
+ export function canonicalJson(value: unknown): string {
1576
+ if (Array.isArray(value)) return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
1577
+ if (value !== null && typeof value === "object") {
1578
+ const o = value as Record<string, unknown>;
1579
+ return `{${Object.keys(o)
1580
+ .filter((k) => o[k] !== undefined)
1581
+ .sort()
1582
+ .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
1583
+ .join(",")}}`;
1584
+ }
1585
+ return JSON.stringify(value) ?? "null";
1586
+ }
1587
+
1588
+ /**
1589
+ * The operation id of an append request: the caller's `--operation`, else (with
1590
+ * `--issue-operation`) one issued from the invocation and the request, so retrying a lost
1591
+ * response gets the same id.
1592
+ */
1593
+ export function appendOperationId(
1594
+ ledger: string,
1595
+ rows: unknown,
1596
+ invocation: Invocation | undefined,
1597
+ options: { operation?: string; issueOperation?: boolean },
1598
+ ): string | undefined {
1599
+ if (options.operation !== undefined) return options.operation;
1600
+ if (options.issueOperation !== true || invocation === undefined) return undefined;
1601
+ const hash = actionHash(canonicalJson({ ledger, rows, invocation: invocation.id }));
1602
+ return `op-${invocation.id.slice(4, 16)}-${hash.slice(0, 12)}`;
1603
+ }
1604
+
1605
+ /**
1606
+ * The correction scope of an append by a workflow-run or a standalone (audit or utility)
1607
+ * invocation; null for any other caller.
1608
+ */
1609
+ export function appendCorrectionScope(invocation: Invocation, ledger: string): string | null {
1610
+ const book = correctionBookKey(invocation);
1611
+ if (book === null) return null;
1612
+ return correctionScope({
1613
+ workflow: book.workflow,
1614
+ run: invocation.run,
1615
+ step: book.step,
1616
+ group: invocation.group,
1617
+ attempt: invocation.attempt,
1618
+ ledger,
1619
+ substep: "append",
1620
+ });
1621
+ }
1622
+
1623
+ /** The workflow and step a correction scope is cut from; the declared step for a standalone call. */
1624
+ function correctionBookKey(invocation: Invocation): { workflow: string; step: string } | null {
1625
+ if (invocation.scope === "run")
1626
+ return invocation.statusPath === null ||
1627
+ invocation.workflow === null ||
1628
+ invocation.step === null
1629
+ ? null
1630
+ : { workflow: invocation.workflow, step: invocation.step };
1631
+ return invocation.standalone === null || invocation.declaredStep === null
1632
+ ? null
1633
+ : { workflow: invocation.standalone, step: invocation.declaredStep };
1634
+ }
1635
+
1636
+ /**
1637
+ * Where the correction events of `invocation` live: the run's `status.jsonl`, or for a standalone
1638
+ * call the event file beside its outbox receipt. Null when the caller has no correction scope.
1639
+ */
1640
+ function correctionBook(
1641
+ cwd: string,
1642
+ invocation: Invocation,
1643
+ ): { file: string; workflow: string; step: string } | null {
1644
+ const key = correctionBookKey(invocation);
1645
+ if (key === null) return null;
1646
+ if (invocation.scope === "run")
1647
+ return invocation.statusPath === null ? null : { file: invocation.statusPath, ...key };
1648
+ const dir = invocationDir(cwd);
1649
+ if (dir === null) return null;
1650
+ const file = path.join(dir, `${invocation.id}.corrections.jsonl`);
1651
+ fs.appendFileSync(file, "");
1652
+ return { file, ...key };
1653
+ }
1654
+
1655
+ /** The `{key, ts}` of each row in prepared `block` bytes. */
1656
+ function receiptRows(block: string): LedgerReceipt["rows"] {
1657
+ const out: LedgerReceipt["rows"] = [];
1658
+ for (const line of block.split("\n")) {
1659
+ if (line.trim() === "") continue;
1660
+ const parsed = parseJson(line);
1661
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") continue;
1662
+ const r = parsed.value as Record<string, unknown>;
1663
+ out.push({ key: typeof r["key"] === "string" ? r["key"] : null, ts: Number(r["ts"]) });
1664
+ }
1665
+ return out;
1666
+ }
1667
+
1271
1668
  /**
1272
1669
  * Append `rows` to one ledger. Every row is checked before any is written, so a
1273
1670
  * refused row leaves the file byte-identical. Each row gets `schema` and a `ts`
1274
1671
  * minted now (never supplied), `repo` when it lacks one and `bkit.version` from
1275
1672
  * `.bkit/version`; an `AGED_KINDS` row also gets `firstTs` + `updates` carried
1276
1673
  * forward from its entry's rows already in the ledger (supplied values replaced).
1277
- * Never rewrites existing rows. Throws a CommandError (USAGE / EXIT_ROW_REFUSED /
1278
- * EXIT_STAGE).
1674
+ * Never rewrites existing rows. The write runs under the ledger's target lock; with
1675
+ * `options.operation` it also records the prepared bytes and a durable receipt, so a
1676
+ * lost response is reconciled by inspecting the ledger, never by appending again.
1677
+ * Throws a CommandError (USAGE / EXIT_ROW_REFUSED / EXIT_STAGE).
1279
1678
  */
1280
- export function appendLedgerRows(root: string, ledger: string, rows: unknown): AppendResult {
1679
+ export function appendLedgerRows(
1680
+ root: string,
1681
+ ledger: string,
1682
+ rows: unknown,
1683
+ invocation?: Invocation,
1684
+ options: AppendOptions = {},
1685
+ ): AppendResult {
1281
1686
  if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
1282
1687
  throw new CommandError(
1283
1688
  EXIT.USAGE,
@@ -1289,75 +1694,241 @@ export function appendLedgerRows(root: string, ledger: string, rows: unknown): A
1289
1694
  if (!Array.isArray(rows)) throw new CommandError(EXIT.USAGE, "--rows must hold a JSON array");
1290
1695
  if (rows.length === 0) throw new CommandError(EXIT.USAGE, "--rows holds no rows");
1291
1696
 
1292
- let repo: string | undefined;
1293
- let version: string | undefined;
1294
- let last: number | undefined;
1295
1697
  const abs = path.join(root, file);
1296
- const prior: unknown[] = fs.existsSync(abs) ? parse(fs.readFileSync(abs, "utf-8")).events : [];
1297
- const out: Array<Record<string, unknown>> = rows.map((raw, i) => {
1298
- const refuse = (why: string) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
1299
- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
1300
- throw refuse("not a JSON object");
1301
- }
1302
- const r = raw as Record<string, unknown>;
1303
- if (Object.hasOwn(r, "ts")) throw refuse("carries ts; ts is minted at append time");
1304
- if (Object.hasOwn(r, "schema")) throw refuse("carries schema; it is set at append time");
1305
- if (!takes.includes(String(r["kind"]))) {
1306
- throw refuse(
1307
- `kind must be ${takes.join(" | ")} in --ledger=${ledger} (got ${String(r["kind"])})`,
1308
- );
1309
- }
1310
- if (Object.hasOwn(r, "bkit")) throw refuse("carries bkit; bkit.version is set at append time");
1311
- repo ??= resolveRepoSlug(root) || "unknown/repo";
1312
- version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
1313
- last = mintTs(last);
1314
- const filled = withLineage(prior, {
1315
- repo,
1316
- ...r,
1317
- schema: SCHEMA,
1318
- ts: last,
1319
- bkit: { version },
1320
- });
1321
- const row: Record<string, unknown> = {};
1322
- for (const k of TOP_ORDER) if (filled[k] !== undefined) row[k] = filled[k];
1323
- for (const [k, v] of Object.entries(filled)) if (!(k in row)) row[k] = v;
1324
- const v = validate(row);
1325
- if (!v.ok) throw refuse(v.reason ?? "invalid");
1326
- const who = writerProblem(row);
1327
- if (who !== undefined) throw refuse(who);
1328
- prior.push(row);
1329
- return row;
1330
- });
1331
-
1332
1698
  const made = mkdirp(path.dirname(abs));
1333
1699
  if (made) throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(file)}: ${made}`);
1334
- const block = out.map((r) => `${JSON.stringify(r)}\n`).join("");
1335
- // A file missing its final newline would glue the first row onto its last one.
1336
- const appendErr = appendText(abs, endsMidLine(abs) ? `\n${block}` : block);
1337
- if (appendErr) throw new CommandError(EXIT_STAGE, `append failed: ${file} — ${appendErr}`);
1338
- return {
1339
- ledger: ledger as AppendLedger,
1340
- file,
1341
- appended: out.length,
1342
- keys: out.map((r) => (typeof r["key"] === "string" ? r["key"] : null)),
1700
+ // The operation store is private to this git repository, never a committed path; a repo-less
1701
+ // root has no place to keep a durable receipt, so an operation there is refused.
1702
+ const ops = ledgerOperationsFile(
1703
+ root,
1704
+ options.operation !== undefined || options.issueOperation === true,
1705
+ );
1706
+ // The request is the ledger and rows alone: an operation stays reconcilable after its
1707
+ // invocation goes stale, and replay writes the recorded bytes, never a re-derived `by`.
1708
+ const hash = actionHash(canonicalJson({ ledger, rows }));
1709
+ if (options.operation !== undefined && options.issueOperation === true)
1710
+ throw new CommandError(
1711
+ EXIT.USAGE,
1712
+ "--issue-operation and --operation are exclusive: the engine issues the id, or the caller names it",
1713
+ );
1714
+ if (options.issueOperation === true && invocation === undefined)
1715
+ throw new CommandError(
1716
+ EXIT.USAGE,
1717
+ "--issue-operation needs --invocation: the id is issued from that invocation's context",
1718
+ );
1719
+ const operation = appendOperationId(ledger, rows, invocation, options);
1720
+ // A rejection before any write is correctable only inside a workflow run (it has a scope to
1721
+ // spend from) and only when the operation can be named by the corrected retry.
1722
+ const scope = invocation === undefined ? null : appendCorrectionScope(invocation, ledger);
1723
+ const reject = (why: string, row: number) => {
1724
+ const message = `row ${row}: ${why}`;
1725
+ return scope !== null && operation !== undefined
1726
+ ? new NoWriteRejection(EXIT_ROW_REFUSED, message, { scope, substep: "append" })
1727
+ : new CommandError(EXIT_ROW_REFUSED, message);
1343
1728
  };
1344
- }
1345
1729
 
1346
- /** True when `abs` exists, is non-empty and its last byte is not a newline. */
1347
- function endsMidLine(abs: string): boolean {
1348
- let fd: number | undefined;
1730
+ const result = (landed: { offset: number; bytes: number }, block: string, replayed: boolean) => {
1731
+ const parsedRows = receiptRows(block);
1732
+ return {
1733
+ ledger: ledger as AppendLedger,
1734
+ file,
1735
+ appended: replayed ? 0 : parsedRows.length,
1736
+ keys: parsedRows.map((r) => r.key),
1737
+ ...(operation === undefined
1738
+ ? {}
1739
+ : {
1740
+ receipt: {
1741
+ operation,
1742
+ ledger,
1743
+ file,
1744
+ offset: landed.offset,
1745
+ bytes: landed.bytes,
1746
+ rows: parsedRows,
1747
+ replayed,
1748
+ },
1749
+ }),
1750
+ };
1751
+ };
1752
+
1753
+ const build = (text: string): string => {
1754
+ let repo: string | undefined;
1755
+ let version: string | undefined;
1756
+ let last: number | undefined;
1757
+ const prior: unknown[] = parse(text).events;
1758
+ const out: Array<Record<string, unknown>> = rows.map((raw, i) => {
1759
+ const refuse = (why: string) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
1760
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
1761
+ throw reject("not a JSON object", i + 1);
1762
+ }
1763
+ const r =
1764
+ invocation === undefined
1765
+ ? (raw as Record<string, unknown>)
1766
+ : withInvocationBy(raw as Record<string, unknown>, invocation, refuse);
1767
+ if (invocation === undefined && byOfRow(r)["modelSource"] === "unavailable")
1768
+ throw refuse(
1769
+ "by.modelSource unavailable needs a validated --invocation; the engine records it, a caller cannot assert it",
1770
+ );
1771
+ if (Object.hasOwn(r, "ts")) throw reject("carries ts; ts is minted at append time", i + 1);
1772
+ if (Object.hasOwn(r, "schema"))
1773
+ throw reject("carries schema; it is set at append time", i + 1);
1774
+ if (!takes.includes(String(r["kind"]))) {
1775
+ throw reject(
1776
+ `kind must be ${takes.join(" | ")} in --ledger=${ledger} (got ${String(r["kind"])})`,
1777
+ i + 1,
1778
+ );
1779
+ }
1780
+ if (Object.hasOwn(r, "bkit"))
1781
+ throw reject("carries bkit; bkit.version is set at append time", i + 1);
1782
+ repo ??= resolveRepoSlug(root) || "unknown/repo";
1783
+ version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
1784
+ last = mintTs(last);
1785
+ const filled = withLineage(prior, {
1786
+ repo,
1787
+ ...r,
1788
+ schema: SCHEMA,
1789
+ ts: last,
1790
+ bkit: { version },
1791
+ });
1792
+ const row: Record<string, unknown> = {};
1793
+ for (const k of TOP_ORDER) if (filled[k] !== undefined) row[k] = filled[k];
1794
+ for (const [k, v] of Object.entries(filled)) if (!(k in row)) row[k] = v;
1795
+ const v = validate(row);
1796
+ if (!v.ok) throw reject(v.reason ?? "invalid", i + 1);
1797
+ const who = writerProblem(row);
1798
+ if (who !== undefined) throw refuse(who);
1799
+ prior.push(row);
1800
+ return row;
1801
+ });
1802
+ return out.map((r) => `${JSON.stringify(r)}\n`).join("");
1803
+ };
1804
+
1805
+ const stage = (err: unknown) =>
1806
+ err instanceof CommandError
1807
+ ? err
1808
+ : new CommandError(EXIT_STAGE, `append failed: ${file} \u2014 ${(err as Error).message}`);
1809
+
1349
1810
  try {
1350
- fd = fs.openSync(abs, "r");
1351
- const size = fs.fstatSync(fd).size;
1352
- if (size === 0) return false;
1353
- const last = Buffer.alloc(1);
1354
- fs.readSync(fd, last, 0, 1, size - 1);
1355
- return last[0] !== 0x0a;
1356
- } catch {
1357
- // No file yet: the append creates it.
1358
- return false;
1359
- } finally {
1360
- if (fd !== undefined) fs.closeSync(fd);
1811
+ return withTargetLock(abs, () => {
1812
+ if (operation === undefined) {
1813
+ const landed = appendHeld(abs, build, { checkpoint: options.checkpoint });
1814
+ return result(landed, landed.block, false);
1815
+ }
1816
+ if (ops === null)
1817
+ throw new CommandError(
1818
+ EXIT.USAGE,
1819
+ `${root} is not inside a git repository: a ledger operation keeps its receipt in the git common dir`,
1820
+ );
1821
+ // The operation store is serialized by its own lock, taken after the target's, so two
1822
+ // ledgers' operations never interleave check and record.
1823
+ return withTargetLock(ops, () => {
1824
+ const known = ledgerOperation(ops, operation, hash);
1825
+ if (known.state === "conflict")
1826
+ throw new CommandError(
1827
+ EXIT_ROW_REFUSED,
1828
+ `operation ${operation} was already used for a different request; nothing written`,
1829
+ );
1830
+ if (known.state === "replay") {
1831
+ const d = (known.row as { detail?: { offset: number; bytes: number; block: string } })
1832
+ .detail;
1833
+ if (d === undefined)
1834
+ throw new CommandError(
1835
+ EXIT_STAGE,
1836
+ `operation ${operation} has a receipt without its effect`,
1837
+ );
1838
+ return result(d, d.block, true);
1839
+ }
1840
+ const intent = ledgerIntent(ops, operation);
1841
+ if (intent !== undefined && intent.hash !== hash)
1842
+ throw new CommandError(
1843
+ EXIT_ROW_REFUSED,
1844
+ `operation ${operation} was already used for a different request; nothing written`,
1845
+ );
1846
+ const receipt = (landed: { offset: number; bytes: number; block: string }) =>
1847
+ recordLedgerOperation(ops, {
1848
+ operation,
1849
+ hash,
1850
+ ref: `${file}@${landed.offset}+${landed.bytes}`,
1851
+ detail: { offset: landed.offset, bytes: landed.bytes, block: landed.block },
1852
+ });
1853
+ if (intent !== undefined) {
1854
+ const have = fs.existsSync(abs) ? fs.readFileSync(abs) : Buffer.alloc(0);
1855
+ const want = Buffer.from(intent.block);
1856
+ const seg = have.subarray(intent.offset, intent.offset + want.length);
1857
+ if (seg.equals(want)) {
1858
+ // The bytes landed whole; confirm them durable and receipt them.
1859
+ const fd = fs.openSync(abs, "r");
1860
+ try {
1861
+ fs.fsyncSync(fd);
1862
+ } finally {
1863
+ fs.closeSync(fd);
1864
+ }
1865
+ receipt(intent);
1866
+ options.checkpoint?.("receipted");
1867
+ return result(intent, intent.block, true);
1868
+ }
1869
+ // Whole lines decide "landed": rows share a byte prefix (`{"schema":3,"ts":...`), so a
1870
+ // foreign row is told apart by being a complete line that differs from ours.
1871
+ // Compare by content, without the newline and without one leading separator newline:
1872
+ // a torn prefix of our line that a later writer completed with its own newline is a
1873
+ // proper prefix of our first line, so it stays uncertain rather than foreign.
1874
+ const stripSeparator = (b: Buffer): Buffer => (b[0] === 0x0a ? b.subarray(1) : b);
1875
+ const firstLine = (b: Buffer): { line: Buffer; complete: boolean } => {
1876
+ const nl = b.indexOf(0x0a);
1877
+ return nl < 0
1878
+ ? { line: b, complete: false }
1879
+ : { line: b.subarray(0, nl), complete: true };
1880
+ };
1881
+ const wantLine = firstLine(stripSeparator(want)).line;
1882
+ const haveLine = firstLine(stripSeparator(have.subarray(intent.offset)));
1883
+ const foreignWholeLine =
1884
+ haveLine.complete &&
1885
+ !(
1886
+ haveLine.line.length <= wantLine.length &&
1887
+ wantLine.subarray(0, haveLine.line.length).equals(haveLine.line)
1888
+ );
1889
+ let landedBytes = 0;
1890
+ while (
1891
+ landedBytes < seg.length &&
1892
+ landedBytes < want.length &&
1893
+ seg[landedBytes] === want[landedBytes]
1894
+ )
1895
+ landedBytes++;
1896
+ if (
1897
+ !foreignWholeLine &&
1898
+ (landedBytes > 0 || (seg.length > 0 && have.length === intent.offset + seg.length))
1899
+ )
1900
+ throw new UncertainEffect(
1901
+ EXIT_STAGE,
1902
+ `operation ${operation}: ${file} holds ${landedBytes} of ${want.length} prepared bytes at the recorded offset; the effect is uncertain, nothing was truncated or retried`,
1903
+ );
1904
+ if (have.length === intent.offset) {
1905
+ // Nothing landed: write the exact prepared bytes again.
1906
+ writePrepared(abs, intent.block, intent.offset);
1907
+ options.checkpoint?.("written");
1908
+ receipt(intent);
1909
+ options.checkpoint?.("receipted");
1910
+ return result(intent, intent.block, false);
1911
+ }
1912
+ // Another writer appended after the failed attempt and none of ours landed: prepare afresh.
1913
+ }
1914
+ const landed = appendHeld(abs, build, {
1915
+ checkpoint: options.checkpoint,
1916
+ prepared: (p) =>
1917
+ recordLedgerIntent(ops, {
1918
+ operation,
1919
+ hash,
1920
+ file,
1921
+ offset: p.offset,
1922
+ bytes: Buffer.byteLength(p.block),
1923
+ block: p.block,
1924
+ }),
1925
+ written: (p) => receipt(p),
1926
+ });
1927
+ return result(landed, landed.block, false);
1928
+ });
1929
+ });
1930
+ } catch (err) {
1931
+ throw stage(err);
1361
1932
  }
1362
1933
  }
1363
1934
 
@@ -1370,9 +1941,216 @@ function append(ctx: RunContext): number {
1370
1941
  if (text.trim() === "") throw new CommandError(EXIT.USAGE, "--rows holds no rows");
1371
1942
  const parsed = parseJson(text);
1372
1943
  if (!parsed.ok) throw new CommandError(EXIT.USAGE, "--rows is not JSON");
1373
- const r = appendLedgerRows(root, String(ctx.flags.ledger), parsed.value);
1374
- ctx.log(`appended ${r.appended} row(s) to ${r.file}`);
1375
- ctx.emit({ ...r });
1944
+ const bound = ctx.invocation?.bookRoot;
1945
+ if (bound !== undefined && bound !== null && bound !== root)
1946
+ throw new CommandError(
1947
+ EXIT.USAGE,
1948
+ `conflict: --root ${root} is not the invocation's book root ${bound}`,
1949
+ );
1950
+ // A runless call has no book root of its own: its output scope is the checkout that issued it.
1951
+ if (ctx.invocation?.scope === "outbox") {
1952
+ const rel = path.relative(ctx.invocation.worktree, root);
1953
+ if (rel.startsWith("..") || path.isAbsolute(rel))
1954
+ throw new CommandError(
1955
+ EXIT.USAGE,
1956
+ `conflict: --root ${root} is outside the checkout ${ctx.invocation.worktree} that issued invocation ${ctx.invocation.id}`,
1957
+ );
1958
+ }
1959
+ const ledger = String(ctx.flags.ledger);
1960
+ const request = {
1961
+ operation: str(ctx.flags.operation),
1962
+ issueOperation: ctx.flags.issueOperation === true,
1963
+ };
1964
+ const run = ctx.invocation;
1965
+ const scope = run === undefined ? null : appendCorrectionScope(run, ledger);
1966
+ const operation = appendOperationId(ledger, parsed.value, run, request);
1967
+ const correctionOf = str(ctx.flags.correctionOf);
1968
+ let spend: CorrectionSpend | undefined;
1969
+ const book = run === undefined || scope === null ? null : correctionBook(ctx.cwd, run);
1970
+ if (correctionOf !== undefined) {
1971
+ if (run === undefined || scope === null || book === null)
1972
+ throw new CommandError(
1973
+ EXIT.USAGE,
1974
+ "--correction-of needs an --invocation with a correction scope: a workflow-run call, or a standalone audit or utility call",
1975
+ );
1976
+ if (operation === undefined || operation === correctionOf)
1977
+ throw new CommandError(
1978
+ EXIT.USAGE,
1979
+ "--correction-of needs a fresh --operation or --issue-operation: a corrected candidate has its own operation id",
1980
+ );
1981
+ const rejected = readStatusRows(book.file).some(
1982
+ (row) =>
1983
+ row.type === CORRECTION_REJECTED_ROW &&
1984
+ row.operation === correctionOf &&
1985
+ row.scope === scope &&
1986
+ row.workflow === book.workflow,
1987
+ );
1988
+ if (!rejected)
1989
+ throw new CommandError(
1990
+ EXIT.USAGE,
1991
+ `--correction-of=${correctionOf} names no rejected ${ledger} append in this step; only a guaranteed no-write rejection of this sub-step can be corrected`,
1992
+ );
1993
+ // An earlier operation on this ledger whose effect is unconfirmed is reconciled first.
1994
+ const target = Object.hasOwn(APPEND_LEDGERS, ledger)
1995
+ ? APPEND_LEDGERS[ledger as AppendLedger].file
1996
+ : undefined;
1997
+ if (target !== undefined && pendingLedgerIntentsFor(root, target).length > 0)
1998
+ throw new UncertainEffect(
1999
+ EXIT_STAGE,
2000
+ `${target} holds an operation whose effect is unconfirmed; reconcile it before any corrected candidate — nothing was written`,
2001
+ );
2002
+ spend = spendCorrection(book.file, book.workflow, scope, operation, CORRECTION_LIMIT, {
2003
+ of: correctionOf,
2004
+ step: book.step,
2005
+ substep: "append",
2006
+ requestHash: actionHash(canonicalJson({ ledger, rows: parsed.value })),
2007
+ });
2008
+ if (!spend.allowed)
2009
+ throw new CorrectionExhausted(
2010
+ EXIT.NO,
2011
+ spend.conflict === true
2012
+ ? `operation ${operation} was already counted as a correction of ${scope} for different rows; a changed candidate needs a fresh operation id and spends the budget (${spend.used} of ${spend.limit}); nothing was written`
2013
+ : `the correction budget of ${scope} is spent (${spend.used} of ${spend.limit}); nothing was written`,
2014
+ scope,
2015
+ );
2016
+ }
2017
+ let r: AppendResult;
2018
+ try {
2019
+ r = appendLedgerRows(root, ledger, parsed.value, ctx.invocation, request);
2020
+ } catch (err) {
2021
+ if (err instanceof NoWriteRejection && book !== null && operation !== undefined) {
2022
+ fs.appendFileSync(
2023
+ book.file,
2024
+ appendLine({
2025
+ type: CORRECTION_REJECTED_ROW,
2026
+ workflow: book.workflow,
2027
+ at: statusTimestamp(),
2028
+ scope: err.detail.scope,
2029
+ substep: err.detail.substep,
2030
+ operation,
2031
+ step: book.step,
2032
+ }),
2033
+ );
2034
+ // The last allowed retry was just used: the rejection is final, not correctable.
2035
+ if (spend !== undefined && spend.remaining === 0)
2036
+ throw new CommandError(err.code, err.message);
2037
+ }
2038
+ throw err;
2039
+ }
2040
+ ctx.log(
2041
+ r.receipt?.replayed === true
2042
+ ? `operation ${r.receipt.operation} already appended to ${r.file}; nothing written`
2043
+ : `appended ${r.appended} row(s) to ${r.file}`,
2044
+ );
2045
+ if (spend === undefined || book === null || scope === null) {
2046
+ ctx.emit({ ...r });
2047
+ return EXIT.OK;
2048
+ }
2049
+ const verified =
2050
+ r.receipt?.replayed === true || r.appended === (parsed.value as unknown[]).length;
2051
+ const succeeded = readStatusRows(book.file).some(
2052
+ (row) => row.type === CORRECTION_SUCCEEDED_ROW && row.operation === operation,
2053
+ );
2054
+ if (verified && !succeeded)
2055
+ fs.appendFileSync(
2056
+ book.file,
2057
+ appendLine({
2058
+ type: CORRECTION_SUCCEEDED_ROW,
2059
+ workflow: book.workflow,
2060
+ at: statusTimestamp(),
2061
+ scope,
2062
+ substep: "append",
2063
+ operation,
2064
+ of: correctionOf,
2065
+ step: book.step,
2066
+ }),
2067
+ );
2068
+ ctx.emit({
2069
+ ...r,
2070
+ correction: {
2071
+ scope,
2072
+ operation,
2073
+ of: correctionOf,
2074
+ used: spend.used,
2075
+ limit: spend.limit,
2076
+ substep: "append",
2077
+ verified,
2078
+ },
2079
+ });
2080
+ return EXIT.OK;
2081
+ }
2082
+
2083
+ /** Page cursor: the snapshot and filter it was cut from, and the offset of the next row. */
2084
+ function encodeCursor(c: { s: string; f: string; o: number }): string {
2085
+ return Buffer.from(JSON.stringify(c)).toString("base64url");
2086
+ }
2087
+
2088
+ function decodeCursor(text: string): { s: string; f: string; o: number } | null {
2089
+ const parsed = parseJson(Buffer.from(text, "base64url").toString("utf-8"));
2090
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object") return null;
2091
+ const v = parsed.value as Record<string, unknown>;
2092
+ return typeof v["s"] === "string" && typeof v["f"] === "string" && Number.isInteger(v["o"])
2093
+ ? { s: v["s"], f: v["f"], o: v["o"] as number }
2094
+ : null;
2095
+ }
2096
+
2097
+ function query(ctx: RunContext): number {
2098
+ const root = rootOf(ctx);
2099
+ const ledger = String(ctx.flags.ledger);
2100
+ if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
2101
+ throw new CommandError(
2102
+ EXIT.USAGE,
2103
+ `--ledger must be one of ${Object.keys(APPEND_LEDGERS).join(", ")} (got '${ledger}')`,
2104
+ );
2105
+ }
2106
+ const { file } = APPEND_LEDGERS[ledger as AppendLedger];
2107
+ const filter = { key: str(ctx.flags.key), status: str(ctx.flags.status) };
2108
+ const limit = wholeNumber(ctx.flags.limit, "limit", QUERY_PAGE, 1);
2109
+ const filterId = JSON.stringify([filter.key ?? null, filter.status ?? null]);
2110
+ const cursorText = str(ctx.flags.cursor);
2111
+ const cursor = cursorText === undefined ? null : decodeCursor(cursorText);
2112
+ if (cursorText !== undefined && cursor === null)
2113
+ throw new CommandError(EXIT.USAGE, "--cursor is not a cursor from this command");
2114
+
2115
+ const abs = path.join(root, file);
2116
+ const read = readText(abs);
2117
+ const missing = !read.ok && !fs.existsSync(abs);
2118
+ const raw = read.ok ? read.text : "";
2119
+ const snapshot = createHash("sha256").update(raw).digest("hex").slice(0, 16);
2120
+ if (cursor !== null && (cursor.s !== snapshot || cursor.f !== filterId))
2121
+ throw new CommandError(
2122
+ EXIT.USAGE,
2123
+ "stale cursor: the ledger or the filter changed since this scan began; start again without --cursor",
2124
+ );
2125
+ const result = queryLedger(raw, filter);
2126
+ const offset = cursor?.o ?? 0;
2127
+ const page = result.rows.slice(offset, offset + limit);
2128
+ const next = offset + limit < result.rows.length ? offset + limit : null;
2129
+ const status = missing
2130
+ ? "missing"
2131
+ : !read.ok
2132
+ ? "unreadable"
2133
+ : result.diagnostics.length > 0
2134
+ ? "partial"
2135
+ : next !== null
2136
+ ? "incomplete"
2137
+ : "clean";
2138
+ ctx.emit({
2139
+ ledger,
2140
+ file,
2141
+ rows: page,
2142
+ nextCursor: next === null ? null : encodeCursor({ s: snapshot, f: filterId, o: next }),
2143
+ snapshot,
2144
+ total: result.rows.length,
2145
+ diagnostics: result.diagnostics,
2146
+ coverage: {
2147
+ status,
2148
+ clean: status === "clean",
2149
+ malformedLines: result.diagnostics.length,
2150
+ lines: result.lines,
2151
+ ...(!read.ok && !missing ? { error: read.error } : {}),
2152
+ },
2153
+ });
1376
2154
  return EXIT.OK;
1377
2155
  }
1378
2156
 
@@ -1392,15 +2170,39 @@ export interface PlanRowsResult {
1392
2170
  export function checkPlanRows(root: string, plan: string): PlanRowsResult {
1393
2171
  const abs = path.resolve(root, plan);
1394
2172
  if (!fs.existsSync(abs)) throw new CommandError(EXIT.USAGE, `--plan not found: ${plan}`);
1395
- const text = fs.readFileSync(abs, "utf-8");
1396
- const line = LEDGER_ROWS_LINE.exec(text)?.[1]?.trim();
1397
- if (line === undefined) {
1398
- throw new CommandError(EXIT_ROWS_MISSING, `${plan} has no **Ledger rows:** line`);
2173
+ const r = readPlanRows(root, fs.readFileSync(abs, "utf-8"));
2174
+ if (r.unreadable !== undefined)
2175
+ throw new CommandError(EXIT_ROWS_MISSING, `${plan}: ${r.unreadable}`);
2176
+ return { keys: r.keys, missing: r.missing };
2177
+ }
2178
+
2179
+ export interface PlanRowsRead extends PlanRowsResult {
2180
+ /** 1-based line of the `**Ledger rows:**` line; 0 when the plan has none. */
2181
+ line: number;
2182
+ /** Why the line names no keys to check: absent, or still a placeholder. */
2183
+ unreadable?: string;
2184
+ }
2185
+
2186
+ /**
2187
+ * Read `text`'s `**Ledger rows:**` line and the keys no `decision` / `deferral`
2188
+ * row under `root` carries. An absent or placeholder line is `unreadable`.
2189
+ */
2190
+ export function readPlanRows(root: string, text: string): PlanRowsRead {
2191
+ const match = LEDGER_ROWS_LINE.exec(text);
2192
+ const line = match?.[1]?.trim();
2193
+ if (match === null || line === undefined) {
2194
+ return { line: 0, keys: [], missing: [], unreadable: "no **Ledger rows:** line" };
1399
2195
  }
2196
+ const at = text.slice(0, match.index).split("\n").length;
1400
2197
  const keys = [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "");
1401
2198
  if (keys.length === 0) {
1402
- if (line.replace(/[."\s]/g, "") === "None") return { keys: [], missing: [] };
1403
- throw new CommandError(EXIT_ROWS_MISSING, `${plan}: **Ledger rows:** is unfilled (${line})`);
2199
+ if (line.replace(/[."\s]/g, "") === "None") return { line: at, keys: [], missing: [] };
2200
+ return {
2201
+ line: at,
2202
+ keys: [],
2203
+ missing: [],
2204
+ unreadable: `**Ledger rows:** is unfilled (${line})`,
2205
+ };
1404
2206
  }
1405
2207
  const onDisk = new Set<string>();
1406
2208
  for (const { file, kinds } of CHECKED_LEDGERS) {
@@ -1411,7 +2213,7 @@ export function checkPlanRows(root: string, plan: string): PlanRowsResult {
1411
2213
  if ((kinds as readonly string[]).includes(e.kind) && typeof key === "string") onDisk.add(key);
1412
2214
  }
1413
2215
  }
1414
- return { keys, missing: keys.filter((k) => !onDisk.has(k)) };
2216
+ return { line: at, keys, missing: keys.filter((k) => !onDisk.has(k)) };
1415
2217
  }
1416
2218
 
1417
2219
  function check(ctx: RunContext): number {
@@ -1466,18 +2268,21 @@ function compactOrError(
1466
2268
  dryRun: boolean,
1467
2269
  ): ReturnType<typeof compactLedgers> | string {
1468
2270
  try {
1469
- return compactLedgers(root, ledgers, dryRun);
1470
- } catch (err) {
1471
- // Reported as the command's staging exit code, with the reason.
1472
- return (err as Error).message;
1473
- }
1474
- }
1475
-
1476
- /** Append `text` to `file`; the error text, or undefined on success. */
1477
- function appendText(file: string, text: string): string | undefined {
1478
- try {
1479
- fs.appendFileSync(file, text);
1480
- return undefined;
2271
+ const targets = ledgers.map((l) => COMPACT_LEDGERS[l]).sort();
2272
+ const locked = (i: number): ReturnType<typeof compactLedgers> => {
2273
+ if (i === targets.length) {
2274
+ for (const t of targets) {
2275
+ const pending = pendingLedgerIntentsFor(root, t);
2276
+ if (pending.length > 0)
2277
+ throw new Error(
2278
+ `${t} has ${pending.length} ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them before compacting`,
2279
+ );
2280
+ }
2281
+ return compactLedgers(root, ledgers, dryRun);
2282
+ }
2283
+ return withTargetLock(path.join(root, targets[i]!), () => locked(i + 1));
2284
+ };
2285
+ return locked(0);
1481
2286
  } catch (err) {
1482
2287
  // Reported as the command's staging exit code, with the reason.
1483
2288
  return (err as Error).message;