SDS-021: SEA™ Forge Delivery Pipeline Service

Type

Software Design Specification - Platform / Compiler Service

Status

Proposed

Implements

PRD-004: SEA™ Forge Delivery Pipeline

1. System Overview

The SEA™ Forge Delivery Pipeline Service is a multi-stage compilation system that orchestrates semantic validation, structural mapping, generator execution, and CI enforcement.

It behaves like a compiler toolchain, not a code editor.

2. High-Level Architecture

Specs (ADR/PRD/SDS)
    ↓
Plan Compiler (Spec Kit)
    ↓
Semantic Compiler (DSL + g3)
    ↓
AST
    ↓
Manifest Compiler
    ↓
Generator Schema Compiler
    ↓
Generators (Nx / bespoke)
    ↓
Generated Code
    ↓
Validation + Drift Check

3. Core Components

3.1 Plan Compiler

Attribute	Value
Input	ADR/PRD/SDS
Output	`plan.yaml`
Handles	Waves, cycles, dependencies, branch naming

Responsibility: Transform specifications into actionable delivery plans structured as waves of TDD cycles.

3.2 Semantic Compiler

Attribute	Value
Input	Specs + Plan
Output	SEA™ DSL models, AST
Validates	SEA™ DSL policies, CALM constraints

Responsibility: Translate human-authored specifications into machine-readable semantic models.

3.3 Manifest Compiler

Attribute	Value
Input	AST
Output	Manifest(s)
Enforces	Architecture style mappings (e.g., Hexagonal)

Responsibility: Map semantic AST to structural manifests that define code organization.

3.4 Generator Schema Compiler

Attribute	Value
Input	Manifest
Output	Nx generator configs, bespoke generator schemas

Responsibility: Transform manifests into generator-specific input formats.

3.5 Generator Runner

Attribute	Value
Executes	Nx generators, bespoke generators
Writes to	Generated directories only
Produces	Regeneration hash for drift detection

Responsibility: Execute code generators deterministically.

3.6 Drift Detector

Attribute	Value
Action	Re-runs generators
Compares	Output to committed state
On mismatch	Fails build

Responsibility: Prevent unauthorized manual edits to generated code.

4. Data Models

4.1 Plan Schema

planVersion: "1.0"
release: "sprint-1"
waves:
  - id: "wave-1"
    name: "Foundation"
    cycles:
      - id: "cycle-1-1"
        name: "Core Domain Models"
        branch: "feat/wave-1/cycle-1-1-core-domain"
        depends: []
        specs:
          - "SDS-002"
      - id: "cycle-1-2"
        name: "Repository Ports"
        branch: "feat/wave-1/cycle-1-2-repo-ports"
        depends: ["cycle-1-1"]
        specs:
          - "SDS-003"

4.2 Override Record Schema

overrideId: "override-001"
reason: "Stripe SDK requires manual binding"
scope:
  - "libs/billing/adapters/stripe"
expiry: "2025-03-01"
backfillRef: "JIRA-1234"
approver: "tech-lead"
createdAt: "2025-01-15T10:00:00Z"

5. Execution Flow (TDD Cycle)

sequenceDiagram
    participant Dev as Developer
    participant Plan as Plan Compiler
    participant Sem as Semantic Compiler
    participant Man as Manifest Compiler
    participant Gen as Generator Runner
    participant CI as CI/CD Pipeline

    Dev->>Plan: Author specs
    Plan->>Plan: Generate plan.yaml
    Plan->>Sem: Compile to SEA™ DSL
    Sem->>Sem: Validate semantics
    Sem->>Man: Generate AST
    Man->>Man: Map to manifest
    Man->>Gen: Compile generator inputs
    Gen->>Gen: Execute generators
    Gen->>CI: Generated code
    CI->>CI: Run tests
    CI->>CI: Drift check
    CI->>Dev: Pass/Fail

Step-by-Step Flow

Branch created for TDD cycle
DSL/manifest updated by agent or developer
Generators executed deterministically
Tests run on generated code
Findings resolved upstream (DSL/manifest/schema)
Drift check ensures no manual edits
Merge to trunk on all gates passing

