Iteratively ingest conversation transcripts and documentation to build a Machine-Extractable DDD specification suite that enables deterministic SDS → SEA-DSL translation. The specification suite forms the “Single Source of Truth” for SEA-Forge™ code generation.

Design Principle: Treat ADR/PRD/SDS as compile targets, not prose documents. Every section must be extractable by an agent without hallucination or invention.

FOUNDATIONAL GUARANTEES

The following three principles underpin every aspect of spec authoring and translation. They form an inviolable contract between specifications and generated code.

1. Isomorphism (Structure Preservation)

Spec Layer	SEA-DSL/Code Layer	Isomorphic Guarantee
Entity (SDS)	`Entity` node	1:1 field mapping; no synthetic fields
Policy (SDS)	`Policy` node + validator	Rule expression preserved verbatim
Command (SDS)	`Flow @command` + handler	Input/output schema identical
Event (SDS)	`Event` node + contract	Payload schema identical
Port (SDS)	Interface definition	Method signatures preserved

Verification: Given any generated artifact, you can reconstruct the originating spec section. Given any spec section, the generated artifact is predictable.

Anti-Pattern: A spec states Entity: User but code generates Customer — this breaks isomorphism.

2. Invariants (Domain Truth Preservation)

Invariant Type	Scope	Enforcement Point	Example
Entity Invariant	Single aggregate	Constructor + state transitions	`order.items.length > 0`
Cross-Entity Invariant	Multiple aggregates	Domain service / saga	`inventory.available >= order.quantity`
Process Invariant	Workflow	Saga / policy handler	`payment.captured → order.confirmed`
System Invariant	Global	Infrastructure	`all events delivered at-least-once`

Preservation Rule: Invariants defined in SDS must appear verbatim in generated validators. The spec is the invariant’s canonical source; code is a projection.

Anti-Pattern: A spec defines POL-001: order.total > 0 but the generated validator allows total >= 0 — this violates invariant preservation.

3. Idempotency (Safe Repeatability)

Operation Type	Idempotency Requirement	Key Strategy	Example
Command	Required for all mutations	Natural key or dedup token	`PlaceOrder`: `customerId + hash(items)`
Event Handler	Required	Event ID + consumer offset	`OrderPlaced → ReserveStock`
Query	Inherent (no mutations)	N/A	`GetOrder`
Saga Step	Required	Step ID + saga instance	`PaymentStep`: `sagaId + stepIndex`

Anti-Pattern: A command lacks idempotency specification → the generator invents one (hallucination) or omits it (bug).

INPUT STATE

INTERNAL ONLY SPECS

Artifact	Path	Purpose
Manifest	`docs/specs/processing_manifest.md`	Processing queue
Context Map	`docs/specs/00_system_context_map.md`	Domain discovery index
ADR Template	See ADR TEMPLATE section	Decision record with compile-ready constraints
PRD Template	See PRD TEMPLATE section	EARS requirements with REQ-IDs
SDS Template	See SDS TEMPLATE section	Extractable design for SEA-DSL generation

Some core specifications are internal-only and are located in docs/specs/.internal/. If a spec file in docs/specs/ contains only a redirect notice, read the full content from the .internal/ path indicated.

Reading Internal Specs

When creating new specs that reference these internal documents, use the .internal/ paths.

Creating New Internal Specs

When drafting a new spec, evaluate whether it should be protected IP using the following criteria:

Criterion	Description	Weight
Non-Obvious Innovation	The approach is novel and not an obvious application of known techniques	High
Competitive Advantage	The design provides significant differentiation from alternatives	High
Proprietary Algorithm	Contains custom algorithms, proofs, or mathematical models	High
Security-Sensitive	Exposes threat models, cryptographic schemes, or attack surfaces	Medium
Core Architecture	Defines foundational patterns that underpin the entire system	Medium
Trade Secret Potential	Could be protected as a trade secret outside of patents	Medium

Decision Rule: If the spec meets 2+ High criteria OR 1 High + 2 Medium criteria, classify it as Internal Only.

Internal Spec Creation Protocol

Stub File Template

