Budgets — จำกัดการลองใหม่และทางสำรองBound Retries, Repairs, and Fallback

Part 10 of twelve. Bound transport retries and semantic revisions with shared budgets, cancellation and a deterministic fallback.

Default decisions and draft text are authored mocks, not live Jev results. Use the tutorial with the matching companion code, tests and exercise linked to a fixed GitHub version.

Outcome and prerequisites

Use Node22.18+ and a terminal. Clone the GitHub companion using its README, or download the complete ZIP, extract it and enter ai-core-functional-lab. No npm install, API key or network inference is needed. The reading-time label excludes about25–45 minutes of hands-on work. Keep one reference copy and make exercises in another.

Download companion ZIP · README / lesson map

This part focuses on src/budget.mjs. Expected gate states describe content and continuation; no state sends a message or changes a real account.

Old functions and the new boundary

Transport retry and semantic revision solve different problems. A transient connection or selected HTTP error may justify retrying one attempt; an unsupported draft needs a new candidate or a fallback. Both spend resources, so a shared aggregate call budget owns every provider attempt.

The reference allows at most8provider calls,2drafts and1transport retry after an eligible initial failure. It uses100milliseconds per-call timeout for offline fixtures. These tiny teaching settings are not production latency targets or a guaranteed monetary spending cap.

SDK retries can multiply a seemingly small outer loop. The current official JavaScript SDK default maxRetries2 means three attempts, not two. This lab uses an optional one-attempt REST adapter instead of the SDK; wiring a live transport later requires reviewed backoff, retry-after and billing accounting.

Seven practical steps

Step 1

Read the aggregate budget check before the provider call. It consumes a unit before starting work and records an attempt even if the call fails. An error response must not erase potentially billable work.

Step 2

Run V009 and find two input attempts. The first simulated transient error is retryable; its usage is unknown. The second succeeds, but final success does not make the first attempt free.

Step 3

Run V001 with max-calls3. Input, generation and semantic output consume the available calls. Quality cannot start; the result must review with call_budget_exhausted rather than accepting an incompletely checked draft.

Step 4

Read timed and inspect its cancellation signal. Timeout aborts the in-flight operation and stops automatic continuation. A provider that ignores cancellation may still complete remotely, so cancellation is not a proof of zero charges.

Step 5

Run V007 and distinguish semantic revise from transport retry. The second candidate is an ordinary template fallback, not a new Jev-generated response. Its semantic and quality checks still consume remaining calls.

Step 6

Run tests for pre-start cancellation, in-flight cancellation, timeout, malformed adapter and aggregate-budget exhaustion during retries. No eligible retry is allowed to exceed the shared cap.

Step 7

Write the terminal policy before adding another fallback. In the reference, a permanent provider failure or uncertainty reviews; an exhausted revision budget also reviews. Do not add retry-until-pass behavior or treat repeated model checks as independent evidence.

Files and runnable commands

Open the exact source and read its dependencies before editing. This is runnable reference code, not a fictional AI-Core SDK. The source links point to a fixed version of the public GitHub companion.

src/budget.mjs · Matching tests · This lesson’s exercise

export class BudgetError extends Error {constructor(code){super(code);this.code=code}}
export async function timed(run,{signal,timeoutMs}) {
  if(signal?.aborted) throw new BudgetError('cancelled');
  const controller=new AbortController();
  let timer,listener;
  const stop=new Promise((_,reject)=>{
    timer=setTimeout(()=>{controller.abort();reject(new BudgetError('timeout'))},timeoutMs);
    listener=()=>{controller.abort();reject(new BudgetError('cancelled'))};
    signal?.addEventListener('abort',listener,{once:true});
  });
  try {return await Promise.race([Promise.resolve().then(()=>run(controller.signal)),stop])}
  finally {clearTimeout(timer);signal?.removeEventListener('abort',listener)}
}
export class CallBudget {
  constructor(policy,{signal}={}){this.policy=policy;this.signal=signal;this.attempts=[];this.used=0}
  async call(stage,request,provider) {
    for(let retry=0;retry<=this.policy.transportRetries;retry++) {
      if(this.signal?.aborted) throw new BudgetError('cancelled');
      if(this.used>=this.policy.maxCalls) throw new BudgetError('call_budget_exhausted');
      this.used++;
      const attempt={stage,transportAttempt:retry+1,evidence:'OFFLINE AUTHORED FIXTURE',usage:null,scenarioMs:null,status:'started'};
      this.attempts.push(attempt);
      try {
        const r=await timed(s=>provider(stage,request,{signal:s}),{signal:this.signal,timeoutMs:this.policy.timeoutMs});
        if(!r||!Object.hasOwn(r,'value')) throw new BudgetError('malformed_adapter');
        const u=r.usage;
        attempt.usage=u&&Number.isSafeInteger(u.input)&&u.input>=0&&Number.isSafeInteger(u.output)&&u.output>=0?{...u}:null;
        attempt.scenarioMs=Number.isFinite(r.scenarioMs)&&r.scenarioMs>=0?r.scenarioMs:null;
        attempt.evidence=r.evidence;attempt.value=structuredClone(r.value);attempt.returnedModel=r.value?.model??null;attempt.status='returned';return r.value;
      } catch(e) {
        attempt.status=e.code??'provider_error';
        if(e.code!=='E_TRANSIENT'||retry===this.policy.transportRetries) throw e;
      }
    }
  }
}

Offline commands:

node src/cli.mjs run --case V009
node src/cli.mjs run --case V001 --max-calls 3
node src/cli.mjs run --case V007
node --test --test-reporter=spec test/budget.test.mjs

Expected output and verification

V009 accepts after one counted transport retry. V001 with three calls reviews before quality. V007 shows a revise event followed by deterministic fallback. Failed attempts retain unknown usage, so complete cost may remain unknown despite a final accepted artifact.

Inspect reasons, history and every attempt rather than only the final label. Unknown usage must remain unknown. A green test demonstrates the specified code path, not universal semantic safety.

A failure to understand

Two outer semantic rounds multiplied by three SDK transport attempts can far exceed the calls visible to an application wrapper. This example avoids a hidden SDK layer; adapting it to an SDK requires counting that layer explicitly.

Exercise in a disposable copy

Set the aggregate call cap to1 and trigger a transient failure in a test. Verify only one provider invocation occurs. Then set an already-aborted signal and verify zero invocations and a human_review result.

Follow the matching exercise file, retain the original and restore the reference before the next chapter. Do not use held-out results to choose a threshold.

Troubleshooting

If a test hangs, make the injected provider observe its abort signal or ensure the timeout race can settle. Do not increase timeouts blindly. The100ms reference setting is for fast canned fixtures, not a live SLA.

Next checkpoint

Before continuing, name the property that code checks exactly, the judgment that may be wrong, the state that stops work and the evidence needed before release.

← Previous lesson · Next lesson →

Sources and version notes

Key takeaways