6. Security Model

Agent Permissions

Resource	Read	Write
Specifications (ADR/PRD/SDS)	✅	❌ (human only)
SEA™ DSL	✅	✅
Manifests	✅	✅
Generator Schemas	✅	✅
Generated Code	✅	❌

CI Enforcement

Directory immutability enforced via CI guards
Generated code directories are marked as readonly in .gitattributes
Manual edits trigger drift detection failure

7. CI/CD Integration

Mandatory Pipeline Steps

stages:
  - stage: semantic-validate
    command: sea semantic validate
    gate: true

  - stage: manifest-validate
    command: sea manifest validate
    gate: true

  - stage: generate
    command: sea generate
    gate: true

  - stage: test
    command: npm test
    gate: true

  - stage: drift-check
    command: sea drift check
    gate: true

CLI Commands

Command	Purpose
`sea semantic validate`	Validate SEA™ DSL models
`sea manifest validate`	Validate manifest schemas
`sea generate`	Execute generators
`sea drift check`	Compare generated vs committed
`sea plan compile`	Generate delivery plan from specs

8. Observability & Audit

Every stage emits artifacts for traceability
All transformations are diffable via semantic versioning
Full lineage preserved from spec → generated code

Audit Events

Event	Payload
`spec.authored`	Spec ID, author, timestamp
`plan.compiled`	Plan ID, wave count, cycle count
`semantic.validated`	Model hash, violations
`manifest.generated`	Manifest ID, DSL refs
`code.generated`	Output hash, generator version
`drift.detected`	File paths, expected vs actual hash

9. Failure Modes

Failure	Response
Semantic error	Block pipeline
Generator error	Fail cycle
Drift detected	Fail merge
Manual override without record	Hard fail

10. Extensibility

New generator types via schema adapters
New architecture styles via manifest compiler plugins
New validation gates via CI hooks
Custom projections via AST transformation plugins

11. Summary

SEA™ Forge Delivery Pipeline is a governed compilation system, not an agent coding framework.

Agents reason, translate, validate, and orchestrate
Generators write code
Semantics remain authoritative

12. Generated Artifacts

12.1 Code Generator Entrypoint

The code generator entrypoint tools/codegen/gen.py is a generated artifact defined by SDS-021.

Location: tools/codegen/gen.py

Purpose: Deterministically generates code from manifest.json files.

Required Parameters:

manifest.json path (positional argument)

Behavioral Contract:

Reads manifest.json from input path
Validates manifest against manifest.schema.json
Generates code to src/gen/ directories as defined in manifest outputRoots
Enforces path containment (all outputs must be under /src/gen/)
Produces deterministic output (same inputs → identical outputs)
No network access required (offline-first)

Determinism Guarantees:

Stable ordering of generated files
No timestamps or random identifiers in output
Template rendering is deterministic
File permissions are consistent

Generated Sections:

Type conversion utilities (_ts_type, _py_type, etc.)
Template environment setup with custom filters
Layer rendering functions (domain, ports, application, adapters)
Manifest validation against schema
Output path enforcement

12.2 Template-Based Generation

The generator uses Jinja2 templates from tools/codegen/templates/:

Template Mapping: | Layer | Template | Output | |——-|———-|——–| | Domain | entity.ts.jinja2 / entity.py.jinja2 | entities/* | | Types | value_object.ts.jinja2 / enum.ts.jinja2 | types/* | | Ports | port.ts.jinja2 / port.py.jinja2 | ports/* | | Application | command.ts.jinja2 / query.ts.jinja2 | commands/, queries/ | | Events | event.ts.jinja2 / event.py.jinja2 | events/* | | Adapters | adapter.ts.jinja2 / adapter.py.jinja2 | adapters/* |

Custom Filters:

ts_type - Convert SDS type to TypeScript
py_type - Convert SDS type to Python
snake_case - PascalCase to snake_case
parse_method_name, parse_method_params, parse_method_return - Method signature parsing