Skip to content

Resource Reservation Ledger

Jump to bottom
William Smith edited this page Jul 13, 2026 · 1 revision

Resource Reservation Ledger

Relevant source files

The following files were used as context for generating this wiki page:

The Resource Reservation Ledger is the central accounting system for tracking commitments of RAM and VRAM across the AXIS cluster. It implements a double-entry style system to ensure that resource allocations are deterministic, persistent, and guarded against overcommitment. The ledger acts as an overlay on top of raw hardware facts, allowing the Placement Engine to reason about "allocatable" headroom rather than just "free" hardware memory.

Ledger Data Model

The ledger tracks individual commitments via the reservation.Entry struct. Each entry represents a specific resource claim tied to an execution lifecycle.

Field Type Description
ID string Unique identifier for the reservation.
Node string The target node where resources are reserved.
OwnerExecID string The ID of the task or execution owning this entry.
RAMMB int64 Amount of system RAM reserved in MB.
VRAMMB int64 Amount of GPU VRAM reserved in MB.
CreatedAt time.Time Timestamp when the reservation was created.
LastHeartbeat time.Time Last recorded liveness signal from the owner.
ExpiresAt time.Time Optional hard deadline for the reservation.

Sources:

Reservation Lifecycle and Liveness

The reservation.Ledger manages the lifecycle of these entries through explicit creation, heartbeat updates, and reclamation.

Heartbeat and Reclamation

To prevent "zombie" reservations from orphaned processes or crashed nodes, the ledger enforces a heartbeat policy. Entries are classified into three states:

  1. Active: Heartbeat received within the HeartbeatStaleWindow (default 2 minutes).
  2. Stale: No heartbeat within the window, but not yet expired.
  3. Expired: Passed the hard ExpiresAt deadline or the LegacyStaleWindow.

The Reclaim() function is called periodically (and during daemon startup) to prune stale or expired entries, returning the resources to the allocatable pool.

Double-Entry Code Entities

The following diagram illustrates how the Ledger interacts with execution and persistence.

Reservation Lifecycle Flow

graph TD
    subgraph "Execution Plane"
        A["RunGuarded"] -- "Reserve()" --> B["Ledger.Reserve"]
        A -- "Heartbeat()" --> C["Ledger.Heartbeat"]
        A -- "Release()" --> D["Ledger.Release"]
    end

    subgraph "reservation.Ledger"
        B -- "lockFileLocked" --> B1["Validate Limits"]
        B1 -- "saveLocked" --> B2["Atomic Write"]
        C -- "Update LastHeartbeat" --> C1["saveLocked"]
        D -- "Delete Entry" --> D1["saveLocked"]
        E["Reclaim()"] -- "IsStale / IsExpired" --> D
    end

    subgraph "Persistence"
        B2 -- "persist.WriteFileAtomic" --> F["~/.axis/ledger.json"]
    end
Loading

Sources:

Overcommit Policy and Capacity Management

The ledger enforces strict resource boundaries defined in reservation.Limits. By default, AXIS adopts a conservative "no overcommit" policy.

Key Limit Parameters

Capacity Calculation

The Ledger calculates AllocatableRAM for a node by taking the total capacity (provided by snapshots via SetNodeCapacity) and subtracting both the system reserve and the sum of all active Entry.RAMMB values.

Sources:

Snapshot Overlay (snapshotview)

While the Ledger maintains the "truth" of commitments, the rest of the system (CLI, Placement Engine) interacts with these commitments via the snapshotview package. The ApplyReservationView function overlays ledger data onto a ClusterSnapshot.

This creates a unified view where NodeFacts fields like RAMReservedMB and RAMAllocatableMB are populated based on the current ledger state.

Entity Association: Snapshot vs Ledger

graph LR
    subgraph "models.ClusterSnapshot"
        N["models.NodeFacts"]
    end

    subgraph "reservation.Ledger"
        L["Ledger.Entries()"]
        S["Ledger.NodeSummaryFor()"]
    end

    subgraph "snapshotview.ApplyReservationView"
        V["Overlay Logic"]
    end

    L --> V
    S --> V
    V -- "Updates" --> N
    N -- "RAMReservedMB" --> Final["Final Snapshot View"]
    N -- "RAMAllocatableMB" --> Final
Loading

Sources:

CLI and API Access

Users can inspect the ledger state using the axis reservations command group.

Command Function Description
axis reservations runReservationsTable Displays a formatted table of all active commitments.
axis reservations list reservationsListCmd Lists entries in text, JSON, or NDJSON format.
axis reservations inspect reservationsInspectCmd Shows full metadata for a specific reservation ID.
axis reservations release reservationsReleaseCmd Manually deletes a reservation from the ledger.

The CLI primarily communicates with the daemon via the /v2/reservations endpoint. If the daemon is unreachable, the CLI attempts a "fallback" mode by loading the local ledger file directly from ~/.axis/ledger.json.

Sources:

AXIS Wiki

Architecture Artifacts

DeepWiki

Clone this wiki locally