Ref-011: SEA™ Forge Manifest Schema Specification

Document Type

Reference / Schema Specification

Purpose

Defines the compiler output manifest (manifest.json) generated by ir_to_manifest.py from SEA™ IR. This manifest bridges SEA™ semantics to code generation, serving as the canonical input for generators.

Design Principles

  1. Compiler output, not hand-written - Generated from IR via ir_to_manifest.py
  2. Schema-validated - Must validate against tools/schemas/manifest.schema.json
  3. Deterministic - Identical IR produces byte-identical manifest
  4. Output containment - All outputRoots must be under **/src/gen/**

Manifest Schema (v1.0)

JSON Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

{
  "manifestVersion": "1.0",
  "context": {
    "name": "bounded-context-name",
    "sdsId": "SDS-XXX",
    "prdIds": ["PRD-001", "PRD-002"],
    "adrIds": ["ADR-003", "ADR-012"]
  },
  "runtime": {
    "language": "python",
    "api": {
      "framework": "fastapi"
    },
    "persistence": {
      "kind": "postgres",
      "orm": "sqlalchemy",
      "migrations": "alembic"
    },
    "messaging": {
      "kind": "kafka",
      "outbox": {
        "enabled": true,
        "table": "outbox_events"
      }
    }
  },
  "codegen": {
    "outputRoots": {
      "domain": "libs/{context}/domain/src/gen",
      "application": "libs/{context}/application/src/gen",
      "ports": "libs/{context}/ports/src/gen",
      "adapters": "libs/{context}/adapters/src/gen",
      "apiApp": "apps/api/src/gen",
      "webApp": "apps/web/src/gen"
    }
  },
  "model": {
    "types": {},
    "aggregates": {},
    "policies": {},
    "cqrs": {
      "commands": {},
      "queries": {}
    },
    "events": {},
    "ports": {}
  }
}

Schema Field Reference

Top-Level Fields (Required)

Field Type Description
manifestVersion string Schema version (currently "1.0")
context object Bounded context identity and traceability
runtime object Runtime technology stack configuration
codegen object Code generation output paths and settings
model object Domain model extracted from IR

context (Required)

Field Type Required Description
name string ✅ Bounded context name (from metadata.namespace)
sdsId string ✅ Software Design Spec reference
prdIds array ✅ Product Requirements Doc references
adrIds array ❌ Architecture Decision Record references

Purpose: Traceability from manifest back to requirements and design docs.

Example:

1
2
3
4
5
6

{
  "name": "order",
  "sdsId": "SDS-021",
  "prdIds": ["PRD-004"],
  "adrIds": ["ADR-003", "ADR-012"]
}

runtime (Required)

Declares the target runtime technology stack.

Field Type Required Description
language string ✅ Primary language: "python", "typescript", "go", "rust"
api object ✅ API framework configuration
persistence object ✅ Database and ORM configuration
messaging object ✅ Message broker and outbox configuration

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "language": "python",
  "api": {
    "framework": "fastapi"
  },
  "persistence": {
    "kind": "postgres",
    "orm": "sqlalchemy",
    "migrations": "alembic"
  },
  "messaging": {
    "kind": "kafka",
    "outbox": {
      "enabled": true,
      "table": "outbox_events"
    }
  }
}

codegen (Required)

Defines where generators write output. All paths MUST be under **/src/gen/**.

Field Type Required Description
outputRoots object ✅ Mapping of layer names to output paths

outputRoots keys (hexagonal architecture):

Key Path Pattern Purpose
domain libs/{context}/domain/src/gen Domain entities, aggregates, value objects
application libs/{context}/application/src/gen Use cases, command/query handlers
ports libs/{context}/ports/src/gen Port interfaces (inbound/outbound)
adapters libs/{context}/adapters/src/gen Adapter implementations
apiApp apps/api/src/gen API layer (controllers, DTOs)
webApp apps/web/src/gen Web UI layer

Example:

1
2
3
4
5
6
7
8
9
10

{
  "outputRoots": {
    "domain": "libs/order/domain/src/gen",
    "application": "libs/order/application/src/gen",
    "ports": "libs/order/ports/src/gen",
    "adapters": "libs/order/adapters/src/gen",
    "apiApp": "apps/api/src/gen",
    "webApp": "apps/web/src/gen"
  }
}

Invariant: Generators MUST fail if attempting to write outside declared outputRoots. See SDS-021 §3.5 Generator Runner.

model (Required)

Contains the domain model extracted from IR.

Field Type Required Description
types object ✅ Resource types (from IR symbols.resources)
aggregates object ✅ Domain aggregates (from IR symbols.entities)
policies object ✅ Business rules (from IR constraints.policies)
cqrs object ✅ Commands and queries (from IR behavior.flows)
events object ✅ Domain events (from IR behavior.flows with @cqrs.kind = "event")
ports object ✅ Port interfaces (currently empty, reserved for future use)

model.types

Extracted from IR symbols.resources.

Structure: { [resourceName: string]: ResourceSymbol }

Example:

1
2
3
4
5
6
7
8
9
10

{
  "Payment": {
    "id": "resource:order:Payment",
    "kind": "resource",
    "name": "Payment",
    "namespace": "order",
    "exported": true,
    "raw": { "type": "Resource", "name": "Payment" }
  }
}

model.aggregates

Extracted from IR symbols.entities. Currently minimal; enriched by generators.

Structure: { [entityName: string]: { fields: {} } }

Example:

1
2
3
4
5
6
7
8

{
  "Order": {
    "fields": {}
  },
  "Customer": {
    "fields": {}
  }
}

model.policies

Extracted from IR constraints.policies.

Structure: { [policyId: string]: PolicyObject }

Example:

1
2
3
4
5
6
7
8
9

{
  "policy:order:ValidOrder": {
    "id": "policy:order:ValidOrder",
    "name": "ValidOrder",
    "namespace": "order",
    "exported": true,
    "raw": { /* AST node */ }
  }
}

