EXECUTION_LAYER_BOUNDARY 0. Purpose
This document defines the strict boundary between the Governance Layer and the Execution Layer.
It prevents:
Hidden side effects
Loading module
Resolving locale, route permissions, and workspace projection.
Resolving locale, route permissions, and workspace projection.
Current scope: Guest
Category: 10_normative | Version: v1.0.0
Owner: DOCUMENT_CUSTODIAN | Review cycle: 90 days
Approval authority: GOVERNANCE_ADMIN
Documentation portal is read-only. Editing and mutation endpoints are disabled.
Kvary platform is originally created in Georgian. Where a Georgian version exists, Georgian is authoritative for platform UI, documentation, and legal interpretation.
Translations into other languages are provided for convenience. Some records may originate in other languages and carry their own source or legal locale for a specific flow, but where a Georgian version is available, the Georgian version prevails for platform-level wording and interpretation.
Metadata incomplete: Document ID, Version, Status, Owner Role, Last Review Date, Next Review Date, Change Log
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
Core is the source of truth.
Execution layer is stateless logic reacting to governance records.
Location:
packages/core/*
Responsibilities:
Append-only ledger
Authorization verification
Version chain enforcement
Lifecycle validation
Deterministic record building
Cryptographic traceability
Error code determinism
Core MUST:
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)
Core is:
Pure, deterministic, replayable.
Location (recommended):
packages/execution/*
Responsibilities:
React to GovernanceRecordV1
Trigger off-chain side effects
Call payment rails
Send notifications
Create blockchain transactions
Coordinate background jobs
Handle retries
Execution layer MUST:
Never create governance records directly
Never bypass ACCESS_DECISION
Never mutate governance payloads
Never derive state from outside ledger
Execution reacts to:
LedgerEntry<GovernanceRecordV1>
Core must not import:
execution/*
api/*
ui/*
database/*
services/*
Execution may import:
core/*
ledger utilities
hashing utilities
❌ 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)
Append:
SETTLEMENT_EVENT action: SETTLEMENT.DEPOSIT_CONFIRMED
Core validates:
Authorization
Lifecycle
Deterministic invariants
Ledger entry created.
Step 2 — Execution Layer reacts
Execution detects:
recordType === "SETTLEMENT_EVENT" action === "SETTLEMENT.DEPOSIT_CONFIRMED"
Execution may:
Call PSP
Call smart contract
Update off-chain system
Trigger payout flow
But:
Execution must NEVER:
Skip governance
Insert its own settlement records
Governance:
KES_VERSION_PROPOSED KES_VERSION_RATIFIED
Execution may:
Deploy smart contract
Pin IPFS
Notify parties
Update off-chain registry
But execution cannot:
Ratify version without governance record
Alter versionHash
Alter commitments
If you replay the ledger from scratch:
You must derive:
Same settlement state
Same KES active version
Same authorization state
Same lifecycle validity
Execution side effects are NOT replayed.
Governance state is replayable.
Recommended 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.
Example:
Rail error → execution → append SETTLEMENT.RAIL_ERROR
But authorization still applies.
Governance record once appended:
Never edited
Never deleted
Never replaced
Never patched
Corrections must be new records.
Execution layer compromise must NOT allow:
Forging governance records
Bypassing authorization
Modifying ledger state
Core validation must reject:
Unauthorized appends
Invalid transitions
Invalid chain states
Execution is optional.
Governance is mandatory.
If execution fails:
Governance state still remains valid.
New governance records must describe recovery.
When adding new domain:
Define governance state machine.
Define authorization matrix.
Define deterministic invariants.
Only then implement execution side effects.
Never reverse the order.
Is it governance or execution?
Does it modify protocol state?
Does it require ACCESS_DECISION?
Is it deterministic?
Can it be replayed from ledger?
If not deterministic → it belongs in execution.
Core = Protocol.
Execution = Infrastructure.
They must never merge.
Governance defines what is allowed. Execution performs what is allowed. Execution never defines what is allowed.