@cbartens/bkit 6.1.1 → 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 (313) 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 +42 -32
  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 +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  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 +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -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 +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -9,15 +9,18 @@
9
9
  // before `git commit`: `git commit --pathspec-from-file=<empty file>` commits
10
10
  // everything already in the index, not nothing.
11
11
  import { spawnSync } from "node:child_process";
12
+ import { createHash } from "node:crypto";
12
13
  import * as fs from "node:fs";
13
14
  import * as os from "node:os";
14
15
  import * as path from "node:path";
15
16
  import { readBkitVersion } from "../../install/version-file.js";
16
17
  import { readBkitConfig } from "../../shared/settings.js";
17
- import { APPEND_LEDGERS, SCHEMA, UNJUSTIFIED_REASON, gitEnv, parse, mintTs, resolveRepoSlug, validate, withLineage, writerProblem, } from "../../ledgers/telemetry.js";
18
+ import { APPEND_LEDGERS, SCHEMA, UNJUSTIFIED_REASON, gitEnv, parse, queryLedger, mintTs, resolveRepoSlug, validate, withLineage, writerProblem, } from "../../ledgers/telemetry.js";
18
19
  import { COMPACT_LEDGERS, compactLedgers } from "../../ledgers/compact.js";
19
- import { CommandError, EXIT, isIgnoredPath, isSharedBranch, parseJson, } from "../lib.js";
20
- import { str } from "./status.js";
20
+ import { CORRECTION_REJECTED_ROW, CORRECTION_SUCCEEDED_ROW, actionHash, appendHeld, appendLine, correctionScope, ledgerIntent, ledgerOperation, ledgerOperationsFile, pendingLedgerIntentsFor, recordLedgerIntent, recordLedgerOperation, statusTimestamp, withTargetLock, writePrepared, } from "../../ledgers/status.js";
21
+ import { CommandError, CorrectionExhausted, EXIT, INVOCATION_FLAG, invocationDir, isIgnoredPath, isSharedBranch, NoWriteRejection, parseJson, UncertainEffect, wholeNumber, } from "../lib.js";
22
+ import { CORRECTION_LIMIT, spendCorrection } from "./counters.js";
23
+ import { readStatusRows, str } from "./status.js";
21
24
  import { NO_MARKERS_REASON, outOfScope, parsePlanBlocks, reuseInventory, } from "./plan-blocks.js";
22
25
  /** Root is not a directory or repo, git is too old, or a ref does not resolve. */
23
26
  export const EXIT_ROOT = 3;
@@ -31,6 +34,8 @@ export const EXIT_EMPTY = 6;
31
34
  export const EXIT_NOT_BOOKKEEPING = 7;
32
35
  /** append: a row was refused (supplied `ts`, wrong kind, invalid, unlisted writer). */
33
36
  export const EXIT_ROW_REFUSED = 8;
37
+ /** Rows per `ledgers query` page unless --limit says otherwise. */
38
+ const QUERY_PAGE = 200;
34
39
  const SCOPES = ["core", "full", "pr"];
35
40
  const MODES = ["stage", "commit", "commit-allow-empty"];
36
41
  /** `package.json` globs as git pathspecs: `:(glob)` unless an entry carries its own magic. */
@@ -77,7 +82,7 @@ const UNION_PATHSPECS = [
77
82
  ":(exclude).bkit/issues.jsonl",
78
83
  ];
79
84
  /** `git <args>` in `cwd`, never throwing and never trimming (NUL-delimited output). */
