← Back Architecture

## State & Transitions

Infrastructure state is modeled as a multi-dimensional FSM. Each dimension has a `current_state`, a `desired_state`, a `blocker` that explains what prevents the transition, and a `catalyst` that describes what would trigger it. `prov next` computes all valid transitions across every dimension simultaneously.

cluster_provisioning
current bootstrapped
desired operational
blocker cert-manager not yet deployed
observability
current partial
desired full_stack
catalyst deploy victoria-metrics + loki
gitops_sync
current active
desired active
blocker none — at desired state
# Current FSM state across all provisioning dimensions
prov state
# All valid next transitions with blockers and catalysts
prov next
# Validate a decision against architectural invariants
prov validate "deploy sops-operator before cert-manager"

## Topology — Connections & Gates

Workspace connections encode the dependency graph between provisioning units. Gates (membranes) are the typed conditions that govern when data, tokens, or control signals can flow across a connection. `prov gates` shows current membrane status — open, closed, or partially open — with the conditions that would change each.

infra-base
↑ upstream: cloud-provider-api
↓ downstream: app-cluster, monitoring
app-cluster
↑ upstream: infra-base, secrets-store
↓ downstream: (none)
secrets-store
↑ upstream: vault-cluster
↓ downstream: app-cluster
# Upstream/downstream connection graph
prov connections
# Membrane (gate) status — open/closed/partial + conditions
prov gates

## Workspace Card

Available for `DevWorkspace` repos (not `Mixed`). Returns a structured summary: workspace identity, cluster list with their types and regions, overall provisioning status, and which gates are currently blocking downstream consumers. Useful as a health check or context card for agents operating in the workspace.

# Identity + clusters + provisioning status summary
prov card
# Example output:
workspace: my-infra
kind: DevWorkspace
clusters: [prod-eu-west-1, staging-eu-west-1]
status: partially_operational
open_gates: 3
closed_gates: 1 # secrets-store → app-cluster blocked

## Platform Capabilities & Backlog

Platform Capabilities

- Reads the manifest capabilities section — what this workspace provides vs. requires
- Structured output: services, APIs, storage backends, auth mechanisms
- Feeds into gate evaluation — capabilities map to open/closed conditions

prov capabilities
Backlog

- Provisioning-scoped backlog items from reflection/backlog.ncl
- Priority filter surfaces High-priority blockers first
- Detail view includes owning dimension, gate impact, and linked connections

prov backlog --priority High
prov backlog show bl-deploy-certmgr

## Daemon UI

The provisioning domain activates the `/provisioning` page in the daemon UI. It is live-reloading and reflects the current FSM state, connection graph, and gate status without restart.

/provisioning
localhost:7421/provisioning
/provisioning State FSM dimension grid — current/desired/blocker per dimension
/provisioning#connections Connections Upstream/downstream dependency graph with status badges
/provisioning#gates Gates Membrane status — open/closed/partial with conditions
The provisioning page reads directly from your ontology NCL files via the daemon's file watcher. Any change to a dimension state, connection node, or gate condition is reflected in the UI within the debounce window (default 300ms). No manual refresh needed.
# Start daemon (provisioning page is served automatically)
ontoref-daemon-boot
# Open in browser
open http://localhost:7421/provisioning
# Or query the provisioning state via API
curl http://localhost:7421/api/provisioning/state

## Activation & CLI Reference

Setup writes `repo_kind = DevWorkspace` (or `Mixed`) to your manifest. The `prov` alias is registered in your shell profile. The provisioning domain reads FSM state from `.ontology/state.ncl` and topology from the provisioning-extension NCL files installed by setup.

# ── Activation ──────────────────────────────────────────
ontoref setup --kind DevWorkspace
ontoref setup --kind Mixed
# ── FSM state ────────────────────────────────────────────
prov state # FSM position across all provisioning dimensions
prov next # next valid transitions + blockers/catalysts
prov validate <decision> # check decision against ontological invariants
# ── Topology ─────────────────────────────────────────────
prov connections # upstream/downstream dependency graph
prov gates # membrane status + opening conditions
# ── Workspace (DevWorkspace only) ────────────────────────
prov card # identity, clusters, status summary
# ── Capabilities & backlog ───────────────────────────────
prov capabilities # platform capabilities from manifest
prov backlog [--priority High|Medium|Low]
prov backlog show <id>
# All of the above also work via the ore alias:
ore prov state