Entity repository
- What it stores or supplies
- Identity-addressed entity observations, projected reads, writes, concurrency tokens, and optional atomic outbox evidence.
- Who owns the meaning
- Cohesive.Entities and its Transitions.
Building Blocks
Cohesive.
Connect entities, queries, Processes, and derived views to physical storage with explicit durability, concurrency, atomicity, and capability evidence.
Core Idea
Cohesive.Storage is where semantic decisions become durable. It persists entity observations, supplies physical data to Relations, commits Process progress, and maintains derived views without moving business meaning into a database-specific repository layer.
The semantic blocks say what must be preserved. Storage integrations say how a particular database, index, or durable store preserves it. When a backend cannot provide the required atomicity, concurrency, completeness, ordering, or delivery behavior, the integration returns capability diagnostics instead of silently weakening the operation.
The repository surface is deliberately small. A caller can request only the fields needed for a decision, then commit the accepted candidate state against the concurrency token it observed:
var current = await loads.TryGet(
context: context,
id: loadId,
options: EntityReadOptions
.ForFields(nameof(Load.Status), nameof(Load.CarrierId))
.WithPartitionKey(tenantId));
if (current is null)
return AssignLoadResult.NotFound;
var committed = await loads.Upsert(
context: context,
write: new EntityWriteRequest(
Entity: candidateState,
ExpectedConcurrencyToken: current.ConcurrencyToken));Here, loads is an IEntityRepository and candidateState is the observation produced after an accepted entity Transition. The same repository contract can also expose typed object mapping, batch-write capabilities, atomic outbox commits, and replayable Process Transition receipts.
Getting Started
The guided walkthrough creates an in-memory repository for one entity, writes and reads semantic state, adds optimistic concurrency, and registers the same repository as a bounded Relations source.
Open the Getting Started guide →
A Small Mental Model
Storage provides several related physical boundaries rather than one universal repository:
Relation source reader
- What it stores or supplies
- Bounded physical facts, identity batches, relationship-key batches, field selection, and completeness evidence.
- Who owns the meaning
- Cohesive.Relations.
Process durable store
- What it stores or supplies
- Continuation, inbox, outbox, operation receipts, worker leases, and control state as one checkpoint aggregate.
- Who owns the meaning
- Cohesive.Processes and its compiled continuation model.
Materialization source and target
- What it stores or supplies
- Change delivery, rebuild progress, isolated target generations, promotion, and synchronization evidence.
- Who owns the meaning
- The source Relation and the materialization definition.
Capability evidence
- What it stores or supplies
- The limits and guarantees a concrete adapter can demonstrate.
- Who owns the meaning
- The adapter and physical deployment boundary.
An observation is the common state carrier. It keeps semantic shape, identity, version, field values, and lineage independent of a provider's document, row, or SDK type.
Why Make the Upfront Investment?
A conventional repository often grows around the conveniences of its first database. Queries, partition assumptions, concurrency behavior, outbox logic, and workflow checkpoints then become provider-specific application code. Cohesive makes these boundaries explicit so the system can validate what a storage binding preserves.
Semantic repository contracts
- What it gives you
- Repositories are bound to entity definitions and observations, so storage code retains shape, identity, version, and field meaning instead of exposing anonymous documents or rows.
Selective acquisition
- What it gives you
- Entity reads and Relation source requests can ask for only the fields and bounded batches required by the operation.
Explicit concurrency
- What it gives you
- Opaque concurrency tokens and expected versions make stale writes and stale decisions visible through structured conflict evidence.
Atomic state and effects
- What it gives you
- A capable repository can commit entity state with canonical outgoing interactions or a Process Transition receipt, supporting transactional-outbox and replay-safe handoff patterns.
One query authority
- What it gives you
- Storage supplies physical facts to Cohesive.Relations instead of introducing another repository predicate, join, projection, aggregation, or paging language.
Durable workflow state
- What it gives you
- Process continuation, accepted inputs, completed operations, outgoing interactions, and control state share one compare-and-swap persistence boundary.
Managed derived views
- What it gives you
- Relation-derived projections can be rebuilt and synchronized into search indexes or other targets with explicit progress, generation, and promotion evidence.
Capability diagnostics
- What it gives you
- Adapters advertise hard limits and semantic guarantees. Unsupported atomicity, completeness, delivery, or synchronization requirements fail with attributable diagnostics.
How Storage Participates in Execution
Storage does not run entity rules, reinterpret queries, or decide Process control flow. It surrounds those interpreters with physical evidence and durable commits.
For an entity operation, the execution environment reads the required state, evaluates the Transition, and asks a repository to commit the accepted candidate against fresh concurrency evidence. If the decision emitted an effect, an outbox-capable repository can make the state change and its canonical envelopes durable together.
For a Process activation, the runtime advances the compiled continuation and asks IProcessDurableStore to commit the resulting checkpoint as one successor. For a Relation evaluation, source readers acquire bounded facts while the Relations evaluator retains query authority. Materialization runtimes connect source progress, derived output, target generations, and promotion through their own explicit storage ports.
Entity State, Concurrency, and Outbox Commits
IEntityRepository is scoped to one logical entity definition. Its core operations are identity-based reads and writes over immutable snapshots. Reads can include a partition hint, expected version, expected concurrency token, and field selection. Writes can carry an opaque optimistic-concurrency token returned by the provider.
Batch requests state their required atomicity: independent writes, same-partition atomicity, or all-or-nothing behavior. The repository advertises which forms it supports and its item limit. The default contract falls back only when no atomic batch guarantee was requested.
IEntityOutboxRepository adds an atomic entity-state and canonical-envelope commit. This is the physical boundary for the transactional outbox pattern when a direct Transition emits events or requests.
When a Process invokes a Transition, IEntityTransitionOperationRepository can instead commit the candidate entity state and the exact Process operation receipt together. Replay returns that receipt without applying the entity decision again. The resulting interaction envelopes are then admitted to the Process outbox, which remains publication authority for that Process occurrence.
Queries Keep One Authority
Storage contributes physical acquisition to Relations. It does not own another query abstraction.
An EntityRelationQuerySourceRegistration binds one graph-qualified shape to a source reader, physical source identity, selectors, capability profile, and hard limits. The reader may supply bounded enumeration, point or batch identity reads, relationship-key batches, selected fields, and completeness evidence. Canonical Relations interpretation still owns filters, joins, projection, aggregation, ordering, and paging.
This distinction lets PostgreSQL, Cosmos DB, or an in-memory repository acquire the same semantic facts through different physical strategies without turning provider syntax into application query meaning.
Durable Process State
Cohesive.Storage.Processes defines the physical durability boundary for a Process. One ProcessDurableCheckpoint combines the current continuation with attempt and activation receipts, accepted inbox inputs, outgoing interaction envelopes, completed host operations, durable request state, worker ownership, and lifecycle control.
IProcessDurableStore uses compare-and-swap revisions, worker fences, and deterministic commit identities. A legal update replaces the checkpoint as one aggregate mutation. An exact retry can replay the retained result; reused identity with different content is rejected.
The current package includes ProcessDurableRuntime and the copy-on-write InMemoryProcessDurableStore reference implementation. The in-memory store is a semantic test oracle, not a production durability provider. Production implementations must preserve the same aggregate and fencing contract.
Relation-Derived Materialized Views
Materialization turns a selected Relation output into maintained physical data such as a search index or denormalized serving view. The Relation remains authority for dependency, lineage, and output meaning; Storage owns rebuild, incremental synchronization, target lifecycle, and progress evidence.
A materialization definition declares consistency, freshness, failure, source, target, and bounded-work requirements. Planning derives affected roots from the Relation dependency manifest. Execution hydrates through the exact Relations plan, writes to an isolated target generation, catches up changes, validates readiness, and promotes through a fenced routing boundary.
Bind one Relation output
The materialization records the exact Relation compilation request, selected output, and synchronization requirements.
- Retain dependency and lineage authority in Relations
- Declare consistency and freshness policy
- Require bounded source and target capabilities
Current Adapters and Boundaries
In-memory reference implementations
- Current role
- Entity/outbox repositories, Relation source reads, Process durable store, materialization sources, targets, routers, and progress stores.
- Boundary
- Deterministic tests and conformance; not production durability claims.
Cohesive.Adapters.Cosmos
- Current role
- Production entity/outbox repository, Relations source reader, pull and managed materialization change sources.
- Boundary
- Partition, query, change-feed, settlement, and request-bound capability evidence remain explicit.
Cohesive.Adapters.Postgres
- Current role
- Npgsql-backed Relations acquisition, materialization rebuild/reconciliation source, and logical-replication change source.
- Boundary
- It is not currently a general IEntityRepository implementation.
Cohesive.Adapters.Elastic
- Current role
- Generation-per-index materialization target and routing integration.
- Boundary
- Elasticsearch is a derived target rather than authoritative entity storage.
Cohesive.Adapters.DurableTask
- Current role
- Authority-neutral Process execution-status projection.
- Boundary
- It is not the canonical Process executor or IProcessDurableStore implementation.
Works with the Other Blocks
Cohesive.Entitiesdefines state, invariants, Transitions, decisions, and outgoing effects.Cohesive.Relationsdefines queries, dependency, lineage, and derived outputs; Storage supplies bounded physical facts.Cohesive.Processesdefines durable coordination; Storage persists its checkpoints and operation evidence.Cohesive.Apibinds entity and Process operations to transport-neutral endpoints without taking storage authority.Cohesive.Presentationprojects entity, Process, and materialization status from the same attributable evidence.
Going Deeper
The Internals page covers repository capabilities, atomic Transition receipts, Process compare-and-swap and worker fencing, canonical source registration, materialization impact planning, rebuild and convergence, routing generations, progress and settlement, bounded control, and removed compatibility surfaces.