Cohesive.Processes 0.1.0-alpha.6

Cohesive.Processes

Canonical, portable Process semantics for coordinating entity transitions, relation/query evaluations, durable interactions, waits, parallel work, recurrence, and terminal outcomes without binding the definition to a workflow engine, storage system, or host-language callback.

Install

dotnet add package Cohesive.Processes
dotnet add package Cohesive.Analyzers

Cohesive.Analyzers supplies the expression-first C# frontend. Add it as an analyzer when using project references.

Author a Process in C#

Human-written Processes start with a syntax-only async ProcessTask<T> method marked by GenerateProcessDefinition. await binds results from semantic Process operations; ordinary local expressions are fused into the nearest effectful operation or terminal result rather than becoming Compute nodes.

[GenerateProcessDefinition(nameof(Run))]
public static partial class CustomerQueryProcess
{
    /// <summary>Exact Relation reference used by the generated Process.</summary>
    public static ExecutionDefinitionReference Relation { get; } = new(
        new("relation/customer-query"),
        new("1"),
        new(
            ExecutionDefinitionFingerprinter.Algorithm,
            ExecutionDefinitionFingerprinter.Canonicalization,
            new string('1', 64)));

    static async ProcessTask<string> Run(
        ProcessContext process,
        string input)
    {
        var queryInput = input;
        var row = await process.Query<string>(Relation, queryInput);
        return row;
    }
}

This exact excerpt is compiled and exercised by ProcessComputationAuthoringTests.cs; a documentation invariant test prevents the README from drifting from that executable source. The generated Define factory accepts ProcessAuthoringMetadata and returns a typed handle containing the canonical execution-definition document and validation result. The annotated Run method is never invoked.

The same syntax supports typed Transition results, Requests/effects, entity reads represented by Relations, if/else, exact switch, explicit Choice/Match policies, durable waits, tuple-valued Fork/Join, bounded admission, child Processes, partition work, and recurrence. Use the executable ApproveCustomerProcess for a compact query/read/Transition/effect/Fork-Join example. Use the Motion DQ onboarding and monitoring definitions for business-shaped branching, Request outcomes, durable waits, bounded parallelism, polling, escalation, and recurrence. Those executable definitions remain the source of truth; this smaller excerpt illustrates the typed-wait shape in isolation.

Typed durable races bind a closed source-only result family and consume it with an immediately following exhaustive type switch:

var review = await process.AwaitMatch<CustomerReviewOutcome>(
    clauses:
    [
        process.Event<DocumentReviewSubmitted>(
            ReviewSubmitted,
            priority: 10,
            when: submitted => submitted.TaskId == reviewTask.Id),
        process.Deadline<DocumentReviewTimedOut>(reviewTask.DueAt)
    ],
    arbitration: ProcessAwaitArbitration.ExclusivePriorityThenClauseId,
    lateInput: ProcessAwaitInputDisposition.Observe,
    staleInput: ProcessAwaitInputDisposition.Reject,
    duplicateInput: ProcessAwaitInputDisposition.ReusePriorDisposition,
    missingTarget: ProcessAwaitMissingTargetDisposition.DeadLetter,
    retentionHorizon: TimeSpan.FromDays(30));

switch (review)
{
    case DocumentReviewTimedOut _:
        return TimedOut();
    case DocumentReviewSubmitted { Decision: var decision }:
        await ApplyDecision(decision);
        break;
}

The case records and bound review local are C# projection types only. Generation fuses each switch section into the corresponding canonical AwaitMatch clause continuation; no union wrapper, discriminator, callback, or CLR state machine is serialized. Every declared alternative must appear exactly once, and adding a clause makes the switch diagnostically incomplete until its case is handled. Interaction case values are the exact typed payload; timer cases are markers and use lexically visible due-time data rather than manufacturing a runtime value. Runtime admission still addresses the exact durable Process token; a portable guard may further constrain the originating business occurrence without replacing that canonical target.

One semantic lifecycle

Expression source, canonical IR, compiled plans, and runtime evidence have distinct ownership:

