From Definition to Physical Evidence

Canonical Definitions and Authoring Frontends

The typed expression API is an authoring frontend. It immediately lowers CLR types, member selections, and supported expression trees into graph-qualified shapes, relationship definitions, and the closed relation model.

Persisted C# delegates and reflection metadata are not execution authority. A validated RelationQueryDocument retains the normalized operators, expressions, bindings, outputs, parameters, and exact shape and relationship references needed to restore the definition. Fingerprints use deterministic ordering and the shared Cohesive identities, versions, provenance, and portable-value model.

Structural authoring, importers, generators, and inference systems may produce the same canonical model. Portable relation drafts preserve unresolved or ambiguous field assignments during authoring without making those uncertain candidates executable semantics.

Definition, Evaluation, and Result

A RelationDefinition is reusable and rooted in supplied input. A QueryDefinition is invoked independently and exposes named row or aggregation results. A RelationQueryEvaluation selects one definition for one invocation and adds parameters, selected outputs, supplied roots, and exact semantic snapshots.

The resulting RelationQueryEvaluationOutcome retains the major phase artifacts instead of flattening them into an opaque DTO response:

Demand-Scoped Compilation

An evaluation can request only particular result branches or projected fields. RelationQueryStaticCompiler traces backward from that demand and prunes unrelated outputs and logical nodes before physical realization.

The retained plan includes fields needed by selected projections as well as predicates, traversal keys, joins, ordering, grouping, aggregation, identity, invariants, cardinality, and diagnostic attribution. RelationQueryFieldSemantics identifies exact semantic uses such as a single string identity field without relying on a provider's physical selector convention.

The requirement graph records what must hold and why. Output-oriented lineage answers which inputs contributed to or influenced a result. The inverse dependency manifest supports impact analysis from an input toward affected outputs. Predicate and temporal membership inputs remain influences even when their values are not projected.

Profile Feasibility and Contextual Realization

Capability checking occurs in two stages:

1. A target profile states the operator and value-semantics closure the adapter can potentially preserve.
2. Bound realization qualifies that answer against the exact compiled plan, selected outputs, physical placement, and adapter evidence.

A PostgreSQL profile may support joins in general, for example, while one requested join is native only when both inputs bind to the same execution domain and the participating fields have compatible encodings and comparison behavior.

Each demand receives an explicit native, composed, constrained, overridden, or unavailable decision. Constraints and overrides remain local and fingerprinted. An unavailable requirement fails before execution rather than silently replacing the requested behavior with a close approximation.

Source Placement and Configuration Attribution

RelationQuerySourcePlacement schema v3 binds compiled logical inputs to exact source instances. A binding records its source, execution domain, acquisition mode, identity selector, demanded field selectors, relationship-key selectors, partition behavior, limits, and whether it came from an explicit declaration or convention.

Identity bindings can now retain the semantic field path that supplies observation identity. A source-native identity with no corresponding shape field remains distinguishable from a physical selector proven to represent a particular semantic field. This evidence is used by planning and materialization instead of inferring identity from matching names.

Effective configuration decisions use the shared configuration-attribution model. Precedence remains visible across explicit local declarations, scoped profiles, adapter conventions, and framework defaults. The normalized placement and every effective choice contribute to its fingerprint.

Bounded Physical Planning and Execution

Composed evaluation turns placement into finite source operations and local semantic stages:

IRelationQuerySourceReader implementations supply primitive facts. They do not independently own filter, join, aggregation, or output semantics. Limits for rows, keys per batch, buffering, fanout, and concurrency are explicit. Exceeding a bound fails or follows an admitted chunking plan; it does not switch to unbounded acquisition.

Current Adapter Paths

The current adapters preserve different subsets of the model:

