Admission & Memory Governance

Algeon admits GPU work once per native query attempt: one admission, one selected device, and one immutable memory grant. Embedded DataFusion sessions and the Flight SQL server share the same process-scoped AlgeonGpuBackend, QueryService, bounded queue, and per-device ledgers. Planning may create an attempt lifecycle and a lazy admission ticket, but it does not reserve a GPU slot. Admission happens when execution first needs the device. EXPLAIN does not admit or execute the plan.

Admission governs device memory. Host memory remains a DataFusion MemoryPool concern.

The runtime path is:

QueryPlan
  -> AttemptCapabilityEvidence
  -> compatible-device resolution
  -> bounded queue and placement
  -> DeviceLedger grant
  -> AdmissionEnvelope
  -> QueryHandle / ExecutionContext

Term	Meaning
AttemptCapabilityEvidence	Planning-owned evidence for required device capabilities and exact executable plan scopes. It contains no memory estimate.
Attempt	One bounded native execution of one admitted query on one selected device.
DeviceLedger	The per-device integer accounting authority for immutable grants, resident cache charges, and attempt slots.
MemoryGrant	The service-configured byte cap committed to one attempt. It becomes the ceiling of the query allocation domain.
AdmissionEnvelope	The physical resources built around a committed grant: attempt lane, root stream, allocation domain, and worker scope.
QueryHandle	The published admission result used by execution. Releasing it returns the attempt resources after cleanup completes.

From capability validation to admission

Planning validates the exact native IR and records its required device capabilities and executable plan scopes in AttemptCapabilityEvidence. A missing memory estimate does not make an operator unsupported and does not reject admission.

A submission reserves queue capacity and a FIFO sequence before device-specific owner resolution. Pending resolution counts against queue capacity and acts as an ordering barrier, so a slow request cannot be bypassed by younger work. The service rejects a request locally when no installed device supports all required capabilities or when the configured cap cannot be granted by a compatible device ledger. Capacity pressure waits within the configured queue and deadline.

Composed GPU execution binds each producer occurrence and the consumer into one evidence set. Runtime activation validates producer scope, occurrence, schema, and resident ownership before execution uses the frames. The composed query uses one ticket, one selected device, and one grant.

Manual AlgeonGpuBackend::admit_query() handles are resource-only. Native execution also requires planning-issued capability and scope evidence.

Device profiles and grants

Each CUDA ordinal has one immutable DeviceResourceProfile, fixed at backend construction. It declares the managed capacity, backend reserve, cache cap, query cap, active-attempt limit, execution-resource bounds, and supported device capabilities.

The DeviceLedger accounts for grants and resident cache charges with integer arithmetic. It is not a residency oracle and does not predict an operator's peak memory. Admission commits the configured query cap when ledger capacity and an attempt slot are available. The grant does not grow, shrink, borrow, or move to another device during the attempt.

Allocation enforcement

The query allocation domain is the single arbiter of the attempt's allocation limit. cuDF, cuGraph, and cuVS execute with the domain memory resource, and an allocation beyond the immutable grant returns a typed allocation failure at its native source. Algeon does not add per-operator reservations or reject work from an estimate-derived byte requirement.

The allocation domain records aligned current and peak bytes for attempt-level observation. Device pool used, reserved, and high-water values remain device-scoped observations; they are not projected as attempt peaks.

cuGraph sizing reads the effective remaining query memory from its execution handle when selecting native batches or strategies. This value is a current sizing snapshot, not a reservation. The allocator still decides whether each real allocation succeeds.

Resident handoff and release

Published GPU-resident outputs retain their backing allocation owners and an immutable resident lease. Freeze verifies that every live producer-domain allocation is represented by the published output owners, deduplicating shared views by backing allocation identity.

A resident grant returns to the ledger only after the final borrow completes, required completion fences succeed, and the allocation domain reaches zero. Cleanup or fence failure closes admission for the affected device and records the cleanup disposition instead of making the grant reusable.

Queue and shutdown behavior

Cancellation, deadlines, and queue closure remove pending requests and release their queue capacity. Service shutdown waits for pending owner resolution, active attempts, resident leases, GPU resources, and observation delivery. Terminal attempt reports are emitted from the runtime observation snapshot.

Public observation

QueryMetrics, DataFusion metrics, JSONL, and TSV reports are projections of the same runtime observation snapshot. Attempt allocation peaks come from the query domain. Device pool observations retain their device scope and availability metadata.

See Cache Design for resident cache policy and Integrating Algeon for backend construction.