Files
archie/docs/prds/runtime-control-plane.md
T

137 lines
5.1 KiB
Markdown

# Runtime control plane
**Status:** Approved
**Date:** 2026-09-20
**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`
## Outcome
Archie can be managed from the Web UI or a messaging channel. Both use the same
API.
## Model
Each feature owns its settings and commands. The database stores them. There is
no global configuration document.
This includes:
- workflows;
- identities and bindings;
- providers and models;
- repository policies;
- channels and schedules;
- capture mappings and bindings;
- tool settings;
- prompts and personas;
- plugin settings.
Plugin code remains installed code. Only its settings are stored in the
database.
Each feature defines its data, validation, permissions, editor fields, and how
changes take effect. Each feature also defines its allowed actions. For example,
identities can be created, suspended, and retired.
Repository and identity settings remain separate. They are not stored as large
records that unrelated features must share.
The State Store process hosts the control-plane API on its existing gRPC server.
No new process is added. Feature code validates changes. Storage code only
writes versions and audit records.
Every write records who made it, where it came from, a request ID, and the
version being edited. The API layer sets the actor; the request body cannot.
The server validates the change, then writes it with its audit record. It rejects
edits to an old version.
The request ID is the write's idempotency key, and it is scoped per org and
per kind, never global. The key is `(org_id, kind, request_id)` — the unique
index `idx_resource_history_org_kind_request` (migration `0021_resources_per_org.sql`)
— so replaying a request ID is the same org's prior write of the same kind, and
a request ID reused across orgs or across kinds is a separate write. This is the
same scoping as the task idempotency key `org/identity/owner/repo/number`
(`docs/prds/orgs-and-access.md`).
## API
The API has four operations:
1. **Catalogue** tells clients what can be viewed or changed and how to edit it.
2. **Query** reads data and versions without exposing secrets.
3. **Command** asks the owning feature to make a change.
4. **Watch** streams changes and errors to clients.
Complex features can use custom screens. They still use the same commands.
A dashboard session or channel sender must map to an Archie identity before it
can run a command. Messaging syntax maps to the same commands as the Web UI.
`archie-ui` receives only an API client. It does not receive a database handle,
daemon pointer, global configuration object, or secret value.
The database stores the requested settings. Each process reports the version it
is using or why it failed. The UI shows both.
Some changes require a restart. The UI shows them as pending. When a live change
replaces a running component, Archie starts and checks the new one before
switching. If the check fails, the old one keeps running.
## Bootstrap, migration, and recovery
Bootstrap contains only the database path, listen addresses, credentials, TLS,
and encryption-key references. State Store and control-plane RPCs use the same
endpoint.
When upgraded, existing instances are migrated to the database. Existing
database values are not overwritten, with one exception: a resource whose
document the build ships is refreshed when the seed itself wrote the stored
copy, because that copy is a previous release's document rather than an
operator's. After migration, settings in TOML are ignored and cannot block
State Store startup.
The Web UI remains available when `archied` or Gateway is down. It shows failed
changes and can correct or roll them back.
Offline commands can back up, restore, validate, and roll back the database.
Recovery does not require `archied` or the Web UI. The database stores secret
references, not secret values.
## Workflows
Users create and edit workflows in the Web UI. Workflows are stored as versioned
YAML. Built-in workflows can be overridden and restored.
A workflow is a list of steps. Each step has a known type and its own settings.
Plugins can add step types. Each run keeps the workflow version it started with.
Yaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful
behaviour must first be available as normal workflow steps.
## First implementation
The first implementation makes task limits editable: maximum model steps,
maximum runtime, and maximum consecutive gate failures.
It includes:
- validated task-limit fields;
- version history and audit records;
- the four API operations;
- authenticated Web UI and messaging access;
- live updates and apply status;
- a Pinia-backed editor in the Web UI;
- a messaging command using the same API;
- migration of existing `[budgets]` values;
- an end-to-end restart test.
Running tasks keep the limits they started with. New tasks use the latest applied
version. This replaces the old settings overlay instead of extending it.
## Not included in the first implementation
- Moving bootstrap or secret values into normal settings.
- A generic JSON editor.
- Rebuilding every settings screen at once.
- Changing the limits of a running task.