Kernel Flow Semantics

Overview

This document defines the CQRS and transactional semantics for kernel execution flows. These semantics ensure deterministic, reliable execution with proper transactional boundaries and event delivery guarantees.

Related Specifications:

• ADR-033: Kernel-Shell Architecture
• PRD-023 REQ-060: Kernel Independence
• SDS-055: Kernel Execution Ports Service
• P04: Flow Annotation Contract (docs/reference/sea_dsl_language_idioms.yml)

Flow Annotation Contract

All kernel flows MUST include @cqrs annotation specifying their kind (command, query, or event). Additional annotations are required based on the CQRS kind as defined in the P04 pattern.

Validation

Flow annotations are validated by tools/flow_lint.py against the AST schema (tools/schemas/ast-v3.schema.json).

1
python tools/flow_lint.py docs/specs/shared/kernel.ast.json --strict

Kernel Flows

1. ExecuteCommand

CQRS Kind: Command

Semantics:

• Transactional: true - All command executions occur within a transaction boundary
• Idempotency: Enabled via correlationId key
• Purpose: Execute domain commands with transactional guarantees

Annotations:

1
2
3
4
5
{
  "cqrs": { "kind": "command" },
  "tx": { "transactional": true },
  "idempotency": { "enabled": true, "key": "correlationId" }
}

Port Interface: CommandBus

• execute<TCommand, TResult>(command: TCommand, context: CommandContext): Promise<TResult>
• isIdempotent(correlationId: string): Promise<boolean>

Invariants:

• Commands MUST have a valid CommandContext
• Commands MUST execute within a transaction boundary
• Idempotent commands deduplicated by correlationId

2. ExecuteQuery

CQRS Kind: Query

Semantics:

• Read Model: Uses ReadProjection for consistent reads
• Consistency Level: Configurable (STRONG, EVENTUAL, SNAPSHOT)
• Purpose: Execute read-only queries against projections

Annotations:

1
2
3
4
{
  "cqrs": { "kind": "query" },
  "read_model": { "source": "ReadProjection" }
}

Port Interface: QueryBus

• execute<TQuery, TResult>(query: TQuery, context: QueryContext): Promise<TResult>
• getConsistencyLevel(): ConsistencyLevel

Invariants:

• Queries MUST have a valid QueryContext
• Queries MUST NOT modify state
• Queries operate on read models/projections

3. PublishEvent

CQRS Kind: Event

Semantics:

• Outbox Pattern: required - All events MUST use transactional outbox
• Delivery: At-least-once delivery guarantee
• Purpose: Publish domain events reliably

Annotations:

1
2
3
4
{
  "cqrs": { "kind": "event" },
  "outbox": { "mode": "required" }
}

Port Interface: EventBus

• publish(event: EventEnvelope): Promise<boolean>
• publishBatch(events: ReadonlyArray<EventEnvelope>): Promise<boolean>

Invariants:

• Events MUST use outbox pattern for persistence
• Events MUST be published within the same transaction as the command
• Events contain full causation/correlation chain

Outbox Pattern Flow:

1. Command executes within transaction
2. Event recorded to outbox table (same transaction)
3. Transaction commits
4. Outbox processor publishes events asynchronously
5. Events marked as published after successful delivery

4. ManageTransaction

CQRS Kind: Command

Semantics:

• Transactional: true - Transaction lifecycle management
• Idempotency: Enabled via transactionId key
• Purpose: Begin, commit, rollback transaction boundaries

Annotations:

1
2
3
4
5
{
  "cqrs": { "kind": "command" },
  "tx": { "transactional": true },
  "idempotency": { "enabled": true, "key": "transactionId" }
}

Port Interface: UnitOfWork

• begin(): Promise<TransactionBoundary>
• commit(boundary: TransactionBoundary): Promise<void>
• rollback(boundary: TransactionBoundary): Promise<void>
• getCurrent(): TransactionBoundary | null

Invariants:

• Only one active transaction boundary per execution context
• All aggregate changes tracked within transaction
• Rollback reverts all changes atomically

Transactional Boundaries

Command Execution Flow

1
2
3
4
5
6
7
1. Begin transaction (UnitOfWork.begin)
2. Load aggregates (Repository.findById)
3. Execute command logic
4. Save modified aggregates (Repository.save with optimistic locking)
5. Record events to outbox (OutboxPort.record)
6. Commit transaction (UnitOfWork.commit)
7. [Async] Publish events from outbox

Failure Handling

• Optimistic Locking Failure: Rollback, retry with latest version
• Validation Failure: Rollback, return error
• Infrastructure Failure: Rollback, propagate exception

Event Delivery Guarantees

Outbox Pattern

Ensures at-least-once delivery by persisting events transactionally:

1. Event Recording: Events written to outbox table in same transaction as domain changes
2. Transaction Commit: Both domain changes and event records commit atomically
3. Asynchronous Publishing: Separate process polls outbox for unpublished events
4. Idempotent Handlers: Event handlers must be idempotent (events may be delivered multiple times)

Event Envelope

All events wrapped in EventEnvelope containing:

• eventType: Event type identifier
• aggregateId & aggregateType: Source aggregate
• version: Aggregate version when event occurred
• causationId: Command that caused this event
• correlationId: Original request correlation ID
• timestamp: Event occurrence time
• metadata: Additional contextual information

Validation & Compliance

Flow Lint Checks

Run flow lint to validate all flows have required annotations:

1
python tools/flow_lint.py docs/specs/shared/kernel.ast.json --strict

Checks:

• ✅ All flows have @cqrs annotation
• ✅ Commands declare @tx (transactional semantics)
• ✅ Commands declare @idempotency (deduplication strategy)
• ✅ Events declare @outbox (delivery guarantees)
• ✅ Queries declare @read_model (projection source)

AST Schema Validation

AST JSON must conform to tools/schemas/ast-v3.schema.json:

• Flow annotations use nested JSON objects (not dotted keys)
• Required fields present for each annotation type

• Enum values valid (e.g., outbox mode: “required”

  “optional”)

Implementation Notes

Port Independence

All kernel ports defined as TypeScript interfaces in libs/sea/ports/src/gen/kernel/ports.ts. Adapters implement these interfaces without kernel coupling.

Domain Types

Domain types (CommandContext, QueryContext, EventEnvelope, TransactionBoundary) defined in libs/sea/domain/src/gen/kernel/types.ts.

Testing

Kernel ports tested independently without shell dependencies (see libs/sea/ports/src/gen/kernel/ports.spec.ts).

References

• Tools: tools/flow_lint.py - Flow annotation validator
• Schema: tools/schemas/ast-v3.schema.json - AST v3 schema
• Idioms: docs/reference/sea_dsl_language_idioms.yml - P04 Flow Annotation Contract
• SDS: docs/specs/shared/sds/055-kernel-execution-ports.sds.yaml