80
- function gitRaw(cwd, args, env = {}, input) {
85
+ export function gitRaw(cwd, args, env = {}, input) {
81
86
  const res = spawnSync("git", args, {
82
87
  cwd,
83
88
  encoding: "utf-8",
@@ -149,6 +154,8 @@ export const EXIT_ROWS_MISSING = 11;
149
154
  /** commit --scope=pr: the checkout is on `dev`, `main` or a detached HEAD, so nothing is committed. */
150
155
  export const EXIT_SHARED_BRANCH = 12;
151
156
  const RECORD_DIR = "bkit/shared-checkout";
157
+ /** Where a stopped run's commit list is parked: a directory the record listing never reads. */
158
+ const PARKED_DIR = "bkit/shared-checkout-parked";
152
159
  const RECORD_FID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
153
160
  /** The checkout's top: git status and pathspecs are relative to it, whatever `cwd` is. */
154
161
  function topOf(cwd) {
@@ -264,6 +271,108 @@ export function removeRecord(cwd, fid) {
264
271
  fs.rmSync(file, { force: true });
265
272
  return true;
266
273
  }
274
+ /** `$(git rev-parse --git-path bkit/shared-checkout-parked/{fid}.json)`, absolute; null for a bad FID or outside a repo. */
275
+ function parkedFile(cwd, fid) {
276
+ if (!RECORD_FID.test(fid) || fid.includes(".."))
277
+ return null;
278
+ const res = gitRaw(cwd, ["rev-parse", "--git-path", `${PARKED_DIR}/${fid}.json`]);
279
+ return res.status === 0 && res.stdout.trim() !== "" ? path.resolve(cwd, res.stdout.trim()) : null;
280
+ }
281
+ /**
282
+ * Park `rec`'s start, commits and pushed list for `workflow` in this clone's git dir, so a
283
+ * resume of a run that stays open can rebuild its record without any remote.
284
+ */
285
+ export function writeParkedCommits(cwd, workflow, rec) {
286
+ const file = parkedFile(cwd, rec.fid);
287
+ if (file === null)
288
+ throw new CommandError(EXIT_ROOT, `cannot park commits for "${rec.fid}"`);
289
+ fs.mkdirSync(path.dirname(file), { recursive: true });
290
+ const parked = {
291
+ workflow,
292
+ at: statusTimestamp(),
293
+ startSha: rec.startSha,
294
+ commits: rec.commits,
295
+ pushed: rec.pushed ?? [],
296
+ };
297
+ fs.writeFileSync(file, `${JSON.stringify(parked, null, 2)}\n`);
298
+ }
299
+ /** The FID's parked commit list for `workflow`; null when absent, unreadable or parked for another workflow. */
300
+ export function readParkedCommits(cwd, fid, workflow) {
301
+ const file = parkedFile(cwd, fid);
302
+ if (file === null || !fs.existsSync(file))
303
+ return null;
304
+ const parsed = parseJson(fs.readFileSync(file, "utf-8"));
305
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object")
306
+ return null;
307
+ const p = parsed.value;
308
+ if (p["workflow"] !== workflow)
309
+ return null;
310
+ const ids = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
311
+ return {
312
+ startSha: typeof p["startSha"] === "string" ? p["startSha"] : "",
313
+ commits: ids(p["commits"]),
314
+ pushed: ids(p["pushed"]),
315
+ };
316
+ }
317
+ /** Remove the FID's parked commit list; false when there was none. */
318
+ export function removeParkedCommits(cwd, fid) {
319
+ const file = parkedFile(cwd, fid);
320
+ if (file === null || !fs.existsSync(file))
321
+ return false;
322
+ fs.rmSync(file, { force: true });
323
+ return true;
324
+ }
325
+ /** The status row type that carries a run's commit list across the removal of its record. */
326
+ export const RUN_COMMITS_ROW = "run-commits";
327
+ /** Append a `run-commits` row for `rec` to the status log `file`. */
328
+ export function appendRunCommits(file, workflow, rec) {
329
+ fs.appendFileSync(file, appendLine({
330
+ type: RUN_COMMITS_ROW,
331
+ workflow,
332
+ at: statusTimestamp(),
333
+ startSha: rec.startSha,
334
+ commits: rec.commits,
335
+ pushed: rec.pushed ?? [],
336
+ }));
337
+ }
338
+ /**
339
+ * The newest `run-commits` row of `workflow`'s open run in the status log `file`. Null
340
+ * when the log or the row is missing.
341
+ */
342
+ export function readRunCommits(file, workflow) {
343
+ if (!fs.existsSync(file))
344
+ return null;
345
+ return runCommitsIn(fs.readFileSync(file, "utf-8"), workflow);
346
+ }
347
+ /**
348
+ * The newest `run-commits` row of `workflow` in the status log `text`, among the rows after
349
+ * the last `workflow-started` row of that workflow, in file order. Null when there is none;
350
+ * a line that is not a JSON object is skipped.
351
+ */
352
+ export function runCommitsIn(text, workflow) {
353
+ const rows = text
354
+ .split("\n")
355
+ .flatMap((line) => {
356
+ const parsed = parseJson(line);
357
+ return parsed.ok && parsed.value !== null && typeof parsed.value === "object"
358
+ ? [parsed.value]
359
+ : [];
360
+ })
361
+ .filter((row) => row["workflow"] === workflow);
362
+ const opened = rows.map((row) => row["type"]).lastIndexOf("workflow-started");
363
+ const row = rows
364
+ .slice(opened + 1)
365
+ .filter((r) => r["type"] === RUN_COMMITS_ROW)
366
+ .at(-1);
367
+ if (row === undefined)
368
+ return null;
369
+ const ids = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
370
+ return {
371
+ startSha: typeof row["startSha"] === "string" ? row["startSha"] : "",
372
+ commits: ids(row["commits"]),
373
+ pushed: ids(row["pushed"]),
374
+ };
375
+ }
267
376
  /** The FID's record, only while its branch is still the one checked out. */
268
377
  export function activeRecord(cwd, fid) {
269
378
  const rec = readRecord(cwd, fid);
@@ -647,19 +756,76 @@ export const ledgersCommand = {
647
756
  required: true,
648
757
  help: "file holding a JSON array of rows without schema, ts or bkit, or - for stdin",
649
758
  },
759
+ {
760
+ ...INVOCATION_FLAG,
761
+ help: `${INVOCATION_FLAG.help}; fills each row's by block (workflow, step, subagent, model, provenance) and refuses a row whose own by disagrees`,
762
+ },
763
+ {
764
+ name: "operation",
765
+ type: "string",
766
+ 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",
767
+ },
768
+ {
769
+ name: "issue-operation",
770
+ type: "boolean",
771
+ 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",
772
+ },
773
+ {
774
+ name: "correction-of",
775
+ type: "string",
776
+ 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",
777
+ },
650
778
  ],
651
779
  output: {
652
780
  ledger: "the ledger appended to",
653
781
  file: "its path, relative to --root",
654
782
  appended: "rows written",
655
783
  keys: "each row's key, in order (null when a row has none)",
784
+ receipt: "with --operation: {operation, ledger, file, offset, bytes, rows[{key, ts}], replayed}; replayed is true when the original effect is returned",
785
+ correction: "with --correction-of: {scope, operation, of, used, limit, substep, verified}; verified is true when the rows landed (or the original receipt was returned)",
656
786
  },
657
787
  exitCodes: {
658
- [EXIT_STAGE]: "mkdir or append failed",
788
+ [EXIT_STAGE]: "mkdir or append failed, the ledger is locked by another writer, or a prior attempt left an uncertain partial write",
659
789
  [EXIT_ROW_REFUSED]: "a row carries ts, has the wrong kind, fails validation, or names a writer not listed for its kind — nothing written",
660
790
  },
661
791
  run: (ctx) => append(ctx),
662
792
  },
793
+ query: {
794
+ summary: "Read one ledger's canonical winners (filtered after the fold), paged, with line diagnostics and coverage. Writes nothing.",
795
+ use: "by-hand",
796
+ flags: [
797
+ { name: "root", type: "string", help: "checkout whose ledger to read (default: cwd)" },
798
+ {
799
+ name: "ledger",
800
+ type: "string",
801
+ required: true,
802
+ help: Object.keys(APPEND_LEDGERS).join(" | "),
803
+ },
804
+ { name: "key", type: "string", help: "only the winner with this key" },
805
+ { name: "status", type: "string", help: "only winners whose status is this (e.g. ACTIVE)" },
806
+ {
807
+ name: "limit",
808
+ type: "string",
809
+ help: `rows per page (default ${QUERY_PAGE}, at least 1)`,
810
+ },
811
+ {
812
+ name: "cursor",
813
+ type: "string",
814
+ help: "nextCursor of the previous page; refused when the ledger or the filter changed",
815
+ },
816
+ ],
817
+ output: {
818
+ ledger: "the ledger read",
819
+ file: "its path, relative to --root",
820
+ rows: "this page of fold winners, oldest ts first (equal ts by identity)",
821
+ nextCursor: "pass as --cursor for the next page, or null on the last page",
822
+ snapshot: "digest of the bytes read; every page of one scan shares it",
823
+ total: "winners that pass the filter, across all pages",
824
+ diagnostics: "each unreadable line: {line, reason}; on every page",
825
+ coverage: "{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",
826
+ },
827
+ run: (ctx) => query(ctx),
828
+ },
663
829
  triage: {
664
830
  summary: "Bucket each deferral row the FID declared by the four Deferral Reason tests, and write the unjustified ones.",
665
831
  use: "workflow",
@@ -987,15 +1153,21 @@ export function unionLedgers(src, dst) {
987
1153
  if (made)
988
1154
  throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(to)}: ${made}`);
989
1155
  if (fs.existsSync(to) && fs.statSync(to).isFile()) {
990
- const existing = fs.readFileSync(to, "utf-8");
991
- const have = new Set(fileLines(existing));
992
- const fresh = fileLines(fs.readFileSync(from, "utf-8")).filter((l) => !have.has(l));
993
- const block = fresh.join("\n").replace(/\n+$/, "");
994
- // A destination missing its final newline would glue the first new row
995
- // onto its last one, leaving a line that is not JSON.
996
- const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
997
- if (block !== "")
998
- fs.appendFileSync(to, `${sep}${block}\n`);
1156
+ // Under the destination's target lock, so a pending ledger operation's bytes are never reordered.
1157
+ withTargetLock(to, () => {
1158
+ const pending = pendingLedgerIntentsFor(dst, rel);
1159
+ if (pending.length > 0)
1160
+ throw new CommandError(EXIT_STAGE, `${rel} has ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them first`);
1161
+ const existing = fs.readFileSync(to, "utf-8");
1162
+ const have = new Set(fileLines(existing));
1163
+ const fresh = fileLines(fs.readFileSync(from, "utf-8")).filter((l) => !have.has(l));
1164
+ const block = fresh.join("\n").replace(/\n+$/, "");
1165
+ // A destination missing its final newline would glue the first new row
1166
+ // onto its last one, leaving a line that is not JSON.
1167
+ const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
1168
+ if (block !== "")
1169
+ fs.appendFileSync(to, `${sep}${block}\n`);
1170
+ });
999
1171
  }
1000
1172
  else {
1001
1173
  const copied = copy(from, to);
@@ -1027,16 +1199,157 @@ const TOP_ORDER = [
1027
1199
  "by",
1028
1200
  "references",
1029
1201
  ];
1202
+ /** A row's `by` block when it is an object, else an empty one. */
1203
+ const byOfRow = (row) => row["by"] !== null && typeof row["by"] === "object" && !Array.isArray(row["by"])
1204
+ ? row["by"]
1205
+ : {};
1206
+ /** The `by` fields an invocation owns; a row may repeat them but never disagree. */
1207
+ const INVOCATION_BY_KEYS = [
1208
+ "workflow",
1209
+ "step",
1210
+ "subagent",
1211
+ "model",
1212
+ "modelSource",
1213
+ "configuredModel",
1214
+ "host",
1215
+ ];
1216
+ /**
1217
+ * `row` with its `by` block completed from the verified invocation. A field the row
1218
+ * asserts that differs from the invocation's, or that the invocation cannot vouch for,
1219
+ * is refused rather than overwritten. A configured pin is recorded as `configuredModel`
1220
+ * only, never as the model that ran.
1221
+ */
1222
+ function withInvocationBy(row, inv, refuse) {
1223
+ const unavailable = inv.observedModel === "unavailable";
1224
+ const expected = {
1225
+ workflow: inv.workflow ?? inv.standalone ?? undefined,
1226
+ step: inv.step ?? inv.declaredStep ?? undefined,
1227
+ subagent: inv.agent ?? undefined,
1228
+ model: inv.agent !== null && inv.observedModel !== null && !unavailable
1229
+ ? inv.observedModel
1230
+ : undefined,
1231
+ modelSource: inv.agent === null || inv.observedModel === null
1232
+ ? undefined
1233
+ : unavailable
1234
+ ? "unavailable"
1235
+ : "observed",
1236
+ configuredModel: inv.agent !== null ? (inv.configuredModel ?? undefined) : undefined,
1237
+ host: inv.agent !== null ? (inv.host ?? undefined) : undefined,
1238
+ };
1239
+ const asserted = row["by"];
1240
+ if (asserted !== undefined &&
1241
+ (asserted === null || typeof asserted !== "object" || Array.isArray(asserted)))
1242
+ throw refuse("by must be an object");
1243
+ const by = { ...asserted };
1244
+ for (const key of INVOCATION_BY_KEYS) {
1245
+ if (by[key] !== undefined && by[key] !== expected[key]) {
1246
+ throw refuse(`conflict: by.${key}=${JSON.stringify(by[key])} disagrees with invocation ${inv.id} (${expected[key] === undefined ? "none" : JSON.stringify(expected[key])})`);
1247
+ }
1248
+ if (by[key] === undefined && expected[key] !== undefined)
1249
+ by[key] = expected[key];
1250
+ }
1251
+ return { ...row, by };
1252
+ }
1253
+ /** `JSON.stringify` with object keys sorted at every depth: equal requests serialize equally. */
1254
+ export function canonicalJson(value) {
1255
+ if (Array.isArray(value))
1256
+ return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
1257
+ if (value !== null && typeof value === "object") {
1258
+ const o = value;
1259
+ return `{${Object.keys(o)
1260
+ .filter((k) => o[k] !== undefined)
1261
+ .sort()
1262
+ .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
1263
+ .join(",")}}`;
1264
+ }
1265
+ return JSON.stringify(value) ?? "null";
1266
+ }
1267
+ /**
1268
+ * The operation id of an append request: the caller's `--operation`, else (with
1269
+ * `--issue-operation`) one issued from the invocation and the request, so retrying a lost
1270
+ * response gets the same id.
1271
+ */
1272
+ export function appendOperationId(ledger, rows, invocation, options) {
1273
+ if (options.operation !== undefined)
1274
+ return options.operation;
1275
+ if (options.issueOperation !== true || invocation === undefined)
1276
+ return undefined;
1277
+ const hash = actionHash(canonicalJson({ ledger, rows, invocation: invocation.id }));
1278
+ return `op-${invocation.id.slice(4, 16)}-${hash.slice(0, 12)}`;
1279
+ }
1280
+ /**
1281
+ * The correction scope of an append by a workflow-run or a standalone (audit or utility)
1282
+ * invocation; null for any other caller.
1283
+ */
1284
+ export function appendCorrectionScope(invocation, ledger) {
1285
+ const book = correctionBookKey(invocation);
1286
+ if (book === null)
1287
+ return null;
1288
+ return correctionScope({
1289
+ workflow: book.workflow,
1290
+ run: invocation.run,
1291
+ step: book.step,
1292
+ group: invocation.group,
1293
+ attempt: invocation.attempt,
1294
+ ledger,
1295
+ substep: "append",
1296
+ });
1297
+ }
1298
+ /** The workflow and step a correction scope is cut from; the declared step for a standalone call. */
1299
+ function correctionBookKey(invocation) {
1300
+ if (invocation.scope === "run")
1301
+ return invocation.statusPath === null ||
1302
+ invocation.workflow === null ||
1303
+ invocation.step === null
1304
+ ? null
1305
+ : { workflow: invocation.workflow, step: invocation.step };
1306
+ return invocation.standalone === null || invocation.declaredStep === null
1307
+ ? null
1308
+ : { workflow: invocation.standalone, step: invocation.declaredStep };
1309
+ }
1310
+ /**
1311
+ * Where the correction events of `invocation` live: the run's `status.jsonl`, or for a standalone
1312
+ * call the event file beside its outbox receipt. Null when the caller has no correction scope.
1313
+ */
1314
+ function correctionBook(cwd, invocation) {
1315
+ const key = correctionBookKey(invocation);
1316
+ if (key === null)
1317
+ return null;
1318
+ if (invocation.scope === "run")
1319
+ return invocation.statusPath === null ? null : { file: invocation.statusPath, ...key };
1320
+ const dir = invocationDir(cwd);
1321
+ if (dir === null)
1322
+ return null;
1323
+ const file = path.join(dir, `${invocation.id}.corrections.jsonl`);
1324
+ fs.appendFileSync(file, "");
1325
+ return { file, ...key };
1326
+ }
1327
+ /** The `{key, ts}` of each row in prepared `block` bytes. */
1328
+ function receiptRows(block) {
1329
+ const out = [];
1330
+ for (const line of block.split("\n")) {
1331
+ if (line.trim() === "")
1332
+ continue;
1333
+ const parsed = parseJson(line);
1334
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object")
1335
+ continue;
1336
+ const r = parsed.value;
1337
+ out.push({ key: typeof r["key"] === "string" ? r["key"] : null, ts: Number(r["ts"]) });
1338
+ }
1339
+ return out;
1340
+ }
1030
1341
  /**
1031
1342
  * Append `rows` to one ledger. Every row is checked before any is written, so a
1032
1343
  * refused row leaves the file byte-identical. Each row gets `schema` and a `ts`
1033
1344
  * minted now (never supplied), `repo` when it lacks one and `bkit.version` from
1034
1345
  * `.bkit/version`; an `AGED_KINDS` row also gets `firstTs` + `updates` carried
1035
1346
  * forward from its entry's rows already in the ledger (supplied values replaced).
1036
- * Never rewrites existing rows. Throws a CommandError (USAGE / EXIT_ROW_REFUSED /
1037
- * EXIT_STAGE).
1347
+ * Never rewrites existing rows. The write runs under the ledger's target lock; with
1348
+ * `options.operation` it also records the prepared bytes and a durable receipt, so a
1349
+ * lost response is reconciled by inspecting the ledger, never by appending again.
1350
+ * Throws a CommandError (USAGE / EXIT_ROW_REFUSED / EXIT_STAGE).
1038
1351
  */
1039
- export function appendLedgerRows(root, ledger, rows) {
1352
+ export function appendLedgerRows(root, ledger, rows, invocation, options = {}) {
1040
1353
  if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
1041
1354
  throw new CommandError(EXIT.USAGE, `--ledger must be one of ${Object.keys(APPEND_LEDGERS).join(", ")} (got '${ledger}')`);
1042
1355
  }
@@ -1046,86 +1359,207 @@ export function appendLedgerRows(root, ledger, rows) {
1046
1359
  throw new CommandError(EXIT.USAGE, "--rows must hold a JSON array");
1047
1360
  if (rows.length === 0)
1048
1361
  throw new CommandError(EXIT.USAGE, "--rows holds no rows");
1049
- let repo;
1050
- let version;
1051
- let last;
1052
1362
  const abs = path.join(root, file);
1053
- const prior = fs.existsSync(abs) ? parse(fs.readFileSync(abs, "utf-8")).events : [];
1054
- const out = rows.map((raw, i) => {
1055
- const refuse = (why) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
1056
- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
1057
- throw refuse("not a JSON object");
1058
- }
1059
- const r = raw;
1060
- if (Object.hasOwn(r, "ts"))
1061
- throw refuse("carries ts; ts is minted at append time");
1062
- if (Object.hasOwn(r, "schema"))
1063
- throw refuse("carries schema; it is set at append time");
1064
- if (!takes.includes(String(r["kind"]))) {
1065
- throw refuse(`kind must be ${takes.join(" | ")} in --ledger=${ledger} (got ${String(r["kind"])})`);
1066
- }
1067
- if (Object.hasOwn(r, "bkit"))
1068
- throw refuse("carries bkit; bkit.version is set at append time");
1069
- repo ??= resolveRepoSlug(root) || "unknown/repo";
1070
- version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
1071
- last = mintTs(last);
1072
- const filled = withLineage(prior, {
1073
- repo,
1074
- ...r,
1075
- schema: SCHEMA,
1076
- ts: last,
1077
- bkit: { version },
1078
- });
1079
- const row = {};
1080
- for (const k of TOP_ORDER)
1081
- if (filled[k] !== undefined)
1082
- row[k] = filled[k];
1083
- for (const [k, v] of Object.entries(filled))
1084
- if (!(k in row))
1085
- row[k] = v;
1086
- const v = validate(row);
1087
- if (!v.ok)
1088
- throw refuse(v.reason ?? "invalid");
1089
- const who = writerProblem(row);
1090
- if (who !== undefined)
1091
- throw refuse(who);
1092
- prior.push(row);
1093
- return row;
1094
- });
1095
1363
  const made = mkdirp(path.dirname(abs));
1096
1364
  if (made)
1097
1365
  throw new CommandError(EXIT_STAGE, `mkdir failed for ${path.dirname(file)}: ${made}`);
1098
- const block = out.map((r) => `${JSON.stringify(r)}\n`).join("");
1099
- // A file missing its final newline would glue the first row onto its last one.
1100
- const appendErr = appendText(abs, endsMidLine(abs) ? `\n${block}` : block);
1101
- if (appendErr)
1102
- throw new CommandError(EXIT_STAGE, `append failed: ${file} — ${appendErr}`);
1103
- return {
1104
- ledger: ledger,
1105
- file,
1106
- appended: out.length,
1107
- keys: out.map((r) => (typeof r["key"] === "string" ? r["key"] : null)),
1366
+ // The operation store is private to this git repository, never a committed path; a repo-less
1367
+ // root has no place to keep a durable receipt, so an operation there is refused.
1368
+ const ops = ledgerOperationsFile(root, options.operation !== undefined || options.issueOperation === true);
1369
+ // The request is the ledger and rows alone: an operation stays reconcilable after its
1370
+ // invocation goes stale, and replay writes the recorded bytes, never a re-derived `by`.
1371
+ const hash = actionHash(canonicalJson({ ledger, rows }));
1372
+ if (options.operation !== undefined && options.issueOperation === true)
1373
+ throw new CommandError(EXIT.USAGE, "--issue-operation and --operation are exclusive: the engine issues the id, or the caller names it");
1374
+ if (options.issueOperation === true && invocation === undefined)
1375
+ throw new CommandError(EXIT.USAGE, "--issue-operation needs --invocation: the id is issued from that invocation's context");
1376
+ const operation = appendOperationId(ledger, rows, invocation, options);
1377
+ // A rejection before any write is correctable only inside a workflow run (it has a scope to
1378
+ // spend from) and only when the operation can be named by the corrected retry.
1379
+ const scope = invocation === undefined ? null : appendCorrectionScope(invocation, ledger);
1380
+ const reject = (why, row) => {
1381
+ const message = `row ${row}: ${why}`;
1382
+ return scope !== null && operation !== undefined
1383
+ ? new NoWriteRejection(EXIT_ROW_REFUSED, message, { scope, substep: "append" })
1384
+ : new CommandError(EXIT_ROW_REFUSED, message);
1108
1385
  };
1109
- }
1110
- /** True when `abs` exists, is non-empty and its last byte is not a newline. */
1111
- function endsMidLine(abs) {
1112
- let fd;
1386
+ const result = (landed, block, replayed) => {
1387
+ const parsedRows = receiptRows(block);
1388
+ return {
1389
+ ledger: ledger,
1390
+ file,
1391
+ appended: replayed ? 0 : parsedRows.length,
1392
+ keys: parsedRows.map((r) => r.key),
1393
+ ...(operation === undefined
1394
+ ? {}
1395
+ : {
1396
+ receipt: {
1397
+ operation,
1398
+ ledger,
1399
+ file,
1400
+ offset: landed.offset,
1401
+ bytes: landed.bytes,
1402
+ rows: parsedRows,
1403
+ replayed,
1404
+ },
1405
+ }),
1406
+ };
1407
+ };
1408
+ const build = (text) => {
1409
+ let repo;
1410
+ let version;
1411
+ let last;
1412
+ const prior = parse(text).events;
1413
+ const out = rows.map((raw, i) => {
1414
+ const refuse = (why) => new CommandError(EXIT_ROW_REFUSED, `row ${i + 1}: ${why}`);
1415
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
1416
+ throw reject("not a JSON object", i + 1);
1417
+ }
1418
+ const r = invocation === undefined
1419
+ ? raw
1420
+ : withInvocationBy(raw, invocation, refuse);
1421
+ if (invocation === undefined && byOfRow(r)["modelSource"] === "unavailable")
1422
+ throw refuse("by.modelSource unavailable needs a validated --invocation; the engine records it, a caller cannot assert it");
1423
+ if (Object.hasOwn(r, "ts"))
1424
+ throw reject("carries ts; ts is minted at append time", i + 1);
1425
+ if (Object.hasOwn(r, "schema"))
1426
+ throw reject("carries schema; it is set at append time", i + 1);
1427
+ if (!takes.includes(String(r["kind"]))) {
1428
+ throw reject(`kind must be ${takes.join(" | ")} in --ledger=${ledger} (got ${String(r["kind"])})`, i + 1);
1429
+ }
1430
+ if (Object.hasOwn(r, "bkit"))
1431
+ throw reject("carries bkit; bkit.version is set at append time", i + 1);
1432
+ repo ??= resolveRepoSlug(root) || "unknown/repo";
1433
+ version ??= readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || "unknown";
1434
+ last = mintTs(last);
1435
+ const filled = withLineage(prior, {
1436
+ repo,
1437
+ ...r,
1438
+ schema: SCHEMA,
1439
+ ts: last,
1440
+ bkit: { version },
1441
+ });
1442
+ const row = {};
1443
+ for (const k of TOP_ORDER)
1444
+ if (filled[k] !== undefined)
1445
+ row[k] = filled[k];
1446
+ for (const [k, v] of Object.entries(filled))
1447
+ if (!(k in row))
1448
+ row[k] = v;
1449
+ const v = validate(row);
1450
+ if (!v.ok)
1451
+ throw reject(v.reason ?? "invalid", i + 1);
1452
+ const who = writerProblem(row);
1453
+ if (who !== undefined)
1454
+ throw refuse(who);
1455
+ prior.push(row);
1456
+ return row;
1457
+ });
1458
+ return out.map((r) => `${JSON.stringify(r)}\n`).join("");
1459
+ };
1460
+ const stage = (err) => err instanceof CommandError
1461
+ ? err
1462
+ : new CommandError(EXIT_STAGE, `append failed: ${file} \u2014 ${err.message}`);
1113
1463
  try {
1114
- fd = fs.openSync(abs, "r");
1115
- const size = fs.fstatSync(fd).size;
1116
- if (size === 0)
1117
- return false;
1118
- const last = Buffer.alloc(1);
1119
- fs.readSync(fd, last, 0, 1, size - 1);
1120
- return last[0] !== 0x0a;
1121
- }
1122
- catch {
1123
- // No file yet: the append creates it.
1124
- return false;
1464
+ return withTargetLock(abs, () => {
1465
+ if (operation === undefined) {
1466
+ const landed = appendHeld(abs, build, { checkpoint: options.checkpoint });
1467
+ return result(landed, landed.block, false);
1468
+ }
1469
+ if (ops === null)
1470
+ throw new CommandError(EXIT.USAGE, `${root} is not inside a git repository: a ledger operation keeps its receipt in the git common dir`);
1471
+ // The operation store is serialized by its own lock, taken after the target's, so two
1472
+ // ledgers' operations never interleave check and record.
1473
+ return withTargetLock(ops, () => {
1474
+ const known = ledgerOperation(ops, operation, hash);
1475
+ if (known.state === "conflict")
1476
+ throw new CommandError(EXIT_ROW_REFUSED, `operation ${operation} was already used for a different request; nothing written`);
1477
+ if (known.state === "replay") {
1478
+ const d = known.row
1479
+ .detail;
1480
+ if (d === undefined)
1481
+ throw new CommandError(EXIT_STAGE, `operation ${operation} has a receipt without its effect`);
1482
+ return result(d, d.block, true);
1483
+ }
1484
+ const intent = ledgerIntent(ops, operation);
1485
+ if (intent !== undefined && intent.hash !== hash)
1486
+ throw new CommandError(EXIT_ROW_REFUSED, `operation ${operation} was already used for a different request; nothing written`);
1487
+ const receipt = (landed) => recordLedgerOperation(ops, {
1488
+ operation,
1489
+ hash,
1490
+ ref: `${file}@${landed.offset}+${landed.bytes}`,
1491
+ detail: { offset: landed.offset, bytes: landed.bytes, block: landed.block },
1492
+ });
1493
+ if (intent !== undefined) {
1494
+ const have = fs.existsSync(abs) ? fs.readFileSync(abs) : Buffer.alloc(0);
1495
+ const want = Buffer.from(intent.block);
1496
+ const seg = have.subarray(intent.offset, intent.offset + want.length);
1497
+ if (seg.equals(want)) {
1498
+ // The bytes landed whole; confirm them durable and receipt them.
1499
+ const fd = fs.openSync(abs, "r");
1500
+ try {
1501
+ fs.fsyncSync(fd);
1502
+ }
1503
+ finally {
1504
+ fs.closeSync(fd);
1505
+ }
1506
+ receipt(intent);
1507
+ options.checkpoint?.("receipted");
1508
+ return result(intent, intent.block, true);
1509
+ }
1510
+ // Whole lines decide "landed": rows share a byte prefix (`{"schema":3,"ts":...`), so a
1511
+ // foreign row is told apart by being a complete line that differs from ours.
1512
+ // Compare by content, without the newline and without one leading separator newline:
1513
+ // a torn prefix of our line that a later writer completed with its own newline is a
1514
+ // proper prefix of our first line, so it stays uncertain rather than foreign.
1515
+ const stripSeparator = (b) => (b[0] === 0x0a ? b.subarray(1) : b);
1516
+ const firstLine = (b) => {
1517
+ const nl = b.indexOf(0x0a);
1518
+ return nl < 0
1519
+ ? { line: b, complete: false }
1520
+ : { line: b.subarray(0, nl), complete: true };
1521
+ };
1522
+ const wantLine = firstLine(stripSeparator(want)).line;
1523
+ const haveLine = firstLine(stripSeparator(have.subarray(intent.offset)));
1524
+ const foreignWholeLine = haveLine.complete &&
1525
+ !(haveLine.line.length <= wantLine.length &&
1526
+ wantLine.subarray(0, haveLine.line.length).equals(haveLine.line));
1527
+ let landedBytes = 0;
1528
+ while (landedBytes < seg.length &&
1529
+ landedBytes < want.length &&
1530
+ seg[landedBytes] === want[landedBytes])
1531
+ landedBytes++;
1532
+ if (!foreignWholeLine &&
1533
+ (landedBytes > 0 || (seg.length > 0 && have.length === intent.offset + seg.length)))
1534
+ throw new UncertainEffect(EXIT_STAGE, `operation ${operation}: ${file} holds ${landedBytes} of ${want.length} prepared bytes at the recorded offset; the effect is uncertain, nothing was truncated or retried`);
1535
+ if (have.length === intent.offset) {
1536
+ // Nothing landed: write the exact prepared bytes again.
1537
+ writePrepared(abs, intent.block, intent.offset);
1538
+ options.checkpoint?.("written");
1539
+ receipt(intent);
1540
+ options.checkpoint?.("receipted");
1541
+ return result(intent, intent.block, false);
1542
+ }
1543
+ // Another writer appended after the failed attempt and none of ours landed: prepare afresh.
1544
+ }
1545
+ const landed = appendHeld(abs, build, {
1546
+ checkpoint: options.checkpoint,
1547
+ prepared: (p) => recordLedgerIntent(ops, {
1548
+ operation,
1549
+ hash,
1550
+ file,
1551
+ offset: p.offset,
1552
+ bytes: Buffer.byteLength(p.block),
1553
+ block: p.block,
1554
+ }),
1555
+ written: (p) => receipt(p),
1556
+ });
1557
+ return result(landed, landed.block, false);
1558
+ });
1559
+ });
1125
1560
  }
1126
- finally {
1127
- if (fd !== undefined)
1128
- fs.closeSync(fd);
1561
+ catch (err) {
1562
+ throw stage(err);
1129
1563
  }
1130
1564
  }
1131
1565
  function append(ctx) {
@@ -1140,9 +1574,172 @@ function append(ctx) {
1140
1574
  const parsed = parseJson(text);
1141
1575
  if (!parsed.ok)
1142
1576
  throw new CommandError(EXIT.USAGE, "--rows is not JSON");
1143
- const r = appendLedgerRows(root, String(ctx.flags.ledger), parsed.value);
1144
- ctx.log(`appended ${r.appended} row(s) to ${r.file}`);
1145
- ctx.emit({ ...r });
1577
+ const bound = ctx.invocation?.bookRoot;
1578
+ if (bound !== undefined && bound !== null && bound !== root)
1579
+ throw new CommandError(EXIT.USAGE, `conflict: --root ${root} is not the invocation's book root ${bound}`);
1580
+ // A runless call has no book root of its own: its output scope is the checkout that issued it.
1581
+ if (ctx.invocation?.scope === "outbox") {
1582
+ const rel = path.relative(ctx.invocation.worktree, root);
1583
+ if (rel.startsWith("..") || path.isAbsolute(rel))
1584
+ throw new CommandError(EXIT.USAGE, `conflict: --root ${root} is outside the checkout ${ctx.invocation.worktree} that issued invocation ${ctx.invocation.id}`);
1585
+ }
1586
+ const ledger = String(ctx.flags.ledger);
1587
+ const request = {
1588
+ operation: str(ctx.flags.operation),
1589
+ issueOperation: ctx.flags.issueOperation === true,
1590
+ };
1591
+ const run = ctx.invocation;
1592
+ const scope = run === undefined ? null : appendCorrectionScope(run, ledger);
1593
+ const operation = appendOperationId(ledger, parsed.value, run, request);
1594
+ const correctionOf = str(ctx.flags.correctionOf);
1595
+ let spend;
1596
+ const book = run === undefined || scope === null ? null : correctionBook(ctx.cwd, run);
1597
+ if (correctionOf !== undefined) {
1598
+ if (run === undefined || scope === null || book === null)
1599
+ throw new CommandError(EXIT.USAGE, "--correction-of needs an --invocation with a correction scope: a workflow-run call, or a standalone audit or utility call");
1600
+ if (operation === undefined || operation === correctionOf)
1601
+ throw new CommandError(EXIT.USAGE, "--correction-of needs a fresh --operation or --issue-operation: a corrected candidate has its own operation id");
1602
+ const rejected = readStatusRows(book.file).some((row) => row.type === CORRECTION_REJECTED_ROW &&
1603
+ row.operation === correctionOf &&
1604
+ row.scope === scope &&
1605
+ row.workflow === book.workflow);
1606
+ if (!rejected)
1607
+ throw new CommandError(EXIT.USAGE, `--correction-of=${correctionOf} names no rejected ${ledger} append in this step; only a guaranteed no-write rejection of this sub-step can be corrected`);
1608
+ // An earlier operation on this ledger whose effect is unconfirmed is reconciled first.
1609
+ const target = Object.hasOwn(APPEND_LEDGERS, ledger)
1610
+ ? APPEND_LEDGERS[ledger].file
1611
+ : undefined;
1612
+ if (target !== undefined && pendingLedgerIntentsFor(root, target).length > 0)
1613
+ throw new UncertainEffect(EXIT_STAGE, `${target} holds an operation whose effect is unconfirmed; reconcile it before any corrected candidate — nothing was written`);
1614
+ spend = spendCorrection(book.file, book.workflow, scope, operation, CORRECTION_LIMIT, {
1615
+ of: correctionOf,
1616
+ step: book.step,
1617
+ substep: "append",
1618
+ requestHash: actionHash(canonicalJson({ ledger, rows: parsed.value })),
1619
+ });
1620
+ if (!spend.allowed)
1621
+ throw new CorrectionExhausted(EXIT.NO, spend.conflict === true
1622
+ ? `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`
1623
+ : `the correction budget of ${scope} is spent (${spend.used} of ${spend.limit}); nothing was written`, scope);
1624
+ }
1625
+ let r;
1626
+ try {
1627
+ r = appendLedgerRows(root, ledger, parsed.value, ctx.invocation, request);
1628
+ }
1629
+ catch (err) {
1630
+ if (err instanceof NoWriteRejection && book !== null && operation !== undefined) {
1631
+ fs.appendFileSync(book.file, appendLine({
1632
+ type: CORRECTION_REJECTED_ROW,
1633
+ workflow: book.workflow,
1634
+ at: statusTimestamp(),
1635
+ scope: err.detail.scope,
1636
+ substep: err.detail.substep,
1637
+ operation,
1638
+ step: book.step,
1639
+ }));
1640
+ // The last allowed retry was just used: the rejection is final, not correctable.
1641
+ if (spend !== undefined && spend.remaining === 0)
1642
+ throw new CommandError(err.code, err.message);
1643
+ }
1644
+ throw err;
1645
+ }
1646
+ ctx.log(r.receipt?.replayed === true
1647
+ ? `operation ${r.receipt.operation} already appended to ${r.file}; nothing written`
1648
+ : `appended ${r.appended} row(s) to ${r.file}`);
1649
+ if (spend === undefined || book === null || scope === null) {
1650
+ ctx.emit({ ...r });
1651
+ return EXIT.OK;
1652
+ }
1653
+ const verified = r.receipt?.replayed === true || r.appended === parsed.value.length;
1654
+ const succeeded = readStatusRows(book.file).some((row) => row.type === CORRECTION_SUCCEEDED_ROW && row.operation === operation);
1655
+ if (verified && !succeeded)
1656
+ fs.appendFileSync(book.file, appendLine({
1657
+ type: CORRECTION_SUCCEEDED_ROW,
1658
+ workflow: book.workflow,
1659
+ at: statusTimestamp(),
1660
+ scope,
1661
+ substep: "append",
1662
+ operation,
1663
+ of: correctionOf,
1664
+ step: book.step,
1665
+ }));
1666
+ ctx.emit({
1667
+ ...r,
1668
+ correction: {
1669
+ scope,
1670
+ operation,
1671
+ of: correctionOf,
1672
+ used: spend.used,
1673
+ limit: spend.limit,
1674
+ substep: "append",
1675
+ verified,
1676
+ },
1677
+ });
1678
+ return EXIT.OK;
1679
+ }
1680
+ /** Page cursor: the snapshot and filter it was cut from, and the offset of the next row. */
1681
+ function encodeCursor(c) {
1682
+ return Buffer.from(JSON.stringify(c)).toString("base64url");
1683
+ }
1684
+ function decodeCursor(text) {
1685
+ const parsed = parseJson(Buffer.from(text, "base64url").toString("utf-8"));
1686
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object")
1687
+ return null;
1688
+ const v = parsed.value;
1689
+ return typeof v["s"] === "string" && typeof v["f"] === "string" && Number.isInteger(v["o"])
1690
+ ? { s: v["s"], f: v["f"], o: v["o"] }
1691
+ : null;
1692
+ }
1693
+ function query(ctx) {
1694
+ const root = rootOf(ctx);
1695
+ const ledger = String(ctx.flags.ledger);
1696
+ if (!Object.hasOwn(APPEND_LEDGERS, ledger)) {
1697
+ throw new CommandError(EXIT.USAGE, `--ledger must be one of ${Object.keys(APPEND_LEDGERS).join(", ")} (got '${ledger}')`);
1698
+ }
1699
+ const { file } = APPEND_LEDGERS[ledger];
1700
+ const filter = { key: str(ctx.flags.key), status: str(ctx.flags.status) };
1701
+ const limit = wholeNumber(ctx.flags.limit, "limit", QUERY_PAGE, 1);
1702
+ const filterId = JSON.stringify([filter.key ?? null, filter.status ?? null]);
1703
+ const cursorText = str(ctx.flags.cursor);
1704
+ const cursor = cursorText === undefined ? null : decodeCursor(cursorText);
1705
+ if (cursorText !== undefined && cursor === null)
1706
+ throw new CommandError(EXIT.USAGE, "--cursor is not a cursor from this command");
1707
+ const abs = path.join(root, file);
1708
+ const read = readText(abs);
1709
+ const missing = !read.ok && !fs.existsSync(abs);
1710
+ const raw = read.ok ? read.text : "";
1711
+ const snapshot = createHash("sha256").update(raw).digest("hex").slice(0, 16);
1712
+ if (cursor !== null && (cursor.s !== snapshot || cursor.f !== filterId))
1713
+ throw new CommandError(EXIT.USAGE, "stale cursor: the ledger or the filter changed since this scan began; start again without --cursor");
1714
+ const result = queryLedger(raw, filter);
1715
+ const offset = cursor?.o ?? 0;
1716
+ const page = result.rows.slice(offset, offset + limit);
1717
+ const next = offset + limit < result.rows.length ? offset + limit : null;
1718
+ const status = missing
1719
+ ? "missing"
1720
+ : !read.ok
1721
+ ? "unreadable"
1722
+ : result.diagnostics.length > 0
1723
+ ? "partial"
1724
+ : next !== null
1725
+ ? "incomplete"
1726
+ : "clean";
1727
+ ctx.emit({
1728
+ ledger,
1729
+ file,
1730
+ rows: page,
1731
+ nextCursor: next === null ? null : encodeCursor({ s: snapshot, f: filterId, o: next }),
1732
+ snapshot,
1733
+ total: result.rows.length,
1734
+ diagnostics: result.diagnostics,
1735
+ coverage: {
1736
+ status,
1737
+ clean: status === "clean",
1738
+ malformedLines: result.diagnostics.length,
1739
+ lines: result.lines,
1740
+ ...(!read.ok && !missing ? { error: read.error } : {}),
1741
+ },
1742
+ });
1146
1743
  return EXIT.OK;
1147
1744
  }
1148
1745
  const LEDGER_ROWS_LINE = /^\*\*Ledger rows:\*\*(.*)$/m;
@@ -1156,16 +1753,32 @@ export function checkPlanRows(root, plan) {
1156
1753
  const abs = path.resolve(root, plan);
1157
1754
  if (!fs.existsSync(abs))
1158
1755
  throw new CommandError(EXIT.USAGE, `--plan not found: ${plan}`);
1159
- const text = fs.readFileSync(abs, "utf-8");
1160
- const line = LEDGER_ROWS_LINE.exec(text)?.[1]?.trim();
1161
- if (line === undefined) {
1162
- throw new CommandError(EXIT_ROWS_MISSING, `${plan} has no **Ledger rows:** line`);
1756
+ const r = readPlanRows(root, fs.readFileSync(abs, "utf-8"));
1757
+ if (r.unreadable !== undefined)
1758
+ throw new CommandError(EXIT_ROWS_MISSING, `${plan}: ${r.unreadable}`);
1759
+ return { keys: r.keys, missing: r.missing };
1760
+ }
1761
+ /**
1762
+ * Read `text`'s `**Ledger rows:**` line and the keys no `decision` / `deferral`
1763
+ * row under `root` carries. An absent or placeholder line is `unreadable`.
1764
+ */
1765
+ export function readPlanRows(root, text) {
1766
+ const match = LEDGER_ROWS_LINE.exec(text);
1767
+ const line = match?.[1]?.trim();
1768
+ if (match === null || line === undefined) {
1769
+ return { line: 0, keys: [], missing: [], unreadable: "no **Ledger rows:** line" };
1163
1770
  }
1771
+ const at = text.slice(0, match.index).split("\n").length;
1164
1772
  const keys = [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "");
1165
1773
  if (keys.length === 0) {
1166
1774
  if (line.replace(/[."\s]/g, "") === "None")
1167
- return { keys: [], missing: [] };
1168
- throw new CommandError(EXIT_ROWS_MISSING, `${plan}: **Ledger rows:** is unfilled (${line})`);
1775
+ return { line: at, keys: [], missing: [] };
1776
+ return {
1777
+ line: at,
1778
+ keys: [],
1779
+ missing: [],
1780
+ unreadable: `**Ledger rows:** is unfilled (${line})`,
1781
+ };
1169
1782
  }
1170
1783
  const onDisk = new Set();
1171
1784
  for (const { file, kinds } of CHECKED_LEDGERS) {
@@ -1178,7 +1791,7 @@ export function checkPlanRows(root, plan) {
1178
1791
  onDisk.add(key);
1179
1792
  }
1180
1793
  }
1181
- return { keys, missing: keys.filter((k) => !onDisk.has(k)) };
1794
+ return { line: at, keys, missing: keys.filter((k) => !onDisk.has(k)) };
1182
1795
  }
1183
1796
  function check(ctx) {
1184
1797
  const root = rootOf(ctx);
@@ -1224,18 +1837,19 @@ function mkdirp(dir) {
1224
1837
  /** {@link compactLedgers}; its results, or the error text. A failed temp write or rename leaves the ledger untouched. */
1225
1838
  function compactOrError(root, ledgers, dryRun) {
1226
1839
  try {
1227
- return compactLedgers(root, ledgers, dryRun);
1228
- }
1229
- catch (err) {
1230
- // Reported as the command's staging exit code, with the reason.
1231
- return err.message;
1232
- }
1233
- }
1234
- /** Append `text` to `file`; the error text, or undefined on success. */
1235
- function appendText(file, text) {
1236
- try {
1237
- fs.appendFileSync(file, text);
1238
- return undefined;
1840
+ const targets = ledgers.map((l) => COMPACT_LEDGERS[l]).sort();
1841
+ const locked = (i) => {
1842
+ if (i === targets.length) {
1843
+ for (const t of targets) {
1844
+ const pending = pendingLedgerIntentsFor(root, t);
1845
+ if (pending.length > 0)
1846
+ throw new Error(`${t} has ${pending.length} ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them before compacting`);
1847
+ }
1848
+ return compactLedgers(root, ledgers, dryRun);
1849
+ }
1850
+ return withTargetLock(path.join(root, targets[i]), () => locked(i + 1));
1851
+ };
1852
+ return locked(0);
1239
1853
  }
1240
1854
  catch (err) {
1241
1855
  // Reported as the command's staging exit code, with the reason.