Format des Aktionskatalogs
Ein Katalog ist ein YAML-Dokument, signiert als DSSE-Envelope über seine exakten Bytes (vcx catalog sign). Der
Vertrag ist contract/v0/catalog.schema.json im Repository; diese Seite fasst ihn zusammen.
apiVersion: catalog.vaicoa.com/v0kind: ActionCatalogmetadata: name: vaicoa-builtin version: 2026.11.9 # nur Ebenen: layer: org.team, environments: [lab, demo]actions: [ … ]playbooks: [ … ]Eine Aktion
Abschnitt betitelt „Eine Aktion“Die eingebaute Aktion env.delete:
- type: env.delete summary: Remove a container and, if asked, its volumes — data is lost riskClass: risky destructive: true params: type: object additionalProperties: false required: [name] properties: name: {type: string, pattern: "^[a-z0-9][a-z0-9-]{0,39}$"} deleteVolumes: {type: boolean, default: false} constraints: - "params.name in state.containers" requires: minLevel: device approval: quorum: [{kind: human, count: 1, minLevel: presence, roles: [owner, operator], channels: [cli, device-app]}] ttl: 1h module: podman_env executor: {name: podman, side: node, minVersion: 0.1.0} display: title: "Delete container {params.name} in {environment}" facts: [{label: Container, value: "{params.name}"}, {label: Delete volumes, value: "{params.deleteVolumes}"}] onReject: "nothing changes; the container keeps running" confirm: "{params.name}" targets: [podman-host] controls: [change-management]| Feld | Bedeutung |
|---|---|
type | der Name der Aktion; Aktionen einer Ebene liegen in ihrem eigenen Namensraum org.<name>.… |
summary | eine Zeile; zugleich die Tool-Beschreibung, die ein Agent sieht |
riskClass | safe, routine oder risky; bestimmt die Standard-Policy |
destructive | wer freigibt, muss zusätzlich das Ziel auswählen oder eintippen (display.confirm); nie wiederholt; nie ein Emergency-Change |
dataAccess | ein Lesezugriff: safe, nicht destruktiv, kein Quorum; wird auf das Lesebudget angerechnet, geschwärzt |
params | JSON Schema, gegen das der Kern die Parameter validiert |
constraints | CEL-Ausdrücke über params, state (aus dem Modul), env, principal, now, assurance; ein bloßer Ausdruck oder {expr, message}, wobei die Meldung die Abhilfe nennt |
requires.minLevel | die niedrigste Stufe dessen, der vorschlägt |
requires.approval.quorum | eine Liste von Gruppen, jede {kind: human|agent, count, minLevel, roles, channels, profile}; jede Gruppe muss erfüllt sein; leer heißt keine Freigabe |
requires.approval.ttl | wie lange eine Freigabe gültig bleibt |
requires.productionApproval | ersetzt approval in Umgebungen, die als Produktion markiert sind; der Node wendet es aus seiner eigenen Konfiguration an |
module | das Modul, das state, Vorbedingungen und den Plan liefert |
executor | {name, side: node|hub, minVersion}: wo und womit die Aktion läuft |
targets | die Zielarten, für die sie gilt: podman-host, k3s-host, k3s, capi, hetzner-cloud, git, core, … |
bindings | ein anderer Executor je Zielart |
credential | die Art des Credential-Slots, den ein Treiber auf Hub-Seite für einen Aufruf bekommt |
display | die Vorlage: title, facts, onReject, confirm; auf dem Gerät der freigebenden Person gerendert |
controls | optionale Labels wie change-management; durch den Katalog-Digest in jedem Audit-Eintrag festgeschrieben |
implements | nur Ebenen: die eingebaute Aktion, die diese einschränkt (alles muss mindestens so streng sein) |
mcp | von einem MCP-Server importierte Aktionen: {server, tool, definitionSha256}, bei jedem Aufruf verglichen |
Einige Invarianten setzt der Kern unabhängig davon durch, was ein Katalog sagt: Wer freigibt, ist nie die Person, die
vorgeschlagen hat; risky-Aktionen brauchen mindestens eine menschliche Gruppe auf presence; und Agent-Gruppen allein
genügen nur für safe und routine.
Ein Playbook
Abschnitt betitelt „Ein Playbook“Playbooks haben dieselben Felder params, constraints, requires und module, dazu:
| Feld | Bedeutung |
|---|---|
forEach | {items, max, maxParallel}: eine begrenzte Liste, über die die Schritte laufen, zum Beispiel die Nodes eines Clusters |
blast | {set, maxShare}: der größte Anteil der Menge, den ein Batch berühren darf |
steps | jeweils {name, action, params, target, check}; Parameter sind Vorlagen über die eigenen Parameter des Playbooks und item |
check | eine Leseaktion und ein CEL-Ausdruck auf ihr Ergebnis, mit wait und interval |
onFailure, rollback | stop (Standard) oder ein benannter Rollback, der sofort läuft, als Teil des freigegebenen Plans |
Die Risikoklasse des Playbooks ist die höchste seiner Schritte. Die Freigabe deckt den expandierten Plan per Digest ab; Nodes prüfen jeden Schritt dagegen.
Eine Ebene ist ein Katalog mit metadata.layer: org.<name>, signiert von den Ownern des Teams
(vcx catalog sign --layer org.<name>) und im Roster gepinnt. Sie darf nur Aktionen in ihrem Namensraum hinzufügen oder
eine eingebaute einschränken (implements); sie kann nie eine Risikoklasse senken, ein Quorum verkleinern oder einen
Executor austauschen. Ein Beispiel liegt im Repository unter examples/catalog/notify/.