crysk 0.0.0-stage → 0.3.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 (229) hide show
  1. package/LICENSE +176 -0
  2. package/README.md +610 -2
  3. package/bin/pr-hero.js +166 -0
  4. package/config/models/anthropic.json +5 -0
  5. package/dist/SKILL-7e3725zn.md +496 -0
  6. package/dist/SKILL-7q35wcaz.md +66 -0
  7. package/dist/SKILL-9at22381.md +74 -0
  8. package/dist/SKILL-ex2hxxh3.md +134 -0
  9. package/dist/adjudicator-dtg2axnh.md +86 -0
  10. package/dist/admission-config.example-a9vqmmad.json +9 -0
  11. package/dist/ci-admission-camfbx2b.md +122 -0
  12. package/dist/cli.js +42292 -0
  13. package/dist/consolidate-ac0mnfyj.md +24 -0
  14. package/dist/deep-review-lifecycle-m698ybjp.md +362 -0
  15. package/dist/deep-review-logic-a6b1gczf.md +156 -0
  16. package/dist/deep-review-parity-0ec904db.md +120 -0
  17. package/dist/deep-review-reliability-qyakbjb9.md +125 -0
  18. package/dist/deep-review-resilience-3tz8y26e.md +118 -0
  19. package/dist/index.js +20190 -0
  20. package/dist/opencode-ci-7b0be64p.md +141 -0
  21. package/dist/review-refuter-j4e9gezy.md +71 -0
  22. package/dist/scout-yvp153q7.md +140 -0
  23. package/dist/summarizer-zca44nxa.md +18 -0
  24. package/dist/workflow-w1g9szna.yml +151 -0
  25. package/package.json +82 -4
  26. package/prompts/consolidate.md +24 -0
  27. package/prompts/default/PROVENANCE.md +18 -0
  28. package/prompts/default/deep-review-lifecycle.md +362 -0
  29. package/prompts/default/deep-review-logic.md +156 -0
  30. package/prompts/default/deep-review-parity.md +120 -0
  31. package/prompts/default/deep-review-reliability.md +125 -0
  32. package/prompts/default/deep-review-resilience.md +118 -0
  33. package/prompts/default/review-refuter.md +71 -0
  34. package/prompts/scout.md +140 -0
  35. package/prompts/summarizer.md +18 -0
  36. package/skills/crysk/SKILL.md +74 -0
  37. package/skills/crysk-ci-setup/SKILL.md +134 -0
  38. package/skills/crysk-ci-setup/assets/admission-config.example.json +9 -0
  39. package/skills/crysk-ci-setup/assets/workflow.yml +151 -0
  40. package/skills/crysk-ci-setup/references/ci-admission.md +122 -0
  41. package/skills/crysk-ci-setup/references/opencode-ci.md +141 -0
  42. package/skills/crysk-loop/SKILL.md +496 -0
  43. package/skills/crysk-loop/adjudicator.md +86 -0
  44. package/skills/crysk-pr/SKILL.md +66 -0
  45. package/src/agent-env.ts +1084 -0
  46. package/src/asset-manifest.ts +83 -0
  47. package/src/assets.d.ts +6 -0
  48. package/src/assets.ts +183 -0
  49. package/src/brand-paths.ts +155 -0
  50. package/src/brand.ts +255 -0
  51. package/src/ci/admission-ledger.ts +350 -0
  52. package/src/ci/classify-error.ts +73 -0
  53. package/src/ci/cli-record.ts +271 -0
  54. package/src/ci/force-comment.ts +39 -0
  55. package/src/ci/gates.ts +923 -0
  56. package/src/ci/outcome.ts +2181 -0
  57. package/src/ci/override.ts +187 -0
  58. package/src/ci/publish.ts +1639 -0
  59. package/src/ci/reporter.ts +626 -0
  60. package/src/ci/review-admission.ts +901 -0
  61. package/src/ci/review-levels.ts +310 -0
  62. package/src/ci/review-policy.ts +18 -0
  63. package/src/ci/review-risk.ts +184 -0
  64. package/src/ci/setup.ts +844 -0
  65. package/src/ci/trigger.ts +1353 -0
  66. package/src/cli.ts +348 -0
  67. package/src/commands/activity.ts +67 -0
  68. package/src/commands/ci-setup-questions.ts +397 -0
  69. package/src/commands/ci-setup.ts +381 -0
  70. package/src/commands/config.ts +99 -0
  71. package/src/commands/doctor.ts +108 -0
  72. package/src/commands/init.ts +139 -0
  73. package/src/commands/mcp.ts +10 -0
  74. package/src/commands/menu.ts +129 -0
  75. package/src/commands/post.ts +302 -0
  76. package/src/commands/skills.ts +83 -0
  77. package/src/commands/status.ts +173 -0
  78. package/src/commands/triage.ts +342 -0
  79. package/src/commands/uninstall.ts +37 -0
  80. package/src/commands/upgrade.ts +214 -0
  81. package/src/commands/usage.ts +98 -0
  82. package/src/compare/compare.ts +28 -0
  83. package/src/compare/floor-test.ts +471 -0
  84. package/src/compare/martian-adapter.ts +80 -0
  85. package/src/config/config.ts +267 -0
  86. package/src/corpus/corpus.ts +1094 -0
  87. package/src/corpus/preflight.ts +1789 -0
  88. package/src/diversity/accounting.ts +90 -0
  89. package/src/diversity/adjudication.ts +145 -0
  90. package/src/diversity/admission.ts +60 -0
  91. package/src/diversity/benchmark.ts +195 -0
  92. package/src/diversity/clustering.ts +285 -0
  93. package/src/diversity/errors.ts +7 -0
  94. package/src/diversity/identity.ts +285 -0
  95. package/src/diversity/index.ts +11 -0
  96. package/src/diversity/pipeline-integration.ts +448 -0
  97. package/src/diversity/projection.ts +57 -0
  98. package/src/diversity/self-contained.ts +68 -0
  99. package/src/diversity/target-validation.ts +179 -0
  100. package/src/doctor-migration.ts +209 -0
  101. package/src/doctor.ts +723 -0
  102. package/src/errors.ts +83 -0
  103. package/src/execution/admission.ts +75 -0
  104. package/src/execution/atomic-write.ts +35 -0
  105. package/src/execution/attempt-evidence.ts +415 -0
  106. package/src/execution/bucket-id.ts +136 -0
  107. package/src/execution/concurrency-limiter.ts +175 -0
  108. package/src/execution/contracts.ts +443 -0
  109. package/src/execution/failure-classification.ts +42 -0
  110. package/src/execution/failure-policy.ts +240 -0
  111. package/src/execution/harness.ts +2548 -0
  112. package/src/execution/settlement.ts +348 -0
  113. package/src/execution/spawned-process.ts +66 -0
  114. package/src/execution/spend-limiter.ts +424 -0
  115. package/src/execution/step-artifacts.ts +55 -0
  116. package/src/execution/usage-normalized.ts +469 -0
  117. package/src/git/git.ts +396 -0
  118. package/src/git/identity.ts +64 -0
  119. package/src/git/refs.ts +140 -0
  120. package/src/home-preflight.ts +443 -0
  121. package/src/home.ts +243 -0
  122. package/src/ignore-file.ts +336 -0
  123. package/src/ignore-read.ts +118 -0
  124. package/src/index.ts +34 -0
  125. package/src/legacy-launchd.ts +29 -0
  126. package/src/mcp/mcp.ts +150 -0
  127. package/src/mcp/preflight.ts +407 -0
  128. package/src/menu-context.ts +192 -0
  129. package/src/model/catalog.ts +251 -0
  130. package/src/model/exec-snapshots.ts +390 -0
  131. package/src/model/free-discovery.ts +302 -0
  132. package/src/model/provider-capabilities.ts +814 -0
  133. package/src/model/routing.ts +600 -0
  134. package/src/pr/admission.ts +847 -0
  135. package/src/pr/ci-admission-gate.ts +665 -0
  136. package/src/pr/ci-publish.ts +76 -0
  137. package/src/pr/discovery.ts +432 -0
  138. package/src/pr/inline.ts +507 -0
  139. package/src/pr/plan.ts +366 -0
  140. package/src/pr/posting.ts +115 -0
  141. package/src/pr/pr-status.ts +787 -0
  142. package/src/pr/pr.ts +3642 -0
  143. package/src/pr/preflight.ts +1031 -0
  144. package/src/pr/publish-outcome.ts +361 -0
  145. package/src/pr/range.ts +119 -0
  146. package/src/pr/reverts-preflight.ts +606 -0
  147. package/src/pr/reverts.ts +377 -0
  148. package/src/pr/review-pr.ts +927 -0
  149. package/src/pr/status.ts +154 -0
  150. package/src/pr/target.ts +388 -0
  151. package/src/pr/teardown.ts +437 -0
  152. package/src/pr/worktree-setup.ts +60 -0
  153. package/src/production-runtime.ts +1877 -0
  154. package/src/progress.ts +487 -0
  155. package/src/rereview/adjudicate.ts +89 -0
  156. package/src/rereview/classify.ts +362 -0
  157. package/src/rereview/identity.ts +211 -0
  158. package/src/rereview/plan.ts +308 -0
  159. package/src/rereview/prepare.ts +1025 -0
  160. package/src/rereview/state.ts +767 -0
  161. package/src/rereview/verify.ts +241 -0
  162. package/src/review/boundary.ts +105 -0
  163. package/src/review/consolidate.ts +246 -0
  164. package/src/review/dedupe.ts +368 -0
  165. package/src/review/drafts.ts +448 -0
  166. package/src/review/findings-conformance.ts +120 -0
  167. package/src/review/findings.ts +714 -0
  168. package/src/review/pipeline.ts +3977 -0
  169. package/src/review/preflight.ts +3575 -0
  170. package/src/review/prompt-set.ts +177 -0
  171. package/src/review/proof-refs.ts +187 -0
  172. package/src/review/report.ts +1821 -0
  173. package/src/review/review.ts +490 -0
  174. package/src/review/root-cause.ts +120 -0
  175. package/src/review/route-preflight.ts +289 -0
  176. package/src/review/run.ts +601 -0
  177. package/src/review/scout.ts +323 -0
  178. package/src/review/size-gate.ts +595 -0
  179. package/src/review/spec.ts +235 -0
  180. package/src/review/step-runner.ts +233 -0
  181. package/src/runner-authority.ts +596 -0
  182. package/src/security/binding-policy.ts +115 -0
  183. package/src/security/credential-broker.ts +773 -0
  184. package/src/security/evidence-redaction.ts +62 -0
  185. package/src/security/execution-authority.ts +27 -0
  186. package/src/security/redact.ts +71 -0
  187. package/src/security/workspace-read-broker.ts +466 -0
  188. package/src/server/client.ts +190 -0
  189. package/src/server/preflight.ts +217 -0
  190. package/src/server/server.ts +327 -0
  191. package/src/signal-handler.ts +50 -0
  192. package/src/store/activity.ts +413 -0
  193. package/src/store/backfill-preflight.ts +49 -0
  194. package/src/store/backfill.ts +141 -0
  195. package/src/store/gc-preflight.ts +206 -0
  196. package/src/store/gc.ts +424 -0
  197. package/src/store/metrics-preflight.ts +229 -0
  198. package/src/store/metrics.ts +236 -0
  199. package/src/store/preflight.ts +748 -0
  200. package/src/store/store.ts +693 -0
  201. package/src/system-tools.ts +355 -0
  202. package/src/transport-registry.ts +1124 -0
  203. package/src/transports/claude-code-cli.ts +1348 -0
  204. package/src/transports/opencode-admission.ts +515 -0
  205. package/src/transports/opencode-client.ts +3328 -0
  206. package/src/transports/opencode-evidence.ts +557 -0
  207. package/src/transports/opencode-mcp.ts +248 -0
  208. package/src/transports/opencode-sdk.ts +2294 -0
  209. package/src/transports/opencode-server.ts +535 -0
  210. package/src/triage/adjudication.ts +113 -0
  211. package/src/triage/reply.ts +125 -0
  212. package/src/triage/triage.ts +255 -0
  213. package/src/ui/activity.ts +173 -0
  214. package/src/ui/config-edit.ts +816 -0
  215. package/src/ui/config.ts +462 -0
  216. package/src/ui/menu.ts +1325 -0
  217. package/src/ui/plan.ts +1039 -0
  218. package/src/ui/primitives.ts +300 -0
  219. package/src/ui/progress.ts +298 -0
  220. package/src/ui/result.ts +552 -0
  221. package/src/ui/review-menu.ts +312 -0
  222. package/src/ui/select.ts +528 -0
  223. package/src/ui/tree.ts +178 -0
  224. package/src/uninstaller.ts +479 -0
  225. package/src/updater.ts +836 -0
  226. package/src/usage.ts +77 -0
  227. package/src/watch/preflight.ts +1389 -0
  228. package/src/watch/watch.ts +1235 -0
  229. package/src/wizard.ts +877 -0
