pantheon-opencode 1.6.3-beta.1 → 1.6.3-beta.11

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 (54) hide show
  1. package/AGENTS.global.md +1 -1
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +81 -0
  4. package/README.md +20 -2
  5. package/bin/pantheon-init.mjs +15 -27
  6. package/package.json +1 -1
  7. package/plugin.json +1 -1
  8. package/pyproject.toml +1 -1
  9. package/scripts/decision-router-budget.mjs +103 -4
  10. package/scripts/decision-router-v2-budget.mjs +2 -2
  11. package/scripts/decision-router-v2-egress.mjs +0 -2
  12. package/scripts/decision-router.mjs +88 -6
  13. package/scripts/install/decision-router-config.mjs +53 -2
  14. package/scripts/install/interactive.mjs +96 -11
  15. package/scripts/install/opencode.mjs +26 -0
  16. package/scripts/install/plugin.mjs +17 -0
  17. package/scripts/jev-live-probe.mjs +210 -0
  18. package/scripts/skill-search.mjs +242 -0
  19. package/scripts/sync-tui.mjs +11 -0
  20. package/src/agents/aphrodite.md +34 -1
  21. package/src/agents/apollo.md +227 -0
  22. package/src/agents/athena.md +24 -0
  23. package/src/agents/demeter.md +33 -0
  24. package/src/agents/gaia.md +24 -0
  25. package/src/agents/hephaestus.md +24 -0
  26. package/src/agents/hermes.md +33 -0
  27. package/src/agents/iris.md +24 -0
  28. package/src/agents/mnemosyne.md +25 -3
  29. package/src/agents/nyx.md +53 -22
  30. package/src/agents/prometheus.md +242 -1
  31. package/src/agents/talos.md +24 -0
  32. package/src/agents/themis.md +24 -0
  33. package/src/agents/zeus.md +46 -6
  34. package/src/pantheon/j-telemetry-file.ts +96 -0
  35. package/src/pantheon/jev-decision-tool.ts +160 -24
  36. package/src/pantheon/jev-decisions.ts +18 -3
  37. package/src/pantheon/jev-rank-verify.ts +435 -0
  38. package/src/pantheon/jev-risk-gate.ts +1 -0
  39. package/src/pantheon/local-decision-budget.ts +170 -5
  40. package/src/pantheon/local-decision-provider-matrix.ts +0 -1
  41. package/src/pantheon/local-decision-usage-evidence.internal.ts +2 -2
  42. package/src/pantheon/v2-decision-budget.ts +4 -2
  43. package/src/plugin-v2.ts +9 -2
  44. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  45. package/src/plugins/tui/dist/tui-v2.js +457 -4
  46. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  47. package/src/plugins/tui/dist/tui.js +1 -1
  48. package/src/plugins/tui/package-lock.json +2 -2
  49. package/src/plugins/tui/package.json +1 -1
  50. package/src/plugins/tui/src/index-v2.tsx +6 -0
  51. package/src/plugins/tui/src/whats-new-highlights.ts +263 -0
  52. package/src/plugins/tui/src/whats-new-open.ts +80 -0
  53. package/src/plugins/tui/src/whats-new-state.ts +128 -0
  54. package/src/plugins/tui/src/whats-new.tsx +119 -0
