docs/prds/workflow-step-vocabulary.md named the repository-rules step type
`workflow.diff-rules` while the vocabulary a deployment resolves carries
`gate.diff-rules` (workflow.DiffRulesStepName), so a definition written to
the document's word is refused at save and at run. The same decision's
sibling, docs/prds/runtime-control-plane.md, still claimed "Plugins can add
step types", which this document's closed-set rule contradicts: an
interpreted plugin contributes none, and a step type arrives as a provider
in the compiled-in set.
Correct both documents, and hold the vocabulary PRD to the provider set with
a guard test: every step-type-shaped name the document identifies must
resolve in workflowsteps.Providers(). The test fails on the pre-fix document
("workflow.diff-rules" is contributed by no provider) and passes after.
Refs: archie-core-vwqc, split from archie-core-gcoj (closed as invalidated by
re-verification: the provider set exists and cross-side agreement is already
pinned).
5.3 KiB
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:
- Catalogue tells clients what can be viewed or changed and how to edit it.
- Query reads data and versions without exposing secrets.
- Command asks the owning feature to make a change.
- 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.
A step type is part of the build's step vocabulary, contributed as a provider at
the composition root; interpreted plugins contribute none
(docs/prds/workflow-step-vocabulary.md). 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.