Expand description
The three plugin contracts of the graph-storage gateway.
The gear is a stateless gateway over a pluggable store: every byte it
serves comes from a GraphStoreV1 implementation behind the port, and
the built-in PostgreSQL store is registered exactly as an external plugin
would be. GraphEngineV1 serves traversal expansion;
EmbeddingProviderV1 turns text into vectors.
An implementation that cannot provide an obligation declares the
corresponding capability absent and returns Unsupported from the
affected method. It never implements a weaker version — a silently
weakened guarantee is worse than an absent capability, because the gear
can route around the second and not the first.
Structs§
- Embed
Request - Batched, not per item: the batch is where a remote provider’s round trip is amortized.
- Embed
Response - Embedding
Plan - The embedding decisions of one ingest batch.
- Embedding
State - What a store holds of one node’s vector, for the coordinator’s skip
decision. Two facts, because both are needed: a vector is worth keeping
only if it was made from the node’s current text (
input_hash) and is rankable under the current space (vector_epoch). - Engine
Cursor - The engine’s applied
(source epoch, graph revision)position. The epoch is a non-reusable timeline identifier, so a projection that survived a point-in-time restore of the source database is detected rather than served. - Expand
Request - Directed one-hop expansion request. Direction is explicit because the undirected shorthand plans as an all-vertex probe; expansion is a one-hop primitive because multi-hop chain patterns enumerate paths and explode on hubs.
- Expand
Response - Node
Embedding - What the Embedding Coordinator decided about one node, for the store to
write. Index-aligned with
IngestRequest::nodes— the same conventionEmbedResponse::vectorsuses, and for the same reason: any other association would have to be keyed on something a batch may legitimately repeat. - Path
Response - Pattern
Request - Declared-capability pattern matching (not shipped by the built-in engine).
- Pattern
Response - Shortest
Path Request - Store
Ctx - Per-call context. The compiled scope is mandatory, not optional: authorization has to reach inside the statements (a search arm applies it before ranking and LIMIT), so it cannot be a filter the gear applies to whatever the plugin returns.
- Vector
Arm - The vector arm of one search, as the coordinator resolved it.
Enums§
- Embedding
Provider Error - Provider-side failure vocabulary. A provider failure fails the ingest batch; it is never downgraded to an unembedded write.
- Graph
Engine Error - Engine-side failure vocabulary.
- Graph
Store Error - Store-side failure vocabulary. The gear normalizes these into canonical errors before they cross the public boundary; no vendor text survives.
- HopBackend
- The hop backends of ADR-0005, as the answer reports them.
Traits§
- Embedding
Provider V1 - The embedding-provider plugin contract
(
cpt-cf-graph-storage-contract-embedding-provider). - Graph
Engine V1 - The traversal-engine plugin contract
(
cpt-cf-graph-storage-contract-graph-engine-plugin). - Graph
Store V1 - The store plugin contract (
cpt-cf-graph-storage-contract-graph-store-plugin).