Use this template for stub files (see docs/specs/shared/sds/034-ifl-federated-ledger.md for a live example):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# <TYPE>-###: <Title>

> **INTERNAL ONLY specifications.**
>
> **Agents:** The full specification is located at `docs/specs/.internal/<ID>-<filename>.md`
>
> This file contains [brief description of what the internal spec covers].

## Summary (Public)

[2-3 sentences describing the spec's purpose at a high level, without revealing implementation details or proprietary approaches.]

## For Full Content

See: `docs/specs/.internal/<ID>-<filename>.md`

Stub Content Guidelines

EXECUTION PROTOCOL

PHASE 1: INGESTION & TRIAGE

PHASE 2: SYNTHESIS & CONFLICT RESOLUTION

PHASE 3: ARTIFACT GENERATION

PHASE 4: SYSTEM STATE UPDATE

ADR TEMPLATE (Decision Record — Compile-Ready)

ADRs must constrain downstream manifest and generator choices. Use structured sections for machine extraction.

Include in Stub	Exclude from Stub
Spec ID and title	Algorithms and pseudocode
High-level purpose	Detailed invariants and policies
Bounded context	Data structures and schemas
Related spec IDs	Security threat models
Pointer to internal path	Implementation details

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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
# ADR-###: <Title>

**Status:** Proposed | Accepted | Deprecated | Superseded  
**Version:** 1.0  
**Date:** YYYY-MM-DD  
**Supersedes:** ADR-### (if applicable)  
**Related ADRs:** ADR-###, ADR-### (if any)  
**Related PRDs:** PRD-### (if any)

---

## Context

[What problem domain this bounded context covers. Forces at play. Why a decision is needed.]

## Decision

[The architectural approach chosen: DDD + hexagonal + CQRS + UoW + outbox, etc.]

## Rationale

[Why this decision was made. Key reasoning. Supporting evidence. Alternatives considered.]

## Constraints (MUST/MUST NOT)

> **Critical for generator choices.** These constraints flow directly into manifests and SEA-DSL.

- MUST use Nx
- MUST use SEA™ pipeline
- MUST generate all runtime code from manifests
- MUST pin SEA™ CLI version in CI
- MUST NOT use raw SQL queries outside repository adapters
- MUST NOT bypass domain validation in commands

## Isomorphic Guarantees

> **Defines structure-preserving mappings** from this ADR to implementation.

| Spec Concept    | Implementation Target       | Mapping Rule                        |
| :-------------- | :-------------------------- | :---------------------------------- |
| Aggregate Root  | SEA™ `Entity @aggregate`     | 1:1; root owns transaction boundary |
| Domain Event    | SEA™ `Event` + outbox record | 1:1; schema identical               |
| Repository Port | Interface + DI binding      | 1:1; methods preserved              |
| Policy          | SEA™ `Policy` + validator    | 1:1; rule expression verbatim       |

## System Invariants

> **Non-negotiable truths** that must hold across the system.

| INV-ID  | Invariant                                      | Type    | Enforcement           |
| :------ | :--------------------------------------------- | :------ | :-------------------- |
| INV-001 | All domain events must be published via outbox | System  | Infrastructure        |
| INV-002 | Commands must be idempotent with explicit keys | Process | Handler generation    |
| INV-003 | No direct database access outside repositories | System  | Linting / code review |

## Quality Attributes

| Attribute    | Target                        | Rationale                      |
| :----------- | :---------------------------- | :----------------------------- |
| Latency      | p99 < 200ms                   | User experience requirement    |
| Consistency  | Strong within bounded context | Domain integrity               |
| Auditability | All state changes logged      | Compliance requirement         |
| Idempotency  | All commands retry-safe       | Distributed system reliability |

## Bounded Contexts Impacted

- `orders`
- `inventory`
- `notifications`

## Consequences

[Trade-offs and complexity this decision adds. What it enables. Migration considerations.]

---

## Success Criteria

Another developer can read this ADR and understand:

1. The architectural guardrails that constrain implementation choices.
2. The isomorphic mappings that guarantee spec-to-code fidelity.
3. The system invariants that must never be violated.

PRD TEMPLATE (EARS + Traceability)

PRDs use EARS (Easy Approach to Requirements Syntax) with strict metadata for agent traceability.

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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
# PRD-###: <Feature Name>

**Status:** Planned | In Progress | Implemented | Deferred  
**Version:** 1.0  
**Date:** YYYY-MM-DD  
**Priority:** High | Medium | Low  
**Satisfies:** [ADR-###, ADR-###]

---

## Overview

- **Feature:** Brief description
- **Business Value:** Why this feature matters
- **Target Users:** Who will use this feature

---

## Requirements

### REQ-###: <Requirement Title>

| Field               | Value                                                                         |
| :------------------ | :---------------------------------------------------------------------------- | ------------- | ---------- |
| **REQ-ID**          | REQ-###                                                                       |
| **Type**            | functional                                                                    | nonfunctional | constraint |
| **EARS**            | `<EARS statement>`                                                            |
| **Bounded-Context** | `orders` (single value, no "maybe")                                           |
| **Data Touched**    | `Order`, `OrderItem` (entity names, or `TBD`)                                 |
| **Invariants**      | `INV-###`, `POL-###` (invariants this requirement establishes or relies upon) |

**Acceptance Criteria (Given/When/Then):**

```gherkin
Given [precondition]
When [action]
Then [expected result]
And [invariant X still holds]
```

**Idempotency Requirement:**

| Aspect         | Specification             |
| :------------- | :------------------------ |
| Repeatable?    | yes / no                  |
| Safe to retry? | yes / no                  |
| Dedup strategy | natural key / token / N/A |

---

### REQ-###: <Another Requirement>

| Field               | Value                                          |
| :------------------ | :--------------------------------------------- |
| **REQ-ID**          | REQ-###                                        |
| **Type**            | functional                                     |
| **EARS**            | `When <trigger>, the system shall <response>.` |
| **Bounded-Context** | `orders`                                       |
| **Data Touched**    | `Order`, `Customer`                            |
| **Invariants**      | `POL-001`, `POL-002`                           |

**Acceptance Criteria:**

```gherkin
Given an authenticated user with a valid cart
When the user submits the order
Then the system creates an Order with status "pending"
And emits an OrderPlaced event
And POL-001 (order has items) holds
And POL-002 (order total > 0) holds
```

**Idempotency Requirement:**

| Aspect         | Specification              |
| :------------- | :------------------------- |
| Repeatable?    | yes                        |
| Safe to retry? | yes                        |
| Dedup strategy | `customerId + hash(items)` |

---

## Success Metrics

| KPI             | Target | Measurement Method |
| :-------------- | :----- | :----------------- |
| Conversion rate | > 70%  | Analytics funnel   |
| Error rate      | < 0.1% | Error monitoring   |

---

## Dependencies

- **Depends on:** PRD-###, ADR-###
- **Blocks:** PRD-###

## Related Specs

- ADR: ADR-###
- SDS: SDS-###

SDS TEMPLATE (Machine-Extractable Design)

The SDS structure guarantees isomorphism (1:1 mapping), invariant preservation (rules survive translation), and idempotency specification (safe repeatability is explicit).

Required Sections (Strict 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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
# SDS-###: <Component/System Name>

**Status:** Draft | Review | Approved | Implemented  
**Version:** 1.0  
**Date:** YYYY-MM-DD  
**Satisfies:** [PRD-###, PRD-###]  
**Bounded-Context:** `orders`

---

## 0. Isomorphism Declaration

> Declares the structure-preserving mappings for this SDS. Enables verification that translation is lossless.

| Spec Section      | SEA-DSL Target        | Cardinality | Verification                  |
| :---------------- | :-------------------- | :---------- | :---------------------------- |
| 2.1 Entities      | `Entity` nodes        | 1:1         | Field names + types match     |
| 2.2 Value Objects | `ValueObject` nodes   | 1:1         | Constraints preserved         |
| 3. Invariants     | `Policy` nodes        | 1:1         | Boolean expression verbatim   |
| 4. Commands       | `Flow @command`       | 1:1         | Input/output schema identical |
| 5. Queries        | `Flow @query`         | 1:1         | Input/output schema identical |
| 6. Events         | `Event` nodes         | 1:1         | Payload schema identical      |
| 7. Ports          | Interface definitions | 1:1         | Method signatures preserved   |

---

## 1. Domain Glossary

> Prevents naming drift (hallucinations love synonyms). Establishes **canonical vocabulary** for isomorphic translation.

| Term        | Definition                     | Type    | Notes                               | Canonical? |
| :---------- | :----------------------------- | :------ | :---------------------------------- | :--------- |
| Order       | A customer's purchase request  | Entity  | Aggregate root                      | ✓          |
| OrderItem   | A line item within an order    | Entity  |                                     | ✓          |
| OrderId     | Unique identifier for an order | VO      | UUID v7                             | ✓          |
| OrderStatus | Current state of an order      | Enum    | pending/confirmed/shipped/cancelled | ✓          |
| OrderPlaced | Event when order is created    | Event   |                                     | ✓          |
| PlaceOrder  | Command to create a new order  | Command |                                     | ✓          |

> **Isomorphism Rule:** Only terms marked `Canonical? ✓` may appear in SEA-DSL. Synonyms must be resolved before translation.

---

## 2. Domain Model (Canonical Tables)

### 2.1 Entities

| Entity    | Fields                                                                                               | Identity | Aggregate Root | Entity Invariants |
| :-------- | :--------------------------------------------------------------------------------------------------- | :------- | :------------- | :---------------- |
| Order     | `id: OrderId`, `status: OrderStatus`, `customerId: CustomerId`, `items: OrderItem[]`, `total: Money` | `id`     | yes            | POL-001, POL-002  |
| OrderItem | `id: OrderItemId`, `productId: ProductId`, `quantity: Quantity`, `unitPrice: Money`                  | `id`     | no             | POL-003           |

### 2.2 Value Objects

| Value Object | Fields                               | Constraints                    | Self-Invariants              |
| :----------- | :----------------------------------- | :----------------------------- | :--------------------------- |
| OrderId      | `value: string`                      | UUID v7 format                 | Format validation            |
| Money        | `amount: number`, `currency: string` | amount >= 0, currency ISO 4217 | Non-negative, valid currency |
| Quantity     | `value: number`                      | value > 0, integer             | Positive integer             |

### 2.3 Enums

| Enum        | Values                                         | Transitions Allowed     |
| :---------- | :--------------------------------------------- | :---------------------- |
| OrderStatus | `pending`, `confirmed`, `shipped`, `cancelled` | See state machine below |

**OrderStatus State Machine Invariant:**

pending → confirmed | cancelled confirmed → shipped | cancelled shipped → (terminal) cancelled → (terminal)

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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
> **Invariant INV-010:** Status transitions must follow the state machine. No backward transitions.

---

## 3. Invariants & Policies

> Becomes SEA™ `Policy` nodes. Enables generated validators. **These are the domain truths that must survive translation.**

### 3.1 Entity Invariants

| POL-ID   | Applies-To | Invariant Type | Rule (Boolean Expression)                       | Error Code         | Error Message                      | Satisfies  |
| :------- | :--------- | :------------- | :---------------------------------------------- | :----------------- | :--------------------------------- | :--------- |
| POL-001  | Order      | Entity         | `order.items.length > 0`                        | `ORDER_EMPTY`      | Order must have at least one item  | REQ-001    |
| POL-002  | Order      | Entity         | `order.total.amount > 0`                        | `ORDER_ZERO_TOTAL` | Order total must be positive       | REQ-001    |
| POL-003  | OrderItem  | Entity         | `item.quantity > 0 AND item.quantity <= 100`    | `INVALID_QTY`      | Quantity must be between 1 and 100 | REQ-002    |

### 3.2 Cross-Entity Invariants

| POL-ID   | Applies-To           | Invariant Type | Rule                                            | Enforcement        | Satisfies  |
| :------- | :------------------- | :------------- | :---------------------------------------------- | :----------------- | :--------- |
| POL-004  | Order, Inventory     | Cross-Entity   | `inventory.available(item.productId) >= item.quantity` | Domain Service | REQ-001    |

### 3.3 Process Invariants

| POL-ID   | Process              | Invariant Type | Rule                                            | Enforcement        | Satisfies  |
| :------- | :------------------- | :------------- | :---------------------------------------------- | :----------------- | :--------- |
| POL-005  | OrderFulfillment     | Process        | `payment.captured → order.status = confirmed`   | Saga               | REQ-005    |

> **Isomorphism Guarantee:** Each POL-ID maps to exactly one `Policy` node in SEA-DSL. The `Rule` column content appears verbatim in the generated validator.

---

## 4. CQRS: Commands

> Generates command DTO + handler + UoW semantics + event emission rules.

### CMD-001: PlaceOrder

| Field             | Value                                                  |
| :---------------- | :----------------------------------------------------- |
| **CMD-ID**        | CMD-001                                                |
| **Input**         | `customerId: CustomerId`, `items: CreateOrderItem[]`   |
| **Preconditions** | POL-001, POL-003, POL-004                              |
| **State Changes** | Creates new `Order` with status `pending`              |
| **Emits Events**  | EVT-001 (OrderPlaced)                                  |
| **Satisfies**     | REQ-001                                                |

**Idempotency Specification:**

| Idempotent? | Key Expression | Strategy | Behavior on Duplicate |
| :---------- | :------------- | :------- | :-------------------- |
| yes | `customerId + hash(items)` | Natural key | Return existing order ID |

**Transactionality:**

| Transactional? | Boundary | Isolation Level | Rollback Trigger |
| :------------- | :------- | :-------------- | :--------------- |
| yes | Order aggregate | Read Committed | Any POL failure |

### CMD-002: CancelOrder

| Field             | Value                                                  |
| :---------------- | :----------------------------------------------------- |
| **CMD-ID**        | CMD-002                                                |
| **Input**         | `orderId: OrderId`, `reason: string`                   |
| **Preconditions** | `order.status IN ['pending', 'confirmed']` (INV-010)   |
| **State Changes** | `order.status := 'cancelled'`                          |
| **Emits Events**  | EVT-002 (OrderCancelled)                               |
| **Satisfies**     | REQ-003                                                |

**Idempotency Specification:**

| Idempotent? | Key Expression | Strategy | Behavior on Duplicate |
| :---------- | :------------- | :------- | :-------------------- |
| yes | `orderId` | Entity state check | No-op if already cancelled |

**Transactionality:**

| Transactional? | Boundary | Isolation Level | Rollback Trigger |
| :------------- | :------- | :-------------- | :--------------- |
| yes | Order aggregate | Read Committed | Invalid status transition |

---

## 5. CQRS: Queries

> Generates query DTO + handler + read adapter. Queries are inherently idempotent.

### QRY-001: GetOrder

| Field           | Value                                                  |
| :-------------- | :----------------------------------------------------- |
| **QRY-ID**      | QRY-001                                                |
| **Input**       | `orderId: OrderId`                                     |
| **Output**      | `OrderDetailDto { id, status, items[], total, createdAt }` |
| **Read Model**  | `orders_view`                                          |
| **Consistency** | strong                                                 |
| **Satisfies**   | REQ-004                                                |
| **Idempotent?** | yes (inherent — no mutations)                          |

### QRY-002: ListOrdersByCustomer

| Field           | Value                                                  |
| :-------------- | :----------------------------------------------------- |
| **QRY-ID**      | QRY-002                                                |
| **Input**       | `customerId: CustomerId`, `page: number`, `limit: number` |
| **Output**      | `OrderSummaryDto[] { id, status, total, createdAt }`   |
| **Read Model**  | `orders_by_customer_view`                              |
| **Consistency** | eventual                                               |
| **Satisfies**   | REQ-005                                                |
| **Idempotent?** | yes (inherent — no mutations)                          |

---

## 6. Domain Events

> Generates event contracts + bus bindings + outbox config.

### EVT-001: OrderPlaced

| Field            | Value                                                  |
| :--------------- | :----------------------------------------------------- |
| **EVT-ID**       | EVT-001                                                |
| **Payload**      | `orderId: OrderId`, `customerId: CustomerId`, `total: Money`, `placedAt: DateTime` |
| **Published To** | `orders.events`                                        |
| **Consumers**    | `inventory` (ReserveStock), `notifications` (SendConfirmation) |
| **Delivery**     | at-least-once                                          |
| **Outbox**       | required: yes                                          |
| **Satisfies**    | REQ-001                                                |

**Consumer Idempotency Contract:**

| Consumer | Handler | Idempotency Key | Behavior on Replay |
| :------- | :------ | :-------------- | :----------------- |
| inventory | ReserveStock | `eventId + orderId` | Skip if reservation exists |
| notifications | SendConfirmation | `eventId` | Skip if notification sent |

### EVT-002: OrderCancelled

| Field            | Value                                                  |
| :--------------- | :----------------------------------------------------- |
| **EVT-ID**       | EVT-002                                                |
| **Payload**      | `orderId: OrderId`, `reason: string`, `cancelledAt: DateTime` |
| **Published To** | `orders.events`                                        |
| **Consumers**    | `inventory` (ReleaseStock), `notifications` (SendCancellation) |
| **Delivery**     | at-least-once                                          |
| **Outbox**       | required: yes                                          |
| **Satisfies**    | REQ-003                                                |

**Consumer Idempotency Contract:**

| Consumer | Handler | Idempotency Key | Behavior on Replay |
| :------- | :------ | :-------------- | :----------------- |
| inventory | ReleaseStock | `eventId + orderId` | Skip if already released |
| notifications | SendCancellation | `eventId` | Skip if notification sent |

> **Isomorphism Guarantee:** Event payload schema in spec = event contract in generated code. No field additions, removals, or renames.

---

## 7. Ports

> Prevents agents from inventing ports inconsistently. Ports are the isomorphic boundary between domain and infrastructure.

| PORT-ID   | Port Name         | Direction | Methods                                      | Used By       | Backed By Adapter       |
| :-------- | :---------------- | :-------- | :------------------------------------------- | :------------ | :---------------------- |
| PORT-001  | OrderRepository   | outbound  | `save(order)`, `findById(id)`, `findByCustomer(customerId)` | CMD-001, CMD-002, QRY-001, QRY-002 | PostgresOrderAdapter |
| PORT-002  | EventPublisher    | outbound  | `publish(event)`                             | CMD-001, CMD-002 | KafkaEventAdapter |
| PORT-003  | InventoryClient   | outbound  | `checkAvailability(items)`                   | CMD-001       | HttpInventoryAdapter |

> **Isomorphism Guarantee:** Port method signatures in spec = interface definitions in code. Adapters implement these interfaces exactly.

---

## 8. Adapters (Implementation Choices)

> Becomes manifest runtime selections.

| Category       | Choice                          | Notes                            |
| :------------- | :------------------------------ | :------------------------------- |
| Persistence    | PostgreSQL + Drizzle ORM        | Primary datastore                |
| Message Bus    | Kafka                           | Production; InMemory for tests   |
| API            | Hono + OpenAPI                  | REST + auto-generated docs       |
| AuthN/Z        | JWT + RBAC                      | Via gateway                      |
| Observability  | OpenTelemetry (logs/metrics/traces) | Unified observability        |

---

## 9. DI/Wiring

> Prevents DI hallucinations. Makes composition root generation deterministic.

| Port              | Adapter Implementation      | Lifetime         | Invariant |
| :---------------- | :-------------------------- | :--------------- | :-------- |
| OrderRepository   | PostgresOrderAdapter        | request          | INV-003 (no direct DB) |
| EventPublisher    | KafkaEventAdapter           | singleton        | INV-001 (outbox required) |
| InventoryClient   | HttpInventoryAdapter        | singleton        | — |

---

## 10. Invariant Summary

> Consolidated view of all invariants for verification.

| INV-ID   | Statement | Type | Defined In | Enforced By |
| :------- | :-------- | :--- | :--------- | :---------- |
| POL-001  | Order must have items | Entity | SDS 3.1 | Order constructor |
| POL-002  | Order total must be positive | Entity | SDS 3.1 | Order constructor |
| POL-003  | Quantity 1-100 | Entity | SDS 3.1 | OrderItem constructor |
| POL-004  | Inventory availability | Cross-Entity | SDS 3.2 | PlaceOrder handler |
| POL-005  | Payment → confirmation | Process | SDS 3.3 | OrderFulfillment saga |
| INV-010  | Status state machine | Entity | SDS 2.3 | Order.transition() |

---

## 11. Related Specs

- **ADRs:** ADR-001, ADR-003
- **PRDs:** PRD-001
- **Other SDS:** SDS-002 (Inventory), SDS-003 (Notifications)

TRACEABILITY REQUIREMENTS

The following ID scheme creates a requirements graph that agents cannot circumvent:

1
ADR-### → PRD-### → REQ-### → SDS(CMD/QRY/POL/EVT/PORT) → SEA™ nodes → generated code files

Isomorphic Traceability

Observable Success

PITFALLS TO AVOID

ANTI-HALLUCINATION STRATEGIES

Core Strategies

Verification Questions

From	To	Isomorphism Type	Verification
REQ → CMD	Requirement → Command	Functional decomposition	REQ.action = CMD.stateChange
POL → Policy node	Invariant → Validator	Rule preservation	POL.rule = Policy.expression
EVT → Event node	Spec event → Contract	Schema identity	EVT.payload = Event.schema
PORT → Interface	Port → Code interface	Signature preservation	PORT.methods = Interface.methods

Layer	ID Example	Links To	Isomorphic To
ADR	ADR-001	→ PRD-001, PRD-002	Constraints → manifest
PRD	PRD-001	→ ADR-001; contains REQ-001..005	Requirements → handlers
REQ (in PRD)	REQ-001	→ CMD-001, EVT-001, POL-001	EARS → implementation
CMD (in SDS)	CMD-001	→ REQ-001, EVT-001, POL-001	Command spec → handler
EVT (in SDS)	EVT-001	→ REQ-001	Event spec → contract
POL (in SDS)	POL-001	→ REQ-001	Invariant → validator
PORT (in SDS)	PORT-001	→ CMD-001, QRY-001	Port → interface

Symptom	Cause	Fix	Violated Principle
Duplicate/mismatched entities in SEA™	Ambiguous naming (“Customer” vs “User”)	Use Domain Glossary; enforce single term	Isomorphism
Validators missing edge cases	Prose-only invariants	Use structured POL table with boolean rules	Invariants
Double-processing bugs, event duplication	Missing idempotency flags	Always specify `Idempotency: yes/no + key`	Idempotency
CRUD handlers instead of rich domain	Missing transactional/state-change specs	Use CMD table with explicit state changes	Invariants
Inconsistent ports across commands	Agents invent ports ad-hoc	Use PORT table; reference by PORT-ID	Isomorphism
Event replay causes side effects	Missing consumer idempotency	Specify `Consumer Idempotency Contract`	Idempotency
Validator allows invalid state	Invariant lost in translation	Verify POL.rule = generated expression	Isomorphism + Invariants
Spec says X, code does Y	No isomorphism verification	Add `Isomorphism Declaration` section	Isomorphism

Principle	Verification Question	Expected Answer
Isomorphism	Can I reconstruct this spec from the generated code?	Yes, 1:1
Isomorphism	Does every spec element have exactly one code target?	Yes
Invariants	Are all “must/always/never” statements captured as POL-###?	Yes
Invariants	Will the invariant rule appear verbatim in the validator?	Yes
Idempotency	Does every command specify its idempotency strategy?	Yes
Idempotency	Does every event consumer specify replay behavior?	Yes
Idempotency	Would running this compilation twice change anything?	No

COMMAND: Begin with Phase 1 (Ingestion & Triage). Report findings before proceeding.

SYSTEM: ARCHITECTURAL COMPILER v3.1 (SEA-DSL Ready)

OBJECTIVE