Cohesive.Relations 0.1.0-alpha.151

Cohesive.Relations

Instance composition

QueryModel optionally groups instance-owned typed queries. Its Queries property exposes the same QueryModelBuilder available for standalone composition. Queries.WithInput<T>("name").Array(id, recipe) and .SingleOrDefault(id, recipe) own the isolated authoring session, parameter, finalization and registration. The array recipe returns result rows. The nested recipe receives (query, input, output) and returns output.From(rows).Key(...) mappings; only the outer SingleOrDefault<TResult> declares cardinality and result type. Recipes perform no runtime work. Stable IDs remain explicit; an optional display name defaults to the exact ID. Query(existingTypedQuery) (or builder Include) still supports separately authored queries. Definition freezes the ordered canonical requests. Failed recipes contribute nothing; duplicate/frozen registrations fail before invoking the recipe. A recipe cannot reentrantly modify or freeze its model. None of this compiles queries or chooses database placement.

For nested results, .SingleOrDefault<Detail>().From(joinedRows).Key(parent, p => p.Id, d => d.Id) selects the rowset separately and declares both sides of its key mapping together. The keyed collection overload likewise takes the source key and child destination before the remaining field mappings. These forms lower through the existing identity slots and canonical assembly, preserving null-parent behavior, absent children, distinct children ordered by ordinal key, and conflict detection. The existing separate From(..., key) / Identity(...) forms remain available when the grouping key is not exposed in the result.

Cohesive.Relations lets applications describe relationships, projections, filters, and queries in typed C# while leaving storage placement and execution strategy to compilers and adapters.

Portable relation drafts support explicit nested fields, statically keyed object construction, explicit coalesce defaults, bounded code-conditionals, key-based collection join and collection select with shape-aware acceptance. Selectors preserve item scope and each target child's contract; source collections must be present and non-null. Explicit single requires exactly one selected item, and explicit parseInt32/parseInt64 convert in-range integer text. parseDecimal converts invariant text without rounding. Named enum literals are checked in their owning graph. Implicit element traversal and undeclared conversions remain unsupported.

Typed imports accept named and inline string enums only when their serialized member sets match. Core EnumTypeRef.IsWireEquivalentTo owns this structural wire rule: enum names and member order are ignored, but ordinal values must match exactly. It does not change nominal equality or fingerprints. The comparison uses allocation-free scans intended for small closed enum sets at preparation time. Nested result projections retain enum declarations in their row graph; enum fields remain closed contracts through compilation and result assembly. Explicit text operations may consume enum wire values, but an arbitrary string or a different member set does not satisfy an enum result contract.

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.

Hosted typed handlers retain fresh portable-value admission while delegating CLR decoding to Core’s pooled UTF-8 boundary. Typed row, nested-result and transition projections prepare plain JSON interpretation at binding construction; customized contracts retain JSON decoding. See qualification.

HostedQuery<TInput, TResult>.AsObservation() binds handlers to admitted observation storage while retaining the original canonical contracts. Use captured FieldPath selectors for sparse reads and ObservationValue.WithFields for immutable batch updates; unchanged subtrees can be returned without CLR materialization. This does not turn a partial datasource projection into a complete value. See schema-bound observation handlers.

Relation and realization fingerprints retain their existing binary profiles while streaming temporary output. See performance qualification.

Install

dotnet add package Cohesive.Relations

Author a relation

A complete Load -> LoadDto relation needs no hand-authored node IDs, binding names, source placement, or adapter configuration:

var author = RelationQuery.Expression();
var loads = author.Source<Load>();

var loadDtos = author.Project(
    loads,
    (Load load) => new LoadDto
    {
        Id = load.Id,
        Status = load.Status
    });

var relation = loadDtos.BuildRelation(dto => dto.Id);

The authoring session derives the logical nodes, bindings, shapes, field assignments, relation identity, display name, and provenance. relation contains the canonical definition and structured validation diagnostics.

Add a relationship when the result needs another fact:

var author = RelationQuery.Expression();
var loads = author.Source<Load>();

var customers = author.Traverse<Load, Customer>(
    loads,
    load => load.CustomerId);

var searchDocuments = author.Project(
    customers,
    (Load load, Customer customer) => new LoadSearchDto
    {
        Id = load.Id,
        CustomerName = customer.Name
    });

var loadSearch = searchDocuments.BuildRelation(dto => dto.Id);

The same traversal may become an in-memory lookup, a PostgreSQL join, bounded source reads followed by local correlation, or another capability-compatible realization. The relation itself does not change.

Use it for

• DTO mapping and enrichment.
• Independently invoked row and aggregation queries.
• Application read models, API results, integration payloads, and reports.
• Field-demand, dependency, lineage, and missing-input analysis.
• Relation-derived materialized views and targeted rebuild planning.
• Portable execution across supplied objects and registered physical sources.

How execution stays honest

The canonical relation/query document is the semantic authority. An invocation selects results and parameters; compilation derives the exact fields and operations it needs. A target must prove those requirements against its capabilities and operating boundaries. Unsupported semantics and incomplete source evidence produce structured diagnostics rather than a weakened query or a misleading empty result.

The expression API is the normal application surface. Structural authoring and direct IR construction remain available for importers, generators, persistence tooling, and compiler tests.

Continue

• Getting started builds, evaluates, and enriches a relation.
• Execution and adapters covers supplied facts, acquisition, placement, and native compilation.
• Diagnostics explains incomplete evidence and requirement gaps.
• Capability reference is generated from the implemented target profiles.
• Migration covers the retired relation-query stack.
• Internals retains the complete semantic model, compiler architecture, use cases, and design rationale.