• The in-memory interpreter is the reference implementation over explicit runtime evidence and performs no I/O.
• PostgreSQL has provider-neutral native SQL compilation for supported rows, aggregation, relationships, explicit and valid-time joins, ordering, and paging. PostgresRelationQuerySourceReader separately executes bounded enumeration, identity point or batch reads, and parameterized relationship predicates through a caller-owned NpgsqlDataSource.
• Cosmos supports native single-container query compilation and SDK execution, plus bounded entity-source reads for composed cross-document plans.
• Elasticsearch lowers a supported single-index closure into SDK request descriptors, including mapped scalar behavior and narrow nested correlation.
• DTO materialization compiles CLR construction kernels over canonical output rows after evaluation.

The PostgreSQL source path is deliberately separate from native-artifact dispatch. Registering its source reader lets the evaluator execute bounded composed reads through Npgsql. A compiled PostgresSqlStatement remains an artifact the application explicitly dispatches.

PostgresMaterializationSource reuses the source reader for item- and byte-bounded keyset pages. Each page is a separate statement snapshot, so it can claim stable ordering and request-local completeness but not a coordinated snapshot across an entire rebuild.

Completeness and Runtime Evidence

RelationQueryRuntimeEvidence carries supplied and acquired observations, parameter values, source completeness, and realized capability evidence into interpretation. The evaluator projects capability evidence from the exact plan and realization rather than allowing a source reader to claim semantics it did not establish.

Complete empty, authoritative absence, missing, null, partial, failed, not attempted, and inconclusive evidence remain distinct. An outer join can emit an unmatched row only when the opposite candidate set is complete and every applicable candidate is a conclusive non-match. An aggregation over partial input cannot be presented as a complete total.

Observation.HasSameContent compares semantic identity, version, lineage, and field values while excluding physical storage concurrency tokens and placement. This supports cross-boundary conformance without treating provider fences as part of the fact itself.

Materialization Dependency Handoff

Relations remains the authority for which inputs influence a selected output. Storage compiles those exact requirements into a materialization impact plan. RelationQueryFieldSemantics and the requirement graph let the compiler distinguish root identity, contributor identity, projected values, predicates, and relationship references.

That handoff enables direct root invalidation, relationship-path traversal, contributor-ledger lookup, or an explicitly bounded global fallback. Storage rejects incremental maintenance when before-images, inverse paths, completeness, or source capabilities are insufficient. It owns change delivery, durable checkpoints, settlement, rebuilds, and promotion of each projection model.

Diagnostics, Explain, and Telemetry

Diagnostics retain definition, node, binding, input, field, relationship, expression site, output, placement, and adapter attribution wherever those facts exist. Definition errors, missing runtime requirements, capability failures, source failures, and incomplete results remain separate categories.

RelationQueryExplainProjector.Project(outcome) produces a portable, payload-safe explanation from retained phase evidence without rerunning the evaluation. Capability summaries index the exact profile and contextual decisions by canonical capability. Bounded telemetry reports compilation, planning, acquisition, interpretation, and failure observations without turning runtime measurements into semantic authority.

Current Boundaries

The implementation deliberately stops at several integration boundaries:

• RelationQueryEvaluator executes the composed physical path; it does not automatically choose and dispatch native PostgreSQL, Cosmos, or Elasticsearch artifacts.
• PostgreSQL native compilation is provider-neutral. The Npgsql reader handles composed source acquisition, not automatic native-query selection.
• Cosmos native compilation remains single-container; cross-container enrichment uses bounded acquisition and local correlation without claiming one atomic snapshot.
• Elasticsearch supports the documented single-index closure and narrow nested correlation rather than arbitrary collection operators.
• Gremlin remains deferred.
• Materialization execution, retry, throttling, source settlement, and target promotion belong to Cohesive.Storage and Cohesive.Control.
• Ari retains model evidence, alternatives, confidence, and review workflow; only accepted mappings become canonical Relations definitions.

These boundaries preserve the distinction between relational programming, a particular realization, and the mechanisms supplied by physical storage systems.

Continue

Return to the Cohesive.Relations overview →

Author and evaluate the first relation →

See how Storage supplies sources and maintains derived views →