# Runtime Capacity Model

Open Orchestra runtime capacity is modeled as a deterministic local-first
contract. Local runs use the implicit `local/local/local-workspace` scope; SaaS
mode requires every request, queue item, lease, event, and snapshot to carry
tenant and workspace scope.

## Core Concepts

- `RuntimeCapacityScope`: platform, tenant, and workspace identity.
- `RuntimeWorkloadClass`: interactive, workflow phase, runtime-native spawn,
  provider-backed phase, background maintenance, or evidence processing.
- `RuntimeCapacityUnit`: weighted runtime demand, currently enforced by
  `concurrencyUnits` with optional budget and resource hints.
- `RuntimeQuotaPolicy`: platform, tenant, and workspace active/queued limits,
  provider/runtime caps, and queue/reject behavior.
- `RuntimeWorkerRecord`: registered worker capabilities, tenant affinity,
  regions, supported providers/runtimes/workload classes, health, capacity, and
  isolation metadata.

## Scheduler Decisions

`RuntimeCapacityScheduler.schedule()` returns one typed decision:

- `admitted`: a `RuntimeLease` was granted for a specific worker.
- `queued`: quota or worker capacity can recover and the request is accepted
  into a scoped queue.
- `rejected`: the request is invalid or the configured policy does not allow
  queueing.
- `deferred`: no eligible worker is available and queueing is disabled.

Evaluation is fail-closed: request validation, SaaS scope, platform quota,
tenant quota, workspace quota, provider/runtime caps, then worker selection.
Queue limits are enforced at platform, tenant, and workspace levels before a
queue decision is returned.

## Load Balancing

Worker selection is constraint-first and score-second. Eligibility checks tenant
affinity, denied tenants, workload class, runtime/provider support, region and
data residency, health, heartbeat freshness, open circuits, and available
capacity. Scoring is deterministic: available capacity, queue depth, failure
count, region preference, health, and tenant affinity are sorted with worker id
as the final tie breaker.

## Isolation

SaaS mode rejects missing tenant/workspace scope. Snapshots can be filtered by
scope so tenant-facing queue evidence does not expose other tenants. Decision
messages use stable reason codes and user-safe summaries rather than worker
internals, queue depths from other tenants, paths, or provider details.

## Current Boundary

This story intentionally keeps capacity state in memory. Hosted queues,
transactional worker leases, tenant-secret routing, and data residency
persistence remain follow-up architecture and security work before SaaS release.