assure-os.demo.scaleright.ai

Architecture

Blocks, workflow, data flow and use cases — drawn from the committed source.

Architecture blocks

Four layers. Operator surfaces drive a Go core; the core is the only thing that writes to Postgres; shared modules sit underneath as vocabulary and schemas. The label on the bottom layer is load-bearing: imported modules define contracts and receipt formats, but they never confer permission to execute anything.

Four layered blocks. Operator surfaces — cmd/api serving HTTP API and web UI, the assurectl CLI, and cmd/agent with worker for collection and dispatch loops — feed into the ServiceAssure Go core. The core contains observe, decide, authorize, execute, verify and model routing. Below it, Postgres holds 19 tenant-scoped tables. At the bottom, shared modules and contracts: action-contracts, model-governance and contracts/v1, marked as not execution authority.
Surfaces call the core; only the core writes to Postgres; shared modules are vocabulary, not authority.

Recovery workflow and its refusal gates

The nine steps run in order, and five gates hang off them. Each gate is a real refusal path, not an error handler: reaching a gate that says no ends the flow and records why. The ordering matters — hard floors like resource protection and locality are checked before approvals are counted, so no quantity of signatures can buy through a floor.

A nine-step vertical flow: observe using docker, systemd and host probes; incident reconciliation with dependency chains; propose plan with typed hashed immutable steps; approve against the exact hash and never by the proposer; evaluate policy with floors checked before approvals; record intent durably before any effect; lease and fence with one live writer per target; typed action of restart, start or replace pod; verify and record via independent read-back. Five gates attach: grounded plans where model output is not authority, auth plus approver role, ops mode gate failing closed to observe, autonomy gate needing explicit environment plus act mode, and unknown effect which blocks the target until reconciled.
Nine steps, five gates. Any gate can end the flow; the outcome is recorded either way.

Why "record intent" sits before "typed action"

A crash before the intent row commits proves no effect was attempted. A crash after it means the effect is of uncertain status — which is a different, worse situation, and the system treats it that way. A sweep marks abandoned executions REAL_OUTCOME_UNKNOWN rather than retrying them, and the affected target stays blocked until someone reconciles it with evidence they gathered independently.

Data flow

Nineteen tables in four groups. Every row in the core write path is keyed by tenant_id; there is deliberately no "list everything" query anywhere in the read model, so a handler cannot serve cross-tenant data by forgetting a filter.

Four groups of Postgres tables. Tenancy and identity: tenants and actors with tenant grants, api tokens stored as sha-256 and revocable, and devices holding enrolment records. Core write path keyed by tenant id: resources of enrolled targets flow to append-only observations, then to incidents that are open or resolved, wrapping to plans that are hashed and immutable, then approvals binding actor to exact hash, then action states with the dispatch journal. Model routing ledger recording refusals as well as calls: model providers registry, model budgets with a daily cap per tenant, and model route usage covering routed and refused. Control and recovery: ops mode observe or act, ops mode audit of who changed the mode, and recovery epochs for restore fencing.
The write path is append-forward. Refusals and mode changes are stored, not just logged.

Use cases the platform supports and executes

Split deliberately: teal domains only read or gather evidence, purple domains change something on a customer system. The amber row is taken verbatim from the release manifest's own explicitly_disabled list — it is part of the product definition, not a backlog of regrets.

Six capability domains in two columns. Read-only domains: observe mixed estates across docker, systemd, hosts and VMs with AWS observation in simulate mode only; detect and correlate incidents with dependency chains, never reporting all-clear on a broken dependency; verify and recover using independent read-back probes with unknown effects quarantined. Change domains: propose typed plans that are hashed, immutable and cancellable with AI proposals grounded to enrolled resources; approve and govern using exact hash with replay and self-approval refused, plus ops mode and autonomy gates; execute typed actions being restart container, start service and disruption-aware replace pod. A final row lists explicitly disabled capabilities: cloud write adapters, fleet HA, bounded autonomy, GitOps mutation and Windows hosts.
Three typed actions exist. There is no general shell executor and no broad API proxy.

The three actions, in full

Action classTargetNotable refusal
restart_container Docker container Refuses a container owned by a native orchestrator (kubelet, Swarm, Nomad labels) rather than fighting its controller.
start_service systemd unit Enrolled units only; no shell passthrough.
replace_pod Kubernetes pod Disruption-aware — refuses when a PodDisruptionBudget would be violated.

Outcomes use a nine-value vocabulary shared with the VBA action contracts, so an outcome recorded here and a receipt produced there cannot disagree about what happened: SIMULATED, REAL_VERIFIED, REAL_ACCEPTED_UNVERIFIED, REAL_PARTIAL, REAL_OUTCOME_UNKNOWN, REAL_FAILED_CONFIRMED_NO_EFFECT, REFUSED, REAPPROVAL_REQUIRED, IDEMPOTENT_REPLAY.

Reaching REAL_VERIFIED requires both provider acceptance and an independent read-back that matches the declared postcondition. Provider acknowledgement alone yields REAL_ACCEPTED_UNVERIFIED — the distinction is the point.