Control Structure

1. Overview

Ocean separates system behavior into complementary control structures:

• services define deployable orchestration boundaries;
• components compose related behavior into reusable domain units;
• FSMs own state and state transitions;
• expressions provide stateless calculations, conditions, validation, mapping, and transformation.

These structures form a composition model rather than a rigid implementation stack.

Conceptually:

Service
   │
   ├── external contracts and infrastructure
   ├── Components
   │      ├── FSMs
   │      ├── Expressions
   │      └── nested Components
   ├── FSMs
   └── Expressions

The exact elements permitted in each scope are defined by the corresponding DSL references.

---

2. Core Principle

Each control structure has a distinct responsibility.

Service     → deployment and orchestration boundary
Component   → stateless behavioral composition
FSM         → stateful behavior
Expression  → stateless logic

This separation keeps deployment concerns, composition, state management, and pure logic explicit in the Ocean model.

Larger systems are assembled by connecting these responsibilities rather than concentrating them in one construct.

---

3. Composition Model

The main composition flow is:

External input
      │
      ▼
Service boundary
      │
      ▼
Component composition
      │
      ▼
FSM behavior
      │
      ▼
State transitions and outputs

Expressions may participate wherever the receiving DSL construct explicitly permits stateless logic.

                  ┌──────────────┐
                  │  Expression  │
                  └──────┬───────┘
                         │
               conditions, mapping,
             validation, transformation
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
     Service          Component          FSM

This diagram describes semantic roles. It does not imply that every DSL construct can invoke every other construct directly.

---

4. Services

A service defines a deployable orchestration boundary.

It brings domain behavior together with the contracts and infrastructure required to expose that behavior as a runnable system unit.

A service may be responsible for:

• exposing APIs;
• receiving or publishing broker messages;
• connecting external inputs to domain behavior;
• composing components;
• coordinating supported FSMs and expressions;
• connecting databases and persistence concerns;
• defining configuration and deployment-facing behavior;
• establishing the boundary of generated output.

A service is not limited to one implementation technology or deployment style. “Microservice” may describe one generated form, but it is not the semantic definition of the Ocean construct.

The exact syntax and permitted service elements are defined by dsl.service.

---

5. Service Responsibilities

The service layer connects external system concerns to the internal behavioral model.

Conceptually:

API ───────────┐
Broker ────────┤
Database ──────┼── Service ── Components / FSMs / Expressions
Configuration ─┤
Artifacts ─────┘

Typical service responsibilities include:

• translating external interactions into internal actions;
• routing internal outputs to external contracts;
• providing infrastructure connections;
• selecting and configuring domain components;
• defining a coherent generation and deployment boundary.

Domain state should remain in stateful behavioral elements rather than becoming implicit service-level state.

---

6. Components

A component is a reusable, stateless unit of behavioral composition.

It can bring together:

• FSMs;
• expressions;
• nested components;
• typed inputs and outputs;
• explicit connections between those elements.

Conceptually:

Component
    ├── inputs
    ├── FSMs
    ├── Expressions
    ├── nested Components
    ├── connections
    └── outputs

A component owns composition, not persistent behavioral state.

The exact syntax and permitted connections are defined by dsl.component.

---

7. Component Responsibilities

Components organize related behavior into meaningful domain modules.

Typical responsibilities include:

• grouping related behavioral elements;
• defining typed entry and exit points;
• connecting component inputs to internal behavior;
• connecting internal outputs to other internal elements;
• exposing selected internal results as component outputs;
• applying explicit transformations where connected types differ;
• hiding internal composition behind a reusable domain boundary.

For example, an order component may compose separate FSMs for ordering, payment, and fulfillment without owning their state itself.

---

8. Component Statelessness

A component does not directly own behavioral state.

State belongs to the stateful elements inside the composition, primarily FSMs.

Component
    │
    ├── connection topology   ← owned by Component
    ├── input/output contract ← owned by Component
    │
    ├── OrderFSM              ← owns order state
    └── PaymentFSM            ← owns payment state

