Runtime Providers and elastic workers

Runtime Providers and elastic workers

Status: future architecture. Nothing on this page expands the scope of Elah 0.0.3 or an earlier runtime milestone.

Boundary

Shepherd decides what Minecraft needs. A Runtime Provider converts a compatible worker request into generic lifecycle operations.

Minecraft telemetry and ownership
               |
               v
            Shepherd
               |
      placement or scaling plan
               |
               v
        Runtime Provider
        /      |       \
    Native   Docker   External

A provider can report capacity and prepare, inspect, drain, or stop workers. It cannot assign a cell, advance an ownership epoch, transfer a player, split a cell, or write authoritative world state.

Provider order

The implementation order is fixed:

1. Native Provider for processes and services on operator-managed bare metal or VMs.
2. Docker Provider with explicit image identity, resources, network, storage, and credentials.
3. External Provider for authenticated hosting-panel and custom-infrastructure integrations.
4. Later optional adapters for Kubernetes, cloud systems, Pterodactyl, Pelican, or other providers.

Native operation remains first class. Elah never requires Docker, Kubernetes, a hosting panel, or a cloud account.

Required provider evidence

A provider must eventually report:

• provider identity and version;
• compatible worker shapes;
• available capacity and fault domains;
• isolation, storage, and network capabilities;
• worker lifecycle and health;
• idempotent operation identity and status.

Every prepared worker must pass identity, protocol, Minecraft version, ElahFolia version, plugin, world, storage, network, and cluster-membership checks before it can own a cell.

Provider success is capacity evidence, not ownership authority.

Worker lifecycle

State	Meaning
COLD	No worker process exists.
WARM	A compatible worker has joined the cluster and owns no authoritative cells.
HOT	The worker owns and serves one or more authoritative cells.

Allowed direction:

COLD -> WARM -> HOT
HOT -> WARM -> COLD

A worker cannot stop or be reclaimed until Elah proves that it owns zero authoritative cells. An uncertain drain fails closed and leaves capacity allocated.

Capacity classes

Class	Meaning
GUARANTEED	Reserved for the cluster and expected to remain available.
BURST	Shared spare capacity available up to an explicit ceiling.
PREEMPTIBLE	Opportunistic capacity that may be reclaimed after a safe drain.

Capacity class does not change ownership safety. Resource envelopes place hard bounds on workers, CPU, memory, storage, generation, network use, priority, preemptible eligibility, and warm capacity.

Resource envelopes are scheduling controls. Customer billing remains outside Elah.

Scheduling evidence

Shepherd combines three evidence groups.

Minecraft pressure:

• Folia region MSPT and tick pressure;
• global TPS and worker MSPT;
• players, entities, and loaded chunks per cell;
• generation and storage pressure;
• adjacency, handoffs, and cross-cell traffic.

Runtime pressure:

• CPU and scheduler saturation;
• memory and garbage-collection pressure;
• disk latency and IOPS;
• network throughput, latency, and loss;
• startup and drain latency.

Constraints:

• ownership and epoch safety;
• resource envelope and capacity class;
• compatibility and provider capabilities;
• machine, rack, and datacenter fault domains;
• operator affinity and anti-affinity.

CPU utilization alone is never enough to trigger a cell migration. Shepherd must first determine whether the pressure can be separated and whether moving work is likely to improve the result.

Cluster and fleet scopes

One Elah cluster is one ownership and administrative domain. A host may run many isolated clusters over a shared infrastructure fleet, but those clusters must not share controller authority, credentials, storage namespaces, networks, metrics, or ownership state.

A fleet plane may allocate provider capacity above Elah. Customer lifecycle, billing, generic host inventory, and provider-wide allocation remain outside Elah's gameplay trust domain.

The project does not reserve a product name or repository for that optional layer.

Roadmap gate

Runtime Provider implementation starts only after Elah proves static multi-worker ownership, handoff, crash recovery, worker drain, dynamic migration, cell split and merge, and placement constraints.

The detailed sequence is in the technical roadmap.