@@ -0,0 +1,424 @@
1
+ // D1-08 PR4 (§9.1): the transactional spend reservation ledger. In-memory
2
+ // per run, behind an interface whose only stateful operations are CAS
3
+ // transitions (design decision D7) — so a durable adapter (D1-08f) can
4
+ // implement `SpendLedger` with zero caller changes.
5
+ //
6
+ // Wiring, corrected 2026-09-02. This header used to say "Not wired into the
7
+ // harness yet; that's PR5b, per the design's own tripwire table", and it had
8
+ // gone stale on both axes. PR5b landed:
9
+ // `StepExecutionHarness.runAttempt` calls `reserve()` before the transport
10
+ // and `finalizeReservation` applies the CAS transition `settlementFromUsage`
11
+ // names (harness.ts), `runPipeline`'s `collectUnresolvedSpend` gathers the
12
+ // terminal `unresolved_remote` reservations into `PipelineResult.unresolved`
13
+ // (pipeline.ts), and `renderResult` prints them and marks the run's cost
14
+ // figure a floor (ui/result.ts).
15
+ //
16
+ // The second axis, which "wired into the harness" alone would still hide, and
17
+ // which held on `dev` until 2026-09-02: no production composition constructed
18
+ // a `SpendLedger` at all, so `this.spendLedger` was undefined on every real
19
+ // run and none of the above executed. It is composed now —
20
+ // `MultiProviderRunner` (production-runtime.ts) holds ONE instance for the
21
+ // run, which is what makes `fencedBuckets` below a run-scoped fence rather
22
+ // than a per-step no-op.
23
+ //
24
+ // It is composed for METERED bindings only, and that is deliberate rather
25
+ // than partial: the guarantee this ledger enforces is about dollars, and
26
+ // `MultiProviderRunner.run` carries the full argument. A claude-only run
27
+ // therefore records zero reservations, and the absent `reservations` key on
28
+ // those steps is the truthful signal, not a gap. `ClaudeCodeRunner`
29
+ // (step-runner.ts) stays ledger-free for the same reason.
30
+ //
31
+ // #182 follow-up: the one exception is a FREE OpenCode binding
32
+ // (`provider_free`), which reserves too even though its capability report says
33
+ // subscription. Without a reservation the free-nonzero rule above would be
34
+ // dead in production — `finalizeReservation` never runs, so a flipped model
35
+ // would keep spending attempts instead of fencing and failing closed. A free
36
+ // step that stays free settles 0 and never fences.
37
+ //
38
+ // Two couplings the spec calls out as the easiest to lose across chained
39
+ // PRs are made TYPE-unreachable here rather than asserted at runtime:
40
+ // 1. `settle()`'s second argument is narrowed to the "settle" arm of
41
+ // SettlementDecision — an attempt whose usage completeness isn't
42
+ // "complete" can never be handed to `settle()` as a bare number; tsc
43
+ // refuses the call before any code runs (spec: "Non-Complete Usage
44
+ // Never Settles As A Number").
45
+ // 2. `reserve()`'s second argument is a branded ReserveToken that only
46
+ // `beginStep()` (attempt 1) or `nextCycle()` on a NON-terminal
47
+ // RetryDisposition can produce. `nextCycle()` returns `undefined` for
48
+ // a terminal disposition, so a terminal attempt structurally cannot
49
+ // construct a token to open a new reserve+admit cycle (spec: "Only
50
+ // Non-Terminal Disposition Starts A New Reserve+Admit Cycle").
51
+
52
+ import { randomUUID } from "node:crypto";
53
+ import type { RetryDisposition } from "./failure-policy";
54
+ import { type NormalizedUsage, outputTokensKnown } from "./usage-normalized";
55
+
56
+ // ---- Coupling 1: settlement decision ----
57
+
58
+ export type SettlementDecision =
59
+ | { readonly kind: "settle"; readonly actualUsd: number }
60
+ | {
61
+ readonly kind: "unresolved";
62
+ readonly knownUsd?: number;
63
+ // #182 follow-up: present ONLY on the free-nonzero arm below. The
64
+ // harness fail-fasts on it (terminal step failure, no retry); every
65
+ // other unresolved arm stays fence-only. Optional and additive so all
66
+ // existing producers/consumers keep compiling — tsc is the net.
67
+ readonly reason?: "free_nonzero_cost";
68
+ };
69
+
70
+ // spec: "Non-Complete Usage Never Settles As A Number" — completeness other
71
+ // than "complete" is ALWAYS the unresolved arm, carrying whatever cash cost
72
+ // is already known (possibly none) rather than inventing a settled number.
73
+ // This is the ONLY producer of SettlementDecision.
74
+ export function settlementFromUsage(
75
+ usage: NormalizedUsage,
76
+ ): SettlementDecision {
77
+ if (usage.completeness !== "complete") {
78
+ return { kind: "unresolved", knownUsd: usage.cashCostUsd };
79
+ }
80
+ if (usage.cashCostUsd === undefined) {
81
+ return { kind: "unresolved", knownUsd: undefined };
82
+ }
83
+ // 2026-09-02, the metered-zero rule: #133's under-reporting failure
84
+ // arriving through the other door. #133 caught a metered route REPORTED as
85
+ // a subscription and therefore priced at nothing; this catches a metered
86
+ // route that reports a NUMBER, and the number is zero.
87
+ //
88
+ // How a zero gets here: the OpenCode client reads the provider's own cost
89
+ // (`asNumber(info.cost)`, opencode-client.ts), and `asNumber` returns 0 for
90
+ // 0 rather than undefined — so a provider OpenCode holds no price for, or a
91
+ // custom endpoint, produces a COMPLETE usage with `cashCostUsd: 0` and
92
+ // `costSource: "provider"`. Every guard above passes it, and it settles as
93
+ // a truthful-looking zero wearing the provider's badge.
94
+ //
95
+ // The credential's billing mode discriminates, never the number: zero cash
96
+ // cost IS truthful for a subscription credential (the design's own
97
+ // subscription rule), and is not truthful for a metered credential that
98
+ // produced output tokens. Both halves are load-bearing — dropping the mode
99
+ // test would misfile every free subscription attempt as unresolved and
100
+ // fence its bucket; dropping the token test would misfile a metered attempt
101
+ // that never reached the provider (`noSessionUsage`, opencode-sdk.ts).
102
+ //
103
+ // `billingMode: "unknown"` is deliberately NOT covered: it is already a
104
+ // blocking preflight result (design doc line 461, enforced by
105
+ // `cashCostAccountingValid` in production-runtime.ts), so no such route
106
+ // reaches an attempt, and a second weaker enforcement point for a fact the
107
+ // gate refuses outright is how the two start disagreeing.
108
+ //
109
+ // No `knownUsd`: the whole point is that this 0 is not a known cost.
110
+ // Carrying it would relocate the same lie into the unresolved arm, where
111
+ // `renderResult` would print "$0 known" beside the fenced bucket.
112
+ if (
113
+ usage.billingMode === "metered" &&
114
+ usage.cashCostUsd === 0 &&
115
+ (outputTokensKnown(usage.tokens) ?? 0) > 0
116
+ ) {
117
+ return { kind: "unresolved", knownUsd: undefined };
118
+ }
119
+ // #182 follow-up, the free-nonzero rule: a model free at probe time can flip
120
+ // to metered before/during the attempt, and the attempt then runs
121
+ // credentialless under an empty projection. The flip is observable at
122
+ // settlement — the transport accumulates provider-reported cost per message
123
+ // (opencode-sdk.ts `cashCostUsd`, `costSource: "provider"`), so priced work
124
+ // on a free-declared route arrives here as complete usage with cash > 0.
125
+ //
126
+ // NO output-token gate, unlike metered-zero: any priced work on a
127
+ // free-declared route is unaccountable by definition, and cash > 0 already
128
+ // implies the provider did priced work. `noSessionUsage` (route-mode stamp +
129
+ // cash 0 + empty tokens) still settles 0 below — a free attempt that never
130
+ // reached the provider is a truthful zero, not a flip.
131
+ //
132
+ // `knownUsd` IS carried here — the documented asymmetry with metered-zero,
133
+ // which drops it. A metered 0 is an untrusted number wearing the provider's
134
+ // badge; a free-route cash figure is the provider's STATED price for work it
135
+ // claims to have billed, and the fence (`markUnresolvedRemote`) plus the
136
+ // harness fail-fast message both need the figure to name what happened.
137
+ if (
138
+ usage.billingMode === "free" &&
139
+ usage.completeness === "complete" &&
140
+ (usage.cashCostUsd ?? 0) > 0
141
+ ) {
142
+ return {
143
+ kind: "unresolved",
144
+ knownUsd: usage.cashCostUsd,
145
+ reason: "free_nonzero_cost",
146
+ };
147
+ }
148
+ return { kind: "settle", actualUsd: usage.cashCostUsd };
149
+ }
150
+
151
+ // ---- Coupling 2: reserve token ----
152
+
153
+ declare const RESERVE: unique symbol;
154
+ export type ReserveToken = { readonly [RESERVE]: true };
155
+
156
+ // Not a secret or a capability — just a value only this module's two
157
+ // functions can produce, so tsc (not a runtime check) is what stops a
158
+ // terminal disposition from calling `reserve()`.
159
+ const RESERVE_TOKEN: ReserveToken = Object.freeze({}) as ReserveToken;
160
+
161
+ // Attempt 1 of any step always has a token to open its first reserve+admit
162
+ // cycle — there is no disposition yet to consult.
163
+ export function beginStep(): ReserveToken {
164
+ return RESERVE_TOKEN;
165
+ }
166
+
167
+ // spec: "Only Non-Terminal Disposition Starts A New Reserve+Admit Cycle" — a
168
+ // terminal disposition (including remote_abort_unconfirmed, which
169
+ // `decideRetryDisposition` folds into "terminal") returns undefined: there
170
+ // is no token, so `reserve()` cannot be called for a new cycle.
171
+ export function nextCycle(
172
+ disposition: RetryDisposition,
173
+ ): ReserveToken | undefined {
174
+ return disposition.action === "terminal" ? undefined : RESERVE_TOKEN;
175
+ }
176
+
177
+ // ---- Ledger ----
178
+
179
+ // spec: "every attempt MUST carry a reservationId and terminal state" — the
180
+ // four states a reservation can occupy. "reserved" is the only
181
+ // non-terminal one; every CAS transition below moves OUT of it exactly
182
+ // once.
183
+ export type SpendReservationState =
184
+ | "reserved"
185
+ | "settled"
186
+ | "released_unstarted"
187
+ | "unresolved_remote";
188
+
189
+ export interface ReserveSpendInput {
190
+ readonly bucketId: string;
191
+ readonly reservedUsd: number;
192
+ readonly sessionId: string;
193
+ readonly attempt: number;
194
+ }
195
+
196
+ export interface SpendReservation {
197
+ readonly reservationId: string;
198
+ readonly bucketId: string;
199
+ readonly sessionId: string;
200
+ readonly attempt: number;
201
+ readonly reservedUsd: number;
202
+ readonly state: SpendReservationState;
203
+ readonly settledUsd?: number;
204
+ readonly knownUsd?: number;
205
+ }
206
+
207
+ // spec: "Unresolved bucket blocks the next paid attempt" — thrown by
208
+ // `reserve()` before a reservation is even created, so no transport spawn
209
+ // can follow it.
210
+ export class SpendReservationFencedError extends Error {
211
+ readonly bucketId: string;
212
+
213
+ constructor(bucketId: string) {
214
+ super(
215
+ `bucket "${bucketId}" is fenced by an unresolved_remote reservation; no new reservations admitted this run`,
216
+ );
217
+ this.name = "SpendReservationFencedError";
218
+ this.bucketId = bucketId;
219
+ }
220
+ }
221
+
222
+ export class SpendReservationNotFoundError extends Error {
223
+ readonly reservationId: string;
224
+
225
+ constructor(reservationId: string) {
226
+ super(`no reservation "${reservationId}"`);
227
+ this.name = "SpendReservationNotFoundError";
228
+ this.reservationId = reservationId;
229
+ }
230
+ }
231
+
232
+ // Thrown when a terminal transition is requested with an idempotency key
233
+ // that differs from the one that already made the reservation terminal —
234
+ // the CAS conflict case, distinct from the same-key no-op.
235
+ export class SpendReservationConflictError extends Error {
236
+ readonly reservationId: string;
237
+ readonly currentState: SpendReservationState;
238
+
239
+ constructor(reservationId: string, currentState: SpendReservationState) {
240
+ super(
241
+ `reservation "${reservationId}" is already terminal ("${currentState}") under a different idempotency key`,
242
+ );
243
+ this.name = "SpendReservationConflictError";
244
+ this.reservationId = reservationId;
245
+ this.currentState = currentState;
246
+ }
247
+ }
248
+
249
+ // D1-08f seam: exactly four async CAS methods keyed by reservationId +
250
+ // idempotencyKey. A durable adapter implements this same interface with
251
+ // zero caller changes (design decision D7).
252
+ export interface SpendLedger {
253
+ reserve(
254
+ input: ReserveSpendInput,
255
+ token: ReserveToken,
256
+ ): Promise<SpendReservation>;
257
+ settle(
258
+ reservationId: string,
259
+ decision: Extract<SettlementDecision, { kind: "settle" }>,
260
+ idempotencyKey: string,
261
+ ): Promise<void>;
262
+ releaseUnstarted(
263
+ reservationId: string,
264
+ idempotencyKey: string,
265
+ ): Promise<void>;
266
+ markUnresolvedRemote(
267
+ reservationId: string,
268
+ knownUsd: number | undefined,
269
+ idempotencyKey: string,
270
+ ): Promise<void>;
271
+ }
272
+
273
+ // D1-08 PR5b (D8): one step's fenced reservation, surfaced at the pipeline
274
+ // and terminal-result boundaries so the cross-run fencing gap (breaker state
275
+ // does not survive a process restart, design decision D7) stays VISIBLE
276
+ // rather than silent. `step` is attached by the caller (pipeline.ts knows
277
+ // step names; this module never does) — everything else is copied verbatim
278
+ // off the terminal `SpendReservation`.
279
+ export interface UnresolvedSpend {
280
+ readonly step: string;
281
+ readonly bucketId: string;
282
+ readonly reservationId: string;
283
+ readonly knownUsd?: number;
284
+ }
285
+
286
+ type TerminalOperationKind =
287
+ | "settled"
288
+ | "released_unstarted"
289
+ | "unresolved_remote";
290
+
291
+ interface LedgerEntry {
292
+ reservation: SpendReservation;
293
+ // Idempotency key of the transition that made this reservation terminal
294
+ // — undefined while still "reserved". A repeat call carrying THIS exact
295
+ // key AND the same operation kind is a no-op; the same key with a
296
+ // different operation kind is a conflict, never a silent overwrite.
297
+ terminalIdempotencyKey?: string;
298
+ terminalOperationKind?: TerminalOperationKind;
299
+ }
300
+
301
+ export class InMemorySpendLedger implements SpendLedger {
302
+ private readonly reservations = new Map<string, LedgerEntry>();
303
+ // spec: "Unresolved bucket blocks the next paid attempt" — once a bucket
304
+ // produces an unresolved_remote reservation, it stays fenced for the rest
305
+ // of this ledger's lifetime (i.e. the run; cross-run persistence is out
306
+ // of scope per "In-Memory Ledger With Surfaced Cross-Run Gap").
307
+ private readonly fencedBuckets = new Set<string>();
308
+
309
+ async reserve(
310
+ input: ReserveSpendInput,
311
+ _token: ReserveToken,
312
+ ): Promise<SpendReservation> {
313
+ if (this.fencedBuckets.has(input.bucketId)) {
314
+ throw new SpendReservationFencedError(input.bucketId);
315
+ }
316
+ const reservation: SpendReservation = {
317
+ reservationId: `resv-${randomUUID()}`,
318
+ bucketId: input.bucketId,
319
+ sessionId: input.sessionId,
320
+ attempt: input.attempt,
321
+ reservedUsd: input.reservedUsd,
322
+ state: "reserved",
323
+ };
324
+ this.reservations.set(reservation.reservationId, { reservation });
325
+ return reservation;
326
+ }
327
+
328
+ async settle(
329
+ reservationId: string,
330
+ decision: Extract<SettlementDecision, { kind: "settle" }>,
331
+ idempotencyKey: string,
332
+ ): Promise<void> {
333
+ this.transition(
334
+ reservationId,
335
+ idempotencyKey,
336
+ "settled",
337
+ (reservation) => ({
338
+ ...reservation,
339
+ state: "settled",
340
+ settledUsd: decision.actualUsd,
341
+ }),
342
+ );
343
+ }
344
+
345
+ async releaseUnstarted(
346
+ reservationId: string,
347
+ idempotencyKey: string,
348
+ ): Promise<void> {
349
+ this.transition(
350
+ reservationId,
351
+ idempotencyKey,
352
+ "released_unstarted",
353
+ (reservation) => ({
354
+ ...reservation,
355
+ state: "released_unstarted",
356
+ }),
357
+ );
358
+ }
359
+
360
+ async markUnresolvedRemote(
361
+ reservationId: string,
362
+ knownUsd: number | undefined,
363
+ idempotencyKey: string,
364
+ ): Promise<void> {
365
+ const applied = this.transition(
366
+ reservationId,
367
+ idempotencyKey,
368
+ "unresolved_remote",
369
+ (reservation) => ({
370
+ ...reservation,
371
+ state: "unresolved_remote",
372
+ knownUsd,
373
+ }),
374
+ );
375
+ if (applied) {
376
+ const entry = this.reservations.get(reservationId);
377
+ if (entry !== undefined) {
378
+ this.fencedBuckets.add(entry.reservation.bucketId);
379
+ }
380
+ }
381
+ }
382
+
383
+ // Test/introspection helper — deliberately NOT part of the SpendLedger
384
+ // interface (D7: "the only stateful operations are CAS transitions"), so
385
+ // a durable adapter is free to back this differently or omit it.
386
+ async getReservation(
387
+ reservationId: string,
388
+ ): Promise<SpendReservation | undefined> {
389
+ return this.reservations.get(reservationId)?.reservation;
390
+ }
391
+
392
+ // The one CAS primitive every terminal transition shares: a repeat call
393
+ // carrying the SAME idempotency key that already produced this exact
394
+ // terminal state is a no-op (spec: "double-settle/double-release on one
395
+ // reservationId+idempotencyKey is a no-op"); a DIFFERENT key on an
396
+ // already-terminal reservation is a conflict, not a silent overwrite.
397
+ private transition(
398
+ reservationId: string,
399
+ idempotencyKey: string,
400
+ operationKind: TerminalOperationKind,
401
+ apply: (reservation: SpendReservation) => SpendReservation,
402
+ ): boolean {
403
+ const entry = this.reservations.get(reservationId);
404
+ if (entry === undefined) {
405
+ throw new SpendReservationNotFoundError(reservationId);
406
+ }
407
+ if (entry.terminalIdempotencyKey !== undefined) {
408
+ if (
409
+ entry.terminalIdempotencyKey === idempotencyKey &&
410
+ entry.terminalOperationKind === operationKind
411
+ ) {
412
+ return false;
413
+ }
414
+ throw new SpendReservationConflictError(
415
+ reservationId,
416
+ entry.reservation.state,
417
+ );
418
+ }
419
+ entry.reservation = apply(entry.reservation);
420
+ entry.terminalIdempotencyKey = idempotencyKey;
421
+ entry.terminalOperationKind = operationKind;
422
+ return true;
423
+ }
424
+ }
@@ -0,0 +1,55 @@
1
+ // Where a step's per-attempt artifacts land, and the retry-reminder text
2
+ // appended to a re-prompt — part of the RUNNER CONTRACT, not a harness
3
+ // implementation detail, because several modules depend on the exact
4
+ // answer: the harness writes these files, review/pipeline.ts indexes them
5
+ // from `pipeline.json` (D1-10c), and execution/attempt-evidence.ts derives
6
+ // its own evidence path the same way. Deriving the names twice is how a
7
+ // pointer starts naming a file that was never written — the exact defect
8
+ // the harness's own comment records ("a hardcoded settlement.json in a
9
+ // cancellation message pointed at a file that never existed for as long as
10
+ // it shipped"), so every caller reads the shape from here.
11
+ //
12
+ // Split out of review/step-runner.ts (architecture guard C2): step-runner.ts
13
+ // itself depends on execution/harness.ts for StepExecutionHarness, so a
14
+ // harness.ts or execution/attempt-evidence.ts import of these helpers FROM
15
+ // step-runner.ts closed a value-import cycle back through it. This file has
16
+ // no imports of its own — a true leaf both sides can depend on one-way.
17
+
18
+ import path from "node:path";
19
+
20
+ // `attempt` is the 1-based attempt NUMBER, which for a settled step equals
21
+ // `StepResult.attempts`: the transient loop and the one format retry both
22
+ // increment the same counter, and the format retry always ends the loop.
23
+ export function attemptLogPath(
24
+ outPath: string,
25
+ stepName: string,
26
+ attempt: number,
27
+ ): string {
28
+ return path.join(path.dirname(outPath), "logs", `${stepName}.${attempt}.log`);
29
+ }
30
+
31
+ export function settlementReceiptPath(
32
+ outPath: string,
33
+ stepName: string,
34
+ attempt: number,
35
+ ): string {
36
+ return path.join(
37
+ path.dirname(outPath),
38
+ `settlement.${stepName}.attempt${attempt}.json`,
39
+ );
40
+ }
41
+
42
+ export function attemptEvidencePath(
43
+ outPath: string,
44
+ stepName: string,
45
+ attempt: number,
46
+ ): string {
47
+ return path.join(
48
+ path.dirname(outPath),
49
+ `evidence.${stepName}.attempt${attempt}.json`,
50
+ );
51
+ }
52
+
53
+ export const FORMAT_RETRY_REMINDER =
54
+ "\n\nREMINDER: your final message must be exactly one JSON object " +
55
+ "matching the mandated shape — no prose, no fences.";