Implementation Plan: SEA-DSL Toolchain

Build the SEA-DSL parsing, validation, formatting, and compilation toolchain with IDE/LSP support, ensuring deterministic AST → IR → Manifest output and strict flow annotation contracts.

Provenance & Traceability

Architectural Decisions (ADRs)

Product Requirements (PRDs)

Software Design Specifications (SDS)

Provenance Chain

graph TD
  ADR4[ADR-004: Semantic Core] --> PRD1[PRD-001: Unified Semantics]
  ADR23[ADR-023: SEA-DSL Policy Shift] --> PRD2[PRD-002: Rule Enforcement]
  PRD1 --> SDS2[SDS-002: DSL Service]
  PRD2 --> SDS2

Architecture and Design

Design Principles Applied

• Isomorphism: SEA-DSL is the single source of truth; AST/IR must be deterministic.
• Invariants: Flow annotation contract enforced (CQRS + tx/outbox/idempotency/read-model).
• Idempotency: Formatting and compilation are repeatable with byte-identical outputs.

Dependency Justification

Updated 2025-12-30: Added specific dependencies from gap analysis section 1.2 (SEA-DSL Parsing & Compilation).

Installation Commands

1
2
3
4
5
6
7
8
# Node.js dependencies
pnpm add tree-sitter tree-sitter-cli @babel/traverse @babel/types @open-policy-agent/opa-wasm

# Python dependencies (in pyproject.toml)
pip install tree-sitter

# OPA CLI (via mise)
mise use opa@0.70.0

SEA-DSL Parsing Pipeline

1
2
3
4
5
6
7
8
9
10
11
// SEA-DSL Parser Port
interface SeaDslParserPort {
  parse(source: string): Promise<SeaAst>;
  validate(ast: SeaAst): Promise<ValidationReport>;
}

// Policy Evaluator Port (wraps OPA)
interface PolicyEvaluatorPort {
  evaluatePolicy(policyId: string, input: object): Promise<PolicyResult>;
  compileRego(regoSource: string): Promise<CompiledPolicy>;
}

Existing Toolchain Components

• AST schema: tools/schemas/ast-v3.schema.json
• IR schema: tools/schemas/sea_ir.schema.json
• Linter: tools/flow_lint.py
• Compiler: tools/ast_to_ir.py

Expected Filetree

1
2
3
4
5
6
/
├── tools/flow_lint.py
├── tools/ast_to_ir.py
├── tools/schemas/ast-v3.schema.json
├── tools/schemas/sea_ir.schema.json
└── docs/reference/sea_dsl_language_reference.yml

Proposed Cycles

Task Breakdown

Wave 1 (Parallel)

• C1A: Lock SEA-DSL grammar/idioms and formatting expectations
  • Implements: Stable authoring experience and deterministic parsing
  • Satisfies: PRD-001 (DSL parsing)
  • Files: docs/reference/sea_dsl_language_reference.yml, docs/reference/sea_dsl_language_idioms.yml
• C1B: Enforce flow annotation contract via schema + lint
  • Implements: CQRS kind + tx/outbox/idempotency/read_model rules
  • Satisfies: PRD-002 (automated enforcement)
  • Files: tools/flow_lint.py, tools/schemas/ast-v2.schema.json

Wave 2 (Depends on Wave 1)

• C2A: Provide semantic hover/diagnostics via LSP/MCP integration
  • Implements: Authoritative semantic probes in editor
  • Satisfies: ADR-017
  • Files: docs/specs/shared/sds/041-ultimate-lsp-hover-specification.md

Validation & Verification

Spec Validation

• SEA-DSL examples conform to sea_dsl_language_reference.yml
• Flow annotations pass tools/flow_lint.py --strict

Implementation Validation

• AST and IR validate against schemas
• AST → IR compilation deterministic across platforms

Open Questions

1. Should ast_to_ir.py reject dotted annotation keys entirely (to match the “nested JSON only” rule)? Reject entirely
2. Where is the canonical formatter spec for SEA-DSL (and should it be enforced in CI)? sea_dsl_language_reference.yml + CI
3. Is LSP a separate binary or embedded in an editor extension for MVP? Embedded in extension (MVP)

Risks & Mitigation

Rollback Strategy

1. Run lint in warn-only mode while updating legacy specs, then re-enable strict mode.

Related Documents

Linked Specifications

Note: SDS-041 (Ultimate LSP Hover) has been superseded by SDS-052 per ADR-017.