Cohesive 0.1.0-alpha.120

Cohesive

Cohesive contains the portable values, shape model, expression IR, execution contracts, and provenance primitives shared by every Cohesive block and adapter.

Install

dotnet add package Cohesive

Start with a shape

Ordinary CLR types can produce a deterministic shape graph without hand-authoring fields or node identities:

using Cohesive.Model;

[ShapeDefinition("shape.shipment", ShapeRoles.Transport)]
public sealed record Shipment(string Id, IReadOnlyList<Stop> Stops);

[ShapeType("type.stop")]
public sealed record Stop(string City, string State);

var graph = new ClrShapeGraphBuilder()
    .AddShape<Shipment>()
    .Build(new("shipping"));

The graph records the semantic types, fields, cardinalities, roles, and CLR provenance used by higher-level blocks. It can be persisted, validated, generated into another host language, or interpreted by a target adapter.

What this package provides

• Graph-qualified shapes, fields, paths, scalar types, cardinality, and nullability.
• Immutable ObservationValue and Observation values with exact shape evidence.
• Explicit EntityObservationSnapshot values when identity and version apply.
• Portable Expr definitions and expression-site analysis shared by compilers and interpreters.
• Canonical execution-definition, interaction, control, trace, explain, provenance, and compatibility contracts.
• Native operation-telemetry emission with failure isolation for caller-owned activities and instruments.
• Common typed quantities, identifiers, codes, paths, diagnostics, and deterministic serialization helpers.

The package does not define Relations, Transitions, Processes, APIs, presentation, storage, or provider behavior. Those blocks depend on these shared semantic contracts.

Observations and snapshots

An Observation describes an immutable shaped value. Entity identity and version remain explicit rather than being silently attached to every value:

Shipment shipment = observation.Materialize<Shipment>();

var snapshot = new EntityObservationSnapshot(
    new EntityId("shipment-42"),
    version: 3,
    observation);

Physical layouts, source placement, relation occurrences, and storage concurrency tokens belong to the interpreting block or adapter.

Native operation telemetry

Library instrumentation can compose OperationTelemetryEmitter over its own native .NET diagnostic objects. The instrumentation owner still defines every scope, instrument, operation, status, tag, and log; the emitter only pairs activity completion with duration/failure measurements and prevents synchronous observers from changing the measured operation. Duration histograms use seconds.

using System.Diagnostics;
using System.Diagnostics.Metrics;
using Cohesive.Observability;

ActivitySource activities = new("Example.Library");
Meter meter = new("Example.Library");
Histogram<double> duration = meter.CreateHistogram<double>("example.operation.duration", "s");
Counter<long> failures = meter.CreateCounter<long>("example.operation.failures", "{failure}");
OperationTelemetryEmitter operations = new(activities, duration, failures);

var activity = operations.StartActivity("example.operation");
var started = operations.StartTimer();
Exception? failure = null;
try
{
    RunOperation();
}
catch (Exception exception)
{
    failure = exception;
    throw;
}
finally
{
    TagList tags = default;
    tags.Add("example.operation.kind", "compile");
    operations.CompleteOperation(
        activity,
        started,
        failure is null ? ActivityStatusCode.Ok : ActivityStatusCode.Error,
        tags,
        failure);
}

Hosts collect the source and meter with their native OpenTelemetry configuration. The emitter neither references the OpenTelemetry SDK nor owns logging, export, sampling, or service-level policy.

Go deeper

• Core internals covers observations, portable JSON values, execution catalogs, interactions, durable requests, Process control, and expression analysis.
• System-wide documentation explains how the blocks fit together.
• Semantic model introduces the shared vocabulary.
• Observation identity decision records the ownership boundary between values, snapshots, and occurrences.
• Native OpenTelemetry registration decision records the boundary between library emission, host collection, and adapter/provider scopes.

Related application blocks include Cohesive.Relations, Cohesive.Transitions, and Cohesive.Processes.

Ordinal observation construction

Observation.Create(shape, layout, immutableValues) retains an ImmutableArray<ObservationValue> in a shared ObservationLayout; the span overload snapshots caller-owned values. Layouts belong to the exact graph instance and shape from which they were compiled. Each slot is one canonical field: Undefined means absent, while Null remains present. Full shape validation still runs. Name-based Fields is an immutable view over the same vector, and canonical serialization, equality, and fingerprints are independent of physical field order. The field view also implements IOrdinalObservationFieldReader, allowing a materializer compiled against that layout to read directly by ordinal.

Default CLR materialization converts native byte observations directly to an independently owned byte[], including inside conventional nested records and arrays. This copies mutable output once; it does not route bytes through JSON text. Explicit serializer customizations retain their chosen conversion contract. Durable detached observation values can opt into PortableValueJsonConverter.TaggedObservationValues, which reuses the PortableValue node encoding to preserve byte, temporal, numeric, and undefined kinds. Opting in changes the wire format and requires a versioned profile; ordinary observation JSON remains unchanged. Entity receipts use the explicit EntityStorageJson profile in Storage.

Type-level value admission

ObservationValidator.TryValidateAgainstType(value, type, out error, graph) exposes the same type checks used by observation admission without manufacturing a one-field shape. Named types resolve only in the supplied graph. This validates a concrete type; field presence and nullability remain the caller's contract. Relation draft admission uses it for graph-owned enum literals.

Exact decimal text

ObservationValue.TryParseExactDecimal(text, out value) validates signed invariant decimal text without rounding. It shares bounded coefficient parsing with JSON-number acquisition, while JSON alone permits exponent notation. The expression evaluator delegates to this helper. The existing TryGetDecimal convenience coercion keeps its broader BCL syntax and rounding behavior.

Execution-document normalization and fingerprinting traverse immutable JSON directly; see canonicalization performance for ownership, exact-byte regression coverage, allocation measurements and remaining costs.

Concurrent JSON profile metadata preparation

SystemTextJsonClrShapeMetadataProvider may be shared by independent CLR graph builders, as in the relation authoring defaults. It freezes serializer options and retains nested field-profile metadata by property for the provider lifetime. One reentrant gate protects cache lookup/publication and the active profile set across nested preparation. A concurrent first use must not be mistaken for a recursive converter profile. Real recursive profiles remain rejected, and failed preparation clears recursion state without caching failure. The gate covers synchronous metadata preparation, not query execution, source reads or observation materialization. Retained named types are reused after successful preparation.

Ari's parallel qualification exposed duplicate-key insertion and false recursive-profile failures. ClrShapeGraphBuilderMetadataTests reproduces cold concurrent access for plain, nested and collection properties, verifies shared retained type identity, and preserves real-cycle rejection and failure cleanup. Warm allocation guards separate cache preparation from 1,000 repeated reads after 10,000 warm-up calls. A local .NET 10 allocation probe over 100,000 warm reads measured approximately 152/1,496/1,584 bytes per plain/nested/collection lookup both before and after synchronization. These existing costs include field metadata/reflection projection; longer converter type names in the regression fixtures measure 2,032/2,120 bytes for nested/collection fields and use separate bounds. The change makes no throughput or end-to-end latency claim. Cold preparation is measured separately and includes serializer/CLR metadata initialization, so its total is not retained cache size. No additional per-row cache or alternative semantic model was introduced.