Declarative Structure. Declarative Change.

Most systems model structure. Few model change precisely. Cohesive makes both first-class:

• An entity defines what exists.
• A transition defines how it may evolve.
• Everything else — relations, queries, workflows, storage, indexes — composes on top of that semantic core.

This module is the state semantics layer of Cohesive.

• Declarative Structure. Declarative Change.
• Where this fits in the Building Blocks
• Entities
• Structure with Semantics
• Fields are First-Class
• Transitions
• Legal Change as a First-Class Concept
• Preconditions, Invariants, and Determinism
• Effects
• Generalizing Events
• State and Patches
• Deriving Change from Meaning
• Event Sourcing and Outbox
• Same Surface. Different Semantics.
• Event Sourcing
• Outbox
• Cohesive’s Position
• Incremental Adoption
• Minimal Adoption
• Deeper Adoption
• “All in” Cohesive
• Why This Matters
• Summary
• References

Where this fits in the Building Blocks

Cohesive Systems has five building blocks:

• Cohesive Relations — observing state (mapping, projection, joins, predicates, query compilation, materialization)
• Cohesive Entities & Transitions — defining state and legal change (this page)
• Cohesive Processes — coordinating and executing intent over time (aka: workflows)
• Cohesive Presentation — exposing structured observations to UI/API consistently
• Cohesive Host — wiring semantics to infrastructure and selecting execution strategies

Entities and transitions are intentionally storage-agnostic and runtime-agnostic.

Entities

Structure with Semantics

An entity is not just a class, record or a table. It is:

• A collection of first-class fields
• A semantic identity (stable meaning, not merely an ID column)
• A state space (the set of possible states the entity may inhabit)
• A set of invariants (constraints that must always hold)

Entities define the structural backbone of the system. They do not depend on:

• Storage engines (Cosmos, Postgres, etc.)
• Indexing strategies (Elastic, Azure Search)
• Workflow runtimes (DurableTask, Orleans)
• Transport (HTTP, queues)

Infrastructure binds to the model, not the other way around.

Fields are First-Class

Fields are not passive properties. They are addressable semantic elements that participate in:

• Transitions — what can change
• Relations — what can be observed, mapped, joined, and projected
• Policies & Invariants — validation, authorization, and lifecycle constraints
• Storage bindings — how a field is persisted and indexed

A field's semantic identity matters because it allows a single definition to be reused across:

• DTO mapping
• Query compilation
• Search index mappings
• Migration logic
• Feature extraction (ML)

This is what "semantics first" means in practice.

Transitions

Legal Change as a First-Class Concept

A transition defines a permitted state transformation. Conceptually:

A transition:

• Is typed
• Declares preconditions
• Must preserve invariants
• Produces deterministic effects

Transitions are pure semantics. They do not:

• Call external systems
• Publish messages
• Start workflows
• Perform I/O

They declare intent. Execution belongs elsewhere. This separation is what makes transitions:

• Testable without infrastructure
• Replay-safe
• Suitable for event sourcing or outbox
• Suitable for synchronous apps or durable workflows

Preconditions, Invariants, and Determinism

A Cohesive transition must be deterministic with respect to its inputs:

• Same input + same prior state ⇒ same effects

Determinism is not a philosophical constraint; it is what makes:

• Replays meaningful
• Projections incremental
• Workflows resumable
• Auditing coherent

Preconditions and invariants should be explicit and local:

• Preconditions guard the transition
• Invariants constrain the resulting state space

Effects

Generalizing Events

Effects are the semantic output of a transition. An effect may represent:

• A domain event (“something occurred”)
• A request for further computation
• A workflow trigger
• An integration intent

An event is a special case of an effect.

Examples:

• TenderAccepted — DomainEvent
• CalculateMileage — ComputationIntent
• StartSettlementProcess — ProcessIntent
• PublishToEDI — IntegrationIntent

Effects are:

• Data only
• Deterministic
• Replay-safe
• Serializable

The transition declares what must happen. The process engine decides how it runs.

State and Patches

Deriving Change from Meaning

In Cohesive, state change is defined by semantic effects. A state-transforming effect defines:

State evolution is derived by applying effects. A patch is not primary. It is a derived artifact that can be computed from the effect and prior state. This eliminates duplication between:

• “What changed” (patch)
• “What happened” (meaningful effect)

Meaning comes first. Mutation follows.

Event Sourcing and Outbox

Same Surface. Different Semantics.

Many systems use either event sourcing or the outbox pattern. On the surface, both emit events. Internally, they differ.

Event Sourcing

• Events are the source of truth
• State is derived by replay
• Atomic boundary is event append
• Snapshots are optimization

Conceptually:

Transition → Event

State = Fold(Apply, Events)

Here, the event defines state change.

Outbox

• State is the source of truth
• State and event are persisted atomically
• Event describes change but does not define it

Conceptually:

Transition → (NewState, Event)

Atomic: State + Outbox row

Here, state mutation is primary.

Cohesive’s Position

Cohesive does not prescribe either model. Transitions produce deterministic effects. Host bindings decide whether:

• State is derived from events (event sourcing)
• State is updated directly with an outbox (outbox)

The semantic model remains unchanged. This separation is deliberate.

Incremental Adoption

You can adopt Entities & Transitions without rewriting your system.

Minimal Adoption

• Define entities and field semantics for a bounded area
• Define transitions for a small set of high-risk operations
• Keep persistence and messaging unchanged
• Test transitions as pure functions

This immediately improves:

• Correctness (explicit invariants)
• Change safety (legal change is constrained)
• Refactorability (behavior is explicit)

Deeper Adoption

• Route state changes through transitions uniformly
• Emit effects consistently
• Introduce processes for long-running workflows
• Introduce relations for projections and query compilation
• Move bindings into host for swappable infrastructure

“All in” Cohesive

• Semantic model is authoritative
• Transitions define all legal change
• Processes coordinate effects durably
• Relations define read models, predicates, transformations (EDI/JSON/flat-file), and ML feature projections
• Host composes runtime and storage adapters

Why This Matters

When entities and transitions are first-class:

• Invariants are explicit
• Change is constrained
• Replay is safe
• Migration is model-able
• Projections are incremental
• Workflows are declarative
• Storage strategy becomes a binding decision

Instead of stitching together:

• ORM
• Event bus
• Workflow engine
• Index pipeline
• Query layer

You define semantics once. Everything else composes around it.

Summary

Cohesive Entities & Transitions are the semantic core:

• Entities define structured state with first-class fields and invariants
• Transitions define legal, deterministic change and emit effects
• Effects generalize events into replay-safe semantic outputs
• Event sourcing and outbox become binding choices, not modeling choices
• Relations and Processes layer cleanly on top

References

Cohesive Relations

Cohesive Processes

Cohesive Presentation