The product model

Polyglot persistence

Relational, document, KV, graph, wide-column, time-series, vector — derived from one product definition.

This page is the documentation contract for the Polyglot persistence surface in Vadyl's final form. It is not a marketing summary: it names the authorities, projections, runtime behavior, examples, limits, errors, and observability expectations that every product implementation must honor.

What this surface owns

Polyglot persistence owns the canonical product-facing contract described here; provider-specific machinery stays behind capability declarations.
Relational, document, KV, graph, wide-column, time-series, vector — derived from one product definition.
The final docs treat this as complete: REST, GraphQL, gRPC, SDK, CLI, MCP, dashboard, observability, limits, errors, and explainability are all covered as projections of one authority.

Canonical authorities

Authority	Role
`ContractProjectionFacet.Entities`	Projects Polyglot persistence from canonical project state into every caller-visible contract.
`ProjectRuntimeDescriptor`	Pins Polyglot persistence to a publication, runtime descriptor, worker, or substrate realization.
`SchemaTransitionOrchestrator`	Canonical owner for Polyglot persistence; downstream surfaces derive from this rather than inventing their own truth.
`PlaneCapabilityGraph`	Places Polyglot persistence inside the UCSA taxonomy and enforces binding, grants, conformance, and consumption.

Projection coverage

Surface kinds	`DatabaseInfrastructure`, `OperationProjectionSurface`, `SubscriptionSurface`, `ExplainabilitySurface`
Projection facets	`Entities`, `Operations`, `ExposureBindings`, `PlaneCapabilityGraph`
Protocols	`Rest`, `OpenApi`, `GraphQL`, `Grpc`, `Sdk`, `Cli`, `Mcp`
Public projections	REST entity CRUD; GraphQL query/mutation; gRPC entity services; SDK entities namespace; CLI entity/schema commands; MCP entity tools

Project-scope parity

Publish, install, consume

Consumption evidence

Runtime behavior

ProjectRuntimeCompiler
ReadCoordinator
WriteCoordinator
family-aware evolution executor
post-access cache gate

REST and controller surface

Code-backed controllers are listed here so the docs menu does not hide the real endpoint surface. The complete route-by-route table remains in the REST controller atlas.

Controller	Base route	Endpoint count	Examples
Entity	`/api/Entity`	16	`POST /` `POST {entityName}` `GET {entityName}/{id}` `POST {entityName}/{id}/restore`
Schema	`/api/Schema`	22	`POST entities` `PUT entities` `POST entities/delete` `DELETE entities`
SchemaTransition	`/api/SchemaTransition`	6	`GET /` `GET {id}` `POST preview` `POST /`
Evolution	`/api/Evolution`	6	`GET runs/{runId}` `GET runs/active` `GET runs/{runId}/nodes` `GET runs/{runId}/barriers`
Explainability	`/api/Explainability`	15	`GET surface` `GET project-runtime` `GET publication/latest` `GET publication/{publicationVersion:long}`

SDK and CLI surface

Projection	Namespace / group	Coverage
SDK	`entities.<Entity>`	list, read, create, update, upsert, delete, count, exists, alternate-key, batch, subscribe. Rendered methods: 10.
SDK	`schema`	metadata, preview, diff, validate, snapshots, migrations, journals, transitions. Rendered methods: 6.
SDK	`explainability`	access, read-plan, surface, publication, analytics, automation, PCG, measure explanations. Rendered methods: 3.
CLI	`vadyl entity`	List, inspect, mutate canonical entities. Rendered commands: 6.
CLI	`vadyl schema`	Schema-transition pipeline operations. Rendered commands: 6.
CLI	`vadyl explain`	Project canonical decision reasoning. Rendered commands: 4.

Input request and output

polyglot-persistence.surface

POST /api/Entity HTTP/1.1
Host: api.vadyl.app
Authorization: Bearer $VADYL_TOKEN
X-Vadyl-Tenant: acme
X-Vadyl-Project: billing
Content-Type: application/json

{
  "surface": "polyglot-persistence",
  "publicationVersion": 412,
  "explain": true
}

Limits and quotas

Error model

Error	Meaning

Observability and explainability

Related references

Full surface atlas

Exposure bindings