Runtime Cloud — aggregate roots¶

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

Aggregate	Service	Root entity	Events	Tables
DeploymentSpecification	IaCProvisioningService	DeploymentSpecification	SpecificationDeclared	DeploymentSpecifications
ProvisioningRun	IaCProvisioningService	ProvisioningRun	ProvisioningPlanned, ProvisioningApplied, ProvisioningFailed	ProvisioningRuns
WorkerPool	ExecutionCapacityService	WorkerPool	WorkerPoolStateChanged	WorkerPools
Quota	ExecutionCapacityService	Quota	QuotaChanged, QuotaExceeded	Quotas
CapacityLease	ExecutionCapacityService	CapacityLease	CapacityLeaseGranted, CapacityLeaseReleased	CapacityLeases
RuntimeInventory	RuntimeEnvironmentService	RuntimeInventory	ObservedStateChanged	RuntimeInventories, ObservedWorkloads
DriftFinding	RuntimeEnvironmentService	DriftFinding	RuntimeDriftDetected	DriftFindings
ReconciliationProposal	RuntimeEnvironmentService	ReconciliationProposal	ReconciliationProposed, ReconciliationDecided	ReconciliationProposals

DeploymentSpecification (IaCProvisioningService)¶

The desired state of one environment or workload: a reference to the IaC program and its version in Git (the repository's InfrastructureModel project), the release it deploys, strategy, configuration references (Config Platform) and secret references (Secret Broker); every applied version is kept.

Field	Type	Required	Description
`specificationId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`environmentId`	`string`	yes
`kind`	`enum:SpecificationKind`	yes
`programRef`	`string`	yes	repository + path of the Pulumi program
`programVersion`	`string`	yes	Commit of the program.
`releaseId`	`guid`	no
`strategy`	`string`	no
`configRefs`	`json`	yes	Config Platform keys by reference.
`secretRefs`	`json`	yes	Secret references; never values.
`version`	`int`	yes
`declaredAt`	`datetime`	yes

Invariants

Desired state lives in Git; the specification records which version was acted on and never edits the program.
Secrets and configuration are references resolved by the runner at apply time from the Secret Broker and the Config Platform.

ProvisioningRun (IaCProvisioningService)¶

One plan-and-apply of a specification version against a target: plan receipt (resources to add, change, delete), the approval when the environment class is production, apply receipt (outputs, duration, result), the promotion that requested it, and the artifacts of logs and state.

Field	Type	Required	Description
`provisioningRunId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`environmentId`	`string`	yes
`specificationId`	`guid`	yes
`specificationVersion`	`int`	yes
`kind`	`enum:ProvisioningKind`	yes
`promotionId`	`guid`	no
`approvalId`	`guid`	no
`planReceipt`	`json`	no	adds, changes, deletes, inputs hash, program version
`applyReceipt`	`json`	no	outputs, duration, result, runner version
`state`	`enum:ProvisioningState`	yes
`logsRef`	`string`	no
`startedAt`	`datetime`	yes
`completedAt`	`datetime`	no

Invariants

An apply against a production environment needs the promotion's approval (production class) or, for a baseline or reconciliation, a policy allow with evidence; the plan is recorded before any apply.
A plan with deletes in production is never applied automatically by reconciliation; it becomes a reconciliation proposal.
Receipts are immutable; a re-run is a new provisioning run.

States (ProvisioningState)

stateDiagram-v2
    Planned --> AwaitingApproval : ProductionWithoutApproval
    Planned --> Applying : ApprovedOrAllowed
    AwaitingApproval --> Applying : ApprovalGranted
    AwaitingApproval --> Rejected : ApprovalRejectedOrExpired
    Applying --> Applied : RunnerSucceeded
    Applying --> Failed : RunnerFailed
    Planned --> Cancelled : Cancel

Hold "Alt" / "Option" to enable pan & zoom

WorkerPool (ExecutionCapacityService)¶

A pool of execution capacity of one kind with its security boundary (shared, tenant-dedicated, customer-hosted), region, node profile, size bounds and autoscaling rule, and the current utilisation.

Field	Type	Required	Description
`poolId`	`string`	yes
`tenantId`	`string`	yes	Platform tenant for shared pools; a tenant for dedicated ones.
`kind`	`enum:PoolKind`	yes
`securityBoundary`	`string`	yes	shared
`region`	`string`	yes
`nodeProfile`	`string`	yes
`minSize`	`int`	yes
`maxSize`	`int`	yes
`currentSize`	`int`	yes
`utilisation`	`decimal`	yes
`state`	`enum:PoolState`	yes

Invariants

Sandboxes with network egress to the internet and browser sessions run only in pools whose security boundary allows it (sandbox controls, original design §35–38).
A tenant's residency rule bounds the regions of the pools it may use.

Quota (ExecutionCapacityService)¶

Limits per tenant or project: concurrent runs, concurrent sandboxes, CPU and memory per attempt, execution minutes per day, derived from the edition (D34) and tightened by Workspace admins.

Field	Type	Required	Description
`quotaId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	no
`concurrentRuns`	`int`	yes
`concurrentSandboxes`	`int`	yes
`cpuPerAttempt`	`decimal`	yes
`memoryGbPerAttempt`	`decimal`	yes
`executionMinutesPerDay`	`int`	yes
`source`	`string`	yes	edition

Invariants

A project quota may only tighten its tenant's; a tenant quota may only tighten its edition's.

CapacityLease (ExecutionCapacityService)¶

A grant of capacity in a pool to one attempt, sandbox, build or browser session for a bounded time, renewed by heartbeat and released on completion; the unit placement and quotas are enforced on.

Field	Type	Required	Description
`leaseId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`runId`	`guid`	no
`attemptId`	`guid`	no
`holderKind`	`string`	yes	attempt
`holderId`	`string`	yes
`poolId`	`string`	yes
`cpu`	`decimal`	yes
`memoryGb`	`decimal`	yes
`state`	`enum:LeaseState`	yes
`grantedAt`	`datetime`	no
`expiresAt`	`datetime`	no
`releasedAt`	`datetime`	no

Invariants

A lease is granted only within the holder's quota and the pool's bounds; otherwise Denied with the limiting quota named (the run waits, visible to the requester).
An expired lease frees capacity; the holder's work is handled by its own lease semantics (attempt lease in Run Control, sandbox lease in the tool executor).

States (LeaseState)

stateDiagram-v2
    Requested --> Granted : CapacityAvailable
    Requested --> Denied : QuotaOrPoolExhausted
    Granted --> Active : HolderStarted
    Active --> Released : HolderCompleted
    Active --> Expired : HeartbeatMissed
    Granted --> Expired : NotStarted

Hold "Alt" / "Option" to enable pan & zoom

RuntimeInventory (RuntimeEnvironmentService)¶

The observed state of one environment: every workload with its kind, image or package version, replicas, endpoints, configuration and secret bindings (by reference), health, and the observation time; the runtime service catalog of the June-2026 design.

Field	Type	Required	Description
`environmentId`	`string`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`workloads`	`json`	yes
`currentReleaseId`	`guid`	no
`specificationVersion`	`int`	no	Declared version last applied.
`observedAt`	`datetime`	yes
`stale`	`bool`	yes

Invariants

Observed state is read from the cluster and cloud APIs, never declared; an environment not observed within the staleness window is marked stale.
Secret bindings are references; values never enter the inventory.

Entities: ObservedWorkload · Value objects: —

DriftFinding (RuntimeEnvironmentService)¶

One difference between the declared specification and the observed state, with kind, resource, declared and observed values and the reconciliation proposal it belongs to.

Field	Type	Required
`findingId`	`guid`	yes
`tenantId`	`string`	yes
`environmentId`	`string`	yes
`kind`	`enum:DriftKind`	yes
`resource`	`string`	yes
`declared`	`json`	no
`observed`	`json`	no
`detectedAt`	`datetime`	yes
`proposalId`	`guid`	no
`resolvedAt`	`datetime`	no

Invariants

A finding is resolved only by a re-observation that no longer shows it; never by hand.

ReconciliationProposal (RuntimeEnvironmentService)¶

A reviewable change that would bring observed state back to declared state (or declare what is observed): the findings it covers, the specification version it would apply, the plan summary, and the decision by an Operator; accepted proposals become provisioning runs.

Field	Type	Required	Description
`proposalId`	`guid`	yes
`tenantId`	`string`	yes
`environmentId`	`string`	yes
`findingIds`	`list:guid`	yes
`direction`	`string`	yes	apply-declared
`planSummary`	`json`	yes
`destructive`	`bool`	yes
`state`	`enum:ProposalState`	yes
`decidedBy`	`string`	no
`provisioningRunId`	`guid`	no
`raisedAt`	`datetime`	yes

Invariants

Destructive or production proposals are always reviewed by an Operator; non-destructive ones outside production may be auto-accepted where policy allows.
A proposal never writes to infrastructure itself; acceptance plans a provisioning run.

States (ProposalState)

stateDiagram-v2
    Proposed --> Accepted : OperatorAccepts
    Proposed --> Rejected : OperatorRejects
    Accepted --> Applied : ProvisioningApplied
    Proposed --> Superseded : NewerProposal

Hold "Alt" / "Option" to enable pan & zoom