Transaction Atlas

1. Was ist eine Transaction?1. What is a Transaction?

Eine Transaction (TX) ist eine kontrollierte, zustandsverändernde Aktion, die von einem Actor (Individual oder Composite) ausgeführt wird, ein oder mehrere Targets betrifft und mit vollständigem Evidence und Audit-Trail aufgezeichnet wird.

Universal: Transactions folgen dem identischen Format — unabhängig ob Human, Agent oder Team ausführt. Keine Sonderbehandlung nach Actor-Typ.

2. Transaction-Struktur (10 Required Fields)2. Transaction Structure (10 Required Fields)

Vollständige YAML-AnatomieComplete YAML Anatomy

id: txn-a1b2c3d4-e5f6-7890-abcd-ef1234567890
kind: transaction
timestamp: 2024-01-20T14:30:00Z

actor:
  id: agent-copilot-001
  type: individual
  role: contributor
  # wenn composite:
  if_composite:
    composite_id: team-backend-core
    member_detail:
      executing_member: agent-copilot-001
      member_role: executor

context:
  space_id: iio-seed
  plan_id: plan-manual-build-2024
  story_id: story-skill-atlas-001
  composition_id: null     # optional

intent: >
  Erstelle den Skill Atlas als neue Manual-Seite
  im Rahmen von Story skill-atlas-001.

target:
  type: artifact
  id: iio/manual/skill-atlas.html
  description: "Neue HTML-Seite für Skill-Registry-Referenz"

pre_state:
  snapshot: {file_exists: false}
  constraints: [story_must_be_active, actor_must_have_role]

operation:
  type: create
  instructions: "create_file skill-atlas.html mit 9 sections"
  deterministic: true

post_state:
  snapshot: {file_exists: true, sections: 9, wired: false}
  state_hash: "sha256:abc123..."

evidence:
  - type: artifact_sample
    id: ev-skill-atlas-file-001
    link: iio/manual/skill-atlas.html
    verified_by: operator-alice
    verified_at: 2024-01-20T14:35:00Z

approvals:
  - actor_id: operator-alice
    role: reviewer
    signature: "hitl-sign-001"
    timestamp: 2024-01-20T14:36:00Z
    comment: "Content verified against SKILL-REGISTRY-LAYER.md"

audit:
  recorded_by: system
  timestamp_recorded: 2024-01-20T14:36:10Z
  fail_closed_gates: [actor_exists, role_resolved, permission_check]
  constraints_checked: [story_active, no_conflict]
  role_conflict_check: passed
  story_consistency: consistent
  transaction_hash: "sha256:def456..."

reversibility:
  can_reverse: true
  reversal_cost: "Datei löschen; Revisions-Index anpassen"
  auto_rollback_on_error: false

related_transactions: []
status: committed

3. Operation-Typen3. Operation Types

Sieben gültige operation.type-Werte — jede TX muss genau einen tragen:

4. TX-Typen (5 kanonische Fälle)4. TX Types (5 Canonical Cases)

actor: alice (Contributor)
target: artifact-api-handler
operation: create
evidence: [code file, tests passing]
approvals: [qa-bot as Reviewer]

actor: composite-team-backend (via alice)
target: role-assignment
operation: modify
context: bob bekommt role "Architect"
evidence: [vote result, consent]
approvals: [team-lead alice]

actor: validator-bot (Validator)
target: shared_state
operation: modify
pre_state: {status: "building"}
post_state: {status: "testing-gate-passed"}
evidence: [test results, logs]

actor: composition-safety-monitor
target: story-consistency
operation: verify
context: P-STORY-003 compliance
evidence: [both stories analyzed]
status: consistent | inconsistent_fail_closed

actor: external-actor-org-x
target: boundary-access-request
operation: request
context: composition-team-backend
evidence: [access request, auth]
approvals: [team-lead alice]
status: granted | denied

5. TX Status-Modell5. TX Status Model

Status-ÜbergängeStatus Transitions

                ┌─────────────┐
                │  executing  │
                └──────┬──────┘
         gates OK?     │        gates FAIL?
              ┌────────┴────────┐
              ▼                 ▼
    ┌──────────────────┐   ┌─────────┐
    │ pending_approval │   │  failed │
    └────────┬─────────┘   └─────────┘
    approved?│  rejected?
      ┌──────┴──────┐
      ▼             ▼
┌──────────┐  ┌──────────┐
│committed │  │  failed  │
└──────────┘  └──────────┘
      │ auto_rollback_on_error=true
      ▼
┌─────────────┐
│ rolled_back │
└─────────────┘

6. Audit Trail Anatomie6. Audit Trail Anatomy

Jede TX schreibt automatisch in den Audit-Log. Der Log ist append-only, nie editierbar.

Audit-Felder im DetailAudit Fields in Detail

7. Reversibilitäts-Modell7. Reversibility Model

Jede TX deklariert explizit, ob und mit welchem Aufwand sie rückgängig gemacht werden kann.

Rollback-Fluss (auto_rollback_on_error: true)Rollback Flow (auto_rollback_on_error: true)

TX Execution Error
  → System detects operation failure
  → pre_state snapshot loaded
  → Target restored to pre_state
  → TX status set to: rolled_back
  → error_reason recorded
  → Audit-Log entry written (immutable)
  → Notification: actor + composition_lead

8. Composite Actor — TX Zurechnung8. Composite Actor — TX Attribution

Wenn ein Team (Composite Actor) eine TX ausführt, wird der ausführende Member im actor.if_composite.member_detail-Block festgehalten. Die TX ist dem Team zugerechnet — nicht dem Einzelmitglied.

actor:
  id: composite-team-backend
  type: composite
  role: contributor-team
  if_composite:
    composite_id: team-backend-core
    member_detail:
      executing_member: agent-copilot-001
      member_role: executor    # Rolle des Members IN der Composition

# → TX wird "team-backend-core" zugerechnet
# → Audit: "executing via agent-copilot-001"
# → member_role legt Berechtigungs-Check fest

Dies ermöglicht vollständige Traceability: Wer hat angeordnet (Composite Actor)? Wer hat ausgeführt (executing_member)?

9. Fail-Closed TX-Regeln9. Fail-Closed TX Rules