Validation Guide

Linting, validation, and troubleshooting for SEA™ DSL files.

Validation Commands

Validate Syntax

1
just sea-validate <file.sea>

Parse to AST

1
just sea-parse <file.sea>

Lint Flows (REQUIRED)

1
python tools/flow_lint.py --strict <file.sea>

Validate All Specs

1
just spec-guard

Flow Lint Requirements

Every Flow MUST have @cqrs annotation.

Annotation Format Rules

1. Use nested JSON objects only
2. Never use dotted keys
3. Validate against AST schema

// ✅ Correct
@cqrs { "kind": "command" }

// ❌ Incorrect
@cqrs.kind "command"

Common Errors

E01: Missing @cqrs

Error: flow_lint.py: Flow "CreateOrder" missing @cqrs annotation

Fix:

Flow "CreateOrder"
  @cqrs { "kind": "command" }  // Add this
from "A" to "B"

E02: Dotted Annotation Key

Error: Invalid annotation format: dotted keys not allowed

Fix:

// ❌ Wrong
@cqrs.kind "command"

// ✅ Correct
@cqrs { "kind": "command" }

E03: Unbound Identifier

Error: Unknown identifier 'f' in expression

Fix:

// ❌ Wrong - f is unbound
Policy check as: (f.quantity > 0)

// ✅ Correct - bind with forall
Policy check as: forall f in flows: (f.quantity > 0)

E04: Domain Collision

Error: Duplicate entity 'Customer' in merged namespace

Fix:

// ❌ Wrong - no domain
Entity "Customer"

// ✅ Correct - explicit domain
Entity "Customer" in sales

E05: Invalid Expression

Error: Policy expression must be boolean

Fix:

// ❌ Wrong - string, not boolean
Policy check as: "amounts must be positive"

// ✅ Correct - boolean expression
Policy check as: (amount > 0)

E06: Invalid Version Format

Error: Invalid version format: expected vX.Y.Z

Fix:

// ❌ Wrong
Entity "Order" v1

// ✅ Correct
Entity "Order" v1.0.0

Pre-Commit Validation

Add to .githooks/pre-commit:

1
2
3
4
5
6
#!/bin/bash
# Validate all .sea files
for file in $(git diff --cached --name-only | grep '\.sea$'); do
  just sea-validate "$file" || exit 1
  python tools/flow_lint.py --strict "$file" || exit 1
done

CI Integration

1
2
3
4
5
# .github/workflows/ci.yml
- name: Validate SEA™ DSL
  run: |
    just spec-guard
    find docs/specs -name "*.sea" -exec python tools/flow_lint.py --strict {} \;

Debugging Tips

1. Validate Incrementally

1
2
3
4
5
# Start with single file
just sea-validate docs/specs/orders/orders.sea

# Then validate all
just spec-guard

2. Check AST Output

1
just sea-parse docs/specs/orders/orders.sea | jq .

3. Enable Verbose Linting

1
python tools/flow_lint.py --verbose docs/specs/orders/orders.sea

4. Check Imports

Ensure imported modules exist:

1
ls docs/specs/<module>/

Last Updated: January 2026