This distinction supports:

• explicit state ownership;
• reusable composition;
• independent FSM validation;
• clearer lifecycle management;
• predictable generation.

---

9. Finite State Machines

An FSM is an atomic stateful unit of behavior.

It defines:

• states;
• events or accepted inputs;
• transitions;
• transition conditions;
• actions and outputs;
• timers or delays where supported;
• the rules governing movement from one state to another.

Conceptually:

Input or event
      │
      ▼
Current state
      │
      ├── evaluate transition condition
      ├── perform transition behavior
      ▼
New state + output

FSMs make state changes explicit and validate them as part of the Ocean model.

The exact syntax and semantics are defined by dsl.fsm.

---

10. FSM Responsibilities

An FSM is responsible for behavior whose result depends on state over time.

Typical responsibilities include:

• accepting typed events or commands;
• evaluating whether a transition is allowed;
• changing state;
• emitting typed outputs;
• reacting to timers or delays;
• enforcing valid behavioral paths;
• making invalid transitions detectable.

An FSM should not absorb deployment, infrastructure, or broad composition concerns that belong to services or components.

---

11. Expressions

An expression is a stateless, side-effect-free unit of logic.

Expressions may provide:

• conditions;
• calculations;
• validation;
• mapping;
• projection;
• transformation;
• reusable decision logic.

Conceptually:

Typed inputs
     │
     ▼
Expression
     │
     ▼
Typed outputs

For the same inputs, an expression should produce the same outputs without relying on mutable internal state or direct external I/O.

The exact syntax and semantics are defined by dsl.expression.

---

12. Expression Usage

Expressions are supporting logic units rather than a layer positioned above or below the other control structures.

They may be used where a receiving DSL construct explicitly permits them.

Common uses include:

• FSM transition conditions;
• FSM calculations or output construction;
• component connection mapping;
• component validation or transformation;
• service-level routing or mapping where supported.

The statement that an expression “can be used anywhere” is intentionally avoided. Each receiving DSL reference defines its valid expression integration points.

---

13. State Ownership

State ownership is a central distinction in the control model.

Construct	Owns behavioral state	Primary responsibility
Service	No implicit domain state	Deployment and orchestration boundary
Component	No	Stateless behavioral composition
FSM	Yes	Stateful behavior and transitions
Expression	No	Stateless logic and transformation

Infrastructure connected through a service, such as a database or broker, may store or transport state externally. That does not make the service itself the owner of implicit behavioral state.

---

14. Boundaries and Encapsulation

Each structure establishes a different boundary:

Service boundary
    └── what is deployed and externally connected

Component boundary
    └── what behavior is composed and reused together

FSM boundary
    └── what state and transitions form one behavioral lifecycle

Expression boundary
    └── what logic forms one stateless reusable operation

These boundaries allow each structure to evolve independently while retaining explicit typed connections.

---

15. Data and Control Flow

Ocean models flow through typed inputs, outputs, events, and connections.

A typical flow may be:

API request
    │
    ▼
Service input mapping
    │
    ▼
Component input
    │
    ▼
FSM event
    │
    ├── Expression evaluates condition
    │
    ▼
FSM transition
    │
    ▼
Component output
    │
    ▼
Service response mapping
    │
    ▼
API response

Other flows may begin or end through brokers, databases, timers, or other supported service connections.

---

16. Typed Connections

Connections between control structures are typed.

This allows Ocean to validate:

• whether a source can provide the data expected by a target;
• whether a mapper or transformation is required;
• whether referenced inputs and outputs exist;
• whether a behavioral flow is internally coherent.

Implicit, untyped communication weakens the model and should not replace declared contracts.

The detailed connection grammar belongs to the DSL reference for the construct that owns the connection.

---

17. Reuse and Composition

Each control structure provides reuse at a different level.

Construct	Reusable concern
Expression	Calculation, condition, validation, or transformation
FSM	Stateful behavioral lifecycle
Component	Coordinated domain behavior
Service	Deployable system capability

