@cbartens/bkit 5.5.0 → 6.0.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 (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -13,8 +13,8 @@
13
13
  // (b) `validate` REJECTS unknown `kind` before write. No reject path in status.ts.
14
14
  // (c) ms `ts` via now*1000|floor, NOT ISO `at`.
15
15
  //
16
- // Version provenance: every row records the emitting `bkitVersion`. Readers ingest
17
- // ALL well-formed rows (no version gating) and report row counts per `bkitVersion`
16
+ // Version provenance: every row records the emitting `bkit.version`. Readers ingest
17
+ // ALL well-formed rows (no version gating) and report row counts per `bkit.version`
18
18
  // so an unexpected version surfaces for triage.
19
19
 
20
20
  import { spawnSync } from "node:child_process";
@@ -111,17 +111,19 @@ export function resolveRepoSlug(cwd: string): string {
111
111
  // Shared envelope (A2-mandatory fields on EVERY row, every kind)
112
112
  // ---------------------------------------------------------------------------
113
113
 
114
- export interface TelemetryEnvelope {
115
- /** Primary id = unix milliseconds (portable: jq `now*1000|floor`). */
116
- ts: number;
117
- /** Closed enum — validated on append; unknown kind rejected. */
118
- kind: TelemetryKind;
119
- /** Origin repo (slug, e.g. "cbartens/bkit"). */
120
- repo: string;
121
- /** bkit version stamped on every row for regression attribution. */
122
- bkitVersion: string;
123
- /** Emitting workflow: design | plan | build | debug | ship | audit */
124
- workflow: string;
114
+ /**
115
+ * Row format version. Rows written without `schema` are read through {@link normalize}.
116
+ * A schema-2 row differs only in its outcome `plan` block ({@link StoredPlanBlock}).
117
+ */
118
+ export const SCHEMA = 3;
119
+
120
+ /** The schema {@link normalize} stamps on a row written without one: the shape it builds. */
121
+ const NORMALIZED_SCHEMA = 2;
122
+
123
+ /** Who wrote a row: the workflow and step it was emitted at, and the subagent when one wrote it. */
124
+ export interface RowBy {
125
+ /** Emitting workflow: design | plan | build | debug | ship | audit; `chat-stats` on `chat` rows; the counted run's on `run` rows. */
126
+ workflow?: string;
125
127
  /**
126
128
  * The WORKFLOW STEP the row was emitted at, e.g. `build-close-workflow`,
127
129
  * `ship-close-gate`. A step of the orchestrator, never an agent name — a
@@ -129,38 +131,58 @@ export interface TelemetryEnvelope {
129
131
  */
130
132
  step: string;
131
133
  /**
132
- * The SUBAGENT that wrote the row, e.g. `bkit-build-challenge-remediate`.
134
+ * The SUBAGENT that wrote the row, e.g. `bkit-build-plan-gaps-remediate`.
133
135
  * Absent on orchestrator-written rows (the workflow itself wrote it).
134
- *
135
- * Distinct from `step`: `step` is WHERE in the workflow, `subagent` is WHO. One of
136
- * the harvest's five slice dimensions (repo/workflow/step/subagent/severity).
137
136
  */
138
137
  subagent?: string;
139
138
  /**
140
139
  * The model that wrote the row, read from the writing subagent's OWN prompt
141
- * frontmatter `model:` at call time — the deterministic source bkit already
142
- * owns, and the only one that stays true when a prompt is re-pinned.
143
- *
144
- * Set ONLY on subagent-written rows, i.e. exactly when `subagent` is set. An
145
- * orchestrator-written row has no `model`: the session model is the operator's
146
- * runtime choice, not a property of the row, and self-reporting it invites the
147
- * same nondeterminism the compliance grader exists to avoid.
140
+ * frontmatter `model:` at call time. Set ONLY on subagent-written rows, i.e.
141
+ * exactly when `subagent` is set.
148
142
  */
149
143
  model?: string;
144
+ }
145
+
146
+ /** The bkit that wrote a row; `chat` rows add what the chat did with bkit. */
147
+ export interface BkitBlock {
148
+ /** bkit version stamped on every row for regression attribution; null on a chat / run row when unknown. */
149
+ version: string | null;
150
+ [field: string]: unknown;
151
+ }
152
+
153
+ export interface TelemetryEnvelope {
154
+ /** {@link SCHEMA} on write; a stored row may carry `2` ({@link StoredPlanBlock}). */
155
+ schema: typeof SCHEMA | typeof NORMALIZED_SCHEMA;
156
+ /** Primary id = unix milliseconds (portable: jq `now*1000|floor`). */
157
+ ts: number;
158
+ /** Closed enum — validated on append; unknown kind rejected. */
159
+ kind: TelemetryKind;
160
+ /**
161
+ * Explicit written-once logical key for the keyed kinds
162
+ * (friction / deferral / failure / knowledge / decision / feature / chat / run).
163
+ * Author writes a stable slug ONCE; recurrence = same-key append.
164
+ * Absent on event kinds that key off composite tuples (compliance / counter / outcome).
165
+ */
166
+ key?: string;
167
+ /** Origin repo (slug, e.g. "cbartens/bkit"). */
168
+ repo: string;
169
+ bkit: BkitBlock;
170
+ by: RowBy;
150
171
  /**
151
172
  * Free-form related context: any pointer that helps a reader place this row —
152
173
  * feature ids, tracker ids (`BAR-217`), PRs, commit SHAs, file paths, sibling
153
174
  * `ts`, a ledger id (`KN-14`, `DE-7`). Every entry is a pointer,
154
- * never an identity: `ts` (with `key` for instinct-loop kinds) identifies the row.
175
+ * never an identity: `ts` (with `key` for keyed kinds) identifies the row.
155
176
  */
156
177
  references?: string[];
157
- /**
158
- * Explicit written-once logical key for instinct-loop kinds
159
- * (friction / deferral / failure / knowledge / decision).
160
- * Author writes a stable slug ONCE; recurrence = same-key append.
161
- * Absent on event kinds that key off composite tuples (compliance / counter / outcome).
162
- */
163
- key?: string;
178
+ }
179
+
180
+ /** The identity block of every row that belongs to one workflow run. */
181
+ export interface RunRef {
182
+ /** HEAD at the run's close — the join key shared by its compliance / counter / outcome rows. */
183
+ parentSha?: string;
184
+ /** Ship-only: the merged PR number. */
185
+ pr?: number;
164
186
  }
165
187
 
166
188
  // ---------------------------------------------------------------------------
@@ -176,7 +198,9 @@ export type TelemetryKind =
176
198
  | "failure"
177
199
  | "knowledge"
178
200
  | "decision"
179
- | "feature";
201
+ | "feature"
202
+ | "chat"
203
+ | "run";
180
204
 
181
205
  export const VALID_KINDS: Set<string> = new Set([
182
206
  "compliance",
@@ -188,6 +212,8 @@ export const VALID_KINDS: Set<string> = new Set([
188
212
  "knowledge",
189
213
  "decision",
190
214
  "feature",
215
+ "chat",
216
+ "run",
191
217
  ]);
192
218
 
193
219
  /**
@@ -195,8 +221,8 @@ export const VALID_KINDS: Set<string> = new Set([
195
221
  * triaged by a human or a later agent (friction / deferral / failure).
196
222
  *
197
223
  * The SAME vocabulary the challenge prompts assign to their findings;
198
- * `@bkit-build-challenge-remediate` passes a blocked finding's severity straight
199
- * through to its deferral row. NOT the preflight `blocker`/`advisory` scale (that
224
+ * `bkit challenge merge` passes a LOW finding's severity straight through to its
225
+ * deferral row. NOT the preflight `blocker`/`advisory` scale (that
200
226
  * gates `bkit install`).
201
227
  *
202
228
  * Absent on machine-generated kinds (compliance / outcome / counter) and on
@@ -268,19 +294,28 @@ export const FEATURE_STATUSES: Set<string> = new Set([
268
294
  * - `needs-decision` — a human decision is missing, and guessing it is worse than
269
295
  * waiting. Confirmation is unavailable inside `/bkit-*` workflows.
270
296
  * - `own-cycle` — genuinely plan-sized: a new architecture, not a mechanical fix.
297
+ * - `low-severity` — a `LOW` challenge finding, written by `bkit challenge merge`;
298
+ * that writer and that severity only.
271
299
  * - `unjustified` — ADJUDICATOR-ONLY (see UNJUSTIFIED_REASON).
272
300
  *
273
- * A writer who cannot pick one of the first four does not have a deferral; it has
274
- * unfinished work (`.agents/rules.md` § Principles, "Finish over deferrals").
301
+ * A writer who cannot pick one of the first four, or `low-severity` where it
302
+ * applies, does not have a deferral; it has unfinished work (`.agents/rules.md`
303
+ * § Principles, "Finish over deferrals").
275
304
  */
276
305
  export type DeferralReason =
277
- "scope-declared" | "hard-blocked" | "needs-decision" | "own-cycle" | "unjustified";
306
+ | "scope-declared"
307
+ | "hard-blocked"
308
+ | "needs-decision"
309
+ | "own-cycle"
310
+ | "low-severity"
311
+ | "unjustified";
278
312
 
279
313
  export const DEFERRAL_REASONS: Set<string> = new Set([
280
314
  "scope-declared",
281
315
  "hard-blocked",
282
316
  "needs-decision",
283
317
  "own-cycle",
318
+ "low-severity",
284
319
  "unjustified",
285
320
  ]);
286
321
 
@@ -309,19 +344,132 @@ export const DEFERRAL_WRITERS: Set<string> = new Set([
309
344
  "bkit-design-generate",
310
345
  "bkit-plan-generate",
311
346
  "bkit-plan-update",
312
- "bkit-build-challenge-remediate",
313
347
  "bkit-debug-abort-handover",
314
348
  "bkit-ship-deferred-sweep",
315
349
  "bkit-utility-update-deferrals",
316
350
  ]);
317
351
 
352
+ /** A writer list that admits every name (`.bkit/jsonl.md` § Ledgers & Writers: "any agent"). */
353
+ export const ANY_WRITER = "any";
354
+
355
+ export interface KindWriters {
356
+ /** Who may write the kind as a subagent, matched against the row's `subagent`. */
357
+ subagents: ReadonlySet<string> | typeof ANY_WRITER;
358
+ /** Which orchestrators may write it, matched against the `workflow` of a row with no `subagent`. */
359
+ orchestrators: ReadonlySet<string> | typeof ANY_WRITER;
360
+ }
361
+
362
+ /**
363
+ * The ledgers `bkit ledgers append` lands rows in, and the kinds each takes.
364
+ * `feature` rows go through `bkit roadmap feature` (it re-renders the board);
365
+ * `chat` / `run` rows are written by bkit's harvest script, to `harvest/stats.jsonl`.
366
+ */
367
+ export const APPEND_LEDGERS = {
368
+ decisions: { file: "docs/decisions.jsonl", kinds: ["decision"] },
369
+ deferrals: { file: "docs/deferrals.jsonl", kinds: ["deferral"] },
370
+ failures: { file: "docs/failures.jsonl", kinds: ["failure"] },
371
+ knowledge: { file: "docs/knowledge.jsonl", kinds: ["knowledge"] },
372
+ friction: { file: ".bkit/friction.jsonl", kinds: ["friction"] },
373
+ stats: { file: ".bkit/stats.jsonl", kinds: ["compliance", "counter", "outcome"] },
374
+ } as const;
375
+
376
+ export type AppendLedger = keyof typeof APPEND_LEDGERS;
377
+ export type AppendKind = (typeof APPEND_LEDGERS)[AppendLedger]["kinds"][number];
378
+
379
+ /** The workflows whose close writes `.bkit/stats.jsonl` rows (`bkit workflows close`, `bkit comply`). */
380
+ const CLOSING_WORKFLOWS = new Set(["design", "plan", "build", "debug", "ship"]);
381
+
382
+ /**
383
+ * `.bkit/jsonl.md` § Ledgers & Writers as code, for the kinds in
384
+ * {@link APPEND_LEDGERS}. EXHAUSTIVE: a name absent from a set does not write the
385
+ * kind. `telemetry.test.ts` holds this to the doc table.
386
+ */
387
+ export const KIND_WRITERS: Record<AppendKind, KindWriters> = {
388
+ decision: {
389
+ subagents: new Set([
390
+ "bkit-debug-failure-remediate",
391
+ "bkit-plan-generate",
392
+ "bkit-plan-update",
393
+ "bkit-utility-update-decisions",
394
+ ]),
395
+ // Build: Decision Pause accept; plan: an open question answered after close; ship: an
396
+ // assumed accept the owner confirms (`bkit decisions apply --by=owner`). All ONLY after
397
+ // explicit human approval.
398
+ orchestrators: new Set(["build", "plan", "ship"]),
399
+ },
400
+ // Build: `bkit challenge merge` writes each LOW challenge finding (`low-severity`). Ship:
401
+ // `bkit decisions pending --defer` writes each assumed accept nobody confirmed (`needs-decision`).
402
+ deferral: { subagents: DEFERRAL_WRITERS, orchestrators: new Set(["build", "ship"]) },
403
+ failure: { subagents: ANY_WRITER, orchestrators: ANY_WRITER },
404
+ knowledge: {
405
+ subagents: new Set([
406
+ "bkit-build-plan-execute",
407
+ "bkit-build-plan-gaps-remediate",
408
+ "bkit-debug-failure-remediate",
409
+ "bkit-utility-update-knowledge",
410
+ ]),
411
+ orchestrators: new Set(),
412
+ },
413
+ friction: {
414
+ subagents: new Set(),
415
+ orchestrators: new Set(["design", "plan", "build", "debug", "ship"]),
416
+ },
417
+ compliance: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
418
+ counter: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
419
+ outcome: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
420
+ };
421
+
422
+ const writerList = (w: KindWriters["subagents"]): string =>
423
+ w === ANY_WRITER ? "any" : w.size === 0 ? "none" : [...w].join(", ");
424
+
425
+ /** A row's `by` block, or an empty one when it has none. */
426
+ const byOf = (row: Record<string, unknown>): Record<string, unknown> =>
427
+ row["by"] !== null && typeof row["by"] === "object" ? (row["by"] as Record<string, unknown>) : {};
428
+
429
+ /**
430
+ * Why `row` may not be written by its author, or undefined when it may. The author
431
+ * is `by.subagent` when set (with its `by.model`), else the orchestrator in
432
+ * `by.workflow` (`.bkit/jsonl.md` § Who Wrote It).
433
+ */
434
+ export function writerProblem(row: Record<string, unknown>): string | undefined {
435
+ const kind = row["kind"] as AppendKind;
436
+ const writers = KIND_WRITERS[kind];
437
+ if (writers === undefined) return `${String(kind)} rows have no append writers`;
438
+ const by = byOf(row);
439
+ const subagent = by["subagent"];
440
+ if (subagent !== undefined) {
441
+ if (typeof subagent !== "string" || subagent === "") {
442
+ return "by.subagent must be a non-empty string";
443
+ }
444
+ if (typeof by["model"] !== "string" || by["model"] === "") {
445
+ return `subagent ${subagent} row missing by.model (its prompt's frontmatter model:)`;
446
+ }
447
+ if (writers.subagents === ANY_WRITER || writers.subagents.has(subagent)) return undefined;
448
+ return `subagent ${subagent} does not write ${kind} rows (subagents: ${writerList(writers.subagents)})`;
449
+ }
450
+ if (by["model"] !== undefined) return "by.model is set only on subagent rows";
451
+ if (writers.orchestrators === ANY_WRITER) return undefined;
452
+ const workflow = by["workflow"];
453
+ if (typeof workflow === "string" && writers.orchestrators.has(workflow)) return undefined;
454
+ return `the ${typeof workflow === "string" ? workflow : "(no workflow)"} orchestrator does not write ${kind} rows (orchestrators: ${writerList(writers.orchestrators)})`;
455
+ }
456
+
457
+ /**
458
+ * A `ts` minted now: `Date.now()`, or `after + 1` when the clock has not passed
459
+ * `after`, moved 1 ms off a whole second. The live-ledger gate fails whole-second
460
+ * values as hand-typed (`audits/repo/ledger-integrity.test.ts`), and a real mint
461
+ * must never trip it.
462
+ */
463
+ export function mintTs(after?: number): number {
464
+ let ts = Date.now();
465
+ if (after !== undefined && ts <= after) ts = after + 1;
466
+ return ts % 1000 === 0 ? ts + 1 : ts;
467
+ }
468
+
318
469
  // compliance — one row per run x rule (kind:"compliance")
319
470
  export interface CompliancePayload {
320
- rule: string;
321
- result: "pass" | "fail" | "n/a";
322
- evidence?: string;
323
- phase: string;
324
- parentSha: string;
471
+ run: { parentSha: string };
472
+ rule: { id: string; verdict: "pass" | "fail" | "n/a"; evidence?: string };
325
473
  }
326
474
 
327
475
  /** Code-coverage percentages (0-100), from a coverage-summary.json `total`. */
@@ -332,94 +480,149 @@ export interface CoverageStats {
332
480
  statements?: number;
333
481
  }
334
482
 
335
- // outcome — one row per WORKFLOW RUN, keyed by (repo, workflow, parentSha).
336
- // Every workflow writes one run row at its close, carrying just the fields that apply to it
337
- // (absent fields are simply omitted — the summary shows a metric only when present).
338
- // `prNumber` is ship-only; the per-run instinct-loop deltas (frictionAdded /
339
- // deferralsAdded / failuresAdded) are what `workflowTelemetry` features.
483
+ /** `start` / `end` unix ms; `totalMinutes` = end - start. `chat` and `run` rows add active time. */
484
+ export interface TimeBlock {
485
+ start: number;
486
+ end: number;
487
+ totalMinutes: number;
488
+ activeMinutes?: number | null;
489
+ lastActivity?: number;
490
+ [field: string]: unknown;
491
+ }
492
+
493
+ export interface LineCounts {
494
+ added: number;
495
+ deleted: number;
496
+ files: number;
497
+ }
498
+
499
+ /** Lines a run changed, split by what the file is; `total` = the sum of the three parts. */
500
+ export interface LinesBlock {
501
+ total: LineCounts & { changed: number };
502
+ code: LineCounts;
503
+ tests: LineCounts;
504
+ docs: LineCounts;
505
+ /** Merges (dev syncs) the count was cut at, so merged-in work is not counted. */
506
+ merges: number;
507
+ }
508
+
509
+ export interface StepTime {
510
+ n: number;
511
+ totalMinutes: number;
512
+ activeMinutes?: number | null;
513
+ }
514
+
515
+ /** Step-done rows per step; `total` = the sum of `byStep`. */
516
+ export interface StepsBlock {
517
+ total: StepTime;
518
+ byStep: Record<string, StepTime>;
519
+ }
520
+
521
+ /** One close-step CI dispatch. */
522
+ export interface CiDispatch {
523
+ status: string | null;
524
+ reason: string | null;
525
+ attempts: number | null;
526
+ }
527
+
528
+ /** One planned task: its `Test first` tests and distinct test files; `null` = the task has no `Test first` field. */
529
+ export interface PlanTask {
530
+ tests: number | null;
531
+ testFiles: number | null;
532
+ }
533
+
534
+ /** The plan a run worked from; `total.tasks` = the sum over `groups`. */
535
+ export interface PlanBlock {
536
+ /** `converted` = the build rewrote its input into the plan file. */
537
+ source: "file" | "converted";
538
+ total: { tasks: number; kb: number };
539
+ groups: Array<{ tasks: PlanTask[] }>;
540
+ }
541
+
542
+ /**
543
+ * A schema-1 or schema-2 row's plan block, read as stored: `brief` = no plan file
544
+ * (only this field); tasks per sub-plan; the complexity check's verdict.
545
+ */
546
+ export interface StoredPlanBlock {
547
+ source: "file" | "brief";
548
+ total?: { tasks: number; kb: number };
549
+ subPlans?: Array<{ kb: number; tasks: PlanTask[] }>;
550
+ complexity?: { verdict: string | null; tasksChecked: number | null; reasons: string[] };
551
+ }
552
+
553
+ export interface BuildBlock {
554
+ verify?: Array<Record<string, unknown>>;
555
+ gapsRemediate?: Array<Record<string, unknown>>;
556
+ holistic?: { verdict: string | null; failures: number | null } | null;
557
+ challenge?: {
558
+ verdict: string | null;
559
+ findings: { total: number; CRITICAL: number; HIGH: number; MEDIUM: number; LOW: number } | null;
560
+ /** The latest `bkit challenge gate` size: small skips challenge-1. Absent before the gate existed. */
561
+ gate?: {
562
+ size: string | null;
563
+ linesChanged: number | null;
564
+ filesChanged: number | null;
565
+ skipped: boolean;
566
+ };
567
+ } | null;
568
+ redTests?: number;
569
+ }
570
+
571
+ /**
572
+ * The context one subagent may fill before it hands over (the plan template's "about 160k
573
+ * tokens" per build group). Rows store peaks only; readers judge them against this.
574
+ */
575
+ export const AGENT_CONTEXT_CAP = 160_000;
576
+
577
+ /**
578
+ * The run's subagents, per agent type: `runs` = subagents of that type with a model call in
579
+ * the run, `peak` = the largest context (input + cache write + cache read tokens of one model
580
+ * call) any of them reached in it. `host` = where the counts came from.
581
+ */
582
+ export interface ContextBlock {
583
+ host: "claude-code";
584
+ byAgent: Record<string, { peak: number; runs: number }>;
585
+ }
586
+
587
+ export const OUTCOME_ENDINGS: Set<string> = new Set(["done", "close-failed"]);
588
+
589
+ // outcome — one row per WORKFLOW RUN, keyed by (repo, by.workflow, run.parentSha), written
590
+ // by `bkit workflows close`. Blocks that do not apply to the workflow are absent.
340
591
  export interface OutcomePayload {
592
+ run: RunRef;
593
+ /** null when the run's start row is missing. */
594
+ time: TimeBlock | null;
595
+ /** `close-failed` = the work finished and the close after it did not (its CI never started). */
596
+ ending: "done" | "close-failed";
597
+ lines?: LinesBlock | null;
598
+ steps?: StepsBlock;
599
+ ci?: CiDispatch[];
341
600
  /**
342
- * Parent commit SHA of the run — the run's identity anchor (shared with the
343
- * `compliance` / `counter` rows written in the same close). Optional: ship rows
344
- * written without it are keyed by `prNumber`.
345
- */
346
- parentSha?: string;
347
- /** Ship-only: the merged PR number. Absent on design/plan/build/debug runs. */
348
- prNumber?: number;
349
- /** Lines added (git diff --stat). */
350
- linesAdded: number;
351
- /** Lines deleted (git diff --stat). */
352
- linesDeleted: number;
353
- /** linesAdded + linesDeleted. */
354
- linesChanged: number;
355
- /** Files changed (git diff --stat). */
356
- filesChanged: number;
357
- /** Count of tasks in the sub-plan(s). */
358
- taskCount: number;
359
- /** Total workflow duration in seconds. */
360
- durationSeconds: number;
361
- /**
362
- * Which CI attempt passed (e.g. 2 = failed once then passed on retry).
363
- * undefined = not yet backfilled by P4 analysis.
364
- */
365
- ciTrySuccess?: number;
366
- /** Number of corrective commits post-PR-open. */
367
- correctiveCommits?: number;
368
- /** Number of PR review iterations. */
369
- reviewIterations?: number;
370
- /**
371
- * The repo's CUMULATIVE count of distinct deferrals at ship time — folded
372
- * entities, not lines. Per-cycle is the DELTA against the previous outcome
373
- * row (see newFailuresThisRun / isErrorRun in commands/analysis.ts).
374
- */
375
- deferrals: number;
376
- /**
377
- * The repo's CUMULATIVE count of distinct failures at ship time — folded
378
- * entities, not lines. Per-cycle is the DELTA against the previous outcome row.
379
- *
380
- * A total, NOT this run's discoveries. Readers MUST diff consecutive rows rather
381
- * than test this absolutely.
382
- */
383
- failures: number;
384
- /**
385
- * Per-run instinct-loop DELTAS — how many rows THIS run added to each ledger,
386
- * counted at close from rows with `workflow == <this workflow>` and
387
- * `ts >= workflow-started`. Distinct from the cumulative `deferrals`/`failures`
388
- * above: those are repo totals, these are what this one run contributed.
389
- * `frictionAdded` is the featured per-workflow signal (see `workflowTelemetry`);
390
- * all three are optional so a workflow that cannot produce one simply omits it.
391
- */
392
- frictionAdded?: number;
393
- deferralsAdded?: number;
394
- failuresAdded?: number;
395
- /**
396
- * `"brief"` = the run had no `{FID}-plan*.md` and worked from its input file
397
- * (build / ship `workflow-meta` row). Absent = the run had a plan. Brief runs
398
- * report `taskCount` 0 and are baselined only against other brief runs.
399
- */
400
- planSource?: "brief";
401
- /**
402
- * Per-tier code-coverage % — each tier's coverage-summary.json `total.*.pct`.
403
- * Best-effort: a tier is absent when its coverage report is not produced
404
- * (coverage is opt-in per tier). Additive-optional —
405
- * no version bump; readers ingest rows with or without it.
601
+ * `repo` = the repo's count of distinct entries at close (folded entities, not lines);
602
+ * `added` = distinct keys THIS run added (rows of this workflow at or after its start),
603
+ * absent when the run's start is unknown.
406
604
  */
407
- coverage?: {
408
- unit?: CoverageStats;
409
- integration?: CoverageStats;
410
- e2e?: CoverageStats;
605
+ ledgers: {
606
+ deferrals: { repo: number; added?: number };
607
+ failures: { repo: number; added?: number };
608
+ friction: { added?: number };
411
609
  };
610
+ plan?: PlanBlock | StoredPlanBlock;
611
+ build?: BuildBlock;
612
+ /** Absent when the host keeps no transcript bkit can tie to the run. */
613
+ context?: ContextBlock;
614
+ ship?: { coverage?: { unit?: CoverageStats; integration?: CoverageStats; e2e?: CoverageStats } };
412
615
  }
413
616
 
414
- // counter — attempt/failure counts, keyed by (repo, workflow, parentSha, counterName)
617
+ // counter — attempt/failure counts, keyed by (repo, by.workflow, run.parentSha, counter.name)
415
618
  export interface CounterPayload {
416
- counterName: string;
417
- counterValue: number;
418
- parentSha: string;
419
- /**
420
- * Trust-tier field: model-self-report (pre-P3) vs shell-bus (post-P3 deterministic).
421
- */
422
- counterSource: "model-self-report" | "shell-bus";
619
+ run: { parentSha: string };
620
+ counter: {
621
+ name: string;
622
+ value: number;
623
+ /** Trust tier: model-self-report vs shell-bus (deterministic). */
624
+ source: "model-self-report" | "shell-bus";
625
+ };
423
626
  }
424
627
 
425
628
  // friction — keyed by explicit `key` field
@@ -542,6 +745,48 @@ export interface FeaturePayload {
542
745
  shippedAt?: number;
543
746
  }
544
747
 
748
+ // chat — one agent chat on any host (a session plus its subagents), written by
749
+ // `scripts/harvest/bkit-harvest.mjs`; keyed by explicit `key` (`<platform>:<sessionId>`).
750
+ // A resumed chat is a same-`key` append; last row wins. The script is the writer and the
751
+ // field reference (its header); the codec checks the join fields and every total.
752
+ export interface ChatPayload {
753
+ key: string;
754
+ session: { platform: string; id: string; [field: string]: unknown };
755
+ time: TimeBlock & { spans?: number[][] };
756
+ issue: { id: string | null; all: string[]; mentioned: string[]; source?: string | null };
757
+ /** `parentSha` values `bkit workflows close` printed in the chat — exact join to the run's rows. */
758
+ run: { parentShas: string[] };
759
+ scan: { files: number; bytes: number; settled: boolean; tokensRecorded?: boolean };
760
+ [field: string]: unknown;
761
+ }
762
+
763
+ // run — one workflow run, read from its run log (`docs/plans/<YYYYMM>/logs/<FID>/status.jsonl`)
764
+ // by `scripts/harvest/bkit-harvest.mjs`; keyed by explicit `key` (`<fid fp>:<workflow>:<start>`).
765
+ // A run whose log grew is a same-`key` append; last row wins.
766
+ export interface RunPayload {
767
+ key: string;
768
+ run: {
769
+ fid: string;
770
+ issue: string | null;
771
+ n: number;
772
+ /** The close step's `parentSha` — exact join to the run's outcome / counter / compliance rows. */
773
+ parentSha: string | null;
774
+ parentShas: string[];
775
+ };
776
+ time: TimeBlock;
777
+ ending: "done" | "close-failed" | "failed" | "decision-pause" | "stopped";
778
+ scan: { rows: number; afterEnd: number; settled: boolean };
779
+ [field: string]: unknown;
780
+ }
781
+
782
+ export const RUN_ENDINGS: Set<string> = new Set([
783
+ "done",
784
+ "close-failed",
785
+ "failed",
786
+ "decision-pause",
787
+ "stopped",
788
+ ]);
789
+
545
790
  // ---------------------------------------------------------------------------
546
791
  // Discriminated union event type
547
792
  // ---------------------------------------------------------------------------
@@ -557,6 +802,8 @@ export type TelemetryEvent = TelemetryEnvelope &
557
802
  | ({ kind: "knowledge" } & KnowledgePayload)
558
803
  | ({ kind: "decision" } & DecisionPayload)
559
804
  | ({ kind: "feature" } & FeaturePayload)
805
+ | ({ kind: "chat" } & ChatPayload)
806
+ | ({ kind: "run" } & RunPayload)
560
807
  );
561
808
 
562
809
  // ---------------------------------------------------------------------------
@@ -565,30 +812,662 @@ export type TelemetryEvent = TelemetryEnvelope &
565
812
  // ---------------------------------------------------------------------------
566
813
 
567
814
  export function identity(event: TelemetryEvent): string {
815
+ const workflow = event.by?.workflow;
568
816
  switch (event.kind) {
569
817
  case "compliance":
570
- return `compliance ${event.repo} ${event.workflow} ${event.parentSha} ${event.rule}`;
818
+ return `compliance ${event.repo} ${workflow} ${event.run?.parentSha} ${event.rule?.id}`;
571
819
  case "outcome": {
572
- // One run row per workflow run: keyed by (repo, workflow, parentSha).
573
- // A ship row with no parentSha falls back to prNumber (then ts), so it stays
820
+ // One run row per workflow run: keyed by (repo, workflow, run.parentSha).
821
+ // A ship row with no parentSha falls back to run.pr (then ts), so it stays
574
822
  // uniquely keyed per PR.
575
823
  const anchor =
576
- event.parentSha ?? (event.prNumber !== undefined ? `pr${event.prNumber}` : `ts${event.ts}`);
577
- return `outcome ${event.repo} ${event.workflow} ${anchor}`;
824
+ event.run?.parentSha ??
825
+ (event.run?.pr !== undefined ? `pr${event.run.pr}` : `ts${event.ts}`);
826
+ return `outcome ${event.repo} ${workflow} ${anchor}`;
578
827
  }
579
828
  case "counter":
580
- return `counter ${event.repo} ${event.workflow} ${event.parentSha} ${event.counterName}`;
829
+ return `counter ${event.repo} ${workflow} ${event.run?.parentSha} ${event.counter?.name}`;
581
830
  case "friction":
582
831
  case "deferral":
583
832
  case "failure":
584
833
  case "knowledge":
585
834
  case "decision":
586
835
  case "feature":
587
- // instinct-loop kinds (+ feature): identity = kind + key
836
+ case "chat":
837
+ case "run":
838
+ // keyed kinds: identity = kind + key
588
839
  return `${event.kind} ${event.repo} ${event.key ?? event.ts}`;
589
840
  }
590
841
  }
591
842
 
843
+ // ---------------------------------------------------------------------------
844
+ // Normalize — read a row written without `schema` in the schema-2 shape
845
+ // ---------------------------------------------------------------------------
846
+
847
+ type Obj = Record<string, unknown>;
848
+ const isObj = (v: unknown): v is Obj => v !== null && typeof v === "object" && !Array.isArray(v);
849
+ /** `o` without its undefined fields, so an absent value stays absent. */
850
+ const defined = (o: Obj): Obj =>
851
+ Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
852
+ const tenthOf = (n: number): number => Math.round(n * 10) / 10;
853
+
854
+ /** Fields of a row written without `schema` that the current shape moves or drops, per kind. */
855
+ const MOVED: Record<string, readonly string[]> = {
856
+ compliance: ["rule", "result", "evidence", "phase"],
857
+ counter: ["counterName", "counterValue", "counterSource", "phase"],
858
+ outcome: [
859
+ "phase",
860
+ "prNumber",
861
+ "linesAdded",
862
+ "linesDeleted",
863
+ "linesChanged",
864
+ "filesChanged",
865
+ "taskCount",
866
+ "durationSeconds",
867
+ "ciTrySuccess",
868
+ "correctiveCommits",
869
+ "reviewIterations",
870
+ "deferrals",
871
+ "failures",
872
+ "frictionAdded",
873
+ "deferralsAdded",
874
+ "failuresAdded",
875
+ "planSource",
876
+ "coverage",
877
+ "redTests",
878
+ ],
879
+ };
880
+ const TOP_MOVED = ["schema", "bkitVersion", "workflow", "step", "subagent", "model", "parentSha"];
881
+
882
+ /**
883
+ * A row in a `schema` shape. A row that carries `schema` is returned as it is; a
884
+ * row written without one is stamped `schema: 2` and has its top section (`bkitVersion` -> `bkit.version`,
885
+ * `workflow` / `step` / `subagent` / `model` -> `by.*`) and the stats kinds' run
886
+ * fields moved into their blocks as far as the row holds them. Fields with no
887
+ * place in the schema-2 shape are dropped, and any kind's `parentSha` moves to
888
+ * `run.parentSha`. `bkit install` / `bkit upgrade` rewrite old rows through it
889
+ * (`./migrate.ts`); readers still call it, as a union merge can bring an old line back.
890
+ */
891
+ export function normalize(raw: unknown): Obj {
892
+ if (!isObj(raw)) return {};
893
+ if (raw["schema"] !== undefined) return raw;
894
+ const kind = String(raw["kind"]);
895
+ const moved = new Set([...TOP_MOVED, ...(MOVED[kind] ?? [])]);
896
+ const rest = Object.fromEntries(Object.entries(raw).filter(([k]) => !moved.has(k)));
897
+ const { ts, kind: _kind, key, repo, references, ...payload } = rest;
898
+ const out: Obj = defined({
899
+ schema: NORMALIZED_SCHEMA,
900
+ ts,
901
+ kind: raw["kind"],
902
+ key,
903
+ repo,
904
+ // "none": the harvest script found no bkit version for the row.
905
+ bkit: {
906
+ version:
907
+ raw["bkitVersion"] === undefined || raw["bkitVersion"] === "none"
908
+ ? null
909
+ : raw["bkitVersion"],
910
+ },
911
+ // An old row's null or empty `workflow` / `subagent` / `model` meant "none": left out.
912
+ by: Object.fromEntries(
913
+ ["workflow", "step", "subagent", "model"]
914
+ .map((f) => [f, raw[f]] as const)
915
+ .filter(([, v]) => v !== undefined && v !== null && v !== ""),
916
+ ),
917
+ references,
918
+ });
919
+ const num = (f: string): number | undefined =>
920
+ typeof raw[f] === "number" ? (raw[f] as number) : undefined;
921
+ switch (kind) {
922
+ case "compliance":
923
+ out["run"] = { parentSha: raw["parentSha"] };
924
+ out["rule"] = defined({ id: raw["rule"], verdict: raw["result"], evidence: raw["evidence"] });
925
+ break;
926
+ case "counter":
927
+ out["run"] = { parentSha: raw["parentSha"] };
928
+ out["counter"] = {
929
+ name: raw["counterName"],
930
+ value: raw["counterValue"],
931
+ source: raw["counterSource"],
932
+ };
933
+ break;
934
+ case "outcome": {
935
+ out["run"] = defined({ parentSha: raw["parentSha"], pr: raw["prNumber"] });
936
+ const seconds = num("durationSeconds");
937
+ if (seconds !== undefined) out["time"] = { totalMinutes: tenthOf(seconds / 60) };
938
+ const added = num("linesAdded");
939
+ const deleted = num("linesDeleted");
940
+ if (added !== undefined && deleted !== undefined) {
941
+ out["lines"] = {
942
+ total: { added, deleted, changed: added + deleted, files: num("filesChanged") ?? 0 },
943
+ };
944
+ }
945
+ out["ledgers"] = {
946
+ deferrals: defined({ repo: num("deferrals"), added: num("deferralsAdded") }),
947
+ failures: defined({ repo: num("failures"), added: num("failuresAdded") }),
948
+ friction: defined({ added: num("frictionAdded") }),
949
+ };
950
+ if (raw["planSource"] === "brief") out["plan"] = { source: "brief" };
951
+ if (isObj(raw["coverage"])) out["ship"] = { coverage: raw["coverage"] };
952
+ if (num("redTests") !== undefined) out["build"] = { redTests: num("redTests") };
953
+ break;
954
+ }
955
+ case "chat":
956
+ return { ...out, ...oldChat(raw) };
957
+ case "run":
958
+ return {
959
+ ...out,
960
+ by: defined({ workflow: raw["workflow"], step: raw["step"] ?? "scan" }),
961
+ ...oldRun(raw),
962
+ };
963
+ }
964
+ const run =
965
+ out["run"] ?? (raw["parentSha"] !== undefined ? { parentSha: raw["parentSha"] } : undefined);
966
+ return { ...out, ...payload, ...defined({ run }) };
967
+ }
968
+
969
+ // The harvest script's own kinds, mapped in full: every schema-1 field has a
970
+ // place in the current shape or is dropped. `scripts/harvest/bkit-harvest.mjs`
971
+ // `normalize` maps them the same way.
972
+
973
+ const objOf = (v: unknown): Obj => (isObj(v) ? v : {});
974
+ const numOr = (v: unknown, or: number | null = 0): number | null =>
975
+ typeof v === "number" ? v : or;
976
+ const arrOf = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
977
+ const TOKENS = ["input", "cacheWrite", "cacheRead", "output", "outputEst", "read"] as const;
978
+ const oldTokens = (t: unknown) => Object.fromEntries(TOKENS.map((k) => [k, numOr(objOf(t)[k])]));
979
+ const oldMix = (m: unknown): Obj | undefined => {
980
+ if (!isObj(m)) return undefined;
981
+ return {
982
+ read: numOr(m["read"]),
983
+ edit: numOr(m["edit"]),
984
+ grep: numOr(m["grep"]),
985
+ shellRead: numOr(m["sedCat"]),
986
+ shellList: numOr(m["findLs"]),
987
+ tests: numOr(m["tests"]),
988
+ serena: numOr(m["serena"]),
989
+ };
990
+ };
991
+ const sumNums = (xs: unknown[]) =>
992
+ xs.reduce<number>((a, x) => a + (typeof x === "number" ? x : 0), 0);
993
+ /** Shell tools by host: the tool a schema-1 chat row's per-chat shell categories move under. */
994
+ const OLD_SHELL_TOOLS = [
995
+ "Bash",
996
+ "bash",
997
+ "Shell",
998
+ "shell",
999
+ "shell_command",
1000
+ "local_shell",
1001
+ "exec_command",
1002
+ "run_command",
1003
+ "run_terminal_cmd",
1004
+ ];
1005
+
1006
+ function oldChat(r: Obj): Obj {
1007
+ const byAgent: Obj = {};
1008
+ for (const [type, av] of Object.entries(objOf(r["agents"]))) {
1009
+ const a = objOf(av);
1010
+ const peaks = arrOf(a["ctxPeaks"]).filter((p): p is number => typeof p === "number");
1011
+ const n = numOr(a["n"], peaks.length) as number;
1012
+ byAgent[type] = defined({
1013
+ n,
1014
+ errors: numOr(a["errors"]),
1015
+ // Per-instance turns were stored only as a sum: known when the type ran once.
1016
+ instances: peaks.map((p) => ({
1017
+ turns: n === 1 ? numOr(a["turns"], null) : null,
1018
+ contextPeak: p,
1019
+ })),
1020
+ usage: {
1021
+ turns: numOr(a["turns"]),
1022
+ tokens: oldTokens(a),
1023
+ context: { peak: numOr(a["ctxPeakMax"], Math.max(0, ...peaks)) },
1024
+ compactions: numOr(a["compactions"]),
1025
+ },
1026
+ mix: oldMix(a["mix"]),
1027
+ });
1028
+ }
1029
+ const byTool: Record<string, Obj> = {};
1030
+ for (const [k, tv] of Object.entries(objOf(r["tools"]))) {
1031
+ const t = objOf(tv);
1032
+ byTool[k] = { calls: numOr(t["calls"]), errors: numOr(t["errors"]) };
1033
+ }
1034
+ const shellTool = OLD_SHELL_TOOLS.find((k) => byTool[k] !== undefined);
1035
+ const bash = objOf(r["bash"]);
1036
+ if (shellTool !== undefined && Object.keys(bash).length > 0)
1037
+ byTool[shellTool]!["byCategory"] = { ...bash };
1038
+ const byModel = Object.fromEntries(
1039
+ Object.entries(objOf(r["models"])).map(([k, m]) => [
1040
+ k,
1041
+ { turns: numOr(objOf(m)["turns"]), tokens: oldTokens(m) },
1042
+ ]),
1043
+ );
1044
+ const m = objOf(r["main"]);
1045
+ const tokens = objOf(r["tokens"]);
1046
+ const byVerb = objOf(r["bkitCli"]);
1047
+ const agents = Object.values(byAgent).map(objOf);
1048
+ const tools = Object.values(byTool);
1049
+ const start = r["start"];
1050
+ const end = r["end"];
1051
+ return {
1052
+ by: defined({ workflow: r["workflow"] ?? "chat-stats", step: r["step"] ?? "scan" }),
1053
+ bkit: {
1054
+ version:
1055
+ r["bkitVersion"] === undefined || r["bkitVersion"] === "none" ? null : r["bkitVersion"],
1056
+ versionSource: r["bkitVersionSource"] ?? "none",
1057
+ via: arrOf(r["bkitVia"]),
1058
+ workflows: arrOf(r["bkitWorkflows"]),
1059
+ prompts: arrOf(r["bkitKinds"]),
1060
+ cli: { total: sumNums(Object.values(byVerb)), byVerb },
1061
+ },
1062
+ session: {
1063
+ platform: r["platform"] ?? "claude-code",
1064
+ id: r["sessionId"] ?? null,
1065
+ hostVersion: r["hostVersion"] ?? null,
1066
+ entrypoint: r["entrypoint"] ?? null,
1067
+ prompts: numOr(r["userPrompts"]),
1068
+ },
1069
+ time: defined({
1070
+ start: start ?? null,
1071
+ end: end ?? null,
1072
+ totalMinutes:
1073
+ typeof r["minutes"] === "number"
1074
+ ? r["minutes"]
1075
+ : typeof start === "number" && typeof end === "number"
1076
+ ? tenthOf((end - start) / 60000)
1077
+ : null,
1078
+ activeMinutes: numOr(r["activeMinutes"], null),
1079
+ spans: arrOf(r["active"]),
1080
+ lastActivity: r["lastActivityAt"],
1081
+ }),
1082
+ issue: {
1083
+ id: r["issue"] ?? null,
1084
+ all: arrOf(r["issues"]),
1085
+ mentioned: arrOf(r["mentioned"]),
1086
+ source: r["issueSource"] ?? "none",
1087
+ },
1088
+ run: { parentShas: arrOf(r["parentShas"]) },
1089
+ effort: objOf(r["effort"]),
1090
+ usage: {
1091
+ total: {
1092
+ turns: numOr(r["turns"]),
1093
+ // Summed from the models, as a fresh scan writes it: the old row's own total
1094
+ // estimated output once over the whole chat, so it can differ from its parts.
1095
+ tokens:
1096
+ Object.keys(byModel).length > 0
1097
+ ? Object.fromEntries(
1098
+ TOKENS.map((k) => [k, sumNums(Object.values(byModel).map((x) => x.tokens[k]))]),
1099
+ )
1100
+ : oldTokens(tokens),
1101
+ context: { start: numOr(tokens["ctxStart"]), peak: numOr(tokens["ctxPeak"]) },
1102
+ compactions: numOr(r["compactions"]),
1103
+ },
1104
+ main: defined({
1105
+ turns: numOr(m["turns"]),
1106
+ tokens: oldTokens(m),
1107
+ context: { peak: numOr(m["ctxPeak"]) },
1108
+ compactions: numOr(m["compactions"]),
1109
+ mix: oldMix(m["mix"]),
1110
+ }),
1111
+ byModel,
1112
+ },
1113
+ agents: {
1114
+ total: {
1115
+ n: numOr(r["subagents"], sumNums(agents.map((a) => a["n"]))),
1116
+ errors: sumNums(agents.map((a) => a["errors"])),
1117
+ },
1118
+ byAgent,
1119
+ },
1120
+ tools: {
1121
+ total: {
1122
+ calls: sumNums(tools.map((t) => t["calls"])),
1123
+ errors: sumNums(tools.map((t) => t["errors"])),
1124
+ },
1125
+ byTool,
1126
+ filesRead: numOr(r["filesRead"]),
1127
+ },
1128
+ scan: defined({
1129
+ files: r["sourceFiles"],
1130
+ bytes: r["sourceBytes"],
1131
+ settled: r["settled"],
1132
+ tokensRecorded: r["tokensRecorded"],
1133
+ }),
1134
+ };
1135
+ }
1136
+
1137
+ /** A schema-1 run row's plan: its per-task lists, grouped when unsplit. */
1138
+ function oldPlan(p: Obj): Obj {
1139
+ const n = numOr(p["subPlans"], 1) as number;
1140
+ const tests = arrOf(p["testsPerTask"]);
1141
+ const files = arrOf(p["testFilesPerTask"]);
1142
+ const tasks = numOr(p["tasks"], tests.length) as number;
1143
+ const kb = numOr(p["kb"]);
1144
+ const out: Obj = { source: "file", total: { tasks, kb } };
1145
+ out["subPlans"] =
1146
+ n === 1
1147
+ ? [
1148
+ {
1149
+ kb,
1150
+ tasks: Array.from({ length: tasks }, (_, i) => ({
1151
+ tests: numOr(tests[i], null),
1152
+ testFiles: numOr(files[i], null),
1153
+ })),
1154
+ },
1155
+ ]
1156
+ : // A split plan's per-task lists were stored flat: which sub-plan each task was in is not known.
1157
+ Array.from({ length: n }, () => ({ kb: null, tasks: null }));
1158
+ if (isObj(p["complexity"])) out["complexity"] = p["complexity"];
1159
+ return out;
1160
+ }
1161
+
1162
+ function oldRun(r: Obj): Obj {
1163
+ const steps = Object.entries(objOf(r["steps"])).map(([k, v]) => [k, objOf(v)] as const);
1164
+ const byStep = Object.fromEntries(
1165
+ steps.map(([k, st]) => [
1166
+ k,
1167
+ {
1168
+ n: numOr(st["n"]),
1169
+ totalMinutes: numOr(st["minutes"]),
1170
+ activeMinutes: numOr(st["active"], null),
1171
+ },
1172
+ ]),
1173
+ );
1174
+ const parts = steps.map(([, st]) => st);
1175
+ const isBuild =
1176
+ r["workflow"] === "build" ||
1177
+ ["verify", "gapsRemediate", "holistic", "challenge", "redTests"].some((k) => k in r);
1178
+ const ch = isObj(r["challenge"]) ? r["challenge"] : undefined;
1179
+ const f = isObj(ch?.["findings"]) ? (ch!["findings"] as Obj) : undefined;
1180
+ const lines = objOf(r["lines"]);
1181
+ const lineParts = ["code", "tests", "docs"].map((k) => objOf(lines[k]));
1182
+ const linesOut =
1183
+ isObj(r["lines"]) && isObj(lines["code"])
1184
+ ? (() => {
1185
+ const added = sumNums(lineParts.map((p) => p["added"]));
1186
+ const deleted = sumNums(lineParts.map((p) => p["deleted"]));
1187
+ return {
1188
+ total: {
1189
+ added,
1190
+ deleted,
1191
+ changed: added + deleted,
1192
+ files: sumNums(lineParts.map((p) => p["files"])),
1193
+ },
1194
+ code: lines["code"],
1195
+ tests: lines["tests"],
1196
+ docs: lines["docs"],
1197
+ merges: lines["merges"],
1198
+ };
1199
+ })()
1200
+ : r["lines"];
1201
+ return defined({
1202
+ run: {
1203
+ fid: r["fid"] ?? null,
1204
+ issue: r["issue"] ?? null,
1205
+ n: numOr(r["run"], null),
1206
+ parentSha: r["parentSha"] ?? null,
1207
+ parentShas: arrOf(r["parentShas"]),
1208
+ },
1209
+ time: defined({
1210
+ start: r["start"] ?? null,
1211
+ end: r["end"] ?? null,
1212
+ totalMinutes: numOr(r["minutes"], null),
1213
+ activeMinutes: numOr(r["activeMinutes"], null),
1214
+ activeFrom: r["activeFrom"] ?? null,
1215
+ lastActivity: r["lastActivityAt"],
1216
+ }),
1217
+ ending: r["ending"],
1218
+ ci: arrOf(r["closeCi"]).map((cv) => {
1219
+ const c = objOf(cv);
1220
+ return defined({
1221
+ status: c["outcome"] ?? null,
1222
+ reason: c["reason"] ?? undefined,
1223
+ attempts: numOr(c["attempts"], null),
1224
+ });
1225
+ }),
1226
+ steps: {
1227
+ total: {
1228
+ n: sumNums(parts.map((st) => st["n"])),
1229
+ totalMinutes: tenthOf(sumNums(parts.map((st) => st["minutes"]))),
1230
+ activeMinutes: parts.some((st) => typeof st["active"] !== "number")
1231
+ ? null
1232
+ : tenthOf(sumNums(parts.map((st) => st["active"]))),
1233
+ },
1234
+ byStep,
1235
+ },
1236
+ lines: linesOut,
1237
+ plan: isObj(r["plan"]) ? oldPlan(r["plan"]) : r["plan"],
1238
+ build: isBuild
1239
+ ? defined({
1240
+ verify: arrOf(r["verify"]),
1241
+ gapsRemediate: arrOf(r["gapsRemediate"]),
1242
+ holistic: r["holistic"] ?? undefined,
1243
+ challenge: ch
1244
+ ? {
1245
+ verdict: ch["verdict"] ?? null,
1246
+ findings: f ? { total: sumNums(Object.values(f)), ...f } : null,
1247
+ }
1248
+ : undefined,
1249
+ redTests: numOr(r["redTests"]),
1250
+ })
1251
+ : undefined,
1252
+ scan: defined({ rows: r["sourceRows"], afterEnd: r["afterEnd"], settled: r["settled"] }),
1253
+ });
1254
+ }
1255
+
1256
+ /** `normalize` typed for readers: every row a fold or report sees. */
1257
+ export const normalizeEvent = (raw: unknown): TelemetryEvent => normalize(raw) as TelemetryEvent;
1258
+
1259
+ // ---------------------------------------------------------------------------
1260
+ // Totals — every total beside its parts must equal them
1261
+ // ---------------------------------------------------------------------------
1262
+
1263
+ const sumOf = (xs: unknown[]): number =>
1264
+ xs.reduce<number>((a, x) => a + (typeof x === "number" ? x : 0), 0);
1265
+ const field = (o: unknown, ...pathTo: string[]): unknown =>
1266
+ pathTo.reduce<unknown>((v, k) => (isObj(v) ? v[k] : undefined), o);
1267
+ const TOKEN_FIELDS = ["input", "cacheWrite", "cacheRead", "output", "outputEst", "read"] as const;
1268
+
1269
+ /**
1270
+ * The first total on `row` that does not equal its parts, or undefined. Only blocks
1271
+ * the row carries are checked. Minute totals are summed from unrounded values, so
1272
+ * each part may be off by its rounding: +-0.1 per part.
1273
+ */
1274
+ export function totalsProblem(row: Obj): string | undefined {
1275
+ const eq = (what: string, total: unknown, parts: number, tol = 0): string | undefined =>
1276
+ typeof total === "number" && Math.abs(total - parts) <= tol + 1e-9
1277
+ ? undefined
1278
+ : `${what} is ${String(total)}, its parts sum to ${tenthOf(parts)}`;
1279
+ const checks: Array<() => string | undefined> = [];
1280
+
1281
+ const lines = row["lines"];
1282
+ if (isObj(lines) && isObj(lines["total"])) {
1283
+ const t = lines["total"];
1284
+ checks.push(() => eq("lines.total.changed", t["changed"], sumOf([t["added"], t["deleted"]])));
1285
+ if (["code", "tests", "docs"].some((p) => isObj(lines[p]))) {
1286
+ for (const f of ["added", "deleted", "files"]) {
1287
+ checks.push(() =>
1288
+ eq(
1289
+ `lines.total.${f}`,
1290
+ t[f],
1291
+ sumOf(["code", "tests", "docs"].map((p) => field(lines, p, f))),
1292
+ ),
1293
+ );
1294
+ }
1295
+ }
1296
+ }
1297
+
1298
+ const time = row["time"];
1299
+ if (isObj(time) && typeof time["start"] === "number" && typeof time["end"] === "number") {
1300
+ checks.push(() =>
1301
+ eq(
1302
+ "time.totalMinutes",
1303
+ time["totalMinutes"],
1304
+ ((time["end"] as number) - (time["start"] as number)) / 60000,
1305
+ 0.1,
1306
+ ),
1307
+ );
1308
+ const spans = time["spans"];
1309
+ if (
1310
+ row["kind"] === "chat" &&
1311
+ Array.isArray(spans) &&
1312
+ typeof time["activeMinutes"] === "number"
1313
+ ) {
1314
+ const ms = sumOf(spans.map((s) => (Array.isArray(s) ? Number(s[1]) - Number(s[0]) : 0)));
1315
+ checks.push(() => eq("time.activeMinutes", time["activeMinutes"], ms / 60000, 0.1));
1316
+ }
1317
+ }
1318
+
1319
+ const steps = row["steps"];
1320
+ if (isObj(steps) && isObj(steps["byStep"]) && isObj(steps["total"])) {
1321
+ const parts = Object.values(steps["byStep"]);
1322
+ for (const f of ["n", "totalMinutes", "activeMinutes"]) {
1323
+ const total = steps["total"][f];
1324
+ if (total === undefined || total === null) continue;
1325
+ const tol = f === "n" ? 0 : 0.1 * Math.max(1, parts.length);
1326
+ checks.push(() => eq(`steps.total.${f}`, total, sumOf(parts.map((p) => field(p, f))), tol));
1327
+ }
1328
+ }
1329
+
1330
+ const plan = row["plan"];
1331
+ if (isObj(plan) && isObj(plan["total"]) && Array.isArray(plan["groups"])) {
1332
+ const groups = plan["groups"];
1333
+ const total = plan["total"];
1334
+ checks.push(() =>
1335
+ eq(
1336
+ "plan.total.tasks",
1337
+ total["tasks"],
1338
+ sumOf(groups.map((g) => arrOf(field(g, "tasks")).length)),
1339
+ ),
1340
+ );
1341
+ }
1342
+
1343
+ const build = row["build"];
1344
+ if (isObj(build)) {
1345
+ const findings = field(build, "challenge", "findings");
1346
+ if (isObj(findings)) {
1347
+ checks.push(() =>
1348
+ eq(
1349
+ "build.challenge.findings.total",
1350
+ findings["total"],
1351
+ sumOf(["CRITICAL", "HIGH", "MEDIUM", "LOW"].map((s) => findings[s])),
1352
+ ),
1353
+ );
1354
+ }
1355
+ if (typeof build["redTests"] === "number" && isObj(field(steps, "byStep"))) {
1356
+ checks.push(() =>
1357
+ eq(
1358
+ "build.redTests",
1359
+ build["redTests"],
1360
+ Number(field(steps, "byStep", "build-task-red", "n") ?? 0),
1361
+ ),
1362
+ );
1363
+ }
1364
+ }
1365
+
1366
+ const usage = row["usage"];
1367
+ const agents = row["agents"];
1368
+ const byAgent = isObj(agents) && isObj(agents["byAgent"]) ? Object.values(agents["byAgent"]) : [];
1369
+ if (isObj(usage)) {
1370
+ const blocks: Array<[string, unknown]> = [
1371
+ ["usage.total", usage["total"]],
1372
+ ["usage.main", usage["main"]],
1373
+ ...Object.entries(isObj(usage["byModel"]) ? usage["byModel"] : {}).map(
1374
+ ([m, u]): [string, unknown] => [`usage.byModel.${m}`, u],
1375
+ ),
1376
+ ...Object.entries(isObj(agents) && isObj(agents["byAgent"]) ? agents["byAgent"] : {}).map(
1377
+ ([a, v]): [string, unknown] => [`agents.byAgent.${a}.usage`, field(v, "usage")],
1378
+ ),
1379
+ ];
1380
+ for (const [name, u] of blocks) {
1381
+ const tokens = field(u, "tokens");
1382
+ if (!isObj(tokens) || tokens["read"] === undefined) continue;
1383
+ checks.push(() =>
1384
+ eq(
1385
+ `${name}.tokens.read`,
1386
+ tokens["read"],
1387
+ sumOf([tokens["input"], tokens["cacheWrite"], tokens["cacheRead"]]),
1388
+ ),
1389
+ );
1390
+ }
1391
+ const total = usage["total"];
1392
+ const models = isObj(usage["byModel"]) ? Object.values(usage["byModel"]) : [];
1393
+ if (isObj(total) && models.length > 0) {
1394
+ checks.push(() =>
1395
+ eq("usage.total.turns", total["turns"], sumOf(models.map((m) => field(m, "turns")))),
1396
+ );
1397
+ for (const f of TOKEN_FIELDS) {
1398
+ if (field(total, "tokens", f) === undefined) continue;
1399
+ checks.push(() =>
1400
+ eq(
1401
+ `usage.total.tokens.${f}`,
1402
+ field(total, "tokens", f),
1403
+ sumOf(models.map((m) => field(m, "tokens", f))),
1404
+ ),
1405
+ );
1406
+ }
1407
+ }
1408
+ if (isObj(total) && total["compactions"] !== undefined) {
1409
+ checks.push(() =>
1410
+ eq(
1411
+ "usage.total.compactions",
1412
+ total["compactions"],
1413
+ sumOf([
1414
+ field(usage, "main", "compactions"),
1415
+ ...byAgent.map((a) => field(a, "usage", "compactions")),
1416
+ ]),
1417
+ ),
1418
+ );
1419
+ }
1420
+ const peak = field(total, "context", "peak");
1421
+ if (typeof peak === "number") {
1422
+ const peaks = [
1423
+ field(usage, "main", "context", "peak"),
1424
+ ...byAgent.flatMap((a) =>
1425
+ Array.isArray(field(a, "instances"))
1426
+ ? (field(a, "instances") as unknown[]).map((i) => field(i, "contextPeak"))
1427
+ : [],
1428
+ ),
1429
+ ].filter((v): v is number => typeof v === "number");
1430
+ if (peaks.length > 0)
1431
+ checks.push(() => eq("usage.total.context.peak", peak, Math.max(...peaks)));
1432
+ }
1433
+ }
1434
+ if (isObj(agents) && isObj(agents["total"]) && isObj(agents["byAgent"])) {
1435
+ const total = agents["total"];
1436
+ for (const f of ["n", "errors"]) {
1437
+ checks.push(() => eq(`agents.total.${f}`, total[f], sumOf(byAgent.map((a) => field(a, f)))));
1438
+ }
1439
+ for (const [name, a] of Object.entries(agents["byAgent"])) {
1440
+ const instances = field(a, "instances");
1441
+ if (Array.isArray(instances)) {
1442
+ checks.push(() => eq(`agents.byAgent.${name}.n`, field(a, "n"), instances.length));
1443
+ }
1444
+ }
1445
+ }
1446
+
1447
+ const tools = row["tools"];
1448
+ if (isObj(tools) && isObj(tools["total"]) && isObj(tools["byTool"])) {
1449
+ const parts = Object.values(tools["byTool"]);
1450
+ for (const f of ["calls", "errors"]) {
1451
+ checks.push(() =>
1452
+ eq(`tools.total.${f}`, field(tools, "total", f), sumOf(parts.map((p) => field(p, f)))),
1453
+ );
1454
+ }
1455
+ }
1456
+
1457
+ const cli = field(row, "bkit", "cli");
1458
+ if (isObj(cli) && isObj(cli["byVerb"])) {
1459
+ checks.push(() =>
1460
+ eq("bkit.cli.total", cli["total"], sumOf(Object.values(cli["byVerb"] as Obj))),
1461
+ );
1462
+ }
1463
+
1464
+ for (const check of checks) {
1465
+ const problem = check();
1466
+ if (problem !== undefined) return problem;
1467
+ }
1468
+ return undefined;
1469
+ }
1470
+
592
1471
  // ---------------------------------------------------------------------------
593
1472
  // Validation result
594
1473
  // ---------------------------------------------------------------------------
@@ -608,13 +1487,19 @@ export function validate(event: unknown): ValidationResult {
608
1487
  }
609
1488
  const e = event as Record<string, unknown>;
610
1489
 
611
- // A2-mandatory envelope fields
612
- const mandatory: string[] = ["ts", "kind", "repo", "bkitVersion", "step"];
613
- for (const field of mandatory) {
1490
+ if (e["schema"] !== SCHEMA) {
1491
+ return { ok: false, reason: `schema must be ${SCHEMA} (got: ${String(e["schema"])})` };
1492
+ }
1493
+ for (const field of ["ts", "kind", "repo", "bkit", "by"]) {
614
1494
  if (e[field] === undefined || e[field] === null) {
615
1495
  return { ok: false, reason: `missing mandatory field: ${field}` };
616
1496
  }
617
1497
  }
1498
+ for (const flat of ["bkitVersion", "workflow", "step", "subagent", "model"]) {
1499
+ if (e[flat] !== undefined) {
1500
+ return { ok: false, reason: `${flat} is not a top-level field (bkit.version, by.*)` };
1501
+ }
1502
+ }
618
1503
 
619
1504
  if (typeof e["ts"] !== "number") {
620
1505
  return { ok: false, reason: "ts must be a number (ms unix)" };
@@ -628,11 +1513,37 @@ export function validate(event: unknown): ValidationResult {
628
1513
  if (typeof e["repo"] !== "string" || e["repo"] === "") {
629
1514
  return { ok: false, reason: "repo must be a non-empty string" };
630
1515
  }
631
- if (typeof e["bkitVersion"] !== "string" || e["bkitVersion"] === "") {
632
- return { ok: false, reason: "bkitVersion must be a non-empty string" };
1516
+ const bkit = e["bkit"];
1517
+ // null on chat / run rows: the script found no bkit version in the repo's history at that time.
1518
+ const unknownVersion =
1519
+ bkit !== undefined &&
1520
+ isObj(bkit) &&
1521
+ bkit["version"] === null &&
1522
+ (e["kind"] === "chat" || e["kind"] === "run");
1523
+ if (
1524
+ !isObj(bkit) ||
1525
+ ((typeof bkit["version"] !== "string" || bkit["version"] === "") && !unknownVersion)
1526
+ ) {
1527
+ return {
1528
+ ok: false,
1529
+ reason: "bkit.version must be a non-empty string (null on chat / run rows)",
1530
+ };
1531
+ }
1532
+ const by = e["by"];
1533
+ if (!isObj(by)) return { ok: false, reason: "by must be an object" };
1534
+ if (typeof by["step"] !== "string" || by["step"] === "") {
1535
+ return { ok: false, reason: "by.step must be a non-empty string" };
1536
+ }
1537
+ for (const f of ["workflow", "subagent", "model"]) {
1538
+ if (by[f] !== undefined && (typeof by[f] !== "string" || by[f] === "")) {
1539
+ return { ok: false, reason: `by.${f} must be a non-empty string when present` };
1540
+ }
1541
+ }
1542
+ if (by["model"] !== undefined && by["subagent"] === undefined) {
1543
+ return { ok: false, reason: "by.model is set only on subagent rows" };
633
1544
  }
634
- if (typeof e["step"] !== "string" || e["step"] === "") {
635
- return { ok: false, reason: "step must be a non-empty string" };
1545
+ if (e["references"] !== undefined && !Array.isArray(e["references"])) {
1546
+ return { ok: false, reason: "references must be an array when present" };
636
1547
  }
637
1548
 
638
1549
  // kind-specific payload validation (minimal — structural check)
@@ -702,79 +1613,167 @@ export function validate(event: unknown): ValidationResult {
702
1613
  return { ok: false, reason: `${kind} rows do not carry reason` };
703
1614
  }
704
1615
 
1616
+ const run = isObj(e["run"]) ? e["run"] : undefined;
1617
+ if (kind === "compliance" || kind === "counter") {
1618
+ if (typeof run?.["parentSha"] !== "string" || run["parentSha"] === "") {
1619
+ return { ok: false, reason: `${kind} row missing run.parentSha` };
1620
+ }
1621
+ }
705
1622
  if (kind === "compliance") {
706
- if (!e["rule"] || !e["result"] || !e["phase"] || !e["parentSha"]) {
707
- return { ok: false, reason: "compliance row missing required payload fields" };
1623
+ const rule = e["rule"];
1624
+ if (!isObj(rule) || typeof rule["id"] !== "string" || rule["id"] === "") {
1625
+ return { ok: false, reason: "compliance row missing rule.id" };
1626
+ }
1627
+ if (!["pass", "fail", "n/a"].includes(rule["verdict"] as string)) {
1628
+ return {
1629
+ ok: false,
1630
+ reason: `compliance rule.verdict must be pass|fail|n/a (got: ${String(rule["verdict"])})`,
1631
+ };
1632
+ }
1633
+ }
1634
+ if (kind === "counter") {
1635
+ const c = e["counter"];
1636
+ if (
1637
+ !isObj(c) ||
1638
+ typeof c["name"] !== "string" ||
1639
+ c["name"] === "" ||
1640
+ typeof c["value"] !== "number"
1641
+ ) {
1642
+ return { ok: false, reason: "counter row needs counter.name and a numeric counter.value" };
1643
+ }
1644
+ if (c["source"] !== "model-self-report" && c["source"] !== "shell-bus") {
1645
+ return { ok: false, reason: "counter.source must be model-self-report or shell-bus" };
708
1646
  }
709
1647
  }
710
1648
  if (kind === "outcome") {
711
- // Every workflow run carries these; `prNumber` is ship-only (see below).
712
- const numFields = [
713
- "linesAdded",
714
- "linesDeleted",
715
- "linesChanged",
716
- "filesChanged",
717
- "taskCount",
718
- "durationSeconds",
719
- "deferrals",
720
- "failures",
721
- ];
722
- for (const f of numFields) {
723
- if (typeof e[f] !== "number") {
724
- return { ok: false, reason: `outcome missing or invalid numeric field: ${f}` };
725
- }
1649
+ if (run === undefined) return { ok: false, reason: "outcome row missing run" };
1650
+ if (run["parentSha"] !== undefined && typeof run["parentSha"] !== "string") {
1651
+ return { ok: false, reason: "outcome run.parentSha must be a string when present" };
1652
+ }
1653
+ if (run["pr"] !== undefined && typeof run["pr"] !== "number") {
1654
+ return { ok: false, reason: "outcome run.pr must be a number when present" };
1655
+ }
1656
+ const time = e["time"];
1657
+ // null: the run's start row is missing, so its time could not be measured.
1658
+ if (
1659
+ time !== null &&
1660
+ (!isObj(time) || ["start", "end", "totalMinutes"].some((f) => typeof time[f] !== "number"))
1661
+ ) {
1662
+ return {
1663
+ ok: false,
1664
+ reason: "outcome row needs time.start, time.end and time.totalMinutes, or time: null",
1665
+ };
726
1666
  }
727
- // prNumber — ship-only, optional; validate only when present.
728
- if (e["prNumber"] !== undefined && typeof e["prNumber"] !== "number") {
729
- return { ok: false, reason: "outcome prNumber must be a number when present" };
1667
+ if (!OUTCOME_ENDINGS.has(e["ending"] as string)) {
1668
+ return {
1669
+ ok: false,
1670
+ reason: `outcome ending must be done|close-failed (got: ${String(e["ending"])})`,
1671
+ };
730
1672
  }
731
- // parentSha — the run's identity anchor; optional (absent on some ship rows).
732
- if (e["parentSha"] !== undefined && typeof e["parentSha"] !== "string") {
733
- return { ok: false, reason: "outcome parentSha must be a string when present" };
1673
+ const ledgers = e["ledgers"];
1674
+ if (
1675
+ typeof field(ledgers, "deferrals", "repo") !== "number" ||
1676
+ typeof field(ledgers, "failures", "repo") !== "number"
1677
+ ) {
1678
+ return {
1679
+ ok: false,
1680
+ reason: "outcome row needs ledgers.deferrals.repo and ledgers.failures.repo",
1681
+ };
734
1682
  }
735
- // Optional per-run numeric metrics: validate type only when present.
736
- for (const f of [
737
- "frictionAdded",
738
- "deferralsAdded",
739
- "failuresAdded",
740
- "correctiveCommits",
741
- "reviewIterations",
742
- "ciTrySuccess",
743
- ]) {
744
- if (e[f] !== undefined && typeof e[f] !== "number") {
745
- return { ok: false, reason: `outcome ${f} must be a number when present` };
1683
+ for (const l of ["deferrals", "failures", "friction"]) {
1684
+ const added = field(ledgers, l, "added");
1685
+ if (added !== undefined && typeof added !== "number") {
1686
+ return { ok: false, reason: `outcome ledgers.${l}.added must be a number when present` };
746
1687
  }
747
1688
  }
748
- if (e["planSource"] !== undefined && e["planSource"] !== "brief") {
749
- return { ok: false, reason: 'outcome planSource must be "brief" when present' };
1689
+ const source = field(e["plan"], "source");
1690
+ if (e["plan"] !== undefined && source !== "file" && source !== "converted") {
1691
+ return {
1692
+ ok: false,
1693
+ reason: `outcome plan.source must be file|converted (got: ${String(source)})`,
1694
+ };
750
1695
  }
751
- // coverage is optional + per-tier; validate structure only when present.
752
- if (e["coverage"] !== undefined) {
753
- const cov = e["coverage"];
754
- if (typeof cov !== "object" || cov === null) {
755
- return { ok: false, reason: "outcome coverage must be an object" };
1696
+ const context = e["context"];
1697
+ if (context !== undefined) {
1698
+ const byAgent = field(context, "byAgent");
1699
+ if (!isObj(context) || typeof context["host"] !== "string" || !isObj(byAgent)) {
1700
+ return { ok: false, reason: "outcome context needs host and a byAgent object" };
756
1701
  }
1702
+ for (const [agent, a] of Object.entries(byAgent)) {
1703
+ if (typeof field(a, "peak") !== "number" || typeof field(a, "runs") !== "number") {
1704
+ return {
1705
+ ok: false,
1706
+ reason: `outcome context.byAgent.${agent} needs numeric peak and runs`,
1707
+ };
1708
+ }
1709
+ }
1710
+ }
1711
+ const cov = field(e["ship"], "coverage");
1712
+ if (cov !== undefined) {
1713
+ if (!isObj(cov)) return { ok: false, reason: "outcome ship.coverage must be an object" };
757
1714
  for (const tier of ["unit", "integration", "e2e"]) {
758
- const t = (cov as Record<string, unknown>)[tier];
1715
+ const t = cov[tier];
759
1716
  if (t === undefined) continue;
760
- if (typeof t !== "object" || t === null) {
761
- return { ok: false, reason: `outcome coverage.${tier} must be an object` };
762
- }
1717
+ if (!isObj(t))
1718
+ return { ok: false, reason: `outcome ship.coverage.${tier} must be an object` };
763
1719
  for (const m of ["lines", "branches", "functions", "statements"]) {
764
- const v = (t as Record<string, unknown>)[m];
765
- if (v !== undefined && typeof v !== "number") {
766
- return { ok: false, reason: `outcome coverage.${tier}.${m} must be a number` };
1720
+ if (t[m] !== undefined && typeof t[m] !== "number") {
1721
+ return { ok: false, reason: `outcome ship.coverage.${tier}.${m} must be a number` };
767
1722
  }
768
1723
  }
769
1724
  }
770
1725
  }
771
1726
  }
772
- if (kind === "counter") {
773
- if (!e["counterName"] || typeof e["counterValue"] !== "number" || !e["parentSha"]) {
774
- return { ok: false, reason: "counter row missing required payload fields" };
1727
+ if (kind === "chat") {
1728
+ if (!e["key"] || typeof e["key"] !== "string") {
1729
+ return { ok: false, reason: "chat row missing required field: key (<platform>:<sessionId>)" };
1730
+ }
1731
+ if (
1732
+ typeof field(e, "time", "start") !== "number" ||
1733
+ typeof field(e, "time", "end") !== "number"
1734
+ ) {
1735
+ return { ok: false, reason: "chat row needs time.start and time.end" };
775
1736
  }
776
- if (e["counterSource"] !== "model-self-report" && e["counterSource"] !== "shell-bus") {
777
- return { ok: false, reason: "counter counterSource must be model-self-report or shell-bus" };
1737
+ if (typeof field(e, "scan", "bytes") !== "number") {
1738
+ return { ok: false, reason: "chat row needs scan.bytes" };
1739
+ }
1740
+ if (!Array.isArray(field(e, "run", "parentShas")) || !Array.isArray(field(e, "issue", "all"))) {
1741
+ return {
1742
+ ok: false,
1743
+ reason: "chat row needs run.parentShas and issue.all arrays (the join keys)",
1744
+ };
1745
+ }
1746
+ }
1747
+ if (kind === "run") {
1748
+ if (!e["key"] || typeof e["key"] !== "string") {
1749
+ return {
1750
+ ok: false,
1751
+ reason: "run row missing required field: key (<fid fp>:<workflow>:<start>)",
1752
+ };
1753
+ }
1754
+ if (typeof run?.["fid"] !== "string" || run["fid"] === "") {
1755
+ return { ok: false, reason: "run row missing required field: run.fid" };
1756
+ }
1757
+ if (
1758
+ typeof field(e, "time", "start") !== "number" ||
1759
+ typeof field(e, "time", "end") !== "number"
1760
+ ) {
1761
+ return { ok: false, reason: "run row needs time.start and time.end" };
1762
+ }
1763
+ if (typeof field(e, "scan", "rows") !== "number") {
1764
+ return { ok: false, reason: "run row needs scan.rows" };
1765
+ }
1766
+ if (!RUN_ENDINGS.has(e["ending"] as string)) {
1767
+ return {
1768
+ ok: false,
1769
+ reason: `run ending must be one of ${[...RUN_ENDINGS].join("|")} (got: ${String(e["ending"])})`,
1770
+ };
1771
+ }
1772
+ if (run["parentSha"] !== null && typeof run["parentSha"] !== "string") {
1773
+ return { ok: false, reason: "run run.parentSha must be a string or null" };
1774
+ }
1775
+ if (!Array.isArray(run["parentShas"])) {
1776
+ return { ok: false, reason: "run row needs a run.parentShas array (the join keys)" };
778
1777
  }
779
1778
  }
780
1779
  if (kind === "feature") {
@@ -789,6 +1788,9 @@ export function validate(event: unknown): ValidationResult {
789
1788
  }
790
1789
  }
791
1790
 
1791
+ const totals = totalsProblem(e);
1792
+ if (totals !== undefined) return { ok: false, reason: `totals: ${totals}` };
1793
+
792
1794
  return { ok: true };
793
1795
  }
794
1796
 
@@ -805,7 +1807,8 @@ export interface ParseResult {
805
1807
  * Tolerant parse — per-line try/catch, skips + counts unparseable lines.
806
1808
  * NEVER throws.
807
1809
  *
808
- * No version gating — ALL well-formed rows are kept regardless of `bkitVersion`.
1810
+ * No version gating — ALL well-formed rows are kept as written, `schema` or not;
1811
+ * {@link fold} reads each through {@link normalize}.
809
1812
  */
810
1813
  export function parse(raw: string): ParseResult {
811
1814
  const result: ParseResult = {
@@ -853,13 +1856,13 @@ export function compareTs(a: { ts: unknown }, b: { ts: unknown }): number {
853
1856
  }
854
1857
 
855
1858
  /**
856
- * Fold events into a Map keyed by per-kind composite identity.
857
- * Later rows (higher ts) win for the same key — last-write-wins fold.
858
- * Mirrors ledgers/status.ts's dedupe approach but with per-kind composite tuples.
1859
+ * Fold events into a Map keyed by per-kind composite identity, each row in the
1860
+ * current shape ({@link normalize}). Later rows (higher ts) win for the same key —
1861
+ * last-write-wins fold.
859
1862
  */
860
1863
  export function fold(events: TelemetryEvent[]): FoldedState {
861
1864
  // Sort by ts ascending so later rows overwrite earlier ones
862
- const sorted = [...events].sort(compareTs);
1865
+ const sorted = events.map(normalizeEvent).sort(compareTs);
863
1866
  const state: FoldedState = new Map();
864
1867
  for (const event of sorted) {
865
1868
  const key = identity(event);
@@ -876,7 +1879,7 @@ export interface FoldFromResult {
876
1879
  state: FoldedState;
877
1880
  rowCount: number;
878
1881
  malformedLineCount: number;
879
- /** Row count per emitting `bkitVersion` — for triage of unexpected versions. */
1882
+ /** Row count per emitting `bkit.version` — for triage of unexpected versions. */
880
1883
  versionCounts: Record<string, number>;
881
1884
  maxRowsWarning: boolean;
882
1885
  }
@@ -895,8 +1898,9 @@ export function foldFrom(paths: string[]): FoldFromResult {
895
1898
  }
896
1899
 
897
1900
  const versionCounts: Record<string, number> = {};
898
- for (const e of allEvents) {
899
- const v = typeof e.bkitVersion === "string" && e.bkitVersion !== "" ? e.bkitVersion : "unknown";
1901
+ for (const e of allEvents.map(normalizeEvent)) {
1902
+ const version = e.bkit?.version;
1903
+ const v = typeof version === "string" && version !== "" ? version : "unknown";
900
1904
  versionCounts[v] = (versionCounts[v] ?? 0) + 1;
901
1905
  }
902
1906
 
@@ -1007,7 +2011,7 @@ export function workflowTelemetry(result: FoldFromResult, workflow?: string): Te
1007
2011
  // Folded ENTITY count per workflow (not raw lines) — an updated row folds to one.
1008
2012
  const workflowCounts: Record<string, number> = {};
1009
2013
  for (const ev of events) {
1010
- const w = ev.workflow || "unknown";
2014
+ const w = ev.by?.workflow || "unknown";
1011
2015
  workflowCounts[w] = (workflowCounts[w] ?? 0) + 1;
1012
2016
  }
1013
2017
 
@@ -1033,14 +2037,17 @@ export function workflowTelemetry(result: FoldFromResult, workflow?: string): Te
1033
2037
 
1034
2038
  // This workflow's run rows (generalized outcome), oldest → newest.
1035
2039
  const runs = events
1036
- .filter((e): e is OutcomeEvent => e.kind === "outcome" && e.workflow === workflow)
2040
+ .filter((e): e is OutcomeEvent => e.kind === "outcome" && e.by?.workflow === workflow)
1037
2041
  .sort(compareTs);
1038
2042
  const cur = runs.at(-1);
1039
- // Baseline only against runs of the same plan source — a brief run (no plan)
1040
- // has no tasks and a different shape, so mixing them skews every median.
2043
+ // Baseline only against runs of the same plan source — a converted run's plan was
2044
+ // written by the build from its input, so mixing it with file runs skews every median.
2045
+ // An old `brief` row (no plan file) counts as converted.
2046
+ const oldBrief = (r: OutcomeEvent | undefined) => r?.plan?.source === "brief";
2047
+ const converted = (r: OutcomeEvent | undefined) => r?.plan?.source === "converted" || oldBrief(r);
1041
2048
  const prev = runs
1042
2049
  .slice(0, -1)
1043
- .filter((r) => r.planSource === cur?.planSource)
2050
+ .filter((r) => converted(r) === converted(cur))
1044
2051
  .slice(-RUN_BASELINE_WINDOW);
1045
2052
 
1046
2053
  const repo = cur?.repo ?? events[0]?.repo ?? "unknown/repo";
@@ -1056,74 +2063,72 @@ export function workflowTelemetry(result: FoldFromResult, workflow?: string): Te
1056
2063
  if (cur) {
1057
2064
  // med·N: median of the previous runs that carry the field, `—` until there are
1058
2065
  // at least RUN_BASELINE_MIN of them (1–2 samples is noise, not a baseline).
1059
- const medCell = (key: keyof OutcomeEvent, fmt: (n: number) => string = String): string => {
1060
- const vals = prev.map((r) => r[key]).filter((v): v is number => typeof v === "number");
2066
+ const medCell = (
2067
+ get: (r: OutcomeEvent) => unknown,
2068
+ fmt: (n: number) => string = String,
2069
+ ): string => {
2070
+ const vals = prev.map(get).filter((v): v is number => typeof v === "number");
1061
2071
  if (vals.length < RUN_BASELINE_MIN) return "—";
1062
2072
  const m = median(vals);
1063
2073
  return m === null ? "—" : fmt(m);
1064
2074
  };
2075
+ const mins = (n: number) => `${n} (${humanizeDuration(n * 60)})`;
2076
+ const show = (
2077
+ label: string,
2078
+ get: (r: OutcomeEvent) => unknown,
2079
+ fmt?: (n: number) => string,
2080
+ ) => {
2081
+ const v = get(cur);
2082
+ if (typeof v === "number") row(label, fmt ? fmt(v) : String(v), medCell(get, fmt));
2083
+ };
1065
2084
 
1066
- // Core metrics — always shown.
1067
- row(
1068
- "durationSeconds",
1069
- `${cur.durationSeconds} (${humanizeDuration(cur.durationSeconds)})`,
1070
- medCell("durationSeconds", (n) => `${n} (${humanizeDuration(n)})`),
1071
- );
1072
- row(
1073
- "linesChanged",
1074
- `${cur.linesChanged} (+${cur.linesAdded}/-${cur.linesDeleted})`,
1075
- medCell("linesChanged"),
1076
- );
1077
- row("filesChanged", `${cur.filesChanged}`, medCell("filesChanged"));
1078
-
1079
- // Conditional metrics — shown only when this run carries them.
1080
- if (cur.planSource) row("planSource", cur.planSource, "—");
1081
- if (cur.taskCount > 0) row("taskCount", `${cur.taskCount}`, medCell("taskCount"));
1082
- if (typeof cur.reviewIterations === "number")
1083
- row("reviewIterations", `${cur.reviewIterations}`, medCell("reviewIterations"));
1084
- if (typeof cur.correctiveCommits === "number")
1085
- row("correctiveCommits", `${cur.correctiveCommits}`, medCell("correctiveCommits"));
1086
- if (typeof cur.ciTrySuccess === "number")
2085
+ show("time.totalMinutes", (r) => r.time?.totalMinutes, mins);
2086
+ const total = cur.lines?.total;
2087
+ if (total) {
1087
2088
  row(
1088
- "ciTrySuccess",
1089
- `${cur.ciTrySuccess}${cur.ciTrySuccess === 1 ? " (first-try)" : ""}`,
1090
- medCell("ciTrySuccess"),
2089
+ "lines.total.changed",
2090
+ `${total.changed} (+${total.added}/-${total.deleted})`,
2091
+ medCell((r) => r.lines?.total?.changed),
1091
2092
  );
1092
- // Instinct-loop deltas — frictionAdded is the featured signal (shown even at 0).
1093
- if (typeof cur.frictionAdded === "number")
1094
- row("frictionAdded", `${cur.frictionAdded}`, medCell("frictionAdded"));
1095
- if (typeof cur.deferralsAdded === "number")
1096
- row("deferralsAdded", `${cur.deferralsAdded}`, medCell("deferralsAdded"));
1097
- if (typeof cur.failuresAdded === "number")
1098
- row("failuresAdded", `${cur.failuresAdded}`, medCell("failuresAdded"));
2093
+ show("lines.total.files", (r) => r.lines?.total?.files);
2094
+ }
2095
+ show("plan.total.tasks", (r) => r.plan?.total?.tasks);
2096
+ if (cur.ending === "close-failed") row("ending", "close-failed", "—");
2097
+ // Instinct-loop deltas — friction is the featured signal (shown even at 0).
2098
+ show("ledgers.friction.added", (r) => r.ledgers?.friction?.added);
2099
+ show("ledgers.deferrals.added", (r) => r.ledgers?.deferrals?.added);
2100
+ show("ledgers.failures.added", (r) => r.ledgers?.failures?.added);
1099
2101
  }
1100
2102
 
1101
- // Compliance — this run's rows. The `outcome` and `compliance` rows are written
1102
- // at different points in a close (different HEADs → different parentSha), so we
1103
- // DON'T match on the run row's parentSha: we take the newest same-workflow
1104
- // compliance group (its parentSha) as "this run".
2103
+ // Compliance — this run's rows: the run row's run.parentSha, else the newest
2104
+ // same-workflow compliance group.
1105
2105
  const complianceRows = events.filter(
1106
- (e): e is ComplianceEvent => e.kind === "compliance" && e.workflow === workflow,
2106
+ (e): e is ComplianceEvent => e.kind === "compliance" && e.by?.workflow === workflow,
1107
2107
  );
1108
- const compSha = complianceRows.slice().sort((a, b) => compareTs(b, a))[0]?.parentSha;
2108
+ const newestSha = complianceRows.slice().sort((a, b) => compareTs(b, a))[0]?.run?.parentSha;
2109
+ const curSha = cur?.run?.parentSha;
2110
+ const compSha = complianceRows.some((c) => c.run?.parentSha === curSha) ? curSha : newestSha;
1109
2111
  if (compSha) {
1110
- const comp = complianceRows.filter((c) => c.parentSha === compSha);
1111
- const pass = comp.filter((c) => c.result === "pass").length;
1112
- const fail = comp.filter((c) => c.result === "fail").length;
1113
- const na = comp.filter((c) => c.result === "n/a").length;
2112
+ const comp = complianceRows.filter((c) => c.run?.parentSha === compSha);
2113
+ const pass = comp.filter((c) => c.rule?.verdict === "pass").length;
2114
+ const fail = comp.filter((c) => c.rule?.verdict === "fail").length;
2115
+ const na = comp.filter((c) => c.rule?.verdict === "n/a").length;
1114
2116
  const denom = pass + fail + na;
1115
2117
  const rate = denom > 0 ? Math.round((pass / denom) * 100) : 0;
1116
2118
  row("compliance", `${pass} pass · ${fail} fail · ${na} n/a (${rate}%)`, "—");
1117
2119
  }
1118
2120
 
1119
- // Attempts — the newest same-workflow *_ATTEMPT counter (this run).
1120
- const attempt = events
2121
+ // Attempts — this run's *_ATTEMPT counter, else the newest same-workflow one.
2122
+ const attempts = events
1121
2123
  .filter(
1122
2124
  (e): e is CounterEvent =>
1123
- e.kind === "counter" && e.workflow === workflow && /_ATTEMPT$/.test(e.counterName),
2125
+ e.kind === "counter" &&
2126
+ e.by?.workflow === workflow &&
2127
+ /_ATTEMPT$/.test(e.counter?.name ?? ""),
1124
2128
  )
1125
- .sort((a, b) => compareTs(b, a))[0];
1126
- if (attempt) row("attempts", `${attempt.counterName} ${attempt.counterValue}`, "—");
2129
+ .sort((a, b) => compareTs(b, a));
2130
+ const attempt = attempts.find((c) => c.run?.parentSha === curSha) ?? attempts[0];
2131
+ if (attempt) row("attempts", `${attempt.counter.name} ${attempt.counter.value}`, "—");
1127
2132
 
1128
2133
  if (tableRows.length > 0) {
1129
2134
  lines.push(
@@ -1134,8 +2139,10 @@ export function workflowTelemetry(result: FoldFromResult, workflow?: string): Te
1134
2139
  );
1135
2140
  }
1136
2141
  lines.push(
1137
- `\`med·${RUN_BASELINE_WINDOW}\` = median of the previous ${RUN_BASELINE_WINDOW} ${workflow}${cur?.planSource ? ` ${cur.planSource}` : ""} runs (— if < ${RUN_BASELINE_MIN}) · ledger ${result.rowCount} rows, ${result.malformedLineCount} malformed`,
2142
+ `\`med·${RUN_BASELINE_WINDOW}\` = median of the previous ${RUN_BASELINE_WINDOW} ${workflow}${converted(cur) ? " converted" : ""} runs (— if < ${RUN_BASELINE_MIN}) · ledger ${result.rowCount} rows, ${result.malformedLineCount} malformed`,
1138
2143
  );
2144
+ if ([cur, ...prev].some(oldBrief))
2145
+ lines.push("Old `plan.source: brief` rows count as `converted`.");
1139
2146
  lines.push(...maxRowsLines);
1140
2147
 
1141
2148
  return { ...base, lines };