@delegance/claude-autopilot 7.10.1 → 7.11.0-pre.1

package/dist/src/core/concurrent-dispatch/budget-reservation.d.ts

@@ -0,0 +1,163 @@
+import { GuardrailError } from '../errors.ts';
+import { SerializedWriter } from '../run-state/serialized-writer.ts';
+/** Budget caps for a single run. `perRunUSD` is the hard ceiling on total
+ *  committed spend (spent + active reservations) across all concurrent
+ *  tasks. `perSubagentUSD` is the per-task hard cap that dispatch refuses
+ *  to exceed even if perRunUSD has headroom. */
+export interface BudgetCaps {
+    /** Total USD this run is allowed to commit across all subagents +
+     *  in-flight reservations. */
+    perRunUSD: number;
+    /** Hard per-subagent cap. A pre-flight estimate exceeding this rejects
+     *  dispatch; an actual cost exceeding it mid-execution triggers the
+     *  scheduler's SIGTERM path (PR 4) — this layer just emits the
+     *  `task.failed` event with `error_type: 'budget_exceeded'`. */
+    perSubagentUSD: number;
+}
+/** Per-task ledger entry. Reconstructed via `replayFromEvents` at startup
+ *  / resume. */
+export interface ReservationEntry {
+    task_id: string;
+    /** Latest reservation value (after any
+     *  `task.budget_increased_reservation` events; ABSOLUTE, not delta). */
+    reserved_usd: number;
+    /** True once `task.budget_released` has landed for this task. */
+    released: boolean;
+    /** Actual cost if `released` is true. */
+    actual_cost_usd?: number;
+}
+/** Result of replaying events.ndjson into a fresh ledger state. */
+export interface BudgetReplaySummary {
+    /** Sum of `actual_cost_usd` across released tasks. Committed against
+     *  `perRunUSD` permanently. */
+    spentTotal: number;
+    /** Sum of `reserved_usd` for tasks NOT yet released. Each task
+     *  contributes its LATEST reservation (absolute value), not the sum of
+     *  reserved + increased values. */
+    activeReservedTotal: number;
+    /** `spentTotal + activeReservedTotal`. The number the headroom check
+     *  compares against `perRunUSD`. */
+    committedTotal: number;
+    /** Per-task latest state. */
+    perTask: Map<string, ReservationEntry>;
+}
+/** Thrown by `reserve()` / `increaseReservation()` when the requested
+ *  amount would push the run over `perRunUSD`, or when a pre-flight
+ *  exceeds `perSubagentUSD`. Carries the GuardrailError code
+ *  `budget_exceeded` for upstream resume classification. */
+export declare class BudgetExceededError extends GuardrailError {
+    constructor(message: string, details: Record<string, unknown>);
+}
+export interface ReserveOptions {
+    /** Pre-flight cost estimate for the task in USD. */
+    preFlightEstimateUsd: number;
+    /** Budget caps for this run. */
+    caps: BudgetCaps;
+}
+export interface IncreaseReservationOptions {
+    /** New reservation total (NOT a delta — the absolute new value). */
+    newReservedUsd: number;
+    /** Free-form reason captured on the event. */
+    reason: string;
+    /** Budget caps for this run. */
+    caps: BudgetCaps;
+}
+export interface ReleaseOptions {
+    /** Actual cost spent by the subagent (from telemetry). */
+    actualCostUsd: number;
+}
+/**
+ * Budget reservation ledger. One instance per run, owned by the scheduler.
+ * All mutations route through the supplied `SerializedWriter` and re-replay
+ * events.ndjson under the exclusive lock so they are atomic against
+ * concurrent callers AND any other `BudgetReservation` instances pointed at
+ * the same run.
+ */
+export declare class BudgetReservation {
+    private readonly writer;
+    /** In-memory mirror of disk state, kept for fast `snapshot()` reads.
+     *  NOT authoritative — every mutating operation re-replays the on-disk
+     *  log inside the writer's exclusive lock before checking caps. Per-task
+     *  reservations stored in USD (public API); the running totals below are
+     *  in MICROS (integer-safe arithmetic). */
+    private reservations;
+    private spentMicros;
+    private activeReservedMicros;
+    constructor(writer: SerializedWriter);
+    /** Re-seed in-memory state from events.ndjson. Call on construction OR
+     *  on resume. Safe to call multiple times — overwrites the cache. */
+    hydrateFromEvents(eventsNdjsonPath: string): Promise<void>;
+    /** Read the current in-memory state. Best-effort: a concurrent writer
+     *  in another instance could make this stale until the next mutating
+     *  call re-hydrates from disk. */
+    snapshot(): BudgetReplaySummary;
+    /**
+     * Reserve budget for a task. Atomic under the writer lock:
+     *
+     *   1. HARD cap check (pre-lock): `preFlightEstimate <= caps.perSubagentUSD`
+     *   2. Acquire SerializedWriter lock
+     *   3. Re-replay events.ndjson from disk (authoritative)
+     *   4. Verify task doesn't already have an in-flight reservation
+     *   5. Verify `caps.perRunUSD - committedTotal >= preFlightEstimate`
+     *      (committedTotal = spent + active reservations)
+     *   6. If pass: append `task.budget_reserved` event + fsync
+     *      If fail: append `task.budget_halt` event + fsync, then throw
+     *   7. Release lock
+     *
+     * Throws `BudgetExceededError` on cap violations. The `task.budget_halt`
+     * variant is durable: the event lands inside the same critical section
+     * before the throw propagates, so a crash post-throw still surfaces the
+     * halt on resume.
+     */
+    reserve(taskId: string, opts: ReserveOptions): Promise<void>;
+    /**
+     * Bump an in-flight reservation to a new ABSOLUTE value. Atomic under
+     * the writer lock; re-replays disk state before checking caps.
+     * Re-checks `perRunUSD` against the NEW reservation total; halts the
+     * run with `task.budget_halt` if the bump would exceed the cap.
+     *
+     * Throws `BudgetExceededError` (with durable `task.budget_halt`) if no
+     * prior reservation exists, the bump is downward (use `release`
+     * instead), or the bump exceeds caps.
+     */
+    increaseReservation(taskId: string, opts: IncreaseReservationOptions): Promise<void>;
+    /**
+     * Release a reservation with the actual cost. Atomic under the writer
+     * lock; re-replays disk state. Moves the task's commitment from
+     * `activeReserved` to `spent`. Emits `task.budget_released` with
+     * `delta_vs_reservation_usd` (positive = under, negative = over).
+     *
+     * Note: a release with `actualCostUsd > reserved_usd` is NOT a halt —
+     * the budget was already committed at reservation time. The scheduler
+     * is expected to issue `increaseReservation` mid-flight when telemetry
+     * suggests overrun, and to emit `task.failed{error_type:'budget_exceeded'}`
+     * if the increase itself fails. This `release` just records the truth.
+     */
+    release(taskId: string, opts: ReleaseOptions): Promise<void>;
+    /** Internal: replace in-memory ledger from a replay summary (in micros).
+     *  Used by every mutating method to re-sync cache with disk under the
+     *  lock. */
+    private applyReplayMicros;
+    /**
+     * Replay events.ndjson into a fresh `BudgetReplaySummary` (decimal USD).
+     * Used by:
+     *   1. `hydrateFromEvents` — runtime cache seed on resume / startup
+     *   2. tests — to assert reconstruction is exact
+     *
+     * Internally calls `replayFromEventsMicros` and converts to USD at the
+     * boundary so external consumers see decimal numbers, but the fold itself
+     * is integer-micro arithmetic.
+     *
+     * Line parsing is lenient: blank lines are skipped, parse failures stop
+     * the walk (treated as truncated tail; the next `appendEvent` would
+     * emit `run.recovery`, and budget state stays consistent up to the
+     * last-known-good line).
+     */
+    static replayFromEvents(eventsNdjsonPath: string): BudgetReplaySummary;
+    /**
+     * Internal: micro-precision replay. Used by every mutating method INSIDE
+     * `withExclusive` so cap checks operate on integer arithmetic.
+     */
+    private static replayFromEventsMicros;
+}
+//# sourceMappingURL=budget-reservation.d.ts.map