Handlung: Eingabe und Wirkung

Stand · Bauplan

Eine Handlung beschreibt eine beabsichtigte Zustandsänderung mit begrenzter Eingabe, Wirkung und Zuständigkeit. Der geplante Vertrag macht sichtbar, was geprüft werden muss, bevor ein Werkzeug etwas verändert.

Ein geplanter Vertrag, kein erreichbarer Endpunkt

Die Felder beschreiben eine prüfbare Entwurfsrichtung. Es gibt hier keinen zugesagten HTTP-Endpunkt, keine SDK-Methode und keine Kompatibilitätsgarantie. Vor einer Implementierung müssen Authentifizierung, Grenzwerte, Serialisierung und Fehlertransport festgelegt und getestet werden.

Vorbedingungen gehören zum Vertrag

Ein erfolgreicher Lesezugriff erlaubt keine Änderung. Die Handlung braucht eigene Rechte, einen bekannten Zielzustand und eine ausdrücklich begrenzte Wirkung. Eine Regelprüfung arbeitet auf dem aktuellen Zustand und nicht allein auf dem früheren Vorschlag des Agenten.

Wiederholen ist keine neue Erlaubnis

Begriff · Idempotenz

Wiederholte Zustellung derselben Absicht erzeugt keine zusätzliche Wirkung. Sie ersetzt keine Berechtigung und keine Freigabe.

Handlungen als Verträge beschreiben

Idempotenz bedeutet, dass die Wiederholung derselben Absicht keine zusätzliche Wirkung erzeugen soll. Sie ersetzt keine Autorisierung. Eine andere Eingabe unter derselben Kennung ist ein Konflikt. Nach einem Zeitüberschreitungsfehler ist zuerst das Zielsystem zu prüfen.

Ergebnis und Ungewissheit protokollieren

Eine gesendete Anfrage ist noch kein bestätigter Erfolg. Das Ergebnis braucht die Antwort des Zielsystems und, wenn möglich, den beobachteten Folgezustand. Ist die Wirkung ungewiss, wird sie als ungewiss geführt. Ein neuer Versuch ohne Abgleich kann eine doppelte Buchung verursachen.

Schema

{
  "id": "<handlung-kennung>",
  "actionType": "<objekttyp>.<operation>.v1",
  "targetId": "<objekt-kennung>",
  "expectedVersion": <version>,
  "input": {
    "<eigenschaft>": "<neuer-wert>"
  },
  "actorRef": "<identitaet>",
  "idempotencyKey": "<wiederholungsschluessel>",
  "approvalRef": "<freigabe-kennung>",
  "deadline": "<zeitpunkt>"
}

Schema 1JSON · Schema mit Platzhaltern

Felder

Feld	Typ	Pflicht	Bedeutung
`id`	`string`	ja	Kennung des Handlungsversuchs.
`actionType`	`string`	ja	Versionierter Name einer erlaubten Operation.
`targetId`	`string`	ja	Kennung des betroffenen Objekts.
`expectedVersion`	`integer`	ja	Revision, gegen die vorbereitet wurde.
`input`	`object`	ja	Typisierte Eingabe ohne zusätzliche unbekannte Felder.
`actorRef`	`string`	ja	Identität, in deren Kontext die Handlung ausgeführt werden soll.
`idempotencyKey`	`string`	ja	Bindet wiederholte Zustellung an dieselbe beabsichtigte Wirkung.
`approvalRef`	`string \| null`	ja	Freigabereferenz, falls die geltende Regel eine Freigabe verlangt.
`deadline`	`string (date-time)`	ja	Zeitgrenze. Abgelaufene Versuche dürfen nicht nachträglich wirken.

Fehlerfälle

Kennung	Bedeutung
`ACTION_NOT_ALLOWED`	Die Operation ist für diesen Kontext nicht erlaubt.
`PRECONDITION_FAILED`	Zustand oder erwartete Revision haben sich verändert.
`APPROVAL_REQUIRED`	Eine passende Freigabe fehlt.
`EFFECT_UNCERTAIN`	Der Zielaufruf wurde unterbrochen; die Wirkung muss vor einem erneuten Versuch abgeglichen werden.

Grenze

Grenze: Dieser Schnittstellenvertrag ist geplant. Ein lokaler Kontrollprototyp belegt weder eine veröffentlichte API noch organisationsweiten Betrieb.