Actuator Cycle Budget

A budget over a physical actuator's OBSERVED TRANSITIONS -- not the requests that asked for them -- so a looping agent, two disagreeing automations, or a retry firing on a command that already succeeded cannot cycle a relay, garage door, valve or lock past its mechanical life. Zero runtime dependencies. Pure functions: the caller supplies the transition history and an injected clock. No I/O, no timers, no device access.

THE SILENT FAILURE. An agent has a tool that actuates something real. Two automations disagree about the desired state and fight; a retry fires on a command that already succeeded; a loop asks again because the state it read was stale. Every one of those is ordinary software behaviour, and every one of them costs a physical cycle out of a part rated for a finite number of them.

COUNTING REQUESTS DOES NOT CATCH IT. Two requests that produce one transition are one cycle; one request that a retry duplicates into two transitions is two. A rate limit on the command path counts the wrong thing in both directions -- it throttles a caller that changed nothing and permits a caller that changed something twice.

So the budget is over what the DEVICE actually did. The failure being prevented is not an error message: it is a relay that fails open in three years instead of fifteen, and nothing in any log will connect that to the afternoon two automations disagreed.

VERIFIED: 65 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateCycleBudget(input: EvaluateCycleBudgetInput): CycleDecision;
  export function getRemainingAllowance(input: RemainingAllowanceInput): RemainingAllowanceResult;
  export function computeUsage( sortedHistory: readonly TransitionRecord[], nowMs: number, windowMs: number, maxTransitions: number, ): WindowUsage;
  export function validateConfig( windowMs: number, maxTransitions: number, ): ConfigValidationSuccess | ValidationFailure;
  export function validateNow(nowMs: number):;
  export function validateHistory( history: readonly TransitionRecord[], nowMs: number, ): HistoryValidationSuccess | ValidationFailure;

  export type RemainingAllowanceResult = { readonly ok: true;
  export type CycleBudgetOverrides = Readonly<Record<string, Partial<CycleBudgetConfig>>>;