Adapter-specific guides are available for Cohesive.Adapters.Postgres, Cohesive.Adapters.Cosmos, and Cohesive.Adapters.Elastic.

Typed row-query results

Expression authoring can retain a typed input and public application result with BuildQuery(id, name, rows, parameter, result: values => ...). The returned RelationQuery<TInput,TResult> captures the existing canonical query, shape documents and relationship catalog without compiling or selecting a backend. Its row type is inferred and can be anonymous; constructor projections still require verified direct field initialization/getters. Where retains a focused binding for the existing typed traversal/projection overloads.

The result callback is a local presentation projection of complete typed rows. It explicitly handles empty results and nesting; it is not serialized as portable query semantics. The shared boundary performs observation decoding, so consumers invoke a typed prepared query instead of maintaining intermediary DTO conversions. This convenience currently requires one exact invocation parameter and one row result; additional or foreign parameters fail closed. Existing structural query and HostedQuery APIs retain their separate responsibilities. See the fulfillment example for backend registration and fluent API binding.

Prepared typed readers implement IRelationQueryReader<TInput,TResult> and retain the exact authored Definition; HTTP bindings can accept that object without taking a dependency on its backend. The narrower IRelationQueryRowsReader contract describes complete bounded rows before typed projection, including missing-field versus null semantics. Neither contract silently discards partiality or adds retry. These convenience contracts do not replace IRelationQueryEvaluator: the existing composed execution path supports cross-source joins and retains phase artifacts, requirement gaps and source-read traces. Native PostgreSQL selection remains explicit; no automatic native-versus-federated dispatcher is introduced.

Preparation exception migration (unreleased PR405)

RelationQueryPreparationException now derives from PreparationException, which derives from InvalidOperationException; it no longer derives from ArgumentException. Callers previously using catch (ArgumentException) for preparation must catch RelationQueryPreparationException or the shared PreparationException instead. Argument validation errors remain separate. The previous default relationQuery.preparation.invalid code is replaced by relationQuery.preparation.semantic or relationQuery.preparation.physical, based on the failed preparation phase. Update code-based handlers accordingly. Explicit relationQuery.subplan.* codes retain their meanings, including resultUnsupported for a successfully compiled query whose result contract is not supported by subplans. Original semantic and physical compiler evidence stays available. No compatibility catch or code alias is introduced.

Fluent query rows and array results

Focused nodes use Where and Select; joined nodes retain both bindings for a two-argument Select. Join means inner join and LeftJoin preserves unmatched left rows. Typed Traverse and TraverseInverse optionally accept a result selector over the starting and related rows, so application code need not manually carry .Binding values into a session-level projection.

var demand = orders.TraverseInverse(reservationOrder,
    (order, reservation) => new Demand(order.Id, reservation.Sku));
var definition = demand
    .LeftJoin(inventory, (row, item) => row.Sku == item.Sku)
    .Select((row, item) => new Availability(row.OrderId, item.Available))
    .BuildArrayQuery(id: new("availability"), name: new("Availability"), parameter: orderId);

This is expression authoring, not IQueryable or deferred backend execution. BuildArrayQuery captures a RelationQuery<TInput, TRow[]>; adapters still own compilation and execution. It returns an empty array for no complete rows and preserves declared ordering only. No allocation or throughput guarantee is claimed for result assembly. Traversal retains existing left/missing-value semantics; selectors lower to canonical IR rather than executing arbitrary CLR callbacks. Existing session ownership and visibility checks apply.

Result assembly is explicitly named RelationQuery<TInput,TResult>.AssembleResult(rowsOrOutcome). It consumes already acquired complete rows/outcomes and performs no IO. Session Project still authors canonical projection nodes; fluent Select is its typed row-chain surface. BuildArrayQuery constructs a definition, making the declaration/execution boundary visible at the call site.

Consumer migration (Ari/Ito included when adopting a release containing this change): update fluent Project to Select, fluent left joins to LeftJoin, and typed-query Project to AssembleResult. Explicit session Project/Join remain available for structural/multi-binding work. The unshipped PR408 terminal ToArray is now BuildArrayQuery. These are source-breaking renames; no compatibility aliases are retained. Alpha.132 contains the previous surface (as does alpha.131 for APIs present there); publishing this PR and upgrading downstream consumers are separate steps. This PR updates in-repository consumers only and does not claim Ari or Ito have adopted the changes.

Reader consistency and reusable physical preparation

IRelationQueryReader<TInput,TResult>.Consistency describes all reads contributing to one result. SingleSnapshot requires one shared observation snapshot; IndependentSources permits independent observations, including multiple reads from one database. Native PostgreSQL statement readers report the former; composed and subplan readers report the latter. Service/API binding checks the declared requirement before publishing routes, and rechecks it when reusing a cached reader. This is a guarantee contract, not an automatic downgrade based on the number of databases.

RelationQueryPhysicalPreparation retains validated interpreter and physical planning evidence for reuse at runtime binding. Affinity checks preserve the exact semantic compilation, placement and policy; this never caches parameters, source observations or results.

Hosted typed query admission

Hosted typed Query admission prepares the framework CLR contract once and reads ordinary envelopes directly from observation fields. Customized members retain their owning JSON converters; explicitly immutable projections can be reused without rebuilding their graph. Portable contract admission still runs per decode. See prepared observation projections for scope and qualification.