Persist and restore the canonical document. Do not persist an expression tree, generated builder callback, CLR task, compiled plan, or authoring session as the Process definition. Static compilation and restored execution consume the document plus explicit linking, policy, capability, and runtime evidence.

Identity and compatibility

Omitting ExecutionNodeId uses deterministic conventions. Conventions are appropriate for local structural details whose identity has no independent compatibility promise. They are not a substitute for explicit durable identity.

Convention-derived decisions are deterministic and recorded in the source map. Inserting unrelated constructs does not globally renumber semantic roles, but moving or changing structurally identified operations may intentionally change their identities and therefore the fingerprint. Treat a change to an explicitly durable identity as a compatibility/versioning decision. Motion DQ intentionally spells out durable identities because its reference definitions lock recovery and cross-revision behavior.

Restricted computation model

The expression frontend accepts only source constructs it can lower into the finite canonical Process model. Semantic operations use await; pure locals use the portable expression closure. Named local functions may describe branches, but are erased after lowering. Arbitrary CLR services, I/O, tasks, reflection, mutable loops, recursion, captured runtime delegates, and host-language suspension cannot enter canonical IR. Unsupported syntax is a source diagnostic, not a callback deferred to runtime.

Durability- and scheduling-relevant policy remains explicit. Await arbitration and input disposition, Fork/Join completion and cancellation, admission limits, child cancellation, recurrence bounds, and compensation purpose are canonical facts. The C# frontend does not infer weaker guarantees or hide those policies behind convenient syntax.

Read is an authoring alias for exact Relation/Query evaluation; it does not create a second entity-read execution model. Effect lowers to a typed durable Request and selected terminal outcome. Referenced Processes, Transitions, Relations/Queries, and interaction contracts use exact definition identity, revision, and fingerprint evidence.

Canonical validation and execution

ProcessDefinitionDocuments.Validate checks graph integrity, exact references, portable expression types, binding visibility, Choice/Match coverage, Fork-token and Join structure, AwaitMatch policies, child protocols, bounded work, recurrence, and finite activation. ProcessStaticCompiler consumes the persisted document and a ProcessDefinitionValidationContext containing exact linked-definition and interaction evidence.

ProcessReferenceInterpreter is the reference in-memory interpretation. Durable execution composes compiled canonical definitions with Cohesive.Storage.Processes.ProcessDurableRuntime and IProcessDurableStore. Other interpreters and adapters must declare supported capabilities and preserve the canonical semantics or emit precise diagnostics.

Advanced lowering escape hatch

ProcessAuthoring.Create and ProcessBuilder<TInput,TResult> remain public, advanced APIs because source generators, importers, compiler tests, and infrastructure may need direct construction of the closed Process-node union. They are not the primary application-authoring surface and are hidden from ordinary IntelliSense through EditorBrowsableState.Advanced. Their callbacks must be finite and synchronous, are discarded immediately, and cannot become persisted or runtime authority.

The former CreateExpression collection DSL has been removed. It covered only sequential graph construction and duplicated the human-facing role now owned by the more capable generated C# computation frontend. Migrate those definitions to GenerateProcessDefinition; use the advanced builder only when code is itself lowering or importing canonical structure.

Retired execution authority

The callback-bearing Cohesive.Processes.Model graph, runtime-delegate source generator, and single-cursor Cohesive.Processes.Runtime.ProcessCheckpoint path are not shipped. Canonical documents compile through ProcessStaticCompiler, execute through declared interpreters, and become durable through the Storage-owned Process runtime. Restoring a Process never loads the expression source, a builder callback, or an authoring state machine.

The DurableTask package retains authority-neutral task-hub query projections only. A future execution adapter must consume compiled canonical definitions and implement or compose the canonical durable-store boundary; it must not revive registry-by-name definitions, delegate replay, or single-cursor checkpoints.

Related packages

• Execution Kernel adoption and migration guide
• Cohesive.Transitions for canonical entity Transition semantics
• Cohesive.Relations for canonical relation and query semantics
• Cohesive.Storage for durable checkpoints, control, and the Process-store contract
• Cohesive.Adapters.DurableTask for authority-neutral task-hub status projections