model.cqrs

Flows tagged with @cqrs.kind = "command" or "query".

Structure:

1
2
3
4
5
6
7
8

{
  "commands": {
    "[flowName]": { /* Flow object */ }
  },
  "queries": {
    "[flowName]": { /* Flow object */ }
  }
}

Flow classification:

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "commands": {
    "CreateOrder": {
      "id": "flow:order:CreateOrder",
      "name": "CreateOrder",
      "tags": ["command"],
      "runtime": {
        "transactional": true,
        "idempotency": { "enabled": true, "key": "header:X-Idempotency-Key" },
        "outbox": null,
        "readModel": { "source": null, "table": null }
      }
    }
  },
  "queries": {
    "GetOrder": {
      "id": "flow:order:GetOrder",
      "name": "GetOrder",
      "tags": ["query"],
      "runtime": {
        "transactional": null,
        "idempotency": { "enabled": false, "key": null },
        "outbox": null,
        "readModel": { "source": "projection", "table": "order_read" }
      }
    }
  }
}

model.events

Flows tagged with @cqrs.kind = "event".

Structure: { [eventName: string]: FlowObject }

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "OrderPlaced": {
    "id": "flow:order:OrderPlaced",
    "name": "OrderPlaced",
    "tags": ["event"],
    "runtime": {
      "transactional": null,
      "idempotency": { "enabled": false, "key": null },
      "outbox": "required",
      "readModel": { "source": null, "table": null }
    }
  }
}

Manifest Compilation Flow

1
2
3
4
5
6
7
8
9

SEA™ DSL (.sea)
    ↓
SEA™ Compiler → AST (.ast.json)
    ↓
ast_to_ir.py → IR (.ir.json)
    ↓
ir_to_manifest.py → manifest.json
    ↓
Generators (gen.py, Nx) → **/src/gen/** (read-only output)

Validation Rules

Schema Validation

  1. IR validation: ir_to_manifest.py validates input against tools/schemas/sea_ir.schema.json
  2. Manifest validation: Output must validate against tools/schemas/manifest.schema.json
  3. Hard-fail on schema errors: Exit code 2 on validation failure

Output Path Enforcement

  1. All codegen.outputRoots values MUST match pattern: **/src/gen
  2. Generators MUST refuse to write outside declared outputRoots
  3. See SDS-021 §3.5 Generator Runner for enforcement details

Determinism

  1. Re-running ir_to_manifest.py on identical IR MUST produce byte-identical manifest
  2. Enforced by:

Example: Minimal Manifest

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "manifestVersion": "1.0",
  "context": {
    "name": "order",
    "sdsId": "SDS-021",
    "prdIds": ["PRD-004"],
    "adrIds": ["ADR-012"]
  },
  "runtime": {
    "language": "python",
    "api": { "framework": "fastapi" },
    "persistence": { "kind": "postgres", "orm": "sqlalchemy", "migrations": "alembic" },
    "messaging": { "kind": "kafka", "outbox": { "enabled": true, "table": "outbox_events" } }
  },
  "codegen": {
    "outputRoots": {
      "domain": "libs/order/domain/src/gen",
      "application": "libs/order/application/src/gen",
      "ports": "libs/order/ports/src/gen",
      "adapters": "libs/order/adapters/src/gen",
      "apiApp": "apps/api/src/gen",
      "webApp": "apps/web/src/gen"
    }
  },
  "model": {
    "types": {},
    "aggregates": { "Order": { "fields": {} } },
    "policies": {},
    "cqrs": { "commands": {}, "queries": {} },
    "events": {},
    "ports": {}
  }
}

Traceability

Spec Satisfies
SDS-021 §3.3 Manifest Compiler
ADR-012 Delivery Pipeline (Stage 5: IR → Manifest)
P-CC C2B Manifest Spec Alignment