Cohesive.Storage 0.1.0-alpha.80

Cohesive.Storage

Cohesive.Storage defines provider-neutral durability, source acquisition, aggregate storage realization, and relation-derived materialization contracts for Cohesive systems.

Typed entity repositories preserve the underlying repository's batch capabilities, item limits, input order, and requested atomicity. UpsertBatch(context, entities, atomicity) maps ordinary records through the same selectors as single writes, then invokes one native batch. Per-candidate concurrency tokens use the canonical EntityBatchWriteRequest overload. Unsupported atomicity is rejected instead of silently using independent writes.

Install

dotnet add package Cohesive.Storage

Register a Relation source

Storage can attach an entity repository to the canonical Relations acquisition port. Shape, source identity, limits, and version projection are derived or declared once:

var source = EntityRelationQuerySourceRegistration.InMemory(
    loadShape,
    repository,
    logicalPartition: RelationQueryLogicalPartitionIdentity.WholeSource,
    observationVersionSemanticPath: FieldPath.FromField("SourceEntityVersion"),
    limits: new(
        maximumBatchSize: 100,
        maximumBufferedRows: 10_000,
        maximumFanOut: 100,
        maximumConcurrency: 4));

var catalog = new EntityRelationQuerySourceCatalog([source]);
IRelationQueryEvaluator evaluator = catalog.CreateEvaluator(physicalPlanningPolicy);
var outcome = await evaluator.EvaluateAsync(evaluation, cancellationToken);

Relations remains authoritative for filters, joins, projections, aggregation, and paging. Storage contributes bounded physical acquisition and exact source evidence.

What this package owns

• Entity repository and observation-stream ports.
• The atomic durable Process aggregate, store contract, and provider-neutral reference runtime.
• Canonical Relation source registration and evaluator composition.
• Aggregate storage structures and target realization documents.
• Relation-derived materialization definitions, impact planning, rebuilds, and incremental synchronization.
• Generation allocation, sealing, validation, promotion, cleanup, routing, and progress evidence.
• Query-authority and lifecycle-control contracts used by storage adapters.

Important boundaries

Cohesive.Storage does not define another query language, Transition model, or Process model. It consumes exact semantic documents and compiled evidence from those owning blocks. Provider SDKs and physical schemas remain in adapter packages.

Retained entity snapshots and Transition operation commits use the explicit lossless EntityStorageJson.CreateOptions() profile. It reuses the core PortableValue tagged node codec for detached observation fields; ordinary JSON serialization is unchanged. Payload format 2 and sha256-entity-v2 commit fingerprints require explicit migration of older retained evidence. Request and operation identities remain stable so old receipts cannot be mistaken for missing operations. See the SQLite adoption and migration notes.

InMemoryProcessDurableStore is the copy-on-write reference implementation and semantic test oracle. It is not a production durability provider and does not claim physical exactly-once publication.

Materialization uses the Relations dependency manifest and lineage rather than copying their edges into a second model. When an incremental route cannot be proven within configured limits, planning fails closed or requires an explicit rebuild policy.

Continue

• Internals covers the durable Process aggregate, source contracts, storage realizations, materialization lifecycle, routing, and query authority in detail.
• Index synchronization runbook covers the operational path.
• Cohesive.Relations owns relation/query semantics and dependency evidence.
• Cohesive.Adapters.Postgres, Cohesive.Adapters.Cosmos, and Cohesive.Adapters.Elastic provide physical interpretations.

Experimental atomic commit declarations

Cohesive.Storage.Commits.IStorageCommitExecutor accepts an immutable StorageCommitIntent: conditional portable item writes, explicit query guard dependencies and a retained operation result. SQLite and Cosmos interpreters commit the writes and receipt atomically within their advertised placement limits. ReconcileAsync resolves exact receipts after uncertain acknowledgments without reading later state. Missing evidence is Unknown, not proof that an operation rolled back.

This bounded profile owns dedicated item storage; it does not yet enlist arbitrary repository tables. See the decision and native capability boundaries.

Third-party interpreters implement the public executor interface and advertise their capability profile. Intent inspection, strict serialization and result factories are public; no friend-assembly registration or access to adapter internals is required.

Commit preflight is executor.Validate(intent): it includes adapter-encoded payload limits without I/O. Capabilities.ValidateStructure(intent) only checks placement and dependencies; full capability validation requires serialized byte evidence when a payload budget is declared. Query guard writes must carry a non-null token captured before the query; initialize a missing guard separately.