Conceptually:

Expressions
     ↓
FSMs
     ↓
Components
     ↓
Services

This is a common composition direction, not a rule that every intermediate level must always be present.

---

18. Direct and Nested Composition

The model allows direct or nested composition where the relevant DSL contracts support it.

For example:

• a component may contain nested components;
• a component may compose FSMs directly;
• a service may compose components;
• a service may use other supported behavioral elements directly;
• FSMs and components may use expressions at defined integration points.

The control structure should be chosen according to semantic responsibility, not merely to satisfy a fixed hierarchy.

---

19. Example: Order Processing

An order-processing capability may be modeled as:

OrderService
    │
    ├── Order API
    ├── Order database
    ├── Event broker
    │
    └── OrderComponent
            │
            ├── OrderFSM
            ├── PaymentFSM
            ├── FulfillmentComponent
            └── Expressions
                    ├── ValidateOrder
                    ├── CalculateTotal
                    └── MapOrderResponse

In this model:

• OrderService owns the deployable boundary and external connections;
• OrderComponent owns the composition of order behavior;
• OrderFSM and PaymentFSM own their respective states and transitions;
• FulfillmentComponent encapsulates a reusable nested behavior module;
• the expressions provide stateless validation, calculation, and mapping.

---

20. Choosing a Control Structure

Use an expression when the behavior:

• is stateless;
• is side-effect-free;
• maps typed inputs to typed outputs;
• represents a calculation, condition, validation, or transformation.

Use an FSM when the behavior:

• depends on current state;
• changes over time;
• reacts to events;
• has explicit valid and invalid transitions.

Use a component when the model:

• composes multiple behavioral elements;
• needs a reusable domain boundary;
• exposes typed inputs and outputs;
• coordinates behavior without directly owning state.

Use a service when the model:

• requires a deployment or generation boundary;
• exposes external contracts;
• connects infrastructure;
• orchestrates domain components as a runnable system capability.

---

21. What This Model Avoids

The control structure model avoids:

• hiding state inside generic components;
• mixing pure logic with external I/O;
• coupling domain behavior directly to deployment technology;
• turning services into unstructured containers of business logic;
• treating every behavior as an FSM when no state exists;
• duplicating composition logic across generated implementations;
• relying on implicit or untyped connections.

The goal is not to maximize the number of layers. It is to make each semantic responsibility explicit.

---

22. Architectural View vs DSL Contracts

This document explains how the control structures relate conceptually.

It does not define their complete grammar.

The normative syntax and detailed semantics are defined by:

• dsl.service;
• dsl.component;
• dsl.fsm;
• dsl.expression.

If this conceptual overview and a normative DSL reference differ on a syntax or validation rule, the normative DSL reference governs that construct.

---

23. Rules and Principles

The following principles apply:

• Services define deployable orchestration boundaries.
• Services connect external contracts and infrastructure to domain behavior.
• Components are reusable, stateless composition units.
• Components may compose FSMs, expressions, and nested components where supported.
• FSMs own behavioral state and explicit transitions.
• Expressions provide stateless, side-effect-free logic.
• Expressions may be used only at integration points supported by the receiving DSL construct.
• Control structures communicate through explicit typed contracts.
• State ownership should remain explicit.
• Deployment concerns should remain separate from domain behavior where possible.
• The model permits direct and nested composition; it is not a mandatory four-layer stack.
• Detailed syntax and validation rules belong to the corresponding DSL references.

---

24. Related Knowledge

The control structure concept is related to:

• dsl.service — defines deployable orchestration boundaries and their external connections.
• dsl.component — defines stateless composition of behavioral elements.
• dsl.fsm — defines stateful behavior through states and transitions.
• dsl.expression — defines reusable stateless logic.
• dsl.api — defines external API contracts that may be exposed through services.
• dsl.database — defines persistence infrastructure connected through services.
• dsl.broker — defines message-based external communication connected through services.

These semantic relationships are declared in the document metadata.