Implementation Plan: Runtime Kernel

Define and generate the kernel execution surface (ports + application orchestration) that executes “business behavior” through deterministic flows, unit-of-work boundaries, and event publication—without coupling to any particular shell (API/CLI/worker).

This plan emphasizes the port-driven kernel: shells translate inputs into commands/queries; the kernel routes and executes.

Provenance & Traceability

Architectural Decisions (ADRs)

Product Requirements (PRDs)

Software Design Specifications (SDS)

Provenance Chain

graph TD
  ADR33[ADR-033: Kernel-Shell] --> PRD23[PRD-023: Platform Integration]
  PRD23 --> SDS13[SDS-013: Execution Architecture]
  PRD23 --> SDS48[SDS-048: UI Integration]

Architecture and Design

Design Principles Applied

• Isomorphism: Kernel ports and use-cases project from the semantic model (Flows + Policies).
• Invariants: Kernel has no runtime dependency on shell configuration (PRD-023 REQ-060).
• Idempotency: Commands declare dedup strategy; event publication uses outbox for at-least-once.

Dependency Justification

• No new dependencies for the kernel layer itself (prefer pure generated ports and application stubs first).

Expected Filetree

1
2
3
4
5
6
7
/
├── libs/sea/
│   ├── domain/src/gen/**            # generated domain primitives
│   ├── ports/src/gen/**             # generated port interfaces
│   ├── application/src/gen/**       # generated use-case handlers
│   └── adapters/src/gen/**          # generated adapter wiring (shell-facing)
└── docs/specs/**                    # semantic source-of-truth

Proposed Cycles

Task Breakdown

Wave 1 (Parallel)

• C1A: Model and generate kernel ports (command bus, query bus, UoW, event bus)
  • Implements: Kernel execution surface
  • Satisfies: PRD-023 REQ-060 (kernel independence)
  • Files: relevant docs/specs/** inputs, generated libs/sea/**/src/gen/**
• C1B: Encode transactional and outbox semantics on flows
  • Implements: @tx, @idempotency, @outbox semantics as required by flow contract
  • Satisfies: Deterministic runtime semantics (lint + manifest)
  • Files: docs/specs/**, tools/flow_lint.py, generated libs/sea/**/src/gen/**

Wave 2 (Depends on Wave 1)

• C2A: Validate kernel independence with shell-free tests
  • Implements: Confidence that libs/sea/* can be compiled/tested standalone
  • Satisfies: PRD-023 REQ-060
  • Files: tests/** (or an existing spec test harness location)

Validation & Verification

Spec Validation

• Ensure kernel-related flows include required annotations (CQRS kind, tx, outbox) via tools/flow_lint.py --strict.

Implementation Validation

• Generated kernel code exists only under **/src/gen/**
• Kernel can be type-checked/tested without building any apps/* (PRD-023 REQ-060)

Open Questions

1. What is the canonical representation of UoW boundaries in the semantic model: Flow annotation only (@tx) or a first-class concept? @tx annotation on Flow
2. Do we require CQRS at the kernel boundary for MVP, or allow a unified “request” abstraction? Required for MVP
3. Where should kernel tests live (existing tests/ vs docs/specs/**/tests/) to keep drift checks clean? Collocated *.spec.ts

Risks & Mitigation

Rollback Strategy

1. If kernel generation becomes too coupled, revert to generating ports only and keep orchestration in specs until mapping stabilizes.

Related Documents

Reference Documents

• Kernel-Shell ADR
• Platform Integration PRD

Linked Specifications