Patterns

1. Overview

A pattern is a reusable Ocean modeling solution — not a complete application, and not a DSL specification. Each pattern answers one question:

When I face this recurring design problem in Ocean, what modeling structure should I use, and why?

Patterns encode design judgment, not just facts. They matter most when deciding how to model something new — which is also what makes them valuable for retrieval-augmented generation and agents deciding how to approach a system they haven’t seen before.

2. How Patterns Differ from Other Knowledge

Knowledge type	Answers
DSL reference	What does this syntax mean?
Concept	What is the underlying model, and why does it work this way?
Pattern	Given this recurring problem, what reusable structure should I use?
Example	Does this solution actually work, end to end?
Voyage	How and why was this example built, step by step?

These roles chain together rather than duplicate each other:

Pattern: Asynchronous Request-Response
    ↓ recommends
Broker + correlation identifier + timeout handling
    ↓ demonstrated by
Asynchronous Answer Aggregation (async)
    ↓ governed by
Broker, Service, Context, and Expression references

A pattern recommends a structure. An example proves it in a runnable system. A Voyage teaches how that example was built. The DSL references that a pattern points to remain the authority on what its syntax means.

3. Pattern Structure

Every pattern in this catalogue follows the same eleven sections: Context, Problem, Forces, Solution, Structure (a small diagram), a minimal DSL sketch, Consequences, Alternatives, Related DSL, Working examples, and Related patterns. A DSL sketch is illustrative — the authoritative, runnable model lives in the linked working example, not in the pattern page.

4. Catalogue

Patterns already demonstrated by the published Ocean examples:

Pattern	Recurring problem	Demonstrated by
Synchronous API Composition	Combine several synchronous API results into one answer.	Synchronous Answer Aggregation
Asynchronous Request-Response	Answer a caller using broker request-response instead of direct API calls.	Asynchronous Answer Aggregation
Entity-Backed FSM	Govern a persistent entity’s lifecycle so only valid transitions apply.	Entity-Based Order FSM
In-Memory FSM	Model transient, mode-dependent behavior with no persisted identity.	In-Memory Calculator FSM
Approval Workflow	Record a human approve/reject decision atomically with its transition.	Invoice Approval Workflow
Secure Secret Access	Give a service typed secret access without secret values in the DSL.	Simple Vault Usage
Database-Backed CRUD	Connect a public API directly to an entity’s persistence operations.	Task Manager

5. Candidate Patterns Not Yet Published

These are good pattern candidates once a clear demonstrating example exists. They are listed here as a backlog, not published pages, so this catalogue never links to an empty document:

• Service orchestration across several owned domain behaviors
• Event-driven state transition without a synchronous request
• External expression implementation (delegating logic to native code)
• UI-to-API integration
• Reusable definition through Import or Include
• Idempotent event handling
• Timeout and failure handling as a cross-cutting concern

6. Contributing a Pattern

A new pattern belongs in this catalogue once it has a working example that demonstrates it. Give it a stable ID of the form pattern.<identifier>, a dedicated patterns/<identifier>.md file following the structure in Section 3, and add it to the table in Section 4.