@@ -0,0 +1,435 @@
1
+ /**
2
+ * The v3.1 rank and verify primitives on the native Jev route (tool modes on
3
+ * `pantheon_jev_decide`, built after the J4 review-mode pattern).
4
+ *
5
+ * ## Rank — `mode: "rank"`, one choice + one score, `{ winner, winnerFit }`
6
+ *
7
+ * Zeus can rank 2–8 named candidates for a state in ONE typed round-trip: one
8
+ * `choice` question (`winner`) over the candidate ids picks the best candidate
9
+ * and one `score` question (`fit`, the 2..10 rubric bound) rates that
10
+ * candidate's fit. THE HONEST LIMITATION: the host Decisions API returns one
11
+ * scalar answer per question (`NativeDecisionRequest` is tied to the 2.2.5
12
+ * host types), so per-candidate scores are not expressible in a single
13
+ * round-trip — one score question per candidate would break the 4-question
14
+ * bound above four candidates, and one ambiguous "score each candidate"
15
+ * question has no per-candidate answer structure to pair back. Rank therefore
16
+ * returns `{ winner, winnerFit }` and NOTHING more: no runner-up, no full
17
+ * ordering. A caller that needs a deeper order uses the explicit-questions
18
+ * mode with its own typed questions.
19
+ *
20
+ * ## Verify — `mode: "verify"`, one predicate per claim, fail-closed BLOCK
21
+ *
22
+ * Zeus can check 1–4 named claims in ONE typed round-trip: one `predicate`
23
+ * question per claim (within the 4-question bound), the claim text riding that
24
+ * question's instructions. The consumer maps each answer: probability
25
+ * ≥ {@link VERIFY_PASS_THRESHOLD} → `PASS`, below → `FAIL`, and every refusal,
26
+ * timeout, duplicate or malformed answer → `BLOCK` (fail-closed: an
27
+ * unanswered mandatory claim must never read as verified). The tool itself
28
+ * never acts on a verdict — `effect` stays `none` — and a gate-chain refusal
29
+ * stays the standard bounded refusal JSON; a caller that REQUIRES a verdict
30
+ * treats every refusal as `BLOCK` at its own call site.
31
+ *
32
+ * ## Sanitization contract (the J4 criteria class)
33
+ *
34
+ * Both modes take bounded caller-provided fields only: rank's candidate ids
35
+ * are strict tokens (they become choice values), its state rides the same
36
+ * 12,000-char bound and verbatim-carriage rule as the presets, and verify's
37
+ * claim texts are the only free text, riding the predicate instructions. The
38
+ * hostility scan mirrors the J4 criteria scan (paths, credential assignments,
39
+ * key material, control characters, over-length): hostile shapes are REJECTED
40
+ * — `CANDIDATE_INVALID` / `CLAIM_INVALID` — never sanitized on the way in.
41
+ * Neither mode has a telemetry point (they are tool modes, not shadow gates)
42
+ * and both reuse the tool's strict answer consumer
43
+ * (`consumeJevDecisionResult`): one answer per question name, duplicates
44
+ * become errors, unbounded host metadata never crosses.
45
+ *
46
+ * @module jev-rank-verify
47
+ */
48
+
49
+ import { consumeJevDecisionResult } from './jev-decisions.ts'
50
+ import type { NativeDecisionRequest, ResolvedNativeDecisionRoute } from './v2-native-decisions.ts'
51
+ import { NATIVE_DECISION_MAX_PROMPT_LENGTH } from './v2-native-decisions.ts'
52
+
53
+ // ─── Bounds ──────────────────────────────────────────────────────────────
54
+
55
+ /** A ranking needs at least two candidates to choose between. */
56
+ export const RANK_MIN_CANDIDATES = 2
57
+ /** Above eight, ranking degrades to explicit questions with a real rubric. */
58
+ export const RANK_MAX_CANDIDATES = 8
59
+
60
+ /** Question name of the rank's choice question. */
61
+ export const RANK_WINNER_QUESTION_NAME = 'winner'
62
+ /** Question name of the rank's fit score question. */
63
+ export const RANK_FIT_QUESTION_NAME = 'fit'
64
+
65
+ /** The fit rubric mirrors the documented 2..10 score-question bound. */
66
+ export const RANK_FIT_LEVEL_COUNT = 9
67
+
68
+ /** At least one claim per verify call; one predicate question per claim. */
69
+ export const VERIFY_MIN_CLAIMS = 1
70
+ /** One predicate question per claim, within the 4-question bound. */
71
+ export const VERIFY_MAX_CLAIMS = 4
72
+ /** Each claim is a bounded 1–200-char instruction string. */
73
+ export const CLAIM_MAX_LENGTH = 200
74
+
75
+ /** Predicate probability at or above which a claim counts as PASS. */
76
+ export const VERIFY_PASS_THRESHOLD = 0.5
77
+
78
+ const CANDIDATE_ID_MAX_LENGTH = 64
79
+ const CLAIM_NAME_MAX_LENGTH = 64
80
+ const DESCRIPTION_MAX_LENGTH = 500
81
+
82
+ /** Candidate ids become choice values: strict bounded tokens only. */
83
+ const TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/
84
+
85
+ const RANK_FIT_LABELS: readonly string[] = Object.freeze([
86
+ 'unusable',
87
+ 'poor',
88
+ 'weak',
89
+ 'fair',
90
+ 'adequate',
91
+ 'good',
92
+ 'strong',
93
+ 'excellent',
94
+ 'exemplary',
95
+ ])
96
+
97
+ const WINNER_INSTRUCTIONS =
98
+ 'Choose the single best candidate from the listed options for the described state. ' +
99
+ 'Answer with exactly one candidate id. Advisory only; nothing is dispatched or executed.'
100
+
101
+ const FIT_INSTRUCTIONS =
102
+ 'Rate how well the candidate you chose as the best fits the described state. ' +
103
+ 'Higher means a better fit; judge from the state and the candidate descriptions alone. ' +
104
+ 'Advisory only; nothing is enforced.'
105
+
106
+ /**
107
+ * The verify request's only input part: a fixed template with NO free-text
108
+ * slot — the claims ride the predicate questions' instructions, so the state
109
+ * part cannot carry them twice (or be mistaken for a content field).
110
+ */
111
+ const VERIFY_STATE_TEMPLATE =
112
+ 'Advisory claim verification. Each claim is stated in its own question below; ' +
113
+ 'assess each claim on its own terms from the claim text alone. Nothing is enforced.'
114
+
115
+ // ─── Hostility scan (mirrors the J4 criteria scan) ───────────────────────
116
+
117
+ /** Path separators in any position: caller prose is never a location. */
118
+ const PATH_PATTERN = /[/\\]/
119
+
120
+ /**
121
+ * Control characters (C0 and DEL — newlines and tabs included): these are
122
+ * single-line prose fields. An explicit code-point scan, not a regex, so the
123
+ * hostile-input check stays lint-clean without a rule suppression.
124
+ */
125
+ function hasControlCharacter(value: string): boolean {
126
+ for (let index = 0; index < value.length; index += 1) {
127
+ const code = value.charCodeAt(index)
128
+ if (code <= 0x1f || code === 0x7f) return true
129
+ }
130
+ return false
131
+ }
132
+
133
+ /** Key material shapes: PEM headers, AWS/SDK/Git token literals, key files. */
134
+ const KEY_MATERIAL_PATTERNS: readonly RegExp[] = Object.freeze([
135
+ /-----BEGIN/,
136
+ /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/,
137
+ /\bsk-[A-Za-z0-9_-]{16,}\b/,
138
+ /\bgh[pousr]_[A-Za-z0-9]{20,}\b/,
139
+ /\b[a-z0-9._-]+\.(?:key|pem|p12|pfx|kdbx)\b/i,
140
+ ])
141
+
142
+ /**
143
+ * Credential ASSIGNMENT shapes only: naming a concept is prose ("handles
144
+ * secrets without echoing them" stays admissible); binding a value to it
145
+ * ("password=hunter2") is a credential shape and is rejected.
146
+ */
147
+ const CREDENTIAL_ASSIGNMENT_PATTERN =
148
+ /\b(?:password|passwd|secret|token|api[-_]?key|credential)s?\s*[:=]\s*\S+/i
149
+
150
+ function isHostileProse(value: string): boolean {
151
+ if (PATH_PATTERN.test(value)) return true
152
+ if (hasControlCharacter(value)) return true
153
+ if (KEY_MATERIAL_PATTERNS.some((pattern) => pattern.test(value))) return true
154
+ return CREDENTIAL_ASSIGNMENT_PATTERN.test(value)
155
+ }
156
+
157
+ function isBoundedNonBlankString(value: unknown, max: number): value is string {
158
+ return typeof value === 'string' && value.trim().length > 0 && value.length <= max
159
+ }
160
+
161
+ function isRecord(value: unknown): value is Record<string, unknown> {
162
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
163
+ }
164
+
165
+ // ─── Rank: request building ──────────────────────────────────────────────
166
+
167
+ const RANK_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
168
+ 'schemaVersion',
169
+ 'mode',
170
+ 'state',
171
+ 'candidates',
172
+ ])
173
+
174
+ export type JevRankBuildFailure = 'RANK_INPUT_INVALID' | 'CANDIDATE_INVALID' | 'STATE_INVALID'
175
+
176
+ export type JevRankBuild =
177
+ | { readonly ok: true; readonly request: Omit<NativeDecisionRequest, 'model'> }
178
+ | { readonly ok: false; readonly reasonCode: JevRankBuildFailure }
179
+
180
+ export type JevRankPreparation =
181
+ | { readonly ok: true; readonly request: NativeDecisionRequest }
182
+ | { readonly ok: false; readonly reasonCode: JevRankBuildFailure }
183
+
184
+ /**
185
+ * Validate the rank tool input and build the model-less request. The state is
186
+ * carried verbatim under the same bound and rule as the presets; the
187
+ * candidates ride the winner question's choice values (ids, strict tokens)
188
+ * and choice descriptions (bounded prose, hostility-scanned). Unknown
189
+ * envelope keys — `questions`, review fields, anything else — refuse the
190
+ * preparation: no second payload slot exists.
191
+ */
192
+ export function buildJevRankRequest(input: unknown): JevRankBuild {
193
+ if (!isRecord(input)) return { ok: false, reasonCode: 'RANK_INPUT_INVALID' }
194
+ for (const key of Object.keys(input)) {
195
+ if (!RANK_ENVELOPE_KEYS.has(key)) return { ok: false, reasonCode: 'RANK_INPUT_INVALID' }
196
+ }
197
+ const state = input.state
198
+ if (!isBoundedNonBlankString(state, NATIVE_DECISION_MAX_PROMPT_LENGTH)) {
199
+ return { ok: false, reasonCode: 'STATE_INVALID' }
200
+ }
201
+ const rawCandidates = input.candidates
202
+ // A MISSING candidates field is a malformed rank; a PRESENT-but-hostile
203
+ // candidates array keeps its precise CANDIDATE_INVALID (the review-mode
204
+ // discipline).
205
+ if (rawCandidates === undefined) return { ok: false, reasonCode: 'RANK_INPUT_INVALID' }
206
+ if (!Array.isArray(rawCandidates)) return { ok: false, reasonCode: 'CANDIDATE_INVALID' }
207
+ if (rawCandidates.length < RANK_MIN_CANDIDATES || rawCandidates.length > RANK_MAX_CANDIDATES) {
208
+ return { ok: false, reasonCode: 'CANDIDATE_INVALID' }
209
+ }
210
+ const seen = new Set<string>()
211
+ const choices: Array<{ value: string; description?: string }> = []
212
+ for (const raw of rawCandidates) {
213
+ if (!isRecord(raw)) return { ok: false, reasonCode: 'CANDIDATE_INVALID' }
214
+ const extraKeys = Object.keys(raw).filter((key) => key !== 'id' && key !== 'description')
215
+ if (extraKeys.length > 0) return { ok: false, reasonCode: 'CANDIDATE_INVALID' }
216
+ const id = raw.id
217
+ if (
218
+ typeof id !== 'string' ||
219
+ id.length > CANDIDATE_ID_MAX_LENGTH ||
220
+ !TOKEN_PATTERN.test(id) ||
221
+ seen.has(id)
222
+ ) {
223
+ return { ok: false, reasonCode: 'CANDIDATE_INVALID' }
224
+ }
225
+ seen.add(id)
226
+ const description = raw.description
227
+ if (description === undefined) {
228
+ choices.push({ value: id })
229
+ } else if (
230
+ isBoundedNonBlankString(description, DESCRIPTION_MAX_LENGTH) &&
231
+ !isHostileProse(description)
232
+ ) {
233
+ choices.push({ value: id, description })
234
+ } else {
235
+ return { ok: false, reasonCode: 'CANDIDATE_INVALID' }
236
+ }
237
+ }
238
+ const request = {
239
+ input: Object.freeze([Object.freeze({ type: 'text' as const, text: state })]),
240
+ questions: Object.freeze([
241
+ Object.freeze({
242
+ type: 'choice' as const,
243
+ name: RANK_WINNER_QUESTION_NAME,
244
+ instructions: WINNER_INSTRUCTIONS,
245
+ choices: Object.freeze(choices.map((choice) => Object.freeze(choice))),
246
+ }),
247
+ Object.freeze({
248
+ type: 'score' as const,
249
+ name: RANK_FIT_QUESTION_NAME,
250
+ instructions: FIT_INSTRUCTIONS,
251
+ levels: Object.freeze(RANK_FIT_LABELS.map((label) => Object.freeze({ label }))),
252
+ }),
253
+ ]),
254
+ } satisfies Omit<NativeDecisionRequest, 'model'>
255
+ return { ok: true, request: Object.freeze(request) }
256
+ }
257
+
258
+ /** `prepareJevPresetRequest` contract: route plus tool input in, request out. */
259
+ export function prepareJevRankRequest(
260
+ route: ResolvedNativeDecisionRoute,
261
+ input: unknown,
262
+ ): JevRankPreparation {
263
+ const built = buildJevRankRequest(input)
264
+ if (!built.ok) return built
265
+ return {
266
+ ok: true,
267
+ request: {
268
+ model: route.model,
269
+ input: built.request.input,
270
+ questions: built.request.questions,
271
+ },
272
+ }
273
+ }
274
+
275
+ // ─── Verify: request building ────────────────────────────────────────────
276
+
277
+ const VERIFY_ENVELOPE_KEYS: ReadonlySet<string> = new Set(['schemaVersion', 'mode', 'claims'])
278
+
279
+ export type JevVerifyBuildFailure = 'VERIFY_INPUT_INVALID' | 'CLAIM_INVALID'
280
+
281
+ export type JevVerifyBuild =
282
+ | { readonly ok: true; readonly request: Omit<NativeDecisionRequest, 'model'> }
283
+ | { readonly ok: false; readonly reasonCode: JevVerifyBuildFailure }
284
+
285
+ export type JevVerifyPreparation =
286
+ | { readonly ok: true; readonly request: NativeDecisionRequest }
287
+ | { readonly ok: false; readonly reasonCode: JevVerifyBuildFailure }
288
+
289
+ function verifyInstructions(claim: string): string {
290
+ return (
291
+ 'Assess the following claim on its own terms and answer the probability that it holds. ' +
292
+ `Claim: "${claim}". Higher means the claim is more likely to hold. ` +
293
+ 'This is advisory verification; nothing is enforced.'
294
+ )
295
+ }
296
+
297
+ /**
298
+ * Validate the verify tool input and build the model-less request: one
299
+ * predicate question per claim, named after the claim, the claim text riding
300
+ * that question's instructions. The verify mode takes NO state text — any
301
+ * smuggled slot (`state`, `candidates`, review fields) refuses the
302
+ * preparation `VERIFY_INPUT_INVALID`; hostile claim shapes keep the precise
303
+ * `CLAIM_INVALID`.
304
+ */
305
+ export function buildJevVerifyRequest(input: unknown): JevVerifyBuild {
306
+ if (!isRecord(input)) return { ok: false, reasonCode: 'VERIFY_INPUT_INVALID' }
307
+ for (const key of Object.keys(input)) {
308
+ if (!VERIFY_ENVELOPE_KEYS.has(key)) return { ok: false, reasonCode: 'VERIFY_INPUT_INVALID' }
309
+ }
310
+ const rawClaims = input.claims
311
+ if (rawClaims === undefined) return { ok: false, reasonCode: 'VERIFY_INPUT_INVALID' }
312
+ if (!Array.isArray(rawClaims)) return { ok: false, reasonCode: 'CLAIM_INVALID' }
313
+ if (rawClaims.length < VERIFY_MIN_CLAIMS || rawClaims.length > VERIFY_MAX_CLAIMS) {
314
+ return { ok: false, reasonCode: 'CLAIM_INVALID' }
315
+ }
316
+ const seen = new Set<string>()
317
+ const questions: Array<{
318
+ type: 'predicate'
319
+ name: string
320
+ instructions: string
321
+ }> = []
322
+ for (const raw of rawClaims) {
323
+ if (!isRecord(raw)) return { ok: false, reasonCode: 'CLAIM_INVALID' }
324
+ const extraKeys = Object.keys(raw).filter((key) => key !== 'name' && key !== 'claim')
325
+ if (extraKeys.length > 0) return { ok: false, reasonCode: 'CLAIM_INVALID' }
326
+ const name = raw.name
327
+ if (
328
+ typeof name !== 'string' ||
329
+ name.length > CLAIM_NAME_MAX_LENGTH ||
330
+ !TOKEN_PATTERN.test(name) ||
331
+ seen.has(name)
332
+ ) {
333
+ return { ok: false, reasonCode: 'CLAIM_INVALID' }
334
+ }
335
+ const claim = raw.claim
336
+ if (!isBoundedNonBlankString(claim, CLAIM_MAX_LENGTH) || isHostileProse(claim)) {
337
+ return { ok: false, reasonCode: 'CLAIM_INVALID' }
338
+ }
339
+ seen.add(name)
340
+ questions.push({ type: 'predicate', name, instructions: verifyInstructions(claim) })
341
+ }
342
+ const request = {
343
+ input: Object.freeze([Object.freeze({ type: 'text' as const, text: VERIFY_STATE_TEMPLATE })]),
344
+ questions: Object.freeze(questions.map((question) => Object.freeze(question))),
345
+ } satisfies Omit<NativeDecisionRequest, 'model'>
346
+ return { ok: true, request: Object.freeze(request) }
347
+ }
348
+
349
+ /** `prepareJevPresetRequest` contract: route plus tool input in, request out. */
350
+ export function prepareJevVerifyRequest(
351
+ route: ResolvedNativeDecisionRoute,
352
+ input: unknown,
353
+ ): JevVerifyPreparation {
354
+ const built = buildJevVerifyRequest(input)
355
+ if (!built.ok) return built
356
+ return {
357
+ ok: true,
358
+ request: {
359
+ model: route.model,
360
+ input: built.request.input,
361
+ questions: built.request.questions,
362
+ },
363
+ }
364
+ }
365
+
366
+ // ─── Consumption ─────────────────────────────────────────────────────────
367
+
368
+ export interface JevRankVerdict {
369
+ /**
370
+ * The host's chosen candidate id; `null` when the answer is missing,
371
+ * mistyped, duplicated, an error, or outside the prepared candidate ids.
372
+ */
373
+ readonly winner: string | null
374
+ /**
375
+ * The host's fit score for the winner, on the prepared 2..10 rubric;
376
+ * `null` under the same failures.
377
+ */
378
+ readonly winnerFit: number | null
379
+ }
380
+
381
+ /**
382
+ * Consume a host Decisions response against the prepared rank request.
383
+ * Strict validation is borrowed wholesale from the tool's consumer
384
+ * (`consumeJevDecisionResult`): an answer counts only when its name and type
385
+ * match the prepared questions, duplicates become errors, and anything else
386
+ * is `null`, never a guess.
387
+ */
388
+ export function consumeJevRankResult(
389
+ response: unknown,
390
+ request: NativeDecisionRequest,
391
+ ): JevRankVerdict {
392
+ const advice = consumeJevDecisionResult(response, request)
393
+ let winner: string | null = null
394
+ let winnerFit: number | null = null
395
+ for (const answer of advice.answers) {
396
+ if (answer.type === 'error') continue
397
+ if (answer.type === 'choice' && answer.name === RANK_WINNER_QUESTION_NAME) {
398
+ winner = answer.choice ?? null
399
+ } else if (answer.type === 'score' && answer.name === RANK_FIT_QUESTION_NAME) {
400
+ winnerFit = answer.score ?? null
401
+ }
402
+ }
403
+ return Object.freeze({ winner, winnerFit })
404
+ }
405
+
406
+ /**
407
+ * The verdict of one verified claim. `BLOCK` is the fail-closed answer: a
408
+ * host refusal, timeout, duplicate or malformed reply must never read as
409
+ * verified (or as refuted — an unverifiable claim is unverifiable, not
410
+ * false).
411
+ */
412
+ export type VerifyClaimVerdict = 'PASS' | 'FAIL' | 'BLOCK'
413
+
414
+ /**
415
+ * Consume a host Decisions response against the prepared verify request:
416
+ * one verdict per claim name. Probability ≥ {@link VERIFY_PASS_THRESHOLD} is
417
+ * `PASS`, below is `FAIL`; error answers, missing answers and any unusable
418
+ * response shape are `BLOCK` — fail-closed.
419
+ */
420
+ export function consumeJevVerifyResult(
421
+ response: unknown,
422
+ request: NativeDecisionRequest,
423
+ ): Readonly<Record<string, VerifyClaimVerdict>> {
424
+ const advice = consumeJevDecisionResult(response, request)
425
+ const verdicts: Record<string, VerifyClaimVerdict> = {}
426
+ for (const question of request.questions) {
427
+ const answer = advice.answers.find((candidate) => candidate.name === question.name)
428
+ if (answer !== undefined && answer.type === 'predicate') {
429
+ verdicts[question.name] = (answer.probability ?? 0) >= VERIFY_PASS_THRESHOLD ? 'PASS' : 'FAIL'
430
+ } else {
431
+ verdicts[question.name] = 'BLOCK'
432
+ }
433
+ }
434
+ return Object.freeze(verdicts)
435
+ }
@@ -349,6 +349,7 @@ const SKIP_REASON_BY_GATE_FAILURE: Readonly<Record<GatedNativeJevFailure, string
349
349
  PRESET_INVALID: 'skip-request-invalid',
