Loading module
Resolving locale, route permissions, and workspace projection.
EXECUTION_LAYER_BOUNDARY
0. Purpose
This document defines the strict boundary between the Governance Layer and the Execution Layer.
It prevents:
Hidden side effects
Non-deterministic behavior
Business logic leaking into Core
Smart-contract chaos
Unauthorized execution
This boundary is mandatory for all domains:
Settlement
KES
Auction
Tender
Future modules
- Architectural Overview
UI / API Layer
↓
Application Layer
↓
Execution Layer
↓
Governance Core (Ledger)
Core is the source of truth.
Execution layer is stateless logic reacting to governance records.
- Governance Layer (Core)
Location:
packages/core/*
Responsibilities:
Append-only ledger
READ 2026-03-28T23:42:21.903Z
READ 2026-03-29T04:52:41.869Z
CORE STRICT SAFE DELETE AFTER RERUN REPORT
PUBLIC | DRAFT | v1.0.0
READ 2026-03-29T03:13:33.020Z
Authorization verification
Version chain enforcement
Deterministic record building
Cryptographic traceability
Never call external services
Never read external DB state
Never depend on environment
Never perform side effects
Never mutate ledger entries
Never be async (unless hashing requires it)
Pure, deterministic, replayable.
React to GovernanceRecordV1
Trigger off-chain side effects
Create blockchain transactions
Coordinate background jobs
Never create governance records directly
Never bypass ACCESS_DECISION
Never mutate governance payloads
Never derive state from outside ledger
LedgerEntry<GovernanceRecordV1>
- One-Way Dependency Rule
STRICT RULE
Core → (no dependency)
Execution → Core
UI → Execution
- What is NOT allowed in Core
❌ Calling payment providers
❌ Sending blockchain transactions
❌ Sending emails
❌ Background scheduling
❌ Webhooks
❌ Retry logic
❌ Time-based state changes
❌ Reading system clock (except hash timestamps if deterministic)
- Example: Settlement Flow
Step 1 — Governance
SETTLEMENT_EVENT
action: SETTLEMENT.DEPOSIT_CONFIRMED
Step 2 — Execution Layer reacts
recordType === "SETTLEMENT_EVENT"
action === "SETTLEMENT.DEPOSIT_CONFIRMED"
Insert its own settlement records
KES_VERSION_PROPOSED
KES_VERSION_RATIFIED
Update off-chain registry
Ratify version without governance record
If you replay the ledger from scratch:
Execution side effects are NOT replayed.
Governance state is replayable.
- Cross-Layer Communication Pattern
ExecutionListener (subscribes to new ledger entries)
↓
Match recordType + action
↓
Perform side effect
↓
Log execution result separately (NOT in governance ledger)
If execution result must be protocol-visible:
Execution must request a new governance record.
Rail error → execution → append SETTLEMENT.RAIL_ERROR
But authorization still applies.
Governance record once appended:
Corrections must be new records.
- State Ownership
Concern Owner
Authorization Core
Version chain Core
Lifecycle enforcement Core
Deterministic errors Core
Payment execution Execution
Blockchain tx Execution
External API calls Execution
Notifications Execution
- Security Boundary
Execution layer compromise must NOT allow:
Forging governance records
Core validation must reject:
Governance state still remains valid.
New governance records must describe recovery.
Define governance state machine.
Define authorization matrix.
Define deterministic invariants.
Only then implement execution side effects.
- Checklist Before Adding New Feature
Is it governance or execution?
Does it modify protocol state?
Does it require ACCESS_DECISION?
Can it be replayed from ledger?
If not deterministic → it belongs in execution.
Execution = Infrastructure.
Governance defines what is allowed.
Execution performs what is allowed.
Execution never defines what is allowed.