rustfs/docs/architecture/workload-admission-contracts.md

# Workload Admission Contracts

This document records the `rustfs/backlog#660` PR-05 and PR-07 scheduler
preservation and runtime workload-class contract slice.

## Preservation Coverage

The `rustfs-concurrency` tests pin the current reusable scheduler and
admission-facing behavior before later snapshot extraction:

- Worker slot over-release remains clamped by the configured worker limit.
- Scheduler default buffer and priority thresholds remain unchanged.
- Scheduler priority boundaries remain high below the high threshold, normal at
  both thresholds, and low above the low threshold.
- Backpressure pipe metadata reads preserve buffer capacity and state without
  mutating the manager state.
- `GetObjectQueueSnapshot` preserves saturated, over-available, and zero-total
  permit semantics.

## Workload Class Contract

`WorkloadClass` defines the required future admission categories:

- Foreground read.
- Foreground write.
- Metadata.
- Scanner.
- Repair.
- Replication.

`AdmissionState`, `WorkloadAdmissionSnapshot`, and
`WorkloadAdmissionRegistrySnapshot` define read-only status shapes for later
runtime owners. They do not replace the current scheduler, request guard,
scanner, heal, replication, or ECStore placement behavior.

## Boundary Rules

- `rustfs-concurrency` owns this reusable contract surface.
- The contract does not depend on `rustfs-ecstore` or RustFS binary runtime
  state.
- No scheduler decision logic, queue capacity, Tokio runtime default, scanner
  admission, heal admission, replication admission, placement, membership, or
  NUMA behavior changes are part of this slice.

## Set-Local Snapshot Extraction

The RustFS storage `ConcurrencyManager` now implements
`WorkloadAdmissionSnapshotProvider` for local foreground-read admission:

- `ForegroundRead` reports local disk-read permit usage through
  `GetObjectQueueSnapshot`.
- `active` is the number of disk-read permits currently in use.
- `limit` is the configured maximum concurrent disk reads.
- `queued` remains `None` because the current semaphore does not expose waiter
  counts.
- Scanner, repair, replication, foreground write, and metadata entries remain
  `Unknown` until their owning runtime components expose read-only status.

This is an observation surface only. Permit acquisition, priority assignment,
buffer sizing, storage media detection, request guards, and queue behavior are
unchanged.

## Heal Repair Snapshot Extraction

The RustFS integration layer now exposes a read-only repair admission snapshot
from the heal runtime counters:

- `Repair` reports the current heal active task count.
- `queued` reports the current heal queue length.
- `limit` remains `None` because the configured heal queue and concurrency
  limits live behind the async heal manager state.
- Other workload classes remain `Unknown` in this provider until their owning
  runtime components expose read-only status.

This is an observation surface only. Heal request admission, queue capacity,
priority merge/drop policy, task scheduling, retry handling, and repair
behavior are unchanged.

## Replication Snapshot Extraction

The RustFS integration layer now exposes a read-only replication admission
snapshot from the existing replication pool and queue statistics:

- `Replication` reports active regular, large-object, and MRF worker counts.
- `queued` reports the current site replication queue count when queue stats
  are immediately observable.
- `limit` remains `None` because replication worker limits remain owned by the
  async replication pool and resize policy.
- If the replication runtime has not initialized, or queue stats are currently
  locked, the snapshot reports `Unknown` instead of blocking or guessing.

This is an observation surface only. Replication admission, queue channel
capacity, worker resize behavior, MRF handling, target dispatch, and resync
behavior are unchanged.

## RustFS Runtime Owner Snapshot Extraction

The RustFS integration layer now extends the workload admission registry with
additional read-only owner mappings:

- `ForegroundRead` reuses the storage `ConcurrencyManager` disk-read permit
  snapshot so the RustFS-level provider exposes the same active and limit
  counts as the storage-local provider.
- `Scanner` reports the existing scanner active work-unit counter. When the
  counter is zero, the snapshot remains `Unknown` because the current counter
  cannot distinguish an idle scanner from a scanner that has not initialized.
- `Metadata` reports `Open` once the bucket metadata runtime handle is
  available, and `Unknown` before initialization.
- `ForegroundWrite` remains `Unknown` until a write-specific admission owner
  exposes a read-only surface.

This is an observation surface only. Disk-read permit acquisition, scanner
cycle scheduling, bucket metadata loading, metadata locks, object write paths,
and queue behavior are unchanged.

## Provider Composition Boundary

`WorkloadAdmissionRegistrySnapshot::overlay` composes provider-owned registry
snapshots without mutating runtime owners:

- The storage concurrency provider remains the source of truth for
  `ForegroundRead`.
- The RustFS runtime owner provider overlays metadata, scanner, repair,
  replication, and foreground-write status on top of the storage registry.
- Matching workload classes are replaced by the later provider snapshot; new
  classes are appended without reordering existing unrelated entries.

This keeps the later controller/status layer consuming a single read-only
registry while preserving the existing storage, scanner, heal, replication, and
metadata ownership boundaries.