EXECUTION LAYER BOUNDARY

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

1. 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.

2. Governance Layer (Core)

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.

3. Execution Layer

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>

4. One-Way Dependency Rule STRICT RULE Core → (no dependency) Execution → Core UI → Execution

Core must not import:

execution/*

api/*

ui/*

database/*

services/*

Execution may import:

core/*

ledger utilities

hashing utilities

5. 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)

6. Example: Settlement Flow Step 1 — Governance

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

7. KES Example

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

8. Determinism Rule

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.

9. Cross-Layer Communication Pattern

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.

10. Immutable Rule

Governance record once appended:

Never edited

Never deleted

Never replaced

Never patched

Corrections must be new records.

11. 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
12. Security Boundary

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

13. Governance Is the Law

Execution is optional.

Governance is mandatory.

If execution fails:

Governance state still remains valid.

New governance records must describe recovery.

14. Future Extension Rule

When adding new domain:

Define governance state machine.

Define authorization matrix.

Define deterministic invariants.

Only then implement execution side effects.

Never reverse the order.

15. Checklist Before Adding New Feature

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.

16. Hard Boundary Statement

Core = Protocol.

Execution = Infrastructure.

They must never merge.

17. Final Principle

Governance defines what is allowed. Execution performs what is allowed. Execution never defines what is allowed.