Files
archie/docs/prds/runtime-control-plane.md
T
sam 0aa0277ee9 docs(prds): name the registered step type and hold the vocabulary PRD to the provider set
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).
2026-10-02 11:05:08 +10:00

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:

  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. 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.