350
350
  RESERVATION_DENIED: 'skip-reservation-denied',
351
351
  DECISION_CALL_FAILED: 'skip-decision-call-failed',
352
+ USAGE_EVIDENCE_UNAVAILABLE: 'skip-usage-evidence-unavailable',
352
353
  USAGE_UNRECONCILED: 'skip-usage-unreconciled',
353
354
  })
354
355
 
@@ -13,7 +13,6 @@ export type BudgetProvider =
13
13
  | 'openai-decisions'
14
14
  | 'typesafe-jev'
15
15
  | 'opencode-console'
16
- | 'jev-free'
17
16
  | 'openrouter'
18
17
  | 'vercel-ai-gateway'
19
18
  | 'cloudflare-workers-ai'
@@ -83,6 +82,20 @@ export interface UncertainReservation {
83
82
  updatedAtMs: number
84
83
  }
85
84
 
85
+ export interface ReleasedHold {
86
+ reservationId: string
87
+ provider: string
88
+ model: string
89
+ period: string
90
+ reservedMicros: number
91
+ stateAtRelease: 'pending' | 'uncertain'
92
+ reason: string
93
+ createdAtMs: number
94
+ releasedAtMs: number
95
+ }
96
+
97
+ export type ReleaseHoldsResult = { released: number; freedMicros: number }
98
+
86
99
  export interface LocalDecisionBudgetLedger {
87
100
  /** Admin/configuration API: writes policy to the local user-level DB. */
88
101
  configureUserCaps(caps: BudgetCaps): void
@@ -108,6 +121,16 @@ export interface LocalDecisionBudgetLedger {
108
121
  listUncertainReservations(): UncertainReservation[]
109
122
  /** Recovery only moves pending rows to uncertain; it never releases budget. */
110
123
  recoverPendingReservations(): number
124
+ /**
125
+ * Release every unresolved hold of one provider, archiving each row into
126
+ * `released_holds` with the mandatory reason. Deliberately narrow: this is
127
+ * the administrative correction for holds of routes that no longer exist
128
+ * (they can never reconcile, so they would freeze budget forever). Live
129
+ * providers roll their holds off with the period instead.
130
+ */
131
+ releaseHoldsForProvider(provider: string, reason: string): ReleaseHoldsResult
132
+ /** Recent archived releases, newest first — the audit view of the above. */
133
+ listReleasedHolds(limit?: number): ReleasedHold[]
111
134
  /** Prune resolved reservations from past UTC periods with no unresolved holds. */
112
135
  pruneCompletedPeriods(): number
113
136
  close(): void
@@ -124,22 +147,23 @@ export interface OpenLocalDecisionBudgetOptions {
124
147
  busyTimeoutMs?: number
125
148
  }
126
149
 
127
- const SCHEMA_VERSION = 3
150
+ const SCHEMA_VERSION = 4
128
151
  const VERSION_TWO = 2
129
152
  const APPLICATION_ID = 0x50424c31
153
+ /** Reason strings recorded on a released hold are bounded for the audit trail. */
154
+ const RELEASE_REASON_MAX_LENGTH = 200
130
155
  const DB_FILENAME = 'decision-budget.sqlite'
131
156
  /** Accounting provider IDs accepted by the ledger. */
132
157
  export const LOCAL_DECISION_BUDGET_PROVIDERS: readonly BudgetProvider[] = Object.freeze([
133
158
  'openai-decisions',
134
159
  'typesafe-jev',
135
160
  'opencode-console',
136
- 'jev-free',
137
161
  'openrouter',
138
162
  'vercel-ai-gateway',
139
163
  'cloudflare-workers-ai',
140
164
  ])
141
165
  const ALLOWED_PROVIDERS = new Set<BudgetProvider>(LOCAL_DECISION_BUDGET_PROVIDERS)
142
- const MODEL_KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
166
+ const MODEL_KEY = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/
143
167
  const RESERVATION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
144
168
  const CLOCK_ROLLBACK_TOLERANCE_MS = 60_000
145
169
 
@@ -610,6 +634,101 @@ export function openLocalDecisionBudgetLedger(
610
634
  })
611
635
  }
