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.
- package/LICENSE +176 -0
- package/README.md +610 -2
- package/bin/pr-hero.js +166 -0
- package/config/models/anthropic.json +5 -0
- package/dist/SKILL-7e3725zn.md +496 -0
- package/dist/SKILL-7q35wcaz.md +66 -0
- package/dist/SKILL-9at22381.md +74 -0
- package/dist/SKILL-ex2hxxh3.md +134 -0
- package/dist/adjudicator-dtg2axnh.md +86 -0
- package/dist/admission-config.example-a9vqmmad.json +9 -0
- package/dist/ci-admission-camfbx2b.md +122 -0
- package/dist/cli.js +42292 -0
- package/dist/consolidate-ac0mnfyj.md +24 -0
- package/dist/deep-review-lifecycle-m698ybjp.md +362 -0
- package/dist/deep-review-logic-a6b1gczf.md +156 -0
- package/dist/deep-review-parity-0ec904db.md +120 -0
- package/dist/deep-review-reliability-qyakbjb9.md +125 -0
- package/dist/deep-review-resilience-3tz8y26e.md +118 -0
- package/dist/index.js +20190 -0
- package/dist/opencode-ci-7b0be64p.md +141 -0
- package/dist/review-refuter-j4e9gezy.md +71 -0
- package/dist/scout-yvp153q7.md +140 -0
- package/dist/summarizer-zca44nxa.md +18 -0
- package/dist/workflow-w1g9szna.yml +151 -0
- package/package.json +82 -4
- package/prompts/consolidate.md +24 -0
- package/prompts/default/PROVENANCE.md +18 -0
- package/prompts/default/deep-review-lifecycle.md +362 -0
- package/prompts/default/deep-review-logic.md +156 -0
- package/prompts/default/deep-review-parity.md +120 -0
- package/prompts/default/deep-review-reliability.md +125 -0
- package/prompts/default/deep-review-resilience.md +118 -0
- package/prompts/default/review-refuter.md +71 -0
- package/prompts/scout.md +140 -0
- package/prompts/summarizer.md +18 -0
- package/skills/crysk/SKILL.md +74 -0
- package/skills/crysk-ci-setup/SKILL.md +134 -0
- package/skills/crysk-ci-setup/assets/admission-config.example.json +9 -0
- package/skills/crysk-ci-setup/assets/workflow.yml +151 -0
- package/skills/crysk-ci-setup/references/ci-admission.md +122 -0
- package/skills/crysk-ci-setup/references/opencode-ci.md +141 -0
- package/skills/crysk-loop/SKILL.md +496 -0
- package/skills/crysk-loop/adjudicator.md +86 -0
- package/skills/crysk-pr/SKILL.md +66 -0
- package/src/agent-env.ts +1084 -0
- package/src/asset-manifest.ts +83 -0
- package/src/assets.d.ts +6 -0
- package/src/assets.ts +183 -0
- package/src/brand-paths.ts +155 -0
- package/src/brand.ts +255 -0
- package/src/ci/admission-ledger.ts +350 -0
- package/src/ci/classify-error.ts +73 -0
- package/src/ci/cli-record.ts +271 -0
- package/src/ci/force-comment.ts +39 -0
- package/src/ci/gates.ts +923 -0
- package/src/ci/outcome.ts +2181 -0
- package/src/ci/override.ts +187 -0
- package/src/ci/publish.ts +1639 -0
- package/src/ci/reporter.ts +626 -0
- package/src/ci/review-admission.ts +901 -0
- package/src/ci/review-levels.ts +310 -0
- package/src/ci/review-policy.ts +18 -0
- package/src/ci/review-risk.ts +184 -0
- package/src/ci/setup.ts +844 -0
- package/src/ci/trigger.ts +1353 -0
- package/src/cli.ts +348 -0
- package/src/commands/activity.ts +67 -0
- package/src/commands/ci-setup-questions.ts +397 -0
- package/src/commands/ci-setup.ts +381 -0
- package/src/commands/config.ts +99 -0
- package/src/commands/doctor.ts +108 -0
- package/src/commands/init.ts +139 -0
- package/src/commands/mcp.ts +10 -0
- package/src/commands/menu.ts +129 -0
- package/src/commands/post.ts +302 -0
- package/src/commands/skills.ts +83 -0
- package/src/commands/status.ts +173 -0
- package/src/commands/triage.ts +342 -0
- package/src/commands/uninstall.ts +37 -0
- package/src/commands/upgrade.ts +214 -0
- package/src/commands/usage.ts +98 -0
- package/src/compare/compare.ts +28 -0
- package/src/compare/floor-test.ts +471 -0
- package/src/compare/martian-adapter.ts +80 -0
- package/src/config/config.ts +267 -0
- package/src/corpus/corpus.ts +1094 -0
- package/src/corpus/preflight.ts +1789 -0
- package/src/diversity/accounting.ts +90 -0
- package/src/diversity/adjudication.ts +145 -0
- package/src/diversity/admission.ts +60 -0
- package/src/diversity/benchmark.ts +195 -0
- package/src/diversity/clustering.ts +285 -0
- package/src/diversity/errors.ts +7 -0
- package/src/diversity/identity.ts +285 -0
- package/src/diversity/index.ts +11 -0
- package/src/diversity/pipeline-integration.ts +448 -0
- package/src/diversity/projection.ts +57 -0
- package/src/diversity/self-contained.ts +68 -0
- package/src/diversity/target-validation.ts +179 -0
- package/src/doctor-migration.ts +209 -0
- package/src/doctor.ts +723 -0
- package/src/errors.ts +83 -0
- package/src/execution/admission.ts +75 -0
- package/src/execution/atomic-write.ts +35 -0
- package/src/execution/attempt-evidence.ts +415 -0
- package/src/execution/bucket-id.ts +136 -0
- package/src/execution/concurrency-limiter.ts +175 -0
- package/src/execution/contracts.ts +443 -0
- package/src/execution/failure-classification.ts +42 -0
- package/src/execution/failure-policy.ts +240 -0
- package/src/execution/harness.ts +2548 -0
- package/src/execution/settlement.ts +348 -0
- package/src/execution/spawned-process.ts +66 -0
- package/src/execution/spend-limiter.ts +424 -0
- package/src/execution/step-artifacts.ts +55 -0
- package/src/execution/usage-normalized.ts +469 -0
- package/src/git/git.ts +396 -0
- package/src/git/identity.ts +64 -0
- package/src/git/refs.ts +140 -0
- package/src/home-preflight.ts +443 -0
- package/src/home.ts +243 -0
- package/src/ignore-file.ts +336 -0
- package/src/ignore-read.ts +118 -0
- package/src/index.ts +34 -0
- package/src/legacy-launchd.ts +29 -0
- package/src/mcp/mcp.ts +150 -0
- package/src/mcp/preflight.ts +407 -0
- package/src/menu-context.ts +192 -0
- package/src/model/catalog.ts +251 -0
- package/src/model/exec-snapshots.ts +390 -0
- package/src/model/free-discovery.ts +302 -0
- package/src/model/provider-capabilities.ts +814 -0
- package/src/model/routing.ts +600 -0
- package/src/pr/admission.ts +847 -0
- package/src/pr/ci-admission-gate.ts +665 -0
- package/src/pr/ci-publish.ts +76 -0
- package/src/pr/discovery.ts +432 -0
- package/src/pr/inline.ts +507 -0
- package/src/pr/plan.ts +366 -0
- package/src/pr/posting.ts +115 -0
- package/src/pr/pr-status.ts +787 -0
- package/src/pr/pr.ts +3642 -0
- package/src/pr/preflight.ts +1031 -0
- package/src/pr/publish-outcome.ts +361 -0
- package/src/pr/range.ts +119 -0
- package/src/pr/reverts-preflight.ts +606 -0
- package/src/pr/reverts.ts +377 -0
- package/src/pr/review-pr.ts +927 -0
- package/src/pr/status.ts +154 -0
- package/src/pr/target.ts +388 -0
- package/src/pr/teardown.ts +437 -0
- package/src/pr/worktree-setup.ts +60 -0
- package/src/production-runtime.ts +1877 -0
- package/src/progress.ts +487 -0
- package/src/rereview/adjudicate.ts +89 -0
- package/src/rereview/classify.ts +362 -0
- package/src/rereview/identity.ts +211 -0
- package/src/rereview/plan.ts +308 -0
- package/src/rereview/prepare.ts +1025 -0
- package/src/rereview/state.ts +767 -0
- package/src/rereview/verify.ts +241 -0
- package/src/review/boundary.ts +105 -0
- package/src/review/consolidate.ts +246 -0
- package/src/review/dedupe.ts +368 -0
- package/src/review/drafts.ts +448 -0
- package/src/review/findings-conformance.ts +120 -0
- package/src/review/findings.ts +714 -0
- package/src/review/pipeline.ts +3977 -0
- package/src/review/preflight.ts +3575 -0
- package/src/review/prompt-set.ts +177 -0
- package/src/review/proof-refs.ts +187 -0
- package/src/review/report.ts +1821 -0
- package/src/review/review.ts +490 -0
- package/src/review/root-cause.ts +120 -0
- package/src/review/route-preflight.ts +289 -0
- package/src/review/run.ts +601 -0
- package/src/review/scout.ts +323 -0
- package/src/review/size-gate.ts +595 -0
- package/src/review/spec.ts +235 -0
- package/src/review/step-runner.ts +233 -0
- package/src/runner-authority.ts +596 -0
- package/src/security/binding-policy.ts +115 -0
- package/src/security/credential-broker.ts +773 -0
- package/src/security/evidence-redaction.ts +62 -0
- package/src/security/execution-authority.ts +27 -0
- package/src/security/redact.ts +71 -0
- package/src/security/workspace-read-broker.ts +466 -0
- package/src/server/client.ts +190 -0
- package/src/server/preflight.ts +217 -0
- package/src/server/server.ts +327 -0
- package/src/signal-handler.ts +50 -0
- package/src/store/activity.ts +413 -0
- package/src/store/backfill-preflight.ts +49 -0
- package/src/store/backfill.ts +141 -0
- package/src/store/gc-preflight.ts +206 -0
- package/src/store/gc.ts +424 -0
- package/src/store/metrics-preflight.ts +229 -0
- package/src/store/metrics.ts +236 -0
- package/src/store/preflight.ts +748 -0
- package/src/store/store.ts +693 -0
- package/src/system-tools.ts +355 -0
- package/src/transport-registry.ts +1124 -0
- package/src/transports/claude-code-cli.ts +1348 -0
- package/src/transports/opencode-admission.ts +515 -0
- package/src/transports/opencode-client.ts +3328 -0
- package/src/transports/opencode-evidence.ts +557 -0
- package/src/transports/opencode-mcp.ts +248 -0
- package/src/transports/opencode-sdk.ts +2294 -0
- package/src/transports/opencode-server.ts +535 -0
- package/src/triage/adjudication.ts +113 -0
- package/src/triage/reply.ts +125 -0
- package/src/triage/triage.ts +255 -0
- package/src/ui/activity.ts +173 -0
- package/src/ui/config-edit.ts +816 -0
- package/src/ui/config.ts +462 -0
- package/src/ui/menu.ts +1325 -0
- package/src/ui/plan.ts +1039 -0
- package/src/ui/primitives.ts +300 -0
- package/src/ui/progress.ts +298 -0
- package/src/ui/result.ts +552 -0
- package/src/ui/review-menu.ts +312 -0
- package/src/ui/select.ts +528 -0
- package/src/ui/tree.ts +178 -0
- package/src/uninstaller.ts +479 -0
- package/src/updater.ts +836 -0
- package/src/usage.ts +77 -0
- package/src/watch/preflight.ts +1389 -0
- package/src/watch/watch.ts +1235 -0
- 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.";
|