Cohesive.Transitions 0.1.0-alpha.132

Cohesive.Transitions

Cohesive.Transitions models one entity change as portable, inspectable semantics: admission rules, branching, sparse updates, invariants, interactions, machine movements, and typed outcomes.

Canonical execution IR declares IImmutableExecutionDefinition, so repeated typed reads share document-owned immutable decoding. Integrity, canonical-wire, contextual semantics, and deployment admission remain independently validated. See immutable execution preparation.

Install

dotnet add package Cohesive.Transitions

Start with an immutable record

Transition expressions can use ordinary POCO properties without inheriting from Entity<T>:

public sealed record RunControl(bool Eligible, string Status);
public sealed record ApproveRun(bool Approved);

At application startup, resolve the entity shape and author the transition:

var entity = ObjectEntityDefinition.For<RunControl>(new("run-control"));
var metadata = new TransitionAuthoringMetadata(
    new("run-control/approve"), new("revision/1"), new("body"),
    new(new(TransitionAuthoring.Producer), new("example/run-control"), DocumentOrigin.Generated));

var approve = TransitionAuthoring.Create<RunControl, ApproveRun, string>(
    entity.Shape,
    metadata,
    transition => transition
        .Invariant(new("valid-status"), state => state.Status != "invalid")
        .Requires(new("eligible"), (state, input) => state.Eligible && input.Approved,
            (state, input) => "rejected")
        .Set(new("approve"), state => state.Status, "approved")
        .Return(new("result"), TransitionOutcomeDisposition.Applied, "approved"));

The shape and the restricted expressions produce the same canonical Transition IR as explicit entities and direct IR authoring. Compile the document once and reuse its plan. Invocation expressions read the original observation; ordered patches produce a candidate observation, and invariants check that candidate. Neither authoring nor execution mutates the record. POCO authoring and execution covers materialization, names, value-object contracts, and the supported subset.

Explicit entity declarations

The C# entity surface discovers fields and produces the canonical observation shape. Ordinary field declarations do not require node IDs:

public enum LoadStatus { Draft, Assigned }

public sealed class Load : Entity<Load>
{
    public Load()
    {
        Status = Field(nameof(Status), LoadStatus.Draft);
        CarrierId = Field<string?>(
            nameof(CarrierId),
            initialValue: null,
            configure: field => field.Optional());

        Invariant(
            "AssignedLoadsHaveACarrier",
            load => load.Status != LoadStatus.Assigned ||
                    load.CarrierId != null);
    }

    public Field<LoadStatus> Status { get; }

    public Field<string?> CarrierId { get; }
}

Transition authoring then uses restricted typed expressions over the current entity observation and a typed input. Those expressions lower immediately into canonical IR; arbitrary method calls, hidden I/O, captured runtime state, loops, and mutation are rejected.

What a Transition produces

• A canonical, persistable ExecutionDefinitionDocument.
• Exact input, entity-observation, and outcome contracts.
• Admission rules and deterministic branch structure.
• An algebraic sparse patch rather than in-place entity mutation.
• Interaction intents and machine movements when declared.
• Candidate-state invariant checks and typed outcome evidence.
• Structured source maps, validation diagnostics, and a semantic fingerprint.

The document is the semantic authority. The typed handle, static plan, reference interpreter decision, repository commit, and emitted interaction envelopes are projections or interpretations of that exact document.

Current authoring boundary

Entity shape discovery and common field defaults are convention-driven. The current Transition builder keeps stable identities explicit for durable rules, branches, updates, and outcomes; advanced examples and the canonical IR are therefore documented separately. Additional identity conventions should be added to the authoring API before they are presented as ordinary syntax.

Use it when

• Entity invariants and legal changes should be explicit and reusable across hosts.
• A decision must be testable without a database, message broker, or HTTP endpoint.
• Storage needs a sparse patch and exact concurrency evidence rather than an opaque callback.
• Processes, APIs, presentation actions, and tooling should reference the same domain behavior.

Continue

• Internals contains the complete explicit authoring example, canonical IR, persistence, compilation, reference interpretation, and expression-site details.
• Execution kernel guide explains Transition linking and execution boundaries.
• Cohesive.Storage attaches repository and commit interpretations.
• Cohesive.Processes coordinates Transition invocations with other semantic work.

Start a multi-entity domain

DomainModelBuilder.Entity<T>(semanticName) returns a typed DomainEntity<T> retaining the exact definition in the built entity catalog. Declare it once, then attach downstream concerns:

var domain = new DomainModelBuilder().Version("1");
var orders = domain.Entity<Order>("orders");
var reservations = domain.Entity<Reservation>("reservations");
var reservationOrder = reservations.References(reservation => reservation.OrderId, orders);
var definition = domain.Build();

entity.Definition supplies transition/storage authority. entity.QueryShape(author) imports that exact graph into a Relations expression session, avoiding an independently inferred CLR query shape. author.Source(entity) combines that import with source creation when a separate shape handle is unnecessary. References uses an existing Relations relationship definition and names the target observation identity; it does not create a foreign key, establish tenant scope or enforce authorization. The typed handle carries both exact endpoint documents, imported automatically by forward and inverse traversal. Explicit imports remain valid; conflicting session registrations fail closed. A traversal retains the separately declared relationship in its authoring catalog. Entity handles contain no runtime state, persistence or workflow. See the runnable fulfillment example.