612
636
 
637
+ function releaseHoldsForProvider(provider: string, reason: string): ReleaseHoldsResult {
638
+ if (typeof provider !== 'string' || provider.length < 1 || provider.length > 64) {
639
+ return { released: 0, freedMicros: 0 }
640
+ }
641
+ if (
642
+ typeof reason !== 'string' ||
643
+ reason.length < 1 ||
644
+ reason.length > RELEASE_REASON_MAX_LENGTH
645
+ ) {
646
+ return { released: 0, freedMicros: 0 }
647
+ }
648
+ return inImmediateTransaction(() => {
649
+ const timestamp = now()
650
+ const rows = db
651
+ .prepare(
652
+ `SELECT id, provider, model, period_utc, reserved_micros, state, created_at_ms
653
+ FROM reservations WHERE provider = ? AND state IN ('pending', 'uncertain')
654
+ ORDER BY created_at_ms, id`,
655
+ )
656
+ .all(provider) as Array<{
657
+ id: string
658
+ provider: string
659
+ model: string
660
+ period_utc: string
661
+ reserved_micros: number
662
+ state: 'pending' | 'uncertain'
663
+ created_at_ms: number
664
+ }>
665
+ if (rows.length === 0) return { released: 0, freedMicros: 0 }
666
+ const archive = db.prepare(
667
+ `INSERT INTO released_holds
668
+ (reservation_id, provider, model, period_utc, reserved_micros, state_at_release,
669
+ reason, created_at_ms, released_at_ms)
670
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
671
+ )
672
+ let freedMicros = 0
673
+ for (const row of rows) {
674
+ archive.run(
675
+ row.id,
676
+ row.provider,
677
+ row.model,
678
+ row.period_utc,
679
+ row.reserved_micros,
680
+ row.state,
681
+ reason,
682
+ row.created_at_ms,
683
+ timestamp,
684
+ )
685
+ freedMicros = safeMicrosTotal(freedMicros + row.reserved_micros)
686
+ }
687
+ const remove = db
688
+ .prepare(
689
+ `DELETE FROM reservations WHERE provider = ? AND state IN ('pending', 'uncertain')`,
690
+ )
691
+ .run(provider)
692
+ if (safeChangeCount(remove.changes) !== rows.length) {
693
+ throw new Error('Reservation rows changed during release')
694
+ }
695
+ return { released: rows.length, freedMicros }
696
+ })
697
+ }
698
+
699
+ function listReleasedHolds(limit?: number): ReleasedHold[] {
700
+ const bound =
701
+ typeof limit === 'number' && Number.isInteger(limit) && limit > 0 ? Math.min(limit, 200) : 20
702
+ const rows = db
703
+ .prepare(
704
+ `SELECT reservation_id, provider, model, period_utc, reserved_micros, state_at_release,
705
+ reason, created_at_ms, released_at_ms
706
+ FROM released_holds ORDER BY released_at_ms DESC, reservation_id LIMIT ?`,
707
+ )
708
+ .all(bound) as Array<{
709
+ reservation_id: string
710
+ provider: string
711
+ model: string
712
+ period_utc: string
713
+ reserved_micros: number
714
+ state_at_release: string
715
+ reason: string
716
+ created_at_ms: number
717
+ released_at_ms: number
718
+ }>
719
+ return rows.map((row) => ({
720
+ reservationId: row.reservation_id,
721
+ provider: row.provider,
722
+ model: row.model,
723
+ period: row.period_utc,
724
+ reservedMicros: row.reserved_micros,
725
+ stateAtRelease: row.state_at_release === 'uncertain' ? 'uncertain' : 'pending',
726
+ reason: row.reason,
727
+ createdAtMs: row.created_at_ms,
728
+ releasedAtMs: row.released_at_ms,
729
+ }))
730
+ }
731
+
613
732
  function pruneCompletedPeriods(): number {
614
733
  return inImmediateTransaction(() => {
615
734
  let currentPeriod: string
@@ -677,6 +796,8 @@ export function openLocalDecisionBudgetLedger(
677
796
  reconcileVerified,
678
797
  listUncertainReservations,
679
798
  recoverPendingReservations,
799
+ releaseHoldsForProvider,
800
+ listReleasedHolds,
680
801
  pruneCompletedPeriods,
681
802
  close: () => db.close(),
682
803
  }
@@ -701,12 +822,16 @@ function ensureSchema(db: DatabaseSync): void {
701
822
  if (applicationId !== 0 || tables.length !== 0) {
702
823
  throw new Error('Refusing to initialize an unrecognized SQLite database')
703
824
  }
704
- createSchemaV3(db)
825
+ createSchemaV4(db)
705
826
  } else if (version === 1 && applicationId === APPLICATION_ID) {
706
827
  migrateVersionOne(db)
707
828
  migrateVersionTwoToThree(db)
829
+ migrateVersionThreeToFour(db)
708
830
  } else if (version === VERSION_TWO && applicationId === APPLICATION_ID) {
709
831
  migrateVersionTwoToThree(db)
832
+ migrateVersionThreeToFour(db)
833
+ } else if (version === 3 && applicationId === APPLICATION_ID) {
834
+ migrateVersionThreeToFour(db)
710
835
  } else if (version !== SCHEMA_VERSION || applicationId !== APPLICATION_ID) {
711
836
  throw new Error('Unsupported or incompatible local decision budget database schema')
712
837
  }
@@ -804,10 +929,50 @@ function migrateVersionTwoToThree(db: DatabaseSync): void {
804
929
  INSERT INTO ledger_state (id, active_period_utc)
805
930
  SELECT id, NULL FROM ledger_state_v2;
806
931
  DROP TABLE ledger_state_v2;
932
+ PRAGMA user_version = 3;
933
+ `)
934
+ }
935
+
936
+ /**
937
+ * v4 adds the `released_holds` archive (immutable audit trail for the
938
+ * administrative release of dead-route holds). The live `reservations` table
939
+ * and its state CHECK are untouched — a release archives the row and deletes
940
+ * it, so the accounting keeps summing only live states.
941
+ */
942
+ function migrateVersionThreeToFour(db: DatabaseSync): void {
943
+ validateVersionThreeSchema(db)
944
+ db.exec(`
945
+ CREATE TABLE released_holds (
946
+ reservation_id TEXT PRIMARY KEY NOT NULL,
947
+ provider TEXT NOT NULL,
948
+ model TEXT NOT NULL,
949
+ period_utc TEXT NOT NULL CHECK (length(period_utc) = 7),
950
+ reserved_micros INTEGER NOT NULL CHECK (reserved_micros > 0),
951
+ state_at_release TEXT NOT NULL CHECK (state_at_release IN ('pending', 'uncertain')),
952
+ reason TEXT NOT NULL CHECK (length(reason) BETWEEN 1 AND ${RELEASE_REASON_MAX_LENGTH}),
953
+ created_at_ms INTEGER NOT NULL,
954
+ released_at_ms INTEGER NOT NULL
955
+ ) STRICT;
956
+ CREATE INDEX released_holds_released_idx ON released_holds (released_at_ms, reservation_id);
807
957
  PRAGMA user_version = ${SCHEMA_VERSION};
808
958
  `)
809
959
  }
810
960
 
961
+ function createSchemaV4(db: DatabaseSync): void {
962
+ createSchemaV3(db)
963
+ migrateVersionThreeToFour(db)
964
+ }
965
+
966
+ function validateVersionThreeSchema(db: DatabaseSync): void {
967
+ // The v3 tables match the post-migration shape; the v4 step adds
968
+ // released_holds on top of them.
969
+ db.prepare(
970
+ `SELECT id, provider, model, period_utc, reserved_micros, actual_micros, state,
971
+ created_at_ms, updated_at_ms FROM reservations LIMIT 0`,
972
+ )
973
+ db.prepare('SELECT id, active_period_utc FROM ledger_state LIMIT 0')
974
+ }
975
+
811
976
  function migrateVersionOne(db: DatabaseSync): void {
812
977
  validateVersionOneSchema(db)
813
978
  const providers = db