KynetraDB · capability catalogue
What KynetraDB does, and what state each part is in.
This catalogue lists 125 capabilities in 8 families. Each entry names the problem it removes, where you reach it, what limits it and the evidence behind its state. When the evidence is missing, the state goes down; the entry is not hidden.
- Available in preview
- 31
- Beta
- 56
- Roadmap
- 34
- Research
- 4
How to read it
Four states, one rule
A capability is Available in preview when we can point to its implementation, to a route, command or SDK export that makes it reachable, and to tests in the engine repository. If any of the three is missing, the state is lower. This edition describes engine edition 5f8ea3af. Tests are listed as present; this site does not report test results.
- Available in preview
- Reachable today through the private-preview server, the command line or an SDK, and backed by tests in the engine repository. Any limit it has is written on its page.
- Beta
- Reachable, with a material limitation that is stated on its page: partial coverage, a missing transport protection, or scale that has not been measured.
- Roadmap
- Not reachable by users. This covers library code the server does not wire, and work in development. No dates are given.
- Research
- Experiments, prototypes and work done for benchmarks. Not scheduled as a feature.
Browse
By family
Search & retrieval
BM25 full-text search
Gives an application relevance-ranked keyword search over its own records without running a separate search cluster.
Available in previewSurfaces and limits: BM25 full-text search
Every entity written to KynetraDB is indexed for keyword search as part of the same write path. POST /v1/search returns the highest-scoring hits ranked by BM25, optionally restricted to one entity kind. The index is a segmented inverted index held in the engine process and snapshotted at checkpoints, so it recovers together with the rest of the database.
- HTTP
POST /v1/search { q, top_k, kind } - SDK
SearchClient.bm25 in the TypeScript, Python, Go and Rust client sources - MCP
kynetra_search (HTTP /mcp and the stdio kynetra-mcp server)
- Keyword matching on exact tokens after case and accent folding. There is no stemming, no phrase or proximity query, no per-field boost and no highlighting.
- Fuzzy matching and synonym expansion exist as engine library functions, but no route, command or client call reaches them, so they are not part of this capability.
- Document frequency still counts tombstoned postings until a future merge, so inverse document frequency drifts slightly on corpora with heavy update and delete churn. Scores of live documents stay exact for the postings that exist.
- The index is held in memory and the server indexes every kind; there is no server setting to narrow it. Plan memory for the whole text of the corpus.
- Relevance against human-labelled judgements has not been measured on a public corpus. The published artifacts measure latency and agreement with the exhaustive scorer on synthetic data.
- The route accepts service credentials: the instance key or a project service key. Anonymous project keys and end-user tokens are refused.
- HTTP
KynQL query language
Gives clients a readable way to filter, project, sort and page one collection without exposing a general query language.
Available in previewSurfaces and limits: KynQL query language
KynQL is a short pipeline for reading one collection: from, where, select, sort, limit and offset, separated by a pipe or a newline. POST /v1/query parses it into a typed plan and runs it under the caller collection permissions and row-level policies. It has no write verbs, and the parser enforces limits on query size, nesting depth and page size.
- HTTP
POST /v1/query { query }
- A query reads the whole collection and filters in memory, so cost is linear in collection size whatever the where clause says. Indexes declared on a collection are not consulted.
- There is no not operator, no membership test, no join, no grouping or aggregate and no text-search predicate. Use the search routes for text and vectors.
- A page holds at most 500 rows.
- KynQL is not exposed through the MCP tools or the client SDKs; the HTTP route is the surface.
- HTTP
Retrieval policies
Decides, before any data is read, whether a caller may retrieve from a collection and which fields may come back, with deny as the default.
Available in previewSurfaces and limits: Retrieval policies
Retrieval policies are versioned grants that name collections, identities, purposes, tools, row filters and field masks. POST /v1/retrieval-policies/query authorises the caller first, reads a candidate window, re-checks every row and masks fields, and returns the same empty result for denial and for absence. A simulate route previews a decision without reading data. The policies govern this route and no other.
- HTTP
POST /v1/retrieval-policies, GET /v1/retrieval-policies, GET /v1/retrieval-policies/{name}, GET .../versions, POST /v1/retrieval-policies/simulate, POST /v1/retrieval-policies/query
- Retrieval policies govern the governed query route alone. The search, vector, hybrid and KynQL routes, the REST plane and realtime are governed by tenant scoping and collection rules, and enabling a policy does not change them.
- The first 1,000 candidate rows of a collection are considered and no more; cursor pagination is not implemented.
- The route lists and filters records of one collection. It does not rank or search.
- A store fault or a recovery fence is a typed error, never an empty denial, so clients should treat 5xx as unknown rather than as denied.
- HTTP
Reranking policies
Lets an operator author, version and apply an explicit ranking policy over retrieval candidates instead of baking ranking rules into application code.
Available in previewSurfaces and limits: Reranking policies
A reranking policy is versioned data: weights over lexical, vector, recency and authority signals, boost and bury rules, a per-group diversity cap, hard exclude or require constraints and a feature-cost budget. POST /v1/reranking-policies/rerank applies a stored or inline policy to candidates the caller supplies and returns the final order with a report of which signals were used or skipped and why. The search routes do not apply policies automatically.
- HTTP
POST /v1/reranking-policies, GET /v1/reranking-policies, GET .../{name}, GET .../{name}/versions, POST /v1/reranking-policies/rerank
- The route reranks candidates supplied in the request. The search, vector and hybrid routes do not call it, so applying a policy is a second request from your application.
- Recency, authority, group and flagged values come from the caller; the platform does not derive them.
- Quality evidence is a fixture-based comparison in the engine repository (a policy improves nDCG over base fusion on a constructed case), not a measurement on production data.
- Rules adjust the normalised score by a fixed amount you choose; there is no learned weighting.
- HTTP
Labelled relevance datasets
Keeps the judgements that retrieval quality is measured against as versioned, content-hashed data next to the corpus.
Available in previewSurfaces and limits: Labelled relevance datasets
A relevance dataset holds graded judgements linking a query id to a candidate id, split assignments, provenance on every judgement and adjudication records where assessors disagree. A draft is edited freely; publishing freezes it into an immutable numbered version with a deterministic digest that an evaluation run can pin.
- HTTP
POST /v1/relevance, GET /v1/relevance/{dataset}, POST .../judgements, POST .../import, PUT .../splits, POST .../adjudications, GET .../conflicts, POST .../publish, GET .../versions, GET .../versions/{version}/export
- Provenance is recorded, not verified. The platform stores who or what produced a judgement but cannot attest it.
- There is no judging interface; judgements arrive through the API.
- Published dataset size limits are not documented, and a dataset is stored as one draft entity and one entity per version, so very large judgement sets should be sized before use.
- Read routes accept any authenticated project credential, so treat the judgements as readable by every holder of a project key.
- HTTP
Vector similarity search
Finds the records whose embeddings sit closest to a query embedding, so an application can search by meaning without running a separate vector store.
BetaSurfaces and limits: Vector similarity search
POST /v1/vector takes a query embedding and returns the entities whose stored embeddings have the highest cosine similarity, optionally restricted by kind or a metadata filter. On the stock server this is an exact scan over every stored embedding: recall is perfect and cost grows with the number of vectors. On the Postgres backend with pgvector enabled, the same route is served by a Postgres-side index.
- HTTP
POST /v1/vector { vector, top_k, kind, filter } - CLI
kynetra search '[0.12, 0.31, ...]' --top-k 10 --kind product (remote mode posts to /v1/vector) - SDK
SearchClient.vector in the TypeScript, Python, Go and Rust client sources - MCP
kynetra_vector_search (HTTP /mcp and the stdio kynetra-mcp server) - Config
KYNETRA_STORAGE_BACKEND=postgres, KYNETRA_PG_VECTOR=true, KYNETRA_PG_VECTOR_DIM
- The exact scan costs time proportional to the number of embeddings with the query dimension. No latency figure has been published for this path on the server; measure your own corpus before relying on it at scale.
- No approximate index is built by the server. The HNSW and SPANN indexes are engine-library features today.
- Cosine similarity is the sole metric. There is no per-index schema, so nothing stops two models of the same width from sharing a kind.
- The TypeScript client comments describe this route as approximate nearest-neighbour search. On the stock server it is exact.
- The Postgres vector path needs a Postgres instance with the vector extension, and its one test is gated on an environment variable that points at such an instance, so it is skipped when the variable is unset.
- The route accepts service credentials: the instance key or a project service key. Anonymous project keys and end-user tokens are refused.
- HTTP
Filtered vector search
Restricts a nearest-neighbour search to one tenant, kind or attribute value so that top_k means the top results among the records you are allowed to see.
BetaSurfaces and limits: Filtered vector search
The kind and filter fields of POST /v1/vector and POST /v1/hybrid apply a metadata pre-filter before ranking, so results come from the filtered set and top_k is honoured against it. On the stock server the filter is applied during an exact scan. The engine also contains a selectivity-aware router for filtered queries over an approximate index, which engages when such an index exists and not otherwise.
- HTTP
POST /v1/vector { vector, top_k, kind, filter } - HTTP
POST /v1/hybrid { q, vector, top_k, kind, filter } - SDK
VectorOpts.filter and HybridOpts.filter in the TypeScript client source
- On the stock server the filter runs inside an exact scan, so cost grows with the corpus even for a very selective filter. The selectivity router and its over-fetch rules apply to an approximate index built through the engine library, not to the exact scan.
- On the Postgres vector path a filter is applied after fetching four times k, so a selective filter can return fewer than k hits.
- The published filtered-search artifacts measure the library index on one Linux host that was under background load; absolute latencies there are higher than a quiet capture, and just the back-to-back before-and-after comparison is meaningful.
- The hybrid route does not report how many matches top_k cut off. It signals a clamp solely when the requested top_k was reduced to 200.
- HTTP
Hybrid search with rank fusion
Combines keyword relevance and semantic similarity into one ranked list on the server, so the client does not have to merge two score scales.
BetaSurfaces and limits: Hybrid search with rank fusion
POST /v1/hybrid runs a BM25 query and a vector query over the same corpus and fuses the two ranked lists with weighted reciprocal-rank fusion. Either leg can be omitted. The response keeps each leg score and rank next to the fused score so a ranking can be inspected.
- HTTP
POST /v1/hybrid { q, vector, top_k, candidate_k, kind, filter, bm25_weight, vector_weight, rrf_k } - SDK
SearchClient.hybrid in the TypeScript and Python client sources
- The vector leg is the exact scan unless an approximate index was built through the engine library, so hybrid cost grows with the number of embeddings. No latency figure is published for the fused route.
- Fusion works on ranks and ignores raw scores. There is no learned or per-query weighting; the weights are what the caller sends.
- Reranking policies are a separate capability and are not applied to this route automatically.
- The response does not say how many matches were cut off by top_k.
- The route accepts service credentials: the instance key or a project service key.
- HTTP
Product catalogue, faceted search and cart signals
Gives a storefront product storage, faceted search and an abandoned-cart signal from the same database as the rest of its data.
BetaSurfaces and limits: Product catalogue, faceted search and cart signals
A product model with variants, stock and money in minor units. POST /v1/products stores a product, GET /v1/products/{id} reads it, and POST /v1/products/search combines BM25 text matching, facet filters and an optional embedding rerank into one ranked list. An opt-in background monitor publishes a realtime event for idle carts. Co-purchase recommendations exist in the engine but are not wired; see the product recommendations entry.
- HTTP
POST /v1/products, GET /v1/products/{id}, POST /v1/products/search - Config
KYNETRA_CART_MONITOR, KYNETRA_CART_IDLE_SECS
- Facets are applied after the BM25 pool is taken, so a selective facet can return fewer than limit results even when more products match.
- Text matching is exact-token BM25. A misspelt query does not match; the module comment mentions fuzzy matching, but the code uses the plain search.
- The embedding rerank is an exact cosine over the pool, not an index search, and it reorders the BM25 candidates without adding to them.
- The product routes accept the instance API key. Project keys and end-user tokens are not accepted, and the products are not namespaced per project, so use them in a single-tenant deployment or behind your own backend.
- The abandoned-cart event is emitted again on every scan while a cart stays idle and has no checkout. Consumers should de-duplicate by cart id.
- The monitor reads the unprefixed kinds cart and checkout. Carts written through project-scoped keys are stored under project-prefixed kinds and are not seen.
- No HTTP-level test of the product routes was found in the engine repository; the model, search and monitor are covered by library tests.
- HTTP
Durable streaming retrieval sessions
Lets a producer push retrieval output to a client as it is produced, and lets the client reconnect and resume without losing or repeating events.
BetaSurfaces and limits: Durable streaming retrieval sessions
A retrieval session is a durable, ordered event log with a numeric cursor. Producers append events, clients read them over server-sent events, and a reconnecting client resumes from the last cursor it saw. Events are ordinary database entities, so sessions survive a restart, and retention is bounded by dropping the oldest events.
- HTTP
POST /v1/retrieval/sessions, GET /v1/retrieval/sessions/{id}, GET and POST /v1/retrieval/sessions/{id}/events, POST /v1/retrieval/sessions/{id}/cancel
- Retention is bounded: a consumer that is further behind than the retained window must restart without a cursor.
- Treat the optional session policy as a filter on replay, not as an access control. Decide who may read a session with project credentials and roles.
- Payloads are opaque JSON; the platform does not validate their shape or check them against a search.
- The live tail is an in-process broadcast. Resume after a disconnect relies on the durable log, not on the broadcast.
- HTTP
HNSW approximate vector index
Searches very large embedding sets approximately, so query cost follows the neighbourhood visited instead of the whole corpus.
RoadmapSurfaces and limits: HNSW approximate vector index
The engine contains an incremental HNSW index: a sealed graph plus an exactly searched delta pool, tombstones and background compaction, so a new write is searchable immediately. It has engine tests and published benchmark artifacts. The server does not build or enable it, so a preview user cannot switch it on today; that is why it is listed as roadmap and not as available.
- Library
Engine::enable_vector_index, Engine::build_vector_hnsw and EngineConfig::vector_tier, vector_quant (Rust engine API; not exposed by the server)
- Not reachable through any route, command or setting of the private-preview server.
- The benchmark figures were taken by calling the library in process; they exclude HTTP handling, authentication and serialisation.
- Approximate search degrades to noise when the corpus has no structure to approximate. The uniform-random result above is the published evidence of that.
- Building the index holds the writer freeze for the whole snapshot, build and swap, so writes stall for the duration. The engine documents this as acceptable for a rare administrative operation.
- The graph is rebuilt in the background after a restart rather than loaded from disk.
- Library
SPANN disk-resident vector index
Keeps most of a very large vector index on disk, so resident memory follows a small centroid navigator instead of the corpus.
RoadmapSurfaces and limits: SPANN disk-resident vector index
The engine contains a disk-resident approximate index in the SPANN family: an in-memory navigator over cluster centroids and on-disk postings of compressed codes, with live writes, rebalancing and memory-mapped reads. It has engine tests and one published memory measurement. The server does not build it, so it is a roadmap capability.
- Library
Engine::enable_vector_index with EngineConfig::vector_tier(ForceDisk) or vector_tier_threshold; disk_vector_codec (Rust engine API; not exposed by the server)
- Not reachable through any route, command or setting of the private-preview server.
- Building the index (k-means, encoding, one fsync per posting) holds the writer freeze for the whole build and can take minutes at scale, so writes stall meanwhile.
- The memory measurement covers one small synthetic corpus on one host and attaches no latency claim. Page-cache pressure on a real host will change behaviour.
- Rebalancing runs one bounded round per flush; a pathological insert stream may need several flushes to settle.
- No end-to-end recall or latency artifact exists for the disk tier at the default 2,000,000-vector threshold.
- Library
Vector quantisation (int8, binary, RaBitQ, Caustic)
Shrinks the memory an approximate vector index needs, while exact reranking protects recall.
RoadmapSurfaces and limits: Vector quantisation (int8, binary, RaBitQ, Caustic)
The engine implements four ways to store index payloads in fewer bytes: int8 scalar quantisation, 1-bit sign quantisation, a 1-bit RaBitQ code with an unbiased estimator, and the Caustic sub-bit residual codec used by the disk tier. Each has tests and, for most, a published artifact that includes the trade-off and the misses. None of the modes is selectable on the server, so the capability is roadmap.
- Library
HnswParams.mode = Int8 | Binary | RaBitQ via EngineConfig::vector_quant; SpannParams.codec = RaBitq | Caustic via EngineConfig::disk_vector_codec (Rust engine API; not exposed by the server)
- Not selectable through any route, command or setting of the private-preview server.
- Quantised payloads trade recall for memory. Binary and RaBitQ need exact rerank to be usable, and rerank reads the full-precision embedding.
- The int8 recall miss at 1M vectors is open in the published artifact.
- All published figures are local scope on one Linux host, from a single operator, with no third-party reproduction.
- Caustic results are published in the same artifact as RaBitQ but are not quoted here, because they are not part of the registered evidence set for this site.
- Library
Aggregate queries
Computes counts, sums, averages, minima and maxima over stored entities, so a dashboard needs no export to a separate analytics store.
RoadmapSurfaces and limits: Aggregate queries
The engine has an aggregation function for count, sum, avg, min and max over the entities of one kind. No route, command, KynQL clause or MCP tool calls it, so a running server cannot be asked for a rollup today. It has engine tests and is used by the materialised-view module, which is also unwired.
- Library
Engine::aggregate(AggregateSpec { kind, field, op }) (Rust engine API; not exposed by the server)
- Not reachable through any route, command or query clause of the private-preview server.
- A single scan over all entities of the kind, with a copy held in memory; cost grows with the kind size.
- No grouping, filtering or time bucketing in the function itself.
- A field that mixes numbers and strings returns null for sum and avg.
- Library
Bloom-filter existence index
Answers whether an id definitely does not exist in a kind without touching the stored entities.
RoadmapSurfaces and limits: Bloom-filter existence index
The engine maintains one growable Bloom filter per entity kind on every write and exposes an exists-in-kind check: false means the id is certainly absent, true means it may be present. Nothing in the server, command line or MCP servers calls the check, so it is an engine capability and nothing more.
- Library
Engine::exists_in_kind(kind, id) (Rust engine API; not exposed by the server)
- Not reachable through any route, command or setting of the private-preview server.
- The filter is rebuilt from the log at boot but never compacted while running, so repeated deletes and re-inserts increase false positives.
- False positives are possible by design; false negatives are not.
- Library
Materialised views
Precomputes a grouped count or aggregate, such as products per category, so repeated facet reads do not rescan the data.
RoadmapSurfaces and limits: Materialised views
The engine has a registry of named view definitions, each a kind, a group-by field and an aggregate, that can be refreshed from the current state and read back as buckets. Refresh is an explicit call that rescans the kind. The server never creates the registry or calls refresh, so this is a roadmap capability. The similarly named /v1/views routes are a different feature.
- Library
ViewRegistry::register, refresh and get with ViewDef { name, kind, group_by_field, agg } (Rust engine API; not exposed by the server)
- Not reachable through any route, command or setting of the private-preview server.
- Refresh is manual and rescans the whole kind; there is no incremental maintenance on write.
- One group-by field per view, and the aggregate is computed over that same field.
- The registry is in memory and is not persisted.
- Library
Co-purchase product recommendations
Suggests products that customers buy together, and boosts search results by that signal.
RoadmapSurfaces and limits: Co-purchase product recommendations
The engine has a co-purchase recommender and a search helper that boosts results by co-occurrence with a seed product. No route, command or tool calls either, so a running server cannot be asked for recommendations today.
- Library
Recommender::recommend, Recommender::recommend_for_user and ProductSearch::with_recommendations (Rust engine API; not exposed by the server)
- Not reachable through any route, command or tool of the private-preview server.
- Every call rescans all order entities and builds the pair counts in memory, so cost grows with orders and with items per order; the module suggests pre-building the matrix offline at large scale.
- Orders must use the items array of product id strings; other shapes yield no signal.
- Library
Federated query gateway
Answers one governed query from several certified remote stores while keeping every source bounded and every row authorised.
RoadmapSurfaces and limits: Federated query gateway
The engine contains a federated query gateway library: an operator-supplied certification registry, a planner that pushes down bounded predicates and nothing richer, and an executor that verifies, authorises and merges the results with lineage. The crate states that it is planned and unmounted, and the server does not import it, so no route or command exposes it.
- Library
kynetra_federation::execute with CertificationRegistry and FederatedSource (Rust crate; not mounted by the server)
- Not reachable through any route, command or setting of the private-preview server.
- Certification entries are not cryptographically signed; the registry is trusted operator input.
- The crate records that, before any customer-facing mount, the owner must accept an availability residual: hidden rows can make a scan read a later page on which a source fails or times out.
- No source adapter for a specific external database ships in the crate; sources implement a trait.
- Library
AI & agents
Retrieval evaluation harness
Turns retrieval quality into a reproducible number that a build can gate on.
Available in previewSurfaces and limits: Retrieval evaluation harness
evalharness is a command-line tool and library that runs a scenario against an engine, scores retrieval against a published relevance dataset with recall@k, NDCG@k and MRR, and exits non-zero when a threshold fails. A run pins the dataset digest, the prompt version and the corpus lineage state, so the same scenario run twice gives the same result.
- CLI
evalharness run --scenario eval.json [--out result.json] [--benchmark-out bench.json] - CLI
evalharness compare --baseline base.json --candidate cand.json - CLI
evalharness regression --scenario regression.json
- The harness calls the engine in process, so it measures what the engine returns, not the HTTP layer.
- The local hash embedder is deterministic but not semantic. For a meaningful semantic evaluation, supply query vectors produced by your real model.
- Recall, NDCG and MRR are the implemented metrics.
- The evaluation makes no model call. The prompt pin in a regression run is recorded but does not change retrieval, so on this path the regression command reports a zero delta by construction, and a test asserts it. It becomes a real prompt comparison once an evaluation path calls a model, which none does today.
- Judgements must already exist as a published relevance dataset.
- CLI
Prompt versioning
Gives a prompt a stable identity and an immutable version history, so prompts change the way code does.
Available in previewSurfaces and limits: Prompt versioning
A prompt family holds versions that are appended and never edited. Each version is byte-immutable, links to its parent, carries a content hash, declares its input variables and refers to a model configuration by name. A movable pointer such as production names the live version, and a rollback appends a new version copied from an earlier one.
- HTTP
POST and GET /v1/prompts; POST and GET /v1/prompts/{family}/versions; POST /v1/prompts/{family}/rollback; GET and PUT /v1/prompts/{family}/pointers/{name}
- Prompts are stored and versioned. Agents and the completion route do not resolve pointers; your application fetches the live version and sends it.
- The secret-key guard checks parameter key names, not values. A secret typed into a free-text value or into the prompt content is not detected.
- There is no templating engine. Declared variables are a contract your application honours; the platform does not render them.
- Read routes accept any authenticated project credential, so treat prompt text as readable by every holder of a project key.
- HTTP
Embedding on write
Keeps vectors current without every client having to call an embedding model before each write.
BetaSurfaces and limits: Embedding on write
A collection can list text fields in embed_source. When a record is inserted through the REST plane without an embedding, the server joins those fields, asks an Ollama-compatible embedding endpoint for a vector and stores it as the record embedding, so the vector and hybrid routes work with no client-side embedding step. If the endpoint fails, the record is stored without a vector.
- HTTP
POST /v1/collections with embed_source; POST /rest/v1/{table} - Config
KYNETRA_EMBED_URL, KYNETRA_EMBED_MODEL
- An Ollama-compatible embeddings endpoint is the one supported kind. The vector width is whatever the model returns; it is not checked against anything stored, and the exact scan skips vectors whose width differs from the query.
- Embedding happens on insert and at no other time. Updates through PATCH and writes through the collection record routes do not re-embed.
- Failure is silent to the caller: the write succeeds without a vector and the sole trace is a server log line. Monitor for unembedded records if search depends on them.
- Each inserted row makes its own sequential call to the endpoint, so a large batch insert waits on that endpoint.
- The text of every inserted row is sent to the configured endpoint. Choose a local endpoint if the data must stay inside your network.
- String fields are used; other types named in embed_source are ignored.
- The tests in the engine repository cover the collection setting; no automated test of the insert path was found.
- HTTP
Managed embedding jobs
Embeds or re-embeds existing records in bounded batches, without redoing finished work, so a model change does not mean a hand-written backfill.
BetaSurfaces and limits: Managed embedding jobs
An embedding job selects records of a kind (or the embeddings of an earlier model), embeds them in batches through the configured embedding provider and stores the vectors as managed embeddings. A re-run skips whatever is current, a killed job resumes from its checkpoint, failing records go to a dead-letter list instead of stopping the job, and a re-embed job migrates a population to a new model.
- HTTP
POST /v1/embedding-jobs/jobs, GET /v1/embedding-jobs/jobs, POST /v1/embedding-jobs/jobs/{id}/run, POST .../cancel, GET .../dead-letters, POST /v1/embedding-jobs/reembed, POST and GET /v1/embedding-jobs/quotas - Config
KYNETRA_EMBED_URL, KYNETRA_EMBED_MODEL, KYNETRA_EMBED_DIM
- run is synchronous: the request stays open until the job reaches a terminal state, so long jobs are exposed to client and proxy timeouts. Polling the job record works, but a background run is not offered.
- The provider is an Ollama-compatible embedding endpoint read from the environment. No other provider is wired.
- Token counts and cost are reported as null; the embedding providers do not report usage, and the job does not invent figures.
- The routes accept the instance API key, and the project is a field of the request body rather than bound to the credential.
- Batch concurrency is one; throughput is bounded by sequential provider calls and the optional rate cap.
- Managed embeddings live under model-encoded kinds, separate from the embedding field of the source record. Search them with a kind filter.
- HTTP
Agent runtime with tool-use loop
Runs a bounded, recorded model-and-tools loop against the database, so an operator can delegate routine checks to an agent without handing it raw access.
BetaSurfaces and limits: Agent runtime with tool-use loop
An agent is a name, a system prompt, an allow-list of actions and an optional provider and model. POST /admin/agents/{id}/run sends a task through a loop of model call, tool call and tool result for at most eight turns, and persists the run with its steps, token counts and an estimated cost. Four preset agents are seeded on first boot, and one agent can delegate to another with a depth limit.
- HTTP
POST /admin/agents, GET /admin/agents, POST /admin/agents/{id}/run, POST /admin/agents/{id}/run/stream, GET /admin/agents/{id}/runs, GET /admin/runs
- Every agent route needs an admin role. Agents are an operator facility, not a per-tenant feature.
- The built-in actions are an operator facility. Give an agent just the actions it needs, and do not expose agent runs to untrusted users.
- Multi-turn tool use has been tested with scripted providers. It has not been exercised against hosted providers for this edition, so verify the behaviour with your own provider before relying on it.
- A run has fixed limits: eight turns, 1,024 output tokens per call and a fixed temperature. They are not per-agent settings.
- Usage from the agent loop is not recorded in the model-observability metrics, which cover the /v1/llm route alone.
- Cost figures are estimates; see the scheduler, approvals and cost entry.
- HTTP
Agent scheduling, approvals and run cost
Runs agents on a schedule, holds risky actions for a human decision and records what each run consumed.
BetaSurfaces and limits: Agent scheduling, approvals and run cost
Three operator controls around the agent runtime. A cron scheduler fires stored agent tasks once per minute bucket. An approval gate parks destructive or external actions until an administrator decides, and denies on timeout. Each run records token usage and an estimated cost, with a summary endpoint over a window of days.
- HTTP
POST and GET /admin/agents/schedules, DELETE /admin/agents/schedules/{id} - HTTP
GET /admin/agents/approvals, POST /admin/agents/approvals/{id}/approve, POST /admin/agents/approvals/{id}/reject - HTTP
GET /admin/agents/runs/summary?days=7
- Schedules have minute resolution and use UTC. A minute missed while the server is down is not made up afterwards.
- The approval hold lasts 300 seconds. There is no outbound notification, so an operator must poll the approvals list or watch the admin console.
- Redaction works on key names. A secret typed into a free-text value is stored in the pending approval record.
- Cost is an estimate from a built-in per-token price table at whole-unit resolution, and an unknown model is priced at zero. The dollar field of the summary uses a unit scale that does not match the table and under-reports. Budget from the token totals instead.
- Actions are gated by the effect they declare, and the built-in read actions are not. Choose action allow-lists with that in mind.
- All of these routes need an admin role.
- HTTP
Built-in agent actions
Gives an agent a fixed set of typed, bounded tools instead of raw engine or shell access.
BetaSurfaces and limits: Built-in agent actions
The runtime registers 18 actions: 13 built-in observation and memory tools, 4 cloud-provider actions and one delegation action. Each declares a JSON schema and an effect, and the approval policy is derived from the effect. GET /admin/actions lists every action with its schema, effect and whether approval is required.
- HTTP
GET /admin/actions (name, description, input_schema, effect, requires_approval, risk)
- Treat agents as an operator facility and grant each one just the actions it needs.
- The stats action reports the data log path to the model, and therefore into the stored run.
- The description of rag_over_log says semantic search; it is BM25 keyword search over run text.
- Provider actions depend on credentials registered in the provider vault.
- There is no action that writes records or files. Writes happen through the approval-gated provider actions and nowhere else.
- HTTP
MCP servers (HTTP and stdio)
Lets an MCP-capable assistant query KynetraDB as a tool without a hand-written adapter.
BetaSurfaces and limits: MCP servers (HTTP and stdio)
KynetraDB offers two MCP surfaces. The server mounts a JSON-RPC endpoint at /mcp with eight tools that read instance state and run search. A separate kynetra-mcp binary speaks MCP over stdio against a local data directory, binds every session to a tenant, workspace, actor and purpose, and can write and delete as well as read.
- MCP
POST /mcp and POST /mcp/message (JSON-RPC 2.0, tools/list and tools/call) - MCP
kynetra-mcp [data-dir] over stdio; KYNETRA_MCP_TENANT, KYNETRA_MCP_WORKSPACE, KYNETRA_MCP_ACTOR, KYNETRA_MCP_PURPOSE, KYNETRA_MCP_READONLY, KYNETRA_MCP_ALLOW_SENSITIVE
- The HTTP endpoint is an operator facility; grant access to it only to operators. Prefer the stdio server when an assistant must be bound to a single tenant.
- GET /mcp/sse opens an event stream that carries no messages. Use POST /mcp for requests.
- The stdio server runs its own engine on a data directory and does not call a running server. Give it a data directory meant for it.
- The stdio search tools fetch four times the limit and filter by scope afterwards, so a query dominated by other scopes can return fewer than the limit.
- The vector tools describe themselves as approximate nearest-neighbour search. On the stock server they run the exact scan.
- The tools capability is the one implemented: no MCP resources, prompts or sampling.
- MCP
LLM provider layer
Puts local and hosted language models behind one completion interface with ordered fallback and token accounting.
BetaSurfaces and limits: LLM provider layer
POST /v1/llm/complete sends a chat request to a named provider, or to the first provider in the fallback chain that answers. Three backends are built in: a local Ollama server, the Anthropic Messages API and any OpenAI-compatible chat endpoint. The response carries the provider, model, stop reason and, when the provider reports it, token usage. GET /v1/llm/providers lists what is configured.
- HTTP
POST /v1/llm/complete, GET /v1/llm/providers, GET /v1/llm/observability - Config
OLLAMA_BASE_URL, OLLAMA_MODEL, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL
- The route needs a platform credential with the editor role. Project keys and end-user tokens are refused.
- The adapters talk to the providers over plain HTTP clients with their default settings. There is no per-request timeout, retry with backoff or circuit breaker inside the provider layer; the fallback chain is a simple ordered try.
- The local Ollama provider is always first when the registry is built from the environment, so an unreachable local server costs an attempt before a hosted provider is tried. Name a provider to skip the chain.
- Tool use is supported by the adapters, but the completion route sends no tools. Tool loops are the agent runtime, whose multi-turn behaviour has been tested with scripted providers and with nothing else.
- Provider errors are returned to the caller as bad-request responses, including the provider text.
- The tests in the engine repository use scripted providers; no automated test calls a live hosted provider.
- HTTP
Agent memory (episodes, facts, graph, procedures)
Gives agents durable memory of what happened, what is known and what worked, retrievable by keyword, by meaning and by relationship.
BetaSurfaces and limits: Agent memory (episodes, facts, graph, procedures)
The memory API stores episodes, facts, graph edges and procedures as ordinary entities in the same log as everything else, and answers recall requests by fusing BM25, vector and graph-hop results. A consolidation run can ask a language model to turn earlier agent runs into facts and procedures. Each recall issues a verifiable receipt.
- HTTP
POST /v1/memory/episodes, /facts, /edges, /procedures, /recall, /consolidate; GET /v1/memory/procedures/{name}, GET /v1/memory/stats - Config
KYNETRA_EMBED_URL, KYNETRA_EMBED_MODEL
- By default a recall is refused with a freshness conflict, because the freshness gate requires the embedding index to be marked fresh and nothing in the stock server marks it. Send allow_stale: true; the response then reports the observed freshness state honestly, which is unknown.
- The memory API is an operator facility in this release and is not yet project-scoped: all memory shares one namespace per deployment. Grant access to it only to operators.
- A write or recall is refused while a vector reindex is in flight for the memory index. No route starts a reindex, so this fence is exercised by tests.
- The vector arm needs an Ollama-compatible embedding endpoint; without one, recall uses BM25 and the graph alone.
- Consolidation quality is whatever the configured model returns. There is no automated evaluation of extracted facts.
- Graph traversal builds an adjacency view of the edges in memory and refreshes it when the log advances; very large graphs will cost memory.
- HTTP
Governed memory assets
Keeps reusable agent knowledge, such as skills, wikis and chat memory, under ownership, access control, versioning and review.
BetaSurfaces and limits: Governed memory assets
The asset registry stores four kinds of memory asset: chat memory, skills, wikis and code graphs. Each is owned by a user in a project, has immutable versions that reference content by address and digest, is shared through visibility and explicit grants, and moves from draft through review to published. Every change writes to a bounded audit trail. The registry stores references and governance, not the content itself.
- HTTP
POST and GET /v1/memory/assets; GET, PATCH and DELETE /v1/memory/assets/{id}; POST and GET .../versions; POST .../publish; POST .../adopt; POST and GET .../grants; DELETE .../grants/{grant_id}
- The registry holds references and digests. The bytes behind content_ref live wherever you put them, and the registry does not fetch or verify them.
- Agents do not consume these assets today. Agent bindings and agent visibility exist in the store, but the HTTP routes reject them until verified agent credentials are available.
- The team boundary is the project organisation; finer teams are not modelled.
- The audit ring keeps the latest 1,000 entries per project, so older entries fall off.
- Listing is paged with a cursor and bounded work per page.
- HTTP
Recall receipts
Gives each retrieval a tamper-evident record of what was returned and under which index state, so an audit can verify it later without the raw query.
BetaSurfaces and limits: Recall receipts
Every successful memory recall issues and stores a receipt: an HMAC-SHA256 digest that binds the project, the principal, a salted and keyed digest of the query (never the query text), the retrieval configuration, the freshness watermark and the ordered result ids and scores. Two admin routes verify a receipt by digest and export a project receipts for offline verification.
- HTTP
POST /admin/v1/rag-receipt/verify { digest, project }; GET /admin/v1/rag-receipt/export?project=&from_ms=&to_ms= - Config
KYNETRA_RAG_RECEIPT_HMAC_KEY
- Receipts are issued by memory recall and by nothing else. The search, vector, hybrid and KynQL routes do not issue them.
- The receipt key follows the audit key unless you set the override. Rotating the audit key does not rotate the receipt key, and receipt key rotation is not wired.
- A per-result source sequence is not bound into the receipt.
- Receipts are kept until an explicit purge; no retention policy runs.
- Both routes need an admin role and default to the shared memory project.
- HTTP
Model usage observability
Shows what language-model calls cost and how they behave, by project, action, provider, model and run, without storing prompts or answers.
BetaSurfaces and limits: Model usage observability
Every completion made through POST /v1/llm/complete is recorded as metadata: who called, which action label, which provider and model, tokens when the provider reported them, latency, retries, fallback and error class. GET /v1/llm/observability returns a tenant view and GET /admin/db/model-metrics returns the fleet view, grouped by model, action, provider, project or run.
- HTTP
GET /v1/llm/observability?by=model|action|provider|project|run - HTTP
GET /admin/db/model-metrics?by=...&project=
- The /v1/llm/complete call site is the one instrumented. Completions made inside the agent loop, streaming runs, memory consolidation and evaluation runs are not recorded, so these metrics cover HTTP-originated calls.
- History is held in memory, is bounded, and starts empty after a restart.
- Cost is an estimate from a built-in price table; use token totals for budgeting.
- The tenant route needs a platform credential with the editor role, and the fleet route an admin role.
- HTTP
Model routing policies
Replaces an implicit provider order with an explicit, versioned decision about which model to call and why.
BetaSurfaces and limits: Model routing policies
A routing policy is versioned data: a catalogue of models with their context window, cost, capabilities and privacy tags, task routes with an author preference order, an allow-list and a deny-list, health thresholds and a circuit-breaker setting. POST /v1/model-routing/decide takes a request and returns a winner, an ordered fallback chain and an explanation, or an explicit denial. The caller then executes the call itself.
- HTTP
POST and GET /v1/model-routing; GET /v1/model-routing/{name}/versions; POST /v1/model-routing/decide; POST /v1/model-routing/outcome
- Routing decides; it does not call the model. Your application sends the request to the chosen provider and reports the outcome.
- Health is built from model observability, which covers /v1/llm/complete calls alone, so it is a partial picture.
- Circuit-breaker state is held in memory per project and model, and every breaker reads closed after a restart.
- Model cost and context figures in the catalogue are authored by the policy writer, not looked up live.
- Publishing needs an admin or service credential. Decide and outcome are open to any authenticated caller for their own project policies.
- HTTP
Model incident response
Gives operators a governed workflow to detect a failing model, apply a bounded and reversible mitigation, and undo it on resolution.
BetaSurfaces and limits: Model incident response
An incident moves through detected, acknowledged, mitigating and resolved or closed. It can be opened by hand or from an error-rate spike seen in model observability. Mitigations come from a closed set (open a model circuit breaker, add the model to the policy deny-list, or advise exclusion), impactful ones need an explicit approval, and resolving the incident lifts every override it applied.
- HTTP
POST and GET /v1/model-incident-response; GET .../{id}; POST .../{id}/acknowledge, /mitigations, /mitigations/{mid}/approve, /mitigations/{mid}/deny, /resolve
- Automatic detection reads model observability, which covers /v1/llm/complete calls alone. A failure spike inside agent runs is not seen, though an incident can always be opened by hand.
- The default notifier writes to the server log. There is no email, pager or webhook adapter.
- Circuit-breaker overrides live in memory and are re-driven after a restart from the stored incident, so a mitigation lasts as long as its open incident.
- All routes need an admin or service credential.
- HTTP
Agent evaluation suites
Checks that an agent definition, its tool allow-list and its approval behaviour still work, as a gate in a build.
BetaSurfaces and limits: Agent evaluation suites
agentevals runs a versioned suite of agent tasks against a deterministic scripted model in a throwaway engine, scores task outcomes and tool-permission violations, and exits non-zero when a promotion threshold fails. It tests the harness around an agent: allow-lists, approvals, assertions and traces. It does not evaluate a real model.
- CLI
agentevals run <scenario.json> [out.json]
- Scripts replace the model, so a suite shows how your allow-lists, approvals and assertions behave, not how a real model behaves.
- Tools are deterministic stand-ins. A suite does not exercise your real tools or data.
- The engine is ephemeral: suites and runs live for one invocation.
- There is no HTTP route; the command line is the surface.
- CLI
Durable, resumable agent runs
Lets a long multi-step agent run survive a restart and resume where it stopped, without repeating side effects.
RoadmapSurfaces and limits: Durable, resumable agent runs
The engine contains a durable run store: a persisted state machine that executes an ordered plan of tool steps and writes a checkpoint after each one. It sits beside the in-memory agent loop. No route or command mounts it, so it is a roadmap capability.
- Library
DurableRunStore (Rust crate kynetra-agents; not mounted by the server)
- Not reachable through any route, command or setting of the private-preview server.
- Exactly-once effects depend on the tool honouring the idempotency key it is given.
- Library
Event-driven agents
Starts an agent run because a durable data event arrived, not because a clock ticked.
RoadmapSurfaces and limits: Event-driven agents
The engine contains an event dispatcher: subscriptions on durable outbox partitions that match events by filter and start a durable agent run for each match, with loop prevention and quotas. It is separate from the cron scheduler. No route or command mounts it, so it is a roadmap capability.
- Library
EventDispatcher and Subscription (Rust crate kynetra-agents; not mounted by the server)
- Not reachable through any route, command or setting of the private-preview server.
- It drives durable runs, which are themselves unmounted.
- Delivery is at least once; handlers and tools should tolerate a repeat.
- Library
Live human and agent handoff
Transfers control of a running agent task between the agent and a person, with exactly one party in control at a time.
RoadmapSurfaces and limits: Live human and agent handoff
The engine contains a handoff store: a durable session that hands a durable run to a human with a bounded, redacted context snapshot, an audited transition log and reconnect from a cursor. Every ownership change is an atomic compare-and-swap. No route or command mounts it, so it is a roadmap capability.
- Library
HandoffStore (Rust crate kynetra-agents; not mounted by the server)
- Not reachable through any route, command or setting of the private-preview server.
- Redaction works on key names, so a secret in a free-text value is not removed from a snapshot.
- It depends on durable runs, which are themselves unmounted.
- Library
Vector schemas and embedding freshness
Refuses to mix incompatible embeddings in one index and refuses to serve vectors that are older than the data they describe.
RoadmapSurfaces and limits: Vector schemas and embedding freshness
Two registries are implemented: a model-aware vector schema per index (dimension, metric, embedding family, normalisation, tokenizer, version) with a controlled reindex state machine, and an embedding freshness watermark per project and model that reports fresh, stale or unknown. Memory recall consults both. No route declares a schema or advances a watermark, so users cannot configure them yet.
- Library
VectorSchemaRegistry and FreshnessRegistry (Rust crate kynetra-server; exercised through /v1/memory/recall)
- Not configurable through any route, command or setting of the private-preview server.
- The registries are enforced for the memory kinds and for nothing else. The generic vector routes do not consult them.
- Reindex completion is a declaration by the caller; it is not tied to the embedding jobs capability.
- Library
Data model & realtime
Universal Log
Gives every write one durable, checksummed home, so a crash or a damaged disk block is detected and handled instead of silently corrupting the database.
Available in previewSurfaces and limits: Universal Log
Every write to KynetraDB is appended to a single log made of checksummed segment files. The key-value, document, search and vector views are in-memory state rebuilt from that log, so recovery after a crash is a replay of the log rather than a repair of many files. Damage in the newest segment is treated as a torn write and cut back; damage in an older, sealed segment stops the engine from opening.
- Config
KYNETRA_DATA (data directory that holds the log) - Config
KYNETRA_COMPRESS_WRITES_OVER_BYTES (compression threshold, 4096 by default) - CLI
kynetra replay --from-seq <n> [--to-seq <m>] [--into stdout|engine|filter]
- The log is written by appending. A delete appends a tombstone, and earlier versions of a record stay in retained segments, in replicas and in restore backups.
- In the default in-memory entity profile the server never trims the log, because the log is the sole durable copy of history. Disk use grows with write history.
- At-rest encryption of log segments is implemented in the engine library but is not switched on by the server; see the encrypted log entry.
- The server can place the log on local files or in PostgreSQL. Other locations are described in the storage backend entries.
- Config
Conditional and optimistic transactions
Lets an application change several records atomically and conditionally, such as taking one unit of stock if stock remains, and retry safely without applying a change twice.
Available in previewSurfaces and limits: Conditional and optimistic transactions
POST /v1/transactions commits a list of puts and deletes as one atomic log record, provided the stated conditions hold when the writer reaches it. A client-supplied idempotency key makes a retry return the original outcome instead of repeating the change. Inside the engine, read-set validation gives interactive transactions snapshot isolation with first-committer-wins.
- HTTP
POST /v1/transactions - Library
Engine::transact, Engine::begin (optimistic transaction), Engine::transaction_receipt
- The route is a service-level surface. It needs a project service key or an operator key, not an end-user token, because it does not apply collection rules or row-level policies.
- The HTTP body supports the conditions exists, missing and attr_eq. Whole-attribute and whole-entity conditions exist in the engine library and not in the HTTP body.
- Interactive read-set transactions are an engine-library API. There is no multi-request interactive transaction over HTTP.
- Records of system kinds and reserved ids cannot be written through this route.
- The receipt has no commit timestamp today.
- HTTP
Typed collections and schema
Gives records a declared shape, with validation and unique constraints that hold under concurrent writers, without a separate schema migration tool.
Available in previewSurfaces and limits: Typed collections and schema
A collection is a named set of typed fields. Its definition is stored in the same log as its records, so the schema survives restarts and travels with backups. Records are validated against it on every write, and unique constraints are enforced by the writer rather than by a pre-check.
- HTTP
GET, POST /v1/collections; GET, DELETE /v1/collections/{name} - HTTP
GET, POST /v1/collections/{name}/indexes; DELETE /v1/collections/{name}/indexes/{index} - HTTP
GET, POST /v1/collections/{name}/records; GET, PATCH, DELETE /v1/collections/{name}/records/{id} - HTTP
GET /admin/collections/export, POST /admin/collections/import
- A collection can carry a declared data contract, but contracts are not enforced at any boundary yet; see the data contracts entry.
- There is no in-place migration tool for existing records: replacing a collection definition does not rewrite stored records. The online schema evolution engine is library code that the server does not wire.
- Unique constraints skip null values, and compound unique indexes skip a record when any member field is null.
- HTTP
Versioned typed views
Lets a team change the shape that clients see over a collection without breaking older clients, with a preview, which writes nothing, of what a change would affect.
Available in previewSurfaces and limits: Versioned typed views
A view is a named, versioned projection over one collection: typed fields, renames, hidden fields and relation references. Each change that is compatible appends a new immutable version; a breaking change is refused with a stable error code. Views refuse writes unless they opt in, and they never bypass the source collection's access rules.
- HTTP
GET, POST /v1/views; GET, DELETE /v1/views/{name}; GET /v1/views/{name}/versions - HTTP
POST /v1/views/{name}/migration-preview - HTTP
GET, POST /v1/views/{name}/records; GET /v1/views/{name}/records/{id}
- A view has one source collection; relation fields project as references to other records.
- Views are not materialised. Each read projects the source records at read time.
- The compatibility check classifies shape changes. It does not migrate stored data.
- HTTP
Realtime subscriptions
Lets a client receive record changes as they happen instead of polling, with row-level access rules applied to each subscriber.
BetaSurfaces and limits: Realtime subscriptions
A WebSocket endpoint accepts a Phoenix-shaped join, leave, broadcast and presence protocol. Joined channels receive INSERT, UPDATE and DELETE events for collection records, filtered per subscriber by the collection's row-level policy. A separate server-sent-events stream gives operators a feed of every change. Delivery is live and in-process, with no replay.
- HTTP
GET /realtime/v1?token=<token> (WebSocket upgrade) - HTTP
GET /v1/realtime?topics=entities,files&kinds=<kind> (server-sent events, operator credentials) - HTTP
GET /v1/changes?since=<seq> (change feed, operator credentials)
- Delivery is live, with no catch-up. The bus is in memory with no replay or resume: a client that disconnects or lags misses events and should re-read after reconnecting.
- Broadcast and presence channels are namespaced by channel name alone, so choose channel names that are unique to your project; the postgres_changes feed is separately scoped to the project.
- The WebSocket token travels in the URL query string. Treat WebSocket URLs as sensitive in logs and proxies.
- postgres_changes covers collection records. Events for other entity kinds, files and agents are not delivered through that feed, and the filter supports column=eq.value comparisons alone.
- On a read replica, realtime connections from project credentials are refused. Connect to the primary.
- The server-sent-events stream has no dedicated test in the engine repository.
- HTTP
File storage
Stores uploaded files next to the data that refers to them, with metadata in the same log, without running a separate file service.
BetaSurfaces and limits: File storage
File bytes go to a local directory or an S3-compatible bucket; the metadata (name, type, size, SHA-256, backend key) is an entity in the log. A Supabase-style storage API adds buckets, per-bucket policies, public URLs and signed URLs, all scoped to the calling project.
- HTTP
POST, GET /storage/v1/bucket; GET, DELETE /storage/v1/bucket/{name} - HTTP
POST, GET, DELETE /storage/v1/object/{bucket}/{path}; POST /storage/v1/object/sign/{bucket}/{path} - HTTP
GET /storage/v1/object/public/{project}/{bucket}/{path}; GET /storage/v1/object/signed/{project}/{bucket}/{path} - HTTP
POST, GET /v1/files; GET, DELETE /v1/files/{id} (operator credentials) - Config
KYNETRA_FILE_BACKEND=local|s3, KYNETRA_FILE_DIR, KYNETRA_S3_*
- File bytes are not in the log. Database backups, log rewind and replication carry the metadata but not the file bytes; a restore that asks for file objects is refused rather than silently partial.
- The S3-compatible backend has no test against a live endpoint in the engine repository; its upload path is covered by signing and URL tests and by fakes.
- Uploads are buffered whole in memory and limited to 64 MiB per request. There is no resumable or multipart upload.
- Image transformation parameters are accepted and ignored; objects come back unchanged.
- A failure between writing the object and recording its metadata can leave an unreferenced object in the backend.
- HTTP
Transactional outbox
Records a domain event in the same atomic commit as the data change that caused it, so an event is never lost or announced for a change that did not happen.
BetaSurfaces and limits: Transactional outbox
A /v1/transactions request can include an emit_event mutation. The event is appended to a durable, ordered outbox partition in the same log record as the request's other writes. Consumers read it later at least once, with offsets, bounded retry and a dead-letter record. The consume side is used by the server's own subsystems; there is no public consume endpoint.
- HTTP
POST /v1/transactions with a mutation {"op":"emit_event","outbox_id","aggregate","event_type","payload","expected_version"} - Library
OutboxStore: append, stage_append, create_consumer, next, report, ack, replay, dead_letters, audit_trail
- Emission is available over HTTP. The consume side (offsets, retry, dead letters, replay) is a library API that the server's agent, approval and run subsystems use; there is no public HTTP endpoint to consume events.
- Retention bounds the event log and nothing else. Idempotency receipts and the audit trail are not pruned, so a workload that uses a fresh idempotency key on every append grows receipt storage without a cap.
- Ordering is defined within an aggregate. Across aggregates the sequence reflects commit order, not a domain relationship.
- Delivery is at least once. Consumers must be idempotent.
- The emit_event mutation is not described in the generated OpenAPI document.
- HTTP
Pulse job queue
Hands out units of work to workers with leases that are fenced against stale holders, so a crashed or slow worker cannot complete a job it no longer owns.
BetaSurfaces and limits: Pulse job queue
Pulse is a durable job queue built on the engine's transactions. Every state change is one atomic commit, claims carry a generation that fences older holders, and retries back off before dead-lettering. Over HTTP it serves the Pipelines control plane's own queue; the general queue is a library API.
- HTTP
POST /v1/pipelinecp/queue:claim_next, /queue/items/{id}:complete, /queue/items/{id}:release, /queue:requeue_expired, /queue:enqueue - HTTP
GET /v1/pipelinecp/queue/health - Library
ScopedQueue, QueuePlanner (kynetra-pulsequeue)
- The HTTP surface exposes a single system queue with fixed job types, for the Pipelines control plane. There is no public API to create arbitrary queues; the general scoped queue is a library API.
- Delivery is at least once, never exactly once.
- The crate authenticates nobody. The server authenticates callers and supplies the project and principal.
- A claim can return a continuation instead of work when the scan budget or the retry bound is reached; callers poll again.
- HTTP
Pipelines control plane
Stores the state of pipeline runs and jobs, and the operations that move them, with retries that replay the original answer instead of repeating a change.
BetaSurfaces and limits: Pipelines control plane
The control plane is a set of HTTP operations over the engine for repositories, runs, jobs, leases, approvals and reporting. Each mutating operation records an immutable outcome row in the same transaction as its effects, so a retry replays the original ids and decisions. It is served at /v1/pipelinecp to controller credentials.
- HTTP
GET /v1/pipelinecp/capabilities - HTTP
POST /v1/pipelinecp/repositories:ensure, /runs:intake, /runs/{id}:finish, /runs/{id}:cancel - HTTP
POST /v1/pipelinecp/jobs/{id}:admit, :skip, :terminate, :approve, :retry; /jobs/{id}/leases:begin, /leases/{generation}:heartbeat, :complete, :expire - HTTP
POST /v1/pipelinecp/migration:begin, :import, :validate, :activate; GET /v1/pipelinecp/migration
- The controller principal alone can call it. The tenant principal class exists in the control plane, but no existing credential maps to it yet, so tenant-scoped callers are refused today.
- Delivery is at least once. Nothing here claims exactly-once execution of external work.
- The control plane stores and orders state. The work itself runs in workers outside the database.
- The expired-lease listing is a bounded scan and reports a partial result when it hits its bound. An intake above the engine envelope is refused with a 413 rather than staged.
- A replica refuses control-plane mutations instead of forwarding them.
- HTTP
Connector fabric
Pulls data from other databases and services into a KynetraDB project through one governed contract, with credentials sealed on the server and repeat pulls that converge instead of duplicating.
BetaSurfaces and limits: Connector fabric
The connector fabric, called Estuary in the engine, runs inlets that read from external sources and write into a project's namespace through a tenant-scoped sink. Credentials are sealed server-side and referenced by handle. Fourteen built-in inlets are registered; two declare change-data-capture and the rest do full pulls.
- HTTP
GET /v1/estuary/inlets; POST /v1/estuary/credentials; POST /v1/estuary/soundings - HTTP
POST /v1/estuary/pulls; GET /v1/estuary/pulls/{id}; POST /v1/estuary/pulls/{id}/cancel - CLI
kynetra --remote <url> ingest sources | connection add --tenant --id --source --credentials-stdin | inspect | run | status | cancel - Config
KYNETRA_ROOT_KEY (enables credential sealing and the routes)
- The PostgreSQL source connection does not use TLS yet. Run the server inside a private network with the source, or reach the source through an SSH tunnel.
- The conformance tests for the PostgreSQL and MongoDB change-data-capture paths need live servers and are opt-in, so they do not run by default.
- A pull runs inside the server process. A large pull competes with the engine for CPU, with no isolation between them.
- The destination is always the project that owns the connection. There is no arbitrary source-to-destination ELT, and the conversion routes plan without executing.
- Project identities that cannot write are refused entirely.
- HTTP
Knowledge ingestion pipeline
Turns documents from a connected source into deduplicated, chunked, embedded and indexed records, with a resumable job and a recorded lineage for each chunk.
BetaSurfaces and limits: Knowledge ingestion pipeline
The ingestion pipeline sits on top of the connector fabric. A pipeline names a source, a sealed credential and a chunking policy; a job runs it through fetch, normalise, identity, deduplicate, chunk, redact, embed and index, and records lineage. Jobs persist their checkpoint, retry within a bound and dead-letter.
- HTTP
POST, GET /v1/ingestion/pipelines; GET /v1/ingestion/pipelines/{id} - HTTP
POST /v1/ingestion/jobs; GET /v1/ingestion/jobs/{id}; POST /v1/ingestion/jobs/{id}/run; POST /v1/ingestion/jobs/{id}/cancel - Config
KYNETRA_ROOT_KEY (enables the routes); embedding provider settings read from the environment
- Running a job is synchronous: the request stays open until the job reaches a terminal state, so a large source holds the connection.
- The routes are switched off without KYNETRA_ROOT_KEY, because a pipeline cannot reach its source without the credential vault.
- Embeddings come from an Ollama-compatible provider configured in the environment.
- The default redaction hook passes content through. A deployment that needs redaction must supply a policy.
- Sources are the connector fabric's inlets, with the limits listed on that entry.
- HTTP
Per-project export
Lets an organisation administrator take one project's data out as a single integrity-hashed file that states exactly what it omits.
BetaSurfaces and limits: Per-project export
GET /admin/v1/projects/{id}/export returns the project's namespace as newline-delimited JSON read from a pinned snapshot, with a header manifest that declares what was left out and a trailer that holds a SHA-256 over the content. Authentication material is stripped. A project that holds state which cannot be rebuilt reports the export as incomplete.
- HTTP
GET /admin/v1/projects/{id}/export (platform-plane credential) - HTTP
Response headers x-kynetra-export-format-version, x-kynetra-export-complete, x-kynetra-export-incomplete-reasons - CLI
kynetra-migrate --to engine --data-dir <dir> --project-id <id> ndjson <file> [--expect-pid <id>] [--require-complete]
- A project with metered usage, PII classification state or an asset-registry audit ring reports itself incomplete today, because those classes are not exported and cannot be rebuilt from what is. Read the omitted list before relying on an export as a backup.
- The hash is a checksum and not a signature. It detects corruption, splicing and relabelling under trusted custody of the file, and it does not show who produced the file. A signed export is a recorded follow-up and is not implemented.
- The body is built in memory and capped at 1 GiB; a larger project gets a 413. True streaming export is not built.
- An export does not include file object bytes, which are outside the log.
- Restore applies ordinary collection rows incrementally. A failed or refused import after the first write leaves the rows it applied, so restore into an isolated target when that matters.
- HTTP
Executable data contracts
Would make a collection's owner, compatibility mode, quality and privacy rules enforceable at the boundaries where data is written and changed.
RoadmapSurfaces and limits: Executable data contracts
The schema crate contains a contract model and suites: a deterministic change classifier, a producer-side record validator, a consumer-side compatibility check and a combined gate. None of it is called from a route or a writer path yet, so a contract can be stored on a collection but is not enforced anywhere.
- Library
kynetra_schema::contract: check_change, validate_record, validate_batch, check_consumer, contract_ci_gate (engine library, not wired to the server)
- Not enforced. A collection can carry a contract field, but no route, writer path, export or query path evaluates it.
- No HTTP or command-line interface reads or writes contracts.
- Library
Online schema evolution
Would change a live collection's definition through staged backfill, validation and promotion, with rollback from any stage.
RoadmapSurfaces and limits: Online schema evolution
The evolve crate holds a persisted migration state machine over the schema service: begin, backfill, validate, promote, or roll back. It refuses breaking changes up front and never promotes a definition that failed validation. The server does not use it, so schema changes today replace the definition directly.
- Library
kynetra_evolve: MigrationMachine, begin_online_migration, SchemaMigrationLedger (engine library, not wired to the server)
- Not reachable from the server or the command line. Replacing a collection definition does not rewrite stored records.
- Backfill functions are supplied by the embedding application as code.
- Library
Bidirectional sync with declared conflict policies
Would let two writable systems exchange changes with an explicit, per-collection rule for what happens when both changed the same record.
RoadmapSurfaces and limits: Bidirectional sync with declared conflict policies
The sync crate defines a versioned mutation model, a hybrid logical clock, per-collection conflict policies and an anti-entropy batch format, and proves convergence in a seeded simulator. No route or command uses it, so no user can run a sync today.
- Library
kynetra_sync: Replica, ConflictPolicy, DeleteSemantics, Batch, SyncEngineAdapter (engine library, not wired to the server)
- Not reachable from the server or the command line, and no transport exists for exchanging batches.
- Convergence is shown in a simulator and in two-engine tests, not over a network.
- Library
Bulk NDJSON load and export
Would move large datasets in and out as streamed, checksummed chunks that can resume, with malformed records quarantined instead of failing the run.
RoadmapSurfaces and limits: Bulk NDJSON load and export
The bulk crate implements streamed NDJSON export with a manifest and an order-independent dataset digest, and chunked import with resume and quarantine. It is a library, and no route or command calls it.
- Library
kynetra_bulk: export_records, export_chunks, import_chunks, DatasetDigest (engine library, not wired to the server)
- Not reachable from the server or the command line.
- The crate states that a terabyte-scale run is external evidence: the harness is parameterised by scale, and the local run used the largest fixture the disk allowed. Nothing here asserts terabyte behaviour.
- CSV is a non-streaming conversion helper outside the streaming path.
- Library
Transaction history checker
Checks recorded concurrent transaction histories for isolation anomalies, so claims about transaction isolation rest on evidence and not on argument.
ResearchSurfaces and limits: Transaction history checker
histcheck is an Elle-style offline checker. Given a recording of concurrent transactions, it builds a dependency graph, finds cycles, classifies them against the standard anomaly taxonomy and gives a verdict for read committed, snapshot isolation, serializable and strict serializable. The engine's tests use it; it is not part of the server.
- Library
histcheck::classify::check, ConsistencyModel (used by engine tests; not part of the server)
- A prototype for evidence-gathering, built independently from the published definitions. It is not a product feature.
- It judges the histories it is given. It does not prove properties of unrecorded executions.
- Library
Durability & recovery
Group commit and write durability
Lets an application choose whether a write is acknowledged after it is on stable storage, while concurrent writers share the cost of each flush.
Available in previewSurfaces and limits: Group commit and write durability
Writes from many clients are queued to one writer, folded into batches and flushed once per batch. In the default strict mode a caller is answered after the flush, so an acknowledged write has reached stable storage. One server setting turns flushing off for workloads that accept losing recent writes in a crash.
- Config
KYNETRA_SYNC=true|false (strict acknowledgement, or no explicit flush) - Library
EngineConfig durability: Strict | IntervalMs(n) | None, and wal_sync_mode (engine library, not wired to the server)
- With KYNETRA_SYNC set to false, a crash can lose acknowledged writes.
- Interval durability and the flush-primitive setting exist in the engine library but cannot be configured through the server.
- The published throughput figure used fsync(2) on macOS. The server uses a stronger default flush on macOS, which the same artifact shows is slower, and no figure for Linux hosts has been published.
- One writer thread serialises all writes on an instance, so write throughput on one instance is bounded by that thread.
- Config
Checkpoints and fast restart
Keeps restart time proportional to recent activity instead of the whole write history, without giving up the log as the source of truth.
Available in previewSurfaces and limits: Checkpoints and fast restart
The engine periodically writes a checkpoint of its in-memory state: a full base file plus small delta files that hold just what changed. On start-up it loads the checkpoint chain and replays the log above it. A damaged checkpoint is never trusted; the engine falls back to the log.
- HTTP
GET /admin/checkpoint (posture), POST /admin/checkpoint (force one) - Config
KYNETRA_CHECKPOINT_EVERY (writes between checkpoints, 10000 by default)
- Checkpoints do not shorten or remove the log. Log files stay on disk.
- The server holds entity values in memory. Capacity on one host is bounded by RAM, and restart time includes loading that state.
- The columnar checkpoint format and the disk-resident entity profile exist in the engine library but are not selectable in the server.
- HTTP
Portable backup bundles
Moves one project's data between compatible environments as a signed, checksummed file set that a third party can verify before trusting it.
Available in previewSurfaces and limits: Portable backup bundles
kynetra backup create seals one project into a bundle directory with a manifest and a records file. The manifest carries per-record checksums and an optional HMAC signature, and the records can be encrypted with AES-256-GCM. Verify proves a bundle is intact before restore, and push and pull move a verified bundle to and from an S3-compatible object store.
- CLI
kynetra backup create --project <id> --out <dir> [--sign-key-id --sign-key-hex] [--enc-key-id --enc-key-hex] - CLI
kynetra backup verify --bundle <dir>; kynetra backup restore --bundle <dir> --project <id> - CLI
kynetra backup push --bundle <dir> --prefix <p>; kynetra backup pull --prefix <p> --bundle-id <id> --out <dir>
- A bundle holds one project, not a whole instance, and file object bytes are not included. A restore reports what was excluded.
- Keys are supplied as command-line values of 64 hex characters. Pass them from a secrets manager through your shell rather than typing them into shared terminals.
- These commands operate on a local data directory. Run them against a stopped server or a copy of the data directory.
- The commands are operator-driven, one bundle at a time. Scheduling and point-in-time restore are the backup chain entry.
- An unsigned bundle is checked for integrity but not for authenticity. Sign bundles that cross a trust boundary.
- The object-store transport is tested against an in-memory fake backend in the engine repository, not against a live provider.
- CLI
Log rewind, undo and the recovery fence
Lets an administrator rewind a database to an earlier log position and undo that rewind, and makes the engine refuse to serve if a rewind fails part-way.
Available in previewSurfaces and limits: Log rewind, undo and the recovery fence
Administrator routes rewind the log to a chosen sequence number, keep a backup of what was dropped so the rewind can be undone, and wipe everything on explicit confirmation. Each destructive step writes a durable intent first. If a step fails, panics or is killed, the engine answers 503 recovery_uncertain instead of serving state that may not match the log.
- HTTP
POST /admin/db/restore; GET /admin/db/restore-backups; POST /admin/db/restore-undo - HTTP
POST /admin/db/delete-all; GET /admin/db/time-travel
- A rewind is destructive: records at or above the target are dropped. Take a backup first, and keep the restore backup until you are sure.
- Resolving an unresolved recovery intent is a manual operator action on the data directory followed by a restart. There is no command for it yet.
- File object bytes are outside the log and are not rewound.
- For library callers, the older read methods keep their signatures and still return none, empty or zero while the engine refuses; callers that must tell absence from failure use the fallible read methods.
- The time window reported by time-travel is estimated from entity timestamps and is approximate.
- HTTP
Read-consistency budgets
Lets a reader state how fresh a read must be and get a refusal, not a silently stale answer, when a replica cannot meet it.
BetaSurfaces and limits: Read-consistency budgets
A GET to /v1 can carry an x-kynetra-consistency header: local, bounded(n) lag, exact(n) position, or an opaque token returned by an earlier call. A node that cannot meet the budget within the deadline refuses with a 412 and machine-readable detail. Successful reads report the assurance they achieved.
- HTTP
Request headers x-kynetra-consistency: local | bounded(n) | exact(n) | token(opaque); x-kynetra-consistency-deadline-ms; x-kynetra-min-seq - HTTP
Response headers x-kynetra-assurance, x-kynetra-lag-class, x-kynetra-consistency-token
- The gate is mounted on the /v1 routes alone. It is not applied to /rest/v1, /v1/collections or the other mounts.
- It reports lag in log positions, not in time.
- Raw bounded and exact budgets are for platform credentials; project credentials use local or tokens.
- HTTP
PostgreSQL storage backend
Lets a team that already runs managed PostgreSQL keep the durable log there instead of on a local disk, with a database-enforced single writer.
BetaSurfaces and limits: PostgreSQL storage backend
With KYNETRA_STORAGE_BACKEND=postgres the durable log is a table in PostgreSQL instead of segment files. Search, vector and document views are still rebuilt in memory from that log. A primary takes a fenced lease in the database before it may write, and read replicas share the same table.
- Config
KYNETRA_STORAGE_BACKEND=postgres, KYNETRA_PG_URL - Config
KYNETRA_PG_SCHEMA, KYNETRA_PG_WRITER_KEY, KYNETRA_PG_WRITER_TTL_SECS, KYNETRA_PG_BATCH (must be 1) - Config
KYNETRA_PG_VECTOR, KYNETRA_PG_VECTOR_DIM (optional pgvector offload)
- The tests that need a live PostgreSQL are opt-in and skip when no database is configured, so they do not run by default.
- No deployment profile in the cluster tooling sets this backend up. The deployment-fit catalogue marks restart durability on this backend as unproven and rejects the pg-ha-read profile today.
- Every write is its own database transaction, so write throughput follows the database round trip. No performance figure is published for this backend.
- The tiny-vps runtime profile, Raft and the native replication path do not combine with it.
- Connections to hosts other than the Neon and Supabase patterns use TLS when the URL asks for it, and otherwise do not.
- Config
Streaming replication and read replicas
Gives read capacity and a warm copy of the data by streaming the primary's log to replicas, with divergence detection and read-your-writes controls.
BetaSurfaces and limits: Streaming replication and read replicas
A replica pulls the primary's log over HTTP, writes each record verbatim into its own log and applies it. It refuses local writes, forwards write requests to the primary, and takes itself out of service if its log ever differs from the primary's. Replication is asynchronous unless quorum commit is enabled, and there is no automatic failover.
- Config
KYNETRA_ROLE=replica, KYNETRA_PRIMARY_URL (file backend) - HTTP
GET /v1/replica/stream?since=<seq>&limit=<n>; POST /v1/replica/ingest - Config
KYNETRA_REPLICA_VERIFY_TAIL, KYNETRA_REPLICA_PROXY_CONCURRENCY, KYNETRA_REPLICATION_TLS_CONFIG
- Replication is asynchronous by default. If the primary fails before records are streamed, those writes are not on the replica. Quorum commit makes the primary wait for a replica.
- There is no automatic failover or promotion in this path. The Raft entry covers automatic leadership change and is a research item.
- Without the replication TLS bundle, the pull carries the instance service key as a bearer token over whatever transport the primary URL names. Use https or a private network.
- Replication copies the log. File bytes are not in the log and are not replicated.
- The published staleness figure is for two engines on one host; a real network adds to it.
- A replica that has diverged stays out of service until it is reseeded by hand.
- Config
Semi-synchronous quorum commit
Lets a primary acknowledge a write once enough replicas have persisted it, so a single node failure does not lose acknowledged writes.
BetaSurfaces and limits: Semi-synchronous quorum commit
When KYNETRA_QUORUM_PEERS lists replicas, the primary pushes each locally durable batch to them and answers its callers once the required number have confirmed. A write that misses quorum returns an error even though the primary keeps it, so callers must treat it as indeterminate.
- Config
KYNETRA_QUORUM_PEERS (comma-separated peer base URLs, on the primary) - Config
KYNETRA_QUORUM_W, KYNETRA_QUORUM_TIMEOUT_MS, KYNETRA_QUORUM_API_KEY
- A write that misses quorum returns an error but remains on the primary. Treat it as indeterminate, not as absent.
- Until the first quorum succeeds, a new primary replicates asynchronously.
- Setting this on a replica is refused, and it cannot be combined with Raft consensus writes.
- The measurement covers three processes on one host over loopback. Behaviour across a real network is not measured.
- There is no automatic failover. Quorum commit protects acknowledged writes; it does not elect a new primary.
- Config
Incremental backup chain, point-in-time restore and drills
Keeps a verified, restorable copy of the log within a declared recovery point, lets an operator restore to a chosen log position, and measures restore time by actually restoring.
BetaSurfaces and limits: Incremental backup chain, point-in-time restore and drills
A scheduler cuts full and incremental slices of the log into an encrypted chain in a local store, verifies each by reading it back, and prunes what a restorable chain no longer needs. restore-to-seq rebuilds a fresh data directory at a chosen position, and a drill restores the latest verified cover and compares it with an independent replay.
- CLI
kynetra backup schedule --store <dir> --state <file> --enc-key-id <id> --enc-key-hex <hex> [--rpo-secs --rto-secs --full-every-secs --keep-full --keep-incremental] [--once] - CLI
kynetra backup restore-to-seq --store <dir> --target-seq <n> --out <new dir> --enc-key-id <id> --enc-key-hex <hex> - CLI
kynetra backup drill --store --state --scratch --evidence --enc-key-id --enc-key-hex; kynetra backup rpo-status --store --state
- The chain store is a local directory. No network call is made, and chain slices are not pushed to an object store by these commands.
- The chain captures the whole instance log, not one project, and every slice is encrypted. Keys are supplied as command-line values, so pass them from a secrets manager.
- It reads the log from position zero, so it cannot be used on an instance whose log has been trimmed.
- Cross-region replication helpers, an immutable vault with retention locks and object-lock header builders exist in the backup crate as library code and are not wired into the command line. Local-directory vault immutability is enforced by the library alone, not by the operating system.
- Run these commands against a stopped server or a copy of the data directory. The scheduler opens the data directory directly.
- CLI
Signed local snapshot backups
Takes a copy of the data directory from the admin API, with a signed manifest that shows what the copy contains and what it leaves out.
BetaSurfaces and limits: Signed local snapshot backups
POST /admin/db/backup copies the data directory into a timestamped folder under it, skipping prior backups and file object storage, and publishes a manifest signed with HMAC-SHA256 under an externally supplied key. Named backup profiles can be saved, but the local snapshot driver is the one that runs.
- HTTP
POST /admin/db/backup; GET, POST /admin/db/backup-profiles; POST /admin/db/backup-profiles/{name}/run - HTTP
GET /admin/db/restore-backups/{name}/manifest; DELETE /admin/db/restore-backups/{name} - Config
KYNETRA_BACKUP_SIGNING_KEYS (key-id:base64, comma-separated)
- The copy lives on the same disk as the data directory. It is not an off-host backup; use the portable bundle push, or copy the folder out, for that.
- The copy is made file by file while the server runs and does not pause writers, so it is not a copy at one log position. For a consistent single-position copy, use portable bundles, which read from a pinned snapshot.
- The copy contains everything in the data directory, including stored secrets such as the authentication signing secret. Protect it like the data directory itself.
- The download route returns 501, and the s3, r2, gcs and azure_blob drivers cannot run.
- File object bytes are not part of the copy.
- Backups are not scheduled by this route; a profile runs when it is called.
- The backup-signing key must be configured, or the route returns an error.
- HTTP
Project migration with cutover and rollback
Moves a project between two KynetraDB environments in resumable, checksummed steps, validates the result before declaring cutover, and can roll back while the source is still authoritative.
BetaSurfaces and limits: Project migration with cutover and rollback
kynetra migrate plans, runs, resumes and rolls back a project move built on the portable backup bundle. It checks compatibility, transfers the bundle in checksummed chunks with a durable checkpoint, restores into a target engine, validates, and then records a cutover watermark. The transport that ships today is local directories; no cloud transport is implemented.
- CLI
kynetra migrate plan --source-project <id> --target-project <id> (alias: dry-run) - CLI
kynetra migrate run | resume --source-project --target-dir --target-project --work-dir [--allow-nonempty-target] - CLI
kynetra migrate rollback --target-dir --source-project --target-project [--quarantine]
- No cloud transport is implemented. The shipped transport moves data between local directories. To move a project between hosts today, use the portable bundle push and pull.
- Validation compares shape and a sample of content, not every record.
- Like the other backup commands, it opens the local data directory directly. Run it against a stopped server or a copy.
- It moves one KynetraDB project to another. Moving data from an external database is covered on the migration page.
- CLI
Partition map and routing epochs
Gives routers and clients one versioned answer to which shard owns a key, and refuses a request that was routed with an out-of-date view.
BetaSurfaces and limits: Partition map and routing epochs
GET and PUT /v1/routing/map serve and publish an epoch-versioned partition map that assigns the 64-bit hash space to shards. A caller that sends x-kynetra-routing-epoch is admitted at the current epoch and is refused with a 412 that carries the fresh map otherwise. The map is metadata: one engine serves every key today, and splitting or moving data between shards is not built.
- HTTP
GET /v1/routing/map (Viewer), PUT /v1/routing/map (administrator; body {"map": {...}}) - HTTP
Request header x-kynetra-routing-epoch on /v1 routes; 412 response carries the current map
- This is the map and the refusal contract, not sharding. The server never routes a key by the map, there is one engine for the whole instance, and publishing a map with several shards moves no data. The routing library names online split and move, dual-read validation, scatter-gather, placement constraints and hotspot detection as not built.
- The epoch header is optional and is checked on /v1 routes. The server does not require clients to send it.
- Raft shard groups exist as simulated code; they do not distribute data across a running cluster.
- HTTP
Mutual TLS for replication pulls
Lets a primary accept log streams solely from replicas that present a certificate for an allowed workload, and lets a replica pin the exact workload it will accept as its primary.
BetaSurfaces and limits: Mutual TLS for replication pulls
Setting KYNETRA_REPLICATION_TLS_CONFIG to a private bundle puts replica pulls into strict mode. The primary serves the log stream on a dedicated listener that requires a client certificate for an allowed workload, and refuses the stream in plaintext on its public listener. The replica reaches the primary over HTTPS and requires the primary's certificate to name the expected workload.
- Config
KYNETRA_REPLICATION_TLS_CONFIG (absolute path to the JSON bundle; absent means legacy bearer-key mode) - HTTP
Dedicated mTLS listener serving GET /v1/replica/stream; public route answers 403 replication_tls_required in strict mode
- It covers the log pull. Quorum pushes, Raft messages and the replica write proxy do not use it.
- Certificates are supplied by the operator as files. The server does not issue, renew or reload them.
- The tests that exercise it use loopback, and no multi-host run is published.
- The instance service key is still required in strict mode.
- The server performs no certificate revocation checks (no revocation list and no online status check). To stop trusting a node, remove its workload from the allowed list or replace the trusted roots, then restart.
- Config
Object-storage log backend
Would make an object store the source of truth for the log, with local disk as a write-through cache that can be wiped and rebuilt.
RoadmapSurfaces and limits: Object-storage log backend
The engine library contains a first slice of an object-storage-native log. Sealed segments are shipped to an object store as atomic uploads and a cold boot can rebuild the log from the store. The server cannot select it, and the slice supports a local filesystem URL and nothing more, so it is not available to users.
- Library
EngineConfig::storage(StorageKind::Object { url: "file:///…", prefix }) (engine library, not wired to the server)
- Not reachable from the server or the command line. Setting KYNETRA_STORAGE_BACKEND to object does not select it.
- A file:// URL is the sole supported form. No S3, GCS or Azure store is implemented.
- Truncating or restoring the log does not remove objects from the store.
- No performance or durability figure exists for this backend.
- Library
Encrypted log with key rotation
Would encrypt every log record at rest and let operators rotate, rewrap and revoke keys without a stop.
RoadmapSurfaces and limits: Encrypted log with key rotation
The engine library can encrypt log payloads with AES-256-GCM under per-segment subkeys and manage a key ring with online rotation, crash-safe rewrap and revocation with MAC'd evidence. The server never turns it on, so no user can reach it today.
- Library
EngineConfig::encrypt_at_rest(key); UniversalLog::{install_keyring, rotate_key, rewrap_below, revoke_key} (engine library, not wired to the server)
- The server and the command line never call the encryption setting, so log segments are written unencrypted. Use disk or volume encryption at the host level for encryption at rest today.
- Raft is written to refuse an encrypted log, because the Raft log keeps a plaintext copy of replicated records.
- There is no operator interface for rotation, rewrap or revocation.
- Library
Disk-resident entity store
Would keep entity values on disk in an LSM projection, with a bounded hot overlay in memory, so capacity is not limited by RAM.
RoadmapSurfaces and limits: Disk-resident entity store
The engine library has a disk-backed entity profile: a fjall LSM projection of the log holds the latest version of every entity, and boot replays the log above its watermark and nothing below it. The server always uses the in-memory profile, so this profile is not available to users yet.
- Library
EngineConfig::entity_store(EntityStoreProfile::Disk { cache_entities }) (engine library, not wired to the server)
- The server does not configure this profile, so a server holds all entity values in memory.
- The benchmark ran the engine library on one host. It says nothing about a server deployment.
- The disk profile requires the file log. Deleted values remain in the LSM until compaction, which the engine does not expose.
- Library
Live migration pipeline between KynetraDB instances
Would move a live instance to a new one while clients keep writing, with a bounded write pause at cutover and a rollback path before release.
RoadmapSurfaces and limits: Live migration pipeline between KynetraDB instances
The pipeline crate is a persisted, resumable stage machine: snapshot, tail, verify, shadow-read, cutover, complete and release. It needs an empty target, copies full content, replays the source's log tail, and re-verifies parity inside a write pause. It is a library; no route or command starts it.
- Library
kynetra_pipeline stage machine (engine library, not wired to the server)
- Not reachable from the server or the command line. For a move that works today, see the project migration entry.
- The caller supplies the write gate and the routing flip. The crate does neither.
- Library
Temporal snapshot reads
Would let a caller re-read the database exactly as it was at an earlier committed position, and fail loudly when that position is no longer retained.
RoadmapSurfaces and limits: Temporal snapshot reads
The engine library can mint a snapshot token naming a committed position and re-pin it later for reads that see exactly that state. If the position has aged out of a retention ring, the engine has rewound, or the process restarted, the read fails with a typed error and never returns newer data. No route or command exposes it.
- Library
Engine::snapshot_token, Engine::snapshot_at, SnapshotToken (engine library, not wired to the server)
- Not reachable from the server or the command line. The admin time-travel route reports a position and a time window and does not read historical state.
- Tokens do not survive a restart, a rewind or retention aging.
- Library
Clean-room log export
Would let an auditor or a future maintainer read and verify an export of the log with ordinary text tools and no knowledge of the engine's storage internals.
RoadmapSurfaces and limits: Clean-room log export
The engine library defines a documented, versioned JSON-lines export of log records, each with a SHA-256 of its canonical encoding, and a standalone reader that depends on no storage code. It is a library feature that no route or command calls today.
- Library
kynetra_core::wal_export: export_to_path, clean_room_read, content_digest (engine library, not wired to the server)
- Not reachable from the server or the command line. The kynetra replay command reads records from a data directory and is a separate feature.
- Encrypted logs cannot be exported through the clean-room path without their keys.
- Library
Health-driven auto-heal
Would turn sustained health evidence into bounded restart, replacement or traffic-removal actions, without blind restart loops.
RoadmapSurfaces and limits: Health-driven auto-heal
The autoheal crate is a policy engine for health-driven runbooks. A check must fail several consecutive observations before any action fires, actions are cooldown-gated and bounded per incident, and every action is audited before it runs. No part of the server or the command line uses it.
- Library
kynetra_autoheal policy and incident engine (engine library, not wired to the server)
- Not reachable from the server or the command line, and no actuator is wired to it.
- Library
Global Traffic Manager decision function
Would choose which endpoint may serve a request across regions and cells, and refuse with a stated reason instead of sending a write to a node that cannot be shown to be the leader.
RoadmapSurfaces and limits: Global Traffic Manager decision function
The gtm crate is a pure function. Given a request and the known endpoints it returns the endpoint the request may go to, or a typed refusal. It does no input or output and reads no clock. Nothing in the server, the command line or an edge adapter calls it today.
- Library
kynetra_gtm::decide(request, endpoints, policy) (engine library, not wired to the server)
- Not reachable from the server or the command line, and no edge adapter exists in the repository.
- It decides placement from endpoint facts that something else must collect and keep current: it does no health checking, discovery or traffic steering. Readiness, role, leader term, positions and residency are values the caller asserts and the function does not verify; the tenant is recorded and not authorised.
- It depends on the partition map and request classes of the routing library, and the server does not shard data, so there is no multi-shard deployment for it to steer.
- Library
Workload identity tokens and issuer rotation
Would let services authenticate to one another with short-lived signed tokens that are bound to an audience and rotate their signing key without a stop.
RoadmapSurfaces and limits: Workload identity tokens and issuer rotation
The workload crate can mint and verify Ed25519 identity tokens and rotate the issuer key through an overlap and revoke sequence. The server does not use the token path. It uses the crate's certificate helpers for replication TLS and nothing else.
- Library
kynetra_workload: IdentityProvider, Verifier, WorkloadClaims, IssuerSigningKey (engine library, not wired to the server)
- Not reachable from the server or the command line. No internal route accepts or issues these tokens.
- The replay guard is per process and in memory.
- The server's use of this crate is limited to certificate checks for replication TLS; see that entry.
- Library
Raft consensus and automatic leadership
Would let a group of nodes agree on the order of writes and elect a new leader automatically when one fails.
ResearchSurfaces and limits: Raft consensus and automatic leadership
KynetraDB contains a hand-written Raft implementation and an opt-in HTTP transport. It is tested under a deterministic fault simulator and with in-process server tests. The server's own configuration notes call it experimental, and no measurement over a real network exists, so it is a research item and not a high-availability claim.
- Config
KYNETRA_RAFT_ENABLED, KYNETRA_RAFT_NODE_ID, KYNETRA_RAFT_PEERS (id=url,...) - Config
KYNETRA_RAFT_QUORUM_WRITES, KYNETRA_RAFT_QUORUM_TIMEOUT_MS - HTTP
POST /v1/raft/message (node-to-node); GET /v1/raft/metrics (operators)
- Experimental. The server's own configuration notes describe it as an experimental transport.
- The evidence is a simulator and in-process tests. No multi-host or real-network measurement is published, and the simulator proves properties of the simulator under the faults it injects.
- Peer messages travel over HTTP or HTTPS with the instance service key as the credential. Run nodes on a private network or use https URLs.
- It does not combine with the PostgreSQL backend.
- It is not a sharded or multi-region deployment. The shard-group code is exercised in simulation and is not a clustered product.
- Config
Chaos readiness corpus
Describes the failure scenarios a future chaos programme could run, with admission rules that refuse experiments beyond a declared blast radius.
ResearchSurfaces and limits: Chaos readiness corpus
The chaos crate is a scenario corpus and a run-record library. It describes fault classes such as log corruption, replica loss and sustained health degradation, and refuses experiments that exceed a policy budget. It does not inject faults or run scenarios.
- Library
kynetra_chaos: Scenario, FaultClass, admission and run records (engine library, not wired to the server)
- It does not inject faults or execute scenarios, and it is not wired to the server. The fault-injection that does exist is inside the engine's own tests.
- Library
Identity & access
Sign-up and password sign-in
Gives an application accounts and password sign-in without a separate identity service.
Available in previewSurfaces and limits: Sign-up and password sign-in
Email-and-password accounts with bcrypt-hashed passwords and signed access tokens. Each project has its own pool of end users, its own signing secret and its own tokens, reached with the project anon key under /auth/v1. Operator accounts are a separate surface and have their own page.
- HTTP
POST /auth/v1/signup - HTTP
POST /auth/v1/token?grant_type=password - HTTP
GET /auth/v1/user - HTTP
POST /auth/v1/logout - Config
KYNETRA_ACCESS_TTL_SECS, KYNETRA_REFRESH_TTL_SECS
- The first account in a new project pool becomes its admin, and a pool admin can change that project's collection definitions and rules. Create the first account yourself, with the service key, before the anon key is public.
- No setting closes project sign-up, which is a normal application feature. If sign-up must be restricted, limit who can reach the project sign-up routes at your own network or proxy layer. Keep operator endpoints, including platform account creation, reachable only by operators.
- Passwords need at least eight characters. There is no strength check, no breached-password check and no account lockout; repeated attempts are limited by the per-address request budget described under request protection.
- Access tokens are stateless. Signing out revokes refresh tokens, and an access token that was already issued stays valid until it expires.
- Sign-up does not require a verified address. Verification is recorded when a one-time code or link is redeemed.
- Multi-factor authentication is not offered for project end users. It covers operator accounts alone.
- No sign-in throughput figure is published for this edition.
- HTTP
Authenticator-app MFA (TOTP)
Closes the single-password risk on operator accounts by requiring a code from an authenticator app.
Available in previewSurfaces and limits: Authenticator-app MFA (TOTP)
Time-based one-time passwords for platform (operator) accounts. A user enrols an authenticator app, proves possession with a first code, receives ten single-use recovery codes, and from then on sign-in needs a code after the password. Administrators can require enrolment for every admin account, and sensitive administrative actions can require a fresh code.
- HTTP
GET /v1/auth/2fa, POST /v1/auth/2fa/enroll, POST /v1/auth/2fa/activate - HTTP
POST /v1/auth/2fa/verify, POST /v1/auth/2fa/recovery/ack, POST /v1/auth/2fa/disable - HTTP
POST /v1/auth/2fa/step-up - CLI
kynetra admin 2fa-status | 2fa-enroll | 2fa-disable --code <code> | 2fa-reset --email <email> - Config
KYNETRA_REQUIRE_2FA_ADMIN, KYNETRA_2FA_ISSUER
- TOTP covers platform (operator) accounts. Project end-user pools are not gated by it.
- An authenticator app is the one second factor. SMS codes and passkeys are not available.
- The enrolment secret is stored in the engine alongside other authentication records. Protect the data directory and its backups accordingly.
- Recovery codes are shown once at activation. A lost factor is cleared by an administrator, and the reset is audited and notified.
- HTTP
Organisation MFA mandate
Lets an organisation require every member to hold a second factor, and to have proved it recently.
Available in previewSurfaces and limits: Organisation MFA mandate
An organisation owner or admin can require every member to hold an active second factor and can bound how old that proof may be. The policy is evaluated whenever a platform session is issued or renewed, so a member without a factor cannot hold a session until they enrol.
- HTTP
GET /admin/v1/orgs/:id/security - HTTP
PUT /admin/v1/orgs/:id/security
- The mandate applies to platform accounts that are members of the organisation. It does not apply to project end users, service keys, the global API key or managed tokens.
- The policy record also stores JWKS endpoint URLs and shows a single-sign-on status field. Both are configuration metadata. Nothing fetches the URLs, no single-sign-on provider can be configured through this route, and neither affects authentication. SAML and OpenID Connect single sign-on are not available.
- The audit entry for a policy change names a generic actor, not the individual administrator.
- HTTP
Project API keys and the global key
Gives browsers and server code credentials of different power, and lets an operator replace them.
Available in previewSurfaces and limits: Project API keys and the global key
Each project has two keys. The anon key is publishable and carries the anon role. The service key is a secret for server-side use and carries admin power inside its project. The deployment also has a global API key for platform operations. Keys are random 256-bit values, and a rotation replaces both keys and the project signing secret together.
- HTTP
POST /admin/v1/orgs/:id/projects (returns anon_key and service_key) - HTTP
POST /admin/v1/projects/:id/keys/rotate - HTTP
apikey header or Authorization: Bearer <key> on every data route - Config
KYNETRA_API_KEY, KYNETRA_ANON_KEY
- A project has one anon key and one service key. Keys have no names, scopes or expiry dates, and rotation replaces them all at once. For scoped, expiring credentials see managed API tokens, which in this release administer tokens alone.
- Rotation has no overlap window. Rotate when every client can be updated at once.
- The service key is shown once and cannot be recovered. Rotate to obtain a new one.
- The global API key is a superuser credential. Keep it out of client code and browsers.
- Key creation and rotation are not recorded in the tamper-evident audit log in this release.
- HTTP
Managed API tokens
Gives automation a credential with an explicit capability list, an expiry and a revoke switch, instead of a user role.
Available in previewSurfaces and limits: Managed API tokens
Organisation-owned bearer tokens that carry a capability list rather than a role. They are created, rotated, disabled and revoked over HTTP, can expire, and are stored as SHA-256 hashes and in no other form. The capability set is closed and in this release covers token administration alone.
- HTTP
GET /admin/tokens, POST /admin/tokens - HTTP
DELETE /admin/tokens/:id - HTTP
POST /admin/tokens/:id/rotate, POST /admin/tokens/:id/disable, POST /admin/tokens/:id/enable
- The capability set is closed: tokens_read and tokens_manage. These tokens do not grant read or write access to data, projects or any other route. They administer tokens.
- A token is shown once, at creation and at rotation. It cannot be recovered afterwards.
- Tokens belong to an organisation and are never bound to a project.
- HTTP
Custom roles and permission bindings
Lets a project give a user less than their built-in role allows, using named roles over a fixed permission catalogue.
Available in previewSurfaces and limits: Custom roles and permission bindings
A project can define named roles from a catalogue of 41 permissions, bind them to users with an optional expiry, and have a request-level overlay narrow what those users can do. Built-in roles stay the ceiling, and custom bindings restrict and never widen.
- HTTP
GET /admin/v1/projects/:id/rbac/catalog - HTTP
GET|POST /admin/v1/projects/:id/rbac/roles, PUT|DELETE /admin/v1/projects/:id/rbac/roles/:role - HTTP
GET|POST /admin/v1/projects/:id/rbac/bindings, DELETE /admin/v1/projects/:id/rbac/bindings/:binding - HTTP
GET /admin/v1/projects/:id/rbac/subjects/:user/effective, POST /admin/v1/projects/:id/rbac/evaluations
- The overlay narrows access and cannot widen it. Built-in roles and collection rules stay the ceiling.
- It applies to requests that carry a user identity inside a project: project end-user tokens and platform sessions acting in a project. Service keys and the global key carry no user identity and are not narrowed.
- The permission catalogue is fixed. Custom permissions cannot be defined, and routes that map to no catalogue entry are not narrowed.
- A role holds at most 64 permission entries.
- HTTP
Collection rules and field visibility
Decides, for each collection and operation, which roles may list, view, create, update or delete records, and which fields each role sees.
Available in previewSurfaces and limits: Collection rules and field visibility
Every collection carries a rules object with an allowed-role list for list, view, create, update and delete, and an optional map from field name to the roles that may see that field. Reads are open by default and writes are restricted by default.
- HTTP
POST /v1/collections (a definition that includes rules) - HTTP
GET|POST /v1/collections/:name/records, GET|PATCH|DELETE /v1/collections/:name/records/:id - HTTP
GET|POST|PATCH|DELETE /rest/v1/:table - HTTP
POST /v1/query
- A new collection is readable by every role, including the anon key, until you restrict list and view. Set both explicitly for private data.
- Field visibility is applied on the table routes under /rest/v1, on KynQL and on typed views. The record routes under /v1/collections apply the role lists but do not remove hidden fields.
- Rules match the role name a request resolved to (admin, editor, viewer, anon, or an organisation role for console sessions) or the wildcard. For finer control use the permission overlay and row-level policies.
- The created_at and updated_at fields are required in a definition payload. The server sets updated_at itself.
- HTTP
Rate limits, safe start-up and response headers
Keeps a server from being exposed without credentials and limits how fast any one client can call it.
Available in previewSurfaces and limits: Rate limits, safe start-up and response headers
Start-up checks that refuse an unauthenticated server on a non-loopback address, fixed-window rate limits per client address and per project, and a standard set of security headers on every response.
- Config
KYNETRA_API_KEY, KYNETRA_REQUIRE_AUTH, KYNETRA_INSECURE_REMOTE - Config
KYNETRA_RATE_LIMIT_GENERAL, _AUTH, _ADMIN, _WRITE, _PROJECT, _WINDOW_SECS - Config
KYNETRA_TRUST_PROXY_HEADERS, KYNETRA_HTTPS_ONLY, KYNETRA_CORS_ORIGINS
- The limiter lives in process memory. Counts are kept per node, reset on restart and are not shared across a cluster or between replicas.
- Fixed windows allow a burst across a window boundary of up to twice the budget.
- The API listener does not terminate TLS. Put a TLS-terminating proxy in front of it. The HSTS header does not encrypt the listener itself.
- There is no per-account lockout, CAPTCHA or address reputation in this release.
- Config
Platform accounts and administration
Gives the people who operate a deployment their own accounts, roles and credential controls, separate from the end users of any project.
BetaSurfaces and limits: Platform accounts and administration
Platform accounts are operator identities. They hold a role of super_admin, admin, editor or viewer, belong to organisations, and reach the administration plane. They sign in without a project key, are managed by administrators over HTTP or with the kynetra admin command, and can be protected with TOTP and an organisation MFA mandate.
- HTTP
POST /v1/auth/signup, POST /v1/auth/login, GET /v1/auth/me - HTTP
GET|POST /v1/auth/users, PATCH|DELETE /v1/auth/users/:id - HTTP
POST /v1/auth/users/:id/password, POST /v1/auth/users/:id/2fa/reset - CLI
kynetra admin users | create-user | set-role | set-password | delete-user - SDK
TypeScript AuthClient: signup, login, me, listUsers, createUser, deleteUser - Config
KYNETRA_SUPERADMIN_EMAIL, KYNETRA_SUPERADMIN_PASSWORD
- Platform accounts and the global key are operator credentials with deployment-wide authority. Issue them only to operators, and keep operator endpoints off the public internet.
- Keep operator endpoints, including platform account creation, reachable only by operators.
- The first account created on a fresh deployment receives admin. Seed a super_admin, or create the first account yourself, before the server is reachable by others.
- The legacy /v1/auth/login route returns a single access token and no refresh token. The TypeScript SDK login helper expects that shape and does not handle an MFA challenge, which must be completed through the HTTP routes.
- No sign-in throughput figure is published for this edition.
- HTTP
Refresh tokens, one-time codes and anonymous sign-in
Keeps users signed in, offers sign-in without a password, and lets a visitor try an application before creating an account.
BetaSurfaces and limits: Refresh tokens, one-time codes and anonymous sign-in
Rotating refresh tokens renew access tokens without a password. Six-digit codes and magic links, delivered by email, support passwordless sign-in, email confirmation and password recovery. Anonymous sign-in creates a viewer account with no password. Delivery and hashing depend on configuration the deployment must supply.
- HTTP
POST /auth/v1/token?grant_type=refresh_token - HTTP
POST /auth/v1/otp, POST /auth/v1/verify, POST /auth/v1/recover - HTTP
POST /auth/v1/signup with a {} JSON body (anonymous) - HTTP
POST /auth/v1/logout - Config
KYNETRA_OTP_HASH_PEPPERS - Config
KYNETRA_SMTP_HOST, KYNETRA_SMTP_PORT, KYNETRA_SMTP_USER, KYNETRA_SMTP_PASS, KYNETRA_SMTP_FROM - Config
KYNETRA_PUBLIC_URL
- One-time codes need a keyed hashing configuration. Set KYNETRA_OTP_HASH_PEPPERS to an active key id and key, plus any older keys that must still verify. Without it, code requests fail with a server error.
- Email is sent over SMTP. The built-in client does not use TLS, so the message and any SMTP credentials travel unencrypted. Point it at a relay on the same host or inside a private network. With no SMTP host configured, the message, including the code and link, is written to the server log instead of being sent.
- A code request for an address that has no account creates a passwordless account record for it, with the viewer role. In an empty pool the first such account becomes admin.
- Anonymous accounts and expired token and code records are not purged automatically in this release, so each anonymous sign-in leaves a stored account behind.
- Refresh tokens are looked up by scanning the stored token records. No throughput figure is published for this edition.
- KYNETRA_PUBLIC_URL sets the base address used in links. It defaults to a local address.
- HTTP
Sign in with Google or GitHub
Lets users sign in with an existing Google or GitHub account instead of creating a new password.
BetaSurfaces and limits: Sign in with Google or GitHub
An authorisation-code flow for Google and GitHub. The server sends the browser to the provider, exchanges the returned code, reads the account email and signs the user in. The client id and secret for each provider are supplied by the deployment through environment variables.
- HTTP
GET /auth/v1/authorize?provider=google|github&redirect_to=<url> - HTTP
GET /auth/v1/callback - Config
KYNETRA_OAUTH_GOOGLE_ID, KYNETRA_OAUTH_GOOGLE_SECRET - Config
KYNETRA_OAUTH_GITHUB_ID, KYNETRA_OAUTH_GITHUB_SECRET - Config
KYNETRA_PUBLIC_URL
- The provider round trip is not covered by automated tests in the engine repository, which is why this capability is beta.
- Google and GitHub are the supported providers. Other OpenID Connect providers are not available.
- Tokens are delivered in the URL fragment of the redirect. Use a redirect target you control, served over HTTPS, and clear the fragment after reading it.
- Accounts are matched by the email address the provider returns, so enable providers whose email addresses you trust to be verified, and no others.
- The callback address defaults to a local address unless KYNETRA_PUBLIC_URL is set.
- HTTP
Signing-secret rotation
Lets an operator replace the platform token-signing secret without editing data by hand.
BetaSurfaces and limits: Signing-secret rotation
A two-step command mints a pending secret that the server accepts alongside the active one, then promotes it. The command runs against the data directory with the kynetra tool, and the server loads each change when it restarts.
- CLI
kynetra rotate auth-secret (status), --start, --promote - Config
KYNETRA_AUTH_SECRET
- The command always works on the local data directory given by --data, even when --remote is set. It does not contact a server, and no HTTP route performs the rotation.
- Promotion ends the old secret at once. Nothing signs with the pending secret before promotion, so access tokens issued before promotion stop verifying at that moment.
- Restart the server after each step so that it loads the change.
- The command writes no audit entry.
- Rotation on a schedule is not available; see the secret rotation machine page.
- CLI
Row-level security policies
Restricts which rows a caller can read or write, for example letting users see their own records and no others.
BetaSurfaces and limits: Row-level security policies
A small policy language evaluated on the server for every row. Policies are written per operation (select, insert, update, delete) as boolean expressions over the row and the caller, such as owner_id == auth.uid(). A request can also declare a purpose that a policy can require.
- HTTP
POST /v1/collections (rules.policies on the definition) - HTTP
GET|POST|PATCH|DELETE /rest/v1/:table - HTTP
POST /v1/query - HTTP
GET /realtime/v1 (subscriptions are filtered by select policies)
- Policies are enforced on the table routes under /rest/v1, on KynQL queries at /v1/query, on typed views and on realtime subscriptions. The record routes under /v1/collections apply the role lists alone. Serve end-user traffic through the first four surfaces.
- Project service keys, and organisation console sessions acting inside a project, skip policies.
- Policies are evaluated row by row after the candidate rows are selected, so they restrict results but do not make a query cheaper. No throughput figure is published.
- The language has no joins, subqueries or functions beyond the four auth functions.
- HTTP
Organisations, projects and tenant isolation
Lets one deployment host many independent projects for different tenants, each with its own users, keys, data and lifecycle.
BetaSurfaces and limits: Organisations, projects and tenant isolation
Organisations own projects. Every record, user and definition of a project is stored under a project-specific prefix, each project has its own keys and signing secret, and a project moves through a lifecycle that can pause, suspend, export and purge it. Isolation is logical: tenants share one engine, one log and one process.
- HTTP
POST|GET /admin/v1/orgs, GET|DELETE /admin/v1/orgs/:id - HTTP
POST|GET /admin/v1/orgs/:id/members, DELETE /admin/v1/orgs/:id/members/:uid - HTTP
POST|GET /admin/v1/orgs/:id/projects, GET|DELETE /admin/v1/projects/:id - HTTP
POST /admin/v1/projects/:id/status, GET /admin/v1/projects/:id/export, POST /admin/v1/projects/:id/purge - HTTP
POST /admin/v1/provision - Config
KYNETRA_RATE_LIMIT_PROJECT
- Isolation is logical. Tenants share one engine, one log and one process. There is no per-tenant process, storage volume or encryption key.
- Platform accounts and the global key are operator credentials with deployment-wide authority. Issue them only to operators, and keep operator endpoints off the public internet.
- A purge is a tombstone plus checkpoint compaction, not cryptographic erasure. Earlier versions of the data remain in the retained log, in backups and restore-undo copies, in replica logs and in disk-store segments until compaction rewrites them. The purge response states this scope.
- Per-project entity and request limits exist in the data model, but no API in this release sets them. The default per-project request budget described under request protection applies.
- Some classes of internal state, for example usage metering and classification state, are not part of an export, so an export can be marked incomplete. Read the manifest before treating an export as a backup.
- The global API key addresses every namespace.
- Project key rotation and organisation membership changes are not written to the tamper-evident audit log. Lifecycle transitions are recorded as tenant-operation records.
- HTTP
Passkeys and WebAuthn
Would let operators use hardware keys and device passkeys as a phishing-resistant second factor.
RoadmapSurfaces and limits: Passkeys and WebAuthn
Not available in this release. Authenticator-app TOTP is the supported second factor. The operator console contains passkey controls, but the server in this release has no passkey routes and no WebAuthn library, so those controls do not work.
- Not reachable in this release.
- The operator console shows passkey controls that call routes this release does not serve.
SAML and single sign-on
Would let an organisation sign its members in through its own identity provider.
RoadmapSurfaces and limits: SAML and single sign-on
Not available. KynetraDB has no SAML and no OpenID Connect single sign-on in this release. Sign-in is by password, one-time code, or Google and GitHub OAuth.
- SAML single sign-on is not available.
- OpenID Connect providers other than Google and GitHub are not available.
- The JWKS endpoint list on an organisation policy has no effect on authentication.
Governance & compliance
Tamper-evident audit log
Leaves a trail of administrative and governance actions that can be checked for after-the-fact edits.
Available in previewSurfaces and limits: Tamper-evident audit log
A log of administrative and governance events that is written by appending and never edited in place. Each entry is chained to the one before it with an HMAC under a server-held key, and the head of the chain is witnessed in two other places, so editing, reordering, deleting or truncating entries is detected by a verification pass. Entries can be browsed, filtered and verified over HTTP.
- HTTP
GET /admin/v1/audit/logs?actor=&action=&limit=&cursor= - HTTP
GET /admin/audit - HTTP
GET /admin/audit/verify - Config
KYNETRA_AUDIT_HMAC_KEY
- The log is tamper-evident, not tamper-proof. Verification needs the key, so the server or a holder of the key checks the chain. When the key is stored in the engine, whoever can rewrite the data directory can also read it. Supply KYNETRA_AUDIT_HMAC_KEY from a secret manager to keep the key apart from the log.
- Audit writes are not part of the action's own transaction. If an append fails, the failure is logged and the action itself proceeds.
- Not every control-plane change is in the chain. Project key rotation and organisation membership changes are not recorded in it, and a few events, such as organisation security and billing updates, are recorded under a generic actor name.
- Operators cannot rotate the chain key in this release; see the audit-log key rotation page.
- There is no automated truncation or archival. Entries are kept in full.
- Each node keeps its own chain, so there is no merged view across a primary and its replicas.
- HTTP
Protected system records
Stops a caller of the ordinary data routes from reading or rewriting the records the server uses to control itself.
Available in previewSurfaces and limits: Protected system records
The server keeps its own control state as records in the same engine: the audit key and checkpoint, role bindings, residency and security policies, organisation membership projections, API token verifiers, approvals, queues and more. The generic read and write routes refuse these kinds under every tenant spelling, and the refusal does not depend on whether the target exists.
- HTTP
Applies to POST /v1/entities, POST /v1/transactions, /rest/v1/:table, /v1/collections/:name/records and the import paths
- Protection applies to the generic data routes. Credentials with platform authority, and the trusted code paths of the server itself, still write these records through their own routes.
- The classification is maintained by hand and checked by a test that scans source text. It is a guard rail and not a proof.
- HTTP
GDPR export and cascade erasure
Collects or deletes the data tied to one user id across the engine, as part of a data-subject request.
BetaSurfaces and limits: GDPR export and cascade erasure
Two administrator routes. Export returns every record that references a user id. Erasure deletes the user record and every record, file and agent artefact that references the id, writes a summary audit record, and refuses to run while a legal hold covers that user.
- HTTP
POST /v1/gdpr/export - HTTP
DELETE /v1/gdpr/user/:id
- Matching is by id in a top-level field: user_id on records, uploaded_by on files, actor on audit entries in the export. Data that links to a person through a nested field or an email address is not found.
- The user step removes the platform account record by id. End-user accounts held in a project pool are not matched by that step, though records that carry the id in user_id are.
- Both routes are admin-only. They scan the whole engine rather than one project, so they are not tenant-scoped; run them as a deliberate operator action. The export is refused above 100,000 entities, and its refusal message mentions a command-line exporter that does not exist in this release.
- Backups already taken, replica logs and exports already delivered are not rewritten. Real erasure from those needs expiry or out-of-band key destruction.
- Legal holds are honoured by the erasure, but there is no route to place or release one in this release.
- HTTP
DPDP compliance records
Keeps structured records of notices, consent, rights requests, retention and breaches for an operator working to the Digital Personal Data Protection Act.
BetaSurfaces and limits: DPDP compliance records
Versioned purpose notices, consent and withdrawal receipts that are added and never overwritten, rights requests with response deadlines, retention rules with a dry run, a breach register with notification clocks, a residency allow list and a readiness report. The records support an operator's own compliance work. They are not a legal certification.
- HTTP
GET /v1/privacy/notices, GET|POST /v1/privacy/consents, GET|POST /v1/privacy/rights-requests - HTTP
GET /admin/compliance/dpdp/readiness, GET|POST /admin/compliance/dpdp/notices - HTTP
GET|POST /admin/compliance/dpdp/consents, GET /admin/compliance/dpdp/rights-requests, POST /admin/compliance/dpdp/rights-requests/:id/status - HTTP
GET|POST /admin/compliance/dpdp/retention-rules, GET /admin/compliance/dpdp/retention-rules/dry-run - HTTP
GET|POST /admin/compliance/dpdp/breaches, POST /admin/compliance/dpdp/breaches/:id/notifications, GET|PUT /admin/compliance/dpdp/residency - HTTP
GET /.well-known/dpdp
- Retention execution is switched off. The execute route returns 501 and deletes nothing, because deletion over HTTP waits on legal-hold and concurrency controls that are not wired to it. The dry run works. Deleting expired data is carried out by the operator.
- Legal holds exist as records and are honoured by erasure, but there is no route to place or release one in this release.
- Notices, consents, rights requests and breach records are held at deployment level, not per project. Retention rules are the one record type scoped to a project.
- The principal-facing routes need a platform account token and are not available to project end-user tokens. An application with its own end users records consent for them through an administrator route.
- This is operational record-keeping. It does not certify compliance with the Act or its rules, and notifying the board and affected principals of a breach stays the operator's duty.
- HTTP
Data-residency policy and placement decisions
Lets a project declare where each kind of data may live and ask the server whether a proposed placement is allowed.
BetaSurfaces and limits: Data-residency policy and placement decisions
A per-project policy of allowed regions for six data paths, a decision route that denies an out-of-region placement, a drift check against observations you supply, and a readiness view that states which paths the feature can and cannot enforce.
- HTTP
GET|PUT /v1/residency/policy - HTTP
POST /v1/residency/placement - HTTP
POST /v1/residency/drift - HTTP
GET /v1/residency/readiness
- The feature answers questions and does not intercept the engine. Storage, backup and deployment code does not consult it, so placement is enforced where a caller, such as your deployment tooling, asks and honours the answer.
- Drift detection works on observations you submit. The server does not discover where data lives.
- The readiness route evaluates the policy without observations, so declared dimensions report unknown until evidence is supplied elsewhere.
- Through the mounted server, tests exercise the policy route inside the forged-policy tests and nowhere else. The placement, drift and readiness routes have no mounted tests of their own, which is why this capability is beta. The decision logic is tested.
- This is not a legal or regulatory certification.
- HTTP
Policy as code
Checks a planned change against a reviewed policy file before it is applied, and records who approved it in a ledger that shows tampering.
BetaSurfaces and limits: Policy as code
A versioned TOML policy file covers schema, access, residency, retention, backup and deployment admission. The kynetra policy command validates the file, checks a planned change set against it, exiting non-zero on any violation so it can gate a pipeline, and records approvals in a hash-chained, MAC-signed ledger bound to the policy and to the change.
- CLI
kynetra policy validate --policy <file> - CLI
kynetra policy check --policy <file> --changes <file> - CLI
kynetra policy approve --ledger <file> --ledger-key <file> --policy <file> --changes <file> --by <name> [--decision approved|rejected] - CLI
kynetra policy verify --ledger <file> --ledger-key <file> [--policy <file> --changes <file>]
- The crate that implements it marks itself partial. It evaluates a change set that you or your pipeline produce. It does not read the live database and does not enforce the policy at run time.
- The commands work on local files and are refused when --remote or KYNETRA_REMOTE is set.
- The ledger is a file protected by a MAC under a key you hold. It shows tampering to a holder of that key. It is not a signature that a third party can check, and it does not defend a ledger whose key is compromised.
- Policy files and change sets are strict. A misspelled key is an error, not a silent default.
- CLI
Audit-log key rotation
Would let an operator replace the key that signs the audit chain without breaking verification of older entries.
RoadmapSurfaces and limits: Audit-log key rotation
The mechanism exists inside the audit log, but no route or command exposes it, so operators cannot rotate the audit key in this release. The log can verify a chain that spans several key epochs, and the mechanism is exercised by tests in the engine repository.
- Not reachable by operators in this release.
- The key is supplied by KYNETRA_AUDIT_HMAC_KEY or stored in the engine, and is replaced by neither route nor command today.
PII detection, redaction and classification
Would find and mask personal data such as email addresses, phone numbers and card numbers before it reaches a model or leaves in an export.
RoadmapSurfaces and limits: PII detection, redaction and classification
Not reachable in this release. The detection and redaction code exists as a library with tests, but no server route, command or SDK call uses it, so it does not run on any data in a deployment.
- Not reachable by users in this release.
- The detectors are heuristic and report measurable false positives and false negatives.
Attribute and purpose authorization engine
Would decide access from role, tenant, purpose, device and workload claims in one default-deny engine.
RoadmapSurfaces and limits: Attribute and purpose authorization engine
Not wired into request handling in this release. The decision engine exists as a library and is used by the policy-as-code checker, but the server does not call it when it authorises a request.
- Not reachable as a request-time authoriser in this release.
- Purpose-based access is available today through row-level policies that call auth.purpose() with the X-Kynetra-Purpose header.
Automatic secret rotation
Would rotate each class of secret through a crash-safe sequence, with proof that the old key is refused.
RoadmapSurfaces and limits: Automatic secret rotation
Not reachable in this release. A rotation state machine and an inventory of secret classes exist as a library, but no route, command or schedule drives them against a live secret.
- Not reachable in this release.
- The seal on an evidence record shows the record was written by the machine to a holder of the evidence key. It is not a signature that a third party can check.
Compliance evidence packs
Would hand an auditor a signed bundle of controls, configuration and audit proofs that can be verified without the database.
RoadmapSurfaces and limits: Compliance evidence packs
Not reachable in this release. Two pieces exist as libraries: a readiness worksheet built from live data, and a signed pack format with an offline verifier command. No server route or command produces either.
- CLI
kynetra-evidence-verify --pack <pack.json> --trust <trust.json> [--json] (verifies a pack; nothing in the server produces one)
- Nothing in the server or the kynetra command builds a pack or a worksheet, so a user cannot produce one in this release.
- Neither the worksheet nor a pack is a certification or an attestation.
- CLI
Capability ledger validator
Keeps the engineering team's own capability claims tied to files that exist in the repository.
ResearchSurfaces and limits: Capability ledger validator
An offline command-line tool in the engine repository that validates a ledger of capability claims. Each claim names a status, a commit and the files that back it. It runs during development. It is not part of the database server and it is not a feature of a deployment.
- CLI
capledger validate <ledger.json> | summary | migrate-v2 | check-artifact | foundry-portfolio
- Internal tooling. It is not reachable from a running server and is not scheduled as a product feature.
- A clean validation shows that files exist. It says nothing about whether a claim is true.
- CLI
APIs, integrations & migration
Discovery document
Lets tools and other Kynetra products find the interfaces, runtime shape and connection contract of a running instance without hard-coded URLs.
Available in previewSurfaces and limits: Discovery document
GET /.well-known/kynetra returns a versioned, secret-free JSON document. It names the base paths of the REST, MCP, telemetry and OpenAPI surfaces, the runtime profile, node role and storage backend, a connection contract, and a short capability list in which each item carries a status, including one marked roadmap. It needs no credentials.
- HTTP
GET /.well-known/kynetra - CLI
kynetra doctor --remote <url> (reads the document as a stage)
- The capability list is short and fixed. It is not an inventory of everything the server does; this catalogue is.
- It describes the instance, not a project. Every caller gets the same document, and it carries no tenant data.
- Integration statuses, for example compatible or contract ready, are labels written into the template. They are not live health checks.
- HTTP
Connection bundle and doctor
Gives a developer the exact URLs, environment variable names and starter snippets for a project, and a read-only check that a client can really connect.
Available in previewSurfaces and limits: Connection bundle and doctor
An administrator can fetch a secret-safe connection bundle for a project, and the kynetra command-line tool can print it as environment variables or JSON and run a staged connection check. The check stops at the first failing stage and reports a stable code. It needs an authorized read to succeed, so a reachable server is not mistaken for a working connection.
- HTTP
GET /admin/v1/projects/{id}/connect - CLI
kynetra connect --remote <url> --project <id> [--format summary|env|json] [--runtime nextjs|vite|astro|sveltekit|nuxt|node|cloudflare] [--check] - CLI
kynetra doctor --remote <url> [--project <id>] [--json] - HTTP
GET /admin/connect/options, /admin/connect/agent-prompt, /admin/connect/connection-string
- The service key is never shown in the bundle. A project that needs a new one has to rotate it.
- The generated snippets are starting points for HTTP clients. The TypeScript client package is described by the server as source available and unpublished.
- kynetra doctor tests one base URL at a time and cannot see a proxy or firewall rule that treats other routes differently.
- HTTP
REST API for collections
Lets a client application read and write any collection through one generic set of URLs, without a hand-written endpoint for each resource.
BetaSurfaces and limits: REST API for collections
Every collection is served at /rest/v1/<name> with list, insert, update and delete, a filter grammar in the query string, column selection, sorting, offset paging and one level of relation embedding. It runs behind the same authentication, collection rules and row-level policies as the other record endpoints. List, update and delete read the whole collection before they filter, so the layer suits small and medium collections today.
- HTTP
GET /rest/v1/:table (list, filter, select, order, limit, offset) - HTTP
POST /rest/v1/:table (insert one or many; upsert with Prefer: resolution=merge-duplicates) - HTTP
PATCH /rest/v1/:table?<filter> (merge a body into every matching record) - HTTP
DELETE /rest/v1/:table?<filter> (delete every matching record) - Config
KYNETRA_CORS_ORIGINS (allowed browser origins; when unset, same-origin requests work and cross-origin requests are not allowed)
- List, PATCH and DELETE read every record of the collection and then filter, sort and page in memory. The cost grows with the size of the collection and no scale has been measured. For large collections use the search, vector and KynQL endpoints.
- Paging is by offset. There is no cursor, so a deep page re-reads the collection, and records added between two requests can shift the window.
- A PATCH or DELETE with no filter applies to every record the caller may change. Always send a filter.
- Embeds follow relation fields one level deep. Nested embeds and reverse relations are not supported.
- Sorting orders numbers and text. Other value types compare as equal.
- The OpenAPI document does not describe these routes.
- Writes through this layer do not raise outbound webhook events.
- HTTP
OpenAPI document
Gives client generators and API explorers a machine-readable description of the server routes.
BetaSurfaces and limits: OpenAPI document
GET /openapi.json returns an OpenAPI 3.1 document that is written by hand inside the server. It describes hundreds of paths across the native /v1 routes, the admin routes and the infrastructure surfaces. It is not complete: several mounts, including the collection REST layer, are missing, and because it is maintained by hand it can drift from the route table.
- HTTP
GET /openapi.json - HTTP
GET /.well-known/kynetra (links to the document in its connect block)
- Partial coverage. These mounts are not described in the document: the collection REST layer under /rest/v1, the /auth/v1, /storage/v1 and /functions/v1 compatibility mounts, the WebSocket realtime endpoint, the outbound webhook routes, the cluster provisioning routes, the Postgres migration job routes and /metrics.
- The document is maintained by hand, so a route added or changed in the server can be missing or out of date until someone updates the entry. Check the capability pages on this site for the surfaces the document leaves out.
- It is not a promise of client compatibility. Generated clients should be tested against your preview.
- HTTP
Outbound webhooks
Lets an external system learn that a record was written, by receiving a signed HTTP POST from KynetraDB.
BetaSurfaces and limits: Outbound webhooks
An administrator registers a URL, a list of event names and a signing secret. When a record is created through the native entity endpoint or the collection record endpoint, KynetraDB posts a JSON event to each matching active subscription with an HMAC-SHA-256 signature header, and keeps a short delivery log. Delivery is a single attempt per event: there are no retries, and several write paths raise no event.
- HTTP
GET /admin/webhooks, POST /admin/webhooks - HTTP
DELETE /admin/webhooks/:id - HTTP
POST /admin/webhooks/:id/test - HTTP
GET /admin/webhooks/:id/deliveries
- One attempt per event. A failed or timed-out delivery is written to the log and not retried, so a receiver that is down misses events. Make the receiver idempotent, and reconcile through the change feed when you need completeness.
- The server raises one event name, record.created, from the two endpoints above. Updates and deletes through the collection record endpoints, writes through the REST layer, transactions and bulk imports raise no webhook event.
- The delivery log holds the newest 50 deliveries across all subscriptions.
- Subscriptions apply to the whole deployment; configure them as an operator. Restrict access to the data directory, because it holds the subscription secrets.
- The signature covers the body. The timestamp travels inside the body, so a receiver that needs replay protection has to check it.
- No automated test in the engine repository covers the subscription store or the delivery code. Test your receiver before you rely on it.
- HTTP
Outbound database sinks
Copies each write to an external database or storage service, so KynetraDB can sit beside an existing data estate and feed it.
BetaSurfaces and limits: Outbound database sinks
When an operator switches sinks on and supplies the settings for a target, KynetraDB mirrors every entity upsert and delete to it. Thirteen targets are implemented. Mirroring is a background call made after the write is acknowledged, with no retry and no backfill, so a target that is down misses writes.
- Config
KYNETRA_ENABLE_SINKS=true (switches mirroring on) - Config
Per-target KYNETRA_* settings, for example KYNETRA_SUPABASE_URL, KYNETRA_SUPABASE_SERVICE_KEY, KYNETRA_SUPABASE_TABLE - HTTP
GET /admin/sinks - HTTP
POST /admin/sinks/ping
- Fire-and-forget. There is no queue, retry or backlog. A write that cannot be mirrored is lost to that target, and a restart drops anything in flight. This edition has no backfill for data that existed before a sink was added.
- A failed mirror shows up as a warning in the server log (sink upsert failed or sink delete failed). The metrics output declares per-sink counters, but nothing in the server updates them in this edition, so do not alert on them.
- Each write is mirrored on its own background task, so two quick writes to one record can arrive at a target in either order.
- Sinks are configured when the server starts and apply to the whole deployment; configure them as an operator.
- Five targets have request-shape tests against a mock server: the PostgREST-style endpoint, Supabase, the MongoDB Atlas Data API, Upstash Redis and Pinecone. The others, whose endpoints are fixed in code, have a configuration test and no request-shape test.
- The MongoDB sink uses the Atlas Data API. Confirm that your MongoDB deployment still offers it before you rely on this target.
- The BigQuery and Firestore sinks take a prepared access token from the environment and do not refresh it. Replace the token and restart when it expires.
- The Redis sink puts the entity JSON in the request path, which makes large entities impractical.
- The flow is one-way. Nothing is read back from a target and conflicts are not detected. The per-target list is on the migration page.
- Config
Data migrators (kynetra-migrate)
Copies data from another database, search service or backend into KynetraDB, so a team can move without writing an import script for each source.
BetaSurfaces and limits: Data migrators (kynetra-migrate)
kynetra-migrate is a command-line tool with fourteen sources and three destinations. It is a one-time copy: it reads the source, writes records and prints a summary. SQLite, D1 and the KynetraDB NDJSON restore have the most test coverage. PostgreSQL, Supabase and the vendor API sources are reachable but lightly tested and have limits that are listed per source. MySQL and MariaDB are not supported.
- CLI
kynetra-migrate --to <stdout|engine|http> [--data-dir DIR] [--kdb-url URL --kdb-key KEY] [--project-id ID] [--limit N] <source> [source options] - CLI
Sources: sqlite, d1, pocketbase, postgres, supabase, firebase, algolia, pinecone, mongo, meilisearch, typesense, convex, appwrite, ndjson
- A one-time copy. No source follows later changes. On the engine destination a second run adds new rows and refuses changed ones.
- Created and updated timestamps on the written records are the time of the run, except for NDJSON restores.
- The HTTP destination sends attributes alone, sends no ids or vectors, and needs the collections to exist first. The route it calls to create collections is not exposed by this server version, so create them with POST /v1/collections before the run.
- PostgreSQL and Supabase connections do not use TLS. Run the tool inside a private network or through an SSH tunnel.
- Several network sources end a run early on a request error with a warning and a success exit status, and Algolia stops at 10,000 records. The per-source limits are on the migration page.
- MySQL and MariaDB are not supported. The one MySQL feature in the engine writes from KynetraDB to a MySQL-compatible table.
- Tests exist for SQLite (16), D1 (3), PocketBase (1), NDJSON restore (26, plus 37 for the destinations), and a few helpers for the vendor sources. No test reads from a live PostgreSQL, Supabase, Firebase, Algolia, Pinecone, Mongo, Meilisearch, Typesense, Convex or Appwrite service.
- CLI
E-commerce platform connectors
Would keep a KynetraDB product catalogue in step with an e-commerce platform by backfilling the catalogue and applying platform webhooks.
RoadmapSurfaces and limits: E-commerce platform connectors
The engine repository contains adapter code for ten e-commerce platforms: Shopify, WooCommerce, BigCommerce, Magento, Medusa, Saleor, commercetools, Vendure, PrestaShop and Wix. The server never calls that code, so no catalogue is imported today. The adapters have tests as a library, but no running part of the product can use them, which is why this entry is roadmap.
- Library
kynetra-connectors crate: Connector trait, ConnectorRegistry and ten adapters (library code; the server does not call it)
- Not reachable. Nothing in the server, the command-line tool or an SDK runs these adapters.
- No adapter has been run against a live platform in the engine repository. The tests use in-memory fixtures.
- The routes the server exposes for connectors acknowledge a request and import nothing. Do not point a platform at them expecting a catalogue to arrive.
- To get product data in today, use the REST layer, the HTTP API or the migration tool.
- Library
Postgres migration job with progress stream
Would let an operator start a PostgreSQL copy from the admin console and watch per-table progress while it runs.
RoadmapSurfaces and limits: Postgres migration job with progress stream
The server has a route that starts a PostgreSQL copy as a background job and a second route meant to stream its progress as server-sent events. In this build the progress stream does not carry the events of the job, and the job writes through an HTTP destination that depends on routes the server does not expose. That makes this entry roadmap. Use kynetra-migrate on the command line instead.
- HTTP
POST /admin/migrate/postgres - HTTP
GET /admin/migrate/postgres/{job_id}/stream
- Treat the route as not working end to end. Starting a job produces no usable progress output, and the writes can fail for missing collections.
- Use kynetra-migrate with --to stdout or --to engine, and read the per-source limits on the migration page.
- No test in the engine repository starts a job or reads its stream. The one test that names the stream route checks that a replica refuses it.
- Unrelated to the PostgreSQL storage backend, which runs the database itself on PostgreSQL.
- HTTP
Deployment & operations
Deployment fit advisor
Tells you, before you build anything, which KynetraDB deployment mode or interoperability path matches a declared workload, and why other options are ruled out.
Available in previewSurfaces and limits: Deployment fit advisor
Platform administrators can post a workload description to /admin/v1/deployment-fit/evaluate and get a deterministic, scored comparison of deployment modes and of paths for bringing data in or mirroring it out. The score is weighted coverage of the needs you declare. It is not a benchmark. Hard disqualifiers, for example a requirement for the PostgreSQL wire protocol, are reported as such.
- HTTP
GET /admin/v1/deployment-fit/catalog - HTTP
POST /admin/v1/deployment-fit/evaluate
- A fit score is not a performance measurement.
- The catalogue is a snapshot compiled into the server and carries its own version string. It reflects what the repository registers at this commit.
- The routes need platform administrator authority.
- HTTP
Metrics, logs and traces
Shows an operator what the server is doing, through request counts and latency per route, slow requests, request correlation, health probes and traces, in formats that existing monitoring tools read.
Available in previewSurfaces and limits: Metrics, logs and traces
The server exposes Prometheus text metrics at /metrics, per-route latency percentiles and error rates for administrators, liveness and readiness probes, a request id on responses, a log warning for slow requests, structured logs and optional OTLP trace export. The retrieval objectives and the alert webhooks are described under their own entry.
- HTTP
GET /metrics (Prometheus text; service key required unless KYNETRA_PUBLIC_METRICS=true) - HTTP
GET /admin/db/slo (per-route latency percentiles and error rate) - HTTP
GET /healthz, GET /readyz, GET /admin/health - Config
KYNETRA_SLOW_QUERY_MS, KYNETRA_SLOW_QUERY_ROUTES, KYNETRA_LOG_FORMAT, OTEL_EXPORTER_OTLP_ENDPOINT, KYNETRA_PUBLIC_METRICS
- The per-route tracker is in memory and cumulative since the process started. It resets on restart and reports no recent-window rate.
- Metrics describe one instance. Aggregation across instances is up to your monitoring system.
- Slow requests are written to the log. They are not stored as records or searchable in the admin console.
- Trace export is off unless OTEL_EXPORTER_OTLP_ENDPOINT is set, and the OTLP endpoint is one you operate.
- HTTP
Capacity planning report
Shows current usage and a forecast against limits, with every number labelled measured, configured or projected, so a forecast is never read as an observation.
Available in previewSurfaces and limits: Capacity planning report
GET /admin/db/capacity returns a capacity plan built from live server state: records, index size, host storage, memory and CPU, request and write rates, and realtime consumers. Every value carries a provenance tag. Forecasts come from an explicit growth assumption, and a projected breach of a limit you configure is flagged.
- HTTP
GET /admin/db/capacity?project=&growth=&periods=&model=&period=&embedding_dim=&price_per_gb=&record_limit=&consumer_limit=&qps_limit=
- Rates are averages over the metrics window or since process start, not peaks.
- Model token rate, disk I/O and network are not measured.
- It is a report. Nothing acts on it, and it does not resize anything.
- It describes one instance. Plan a fleet by combining the reports.
- HTTP
Command-line tool (kynetra)
Lets an operator set up, run, inspect and administer an instance from a terminal, against a local data directory or a remote server.
Available in previewSurfaces and limits: Command-line tool (kynetra)
The kynetra binary sets up a standalone instance, starts it, installs it as a service on Linux, reads and writes data, replays the log, scaffolds starter projects and administers remote servers. Some subcommands act on a local data directory and others call the HTTP API. Setup, scaffolding, replay and the connection check have tests. Several front-ends are thin wrappers whose logic is tested in their own crates.
- CLI
kynetra init [--bind ADDR] [--profile NAME] [--force]; kynetra start [--dry-run]; kynetra status; kynetra install [--root DIR] [--no-start] - CLI
kynetra put <kind> <json> | get <id> | delete <id> | filter <terms> | search <vector> | stats - CLI
kynetra replay --from-seq N [--to-seq M] [--into stdout|engine|filter] - CLI
kynetra new <template> [dir] | new --list; kynetra rotate auth-secret --start|--promote - CLI
kynetra login | whoami | connect | doctor | infra | provider | admin | ingest | backup | migrate | policy (with --remote)
- The local data subcommands open the data directory themselves. To work with a running server, use --remote.
- login --password and admin set-password take the password as a command-line argument, which shell history and process listings can record. Use a throwaway shell or clear the history.
- provider import-env supports DigitalOcean alone.
- The admin, backup, migrate and policy front-ends have no tests in the CLI crate itself. Their logic is tested in their own crates.
- kynetra install writes a systemd layout for Linux. It does not run on other systems and is not a cloud installer.
- CLI
Cloud provider adapters
Lets an administrator register cloud credentials once, then list, deploy, resize and destroy instances through provider APIs from the admin API, the command line or an agent.
BetaSurfaces and limits: Cloud provider adapters
The server has adapters for fifteen providers. Twelve of them can create a container service or a virtual machine from an image you supply; two create PostgreSQL databases; Cloudflare offers inventory and edge-gateway calls and no deploy. Credentials are sealed in the log. This is code that calls provider APIs. It is not a tested installer: one provider has an opt-in live test, no adapter attaches persistent storage, and the image has to be one you build and host.
- HTTP
GET|POST /admin/providers, GET /admin/providers/catalog, GET|DELETE /admin/providers/:id - HTTP
POST /admin/providers/:id/test, GET /admin/providers/:id/instances, GET /admin/providers/:id/breaker - HTTP
POST /admin/providers/:id/deploy - HTTP
DELETE /admin/providers/:id/instances/:instance_id, POST /admin/providers/:id/instances/:instance_id/resize - CLI
kynetra provider import-env digitalocean --name <name> [--env VAR] [--rotate]
- Not a tested installer. The tests that exercise deploy, list or destroy requests cover DigitalOcean (9 unit tests, most against a mock server, plus gated live tests), QuantumOS (5), Oracle (2) and Azure (1). The AWS, Google Cloud, Fly, Heroku, Railway, Render, Linode, Vultr, Neon, Supabase and Cloudflare adapters have no request-level test.
- The one live check is opt-in and needs your own token. It deploys a generic public test container to DigitalOcean App Platform, resizes it and destroys it. It does not deploy KynetraDB.
- You supply the image. The site does not document a published KynetraDB image in this edition, and AWS App Runner accepts ECR images and refuses others.
- No adapter creates or attaches a persistent volume for the data directory. Treat storage on a container service as ephemeral unless you point the instance at PostgreSQL through its environment: set KYNETRA_STORAGE_BACKEND to postgres or pg, together with KYNETRA_PG_URL. Any other value of KYNETRA_STORAGE_BACKEND is not rejected. The server logs that it is using the file log and starts on local files, so a misspelt value leaves you on ephemeral storage without an error.
- Heroku deploy creates the app and its configuration. Releasing the image is up to you.
- The Cloudflare adapter offers inventory and edge-gateway calls, with no deploy or destroy. Supabase and Neon create PostgreSQL projects.
- The deployment page lists target profiles with manifests and notes. Those are not installers either, and this entry is separate from them.
- HTTP
Cluster deployment
Creates one node, or a primary with two replicas, on a registered provider with the replication environment already wired.
BetaSurfaces and limits: Cluster deployment
POST /admin/v1/clusters deploys one KynetraDB node, or a primary plus two replicas for the high-availability option, through a provider adapter and records the result. The replicas start in the replica role and point at the primary URL. Profiles whose promised behaviour the code does not configure, such as sharded and PostgreSQL-durability high availability, are refused. The path where every node deploys successfully is not exercised against a provider in the engine tests.
- HTTP
POST /admin/v1/clusters, GET /admin/v1/clusters, GET|DELETE /admin/v1/clusters/:id - HTTP
GET /admin/v1/clusters/catalog, POST /admin/v1/clusters/estimate - HTTP
GET /admin/v1/clusters/:id/topology, GET /admin/v1/clusters/:id/connection - Config
KYNETRA_CLUSTER_IMAGE (default container image for cluster nodes)
- The success path, where every node deploys, is not exercised against a live or mock provider in the engine repository. The tests cover the catalogue, cost arithmetic, admission refusals, the profile rules and entity round trips.
- High availability here means a primary with two read replicas created together. The cluster code does not elect a leader or move traffic when a node fails. The catalogue text for the option carries an availability label; treat it as descriptive text, not a commitment.
- The storage minimum and limit, the cluster name and the engine label are set on nodes as environment variables that no code in the server reads, so they do not size or cap storage.
- Nodes use the image in the request or in KYNETRA_CLUSTER_IMAGE, with a default compiled into the server. This edition does not document a published image, so set one explicitly. AWS needs an ECR image.
- The role endpoints under a cluster are placeholders. They return a connection string in the PostgreSQL URL form and a role that stays in pending_provision, and KynetraDB does not speak the PostgreSQL wire protocol. Do not use them.
- DELETE destroys each member through its provider adapter and then removes the cluster record even if a member could not be destroyed. Read destroy_errors in the response and check the provider console for anything left running.
- Catalogue prices are descriptive values for the estimate. They are not provider billing.
- No adapter attaches persistent storage, as described under cloud provider adapters.
- HTTP
Infrastructure job ledger and lifecycle records
Records every provider destroy, resize and inventory request as a durable job, and keeps planning state for storage growth, replica failover, resource health and spend budgets.
BetaSurfaces and limits: Infrastructure job ledger and lifecycle records
Two route groups for platform administrators. /admin/v1/infra-ops runs destroy, resize and inventory jobs against the provider adapters and keeps them in a durable ledger that survives restarts. /admin/v1/infra-lifecycle stores autoscaling policies, failover state, health observations and budgets, and computes decisions from facts you supply. It does not resize disks, promote replicas or move traffic.
- HTTP
POST|GET /admin/v1/infra-ops/jobs, GET /admin/v1/infra-ops/jobs/:id, POST /admin/v1/infra-ops/jobs/:id/cancel, POST /admin/v1/infra-ops/jobs/:id/retry - HTTP
GET /admin/v1/infra-ops/capabilities/:provider_kind, /metrics, /telemetry, /audit - HTTP
PUT|GET /admin/v1/infra-lifecycle/autoscale/policies/:id, POST .../evaluate - HTTP
PUT|GET /admin/v1/infra-lifecycle/failover/:id, POST .../fence, .../promote, .../complete - HTTP
PUT|GET /admin/v1/infra-lifecycle/health/:ref_hash, PUT|GET .../budgets/:id, POST .../budgets/:id/spend - CLI
kynetra infra [--json] <subcommand> (needs --remote; reads capabilities, jobs and metrics)
- The job ledger inherits the provider limits: some adapters have request-level tests and others have none, and none attaches persistent storage.
- Storage autoscaling returns a decision and does not act on it. Applying a resize is refused, and the answer says that storage expansion fails closed until a provider adapter supports changing disk capacity.
- The failover records are planning state. They do not stop a primary, promote a replica or reroute traffic, and the facts they use are supplied by the caller.
- Metrics are bounded: usage records are kept in a fixed-size ring, and provider billing is reported as unknown unless a measured cost source exists.
- The routes need platform administrator authority. A project-scoped token is refused.
- HTTP
Managed PostgreSQL lifecycle
Creates, tracks and deletes provider-hosted PostgreSQL databases with a durable intent record and an ownership-checked delete, so a half-finished provider call does not leave an unknown resource.
BetaSurfaces and limits: Managed PostgreSQL lifecycle
Under /admin/databases an administrator can request a managed PostgreSQL database from DigitalOcean. A reconciler drives the request from requested to ready, and a database counts as ready after, and not before, an authenticated TLS connection has reached the intended database. It is PostgreSQL, not KynetraDB. It runs on a single local primary, and pause, resume and on-demand backup return typed unsupported answers.
- HTTP
GET|POST /admin/databases - HTTP
GET|DELETE /admin/databases/:id, GET /admin/databases/:id/credentials - HTTP
POST /admin/databases/:id/reconcile - HTTP
POST /admin/databases/:id/pause, /resume, /backup (typed 501 unsupported)
- PostgreSQL, not KynetraDB. This creates a database for your applications, or one you can point the PostgreSQL storage backend of KynetraDB at. It is not a managed KynetraDB, and managed native provisioning returns a typed unsupported answer. The storage backend is chosen with KYNETRA_STORAGE_BACKEND=postgres (or pg) and KYNETRA_PG_URL; any other value starts the server on the file log without an error, so check the spelling.
- DigitalOcean is the provider with a managed database adapter in this edition.
- It needs a standalone primary with local storage and strict durability (KYNETRA_SYNC=true). Replicas, clusters with failover, Raft, replication quorum and external storage writers are refused with a 503.
- The tests drive a scriptable fake cloud. The opt-in live DigitalOcean test covers App Platform apps, not managed databases.
- Pause, resume and on-demand backup are not supported. A backup request with auto-backup set to true at creation is refused.
- HTTP
Retrieval objectives, burn rate and alert webhooks
Turns retrieval quality and freshness signals into error budgets and burn rates, and sends a webhook when a budget is being used up too fast.
BetaSurfaces and limits: Retrieval objectives, burn rate and alert webhooks
GET /admin/db/slo/retrieval reports ten default objectives, such as availability, latency, recall, index and source freshness, saturation and policy denial, each with an error budget and a burn rate. A background task can post an incident to a webhook when a burn rate crosses a threshold in two windows. A simpler error-rate alert posts when the share of 4xx and 5xx responses exceeds a threshold. Three objectives have no data source, and recall needs an external feed.
- HTTP
GET /admin/db/slo/retrieval - HTTP
POST /admin/db/slo/retrieval/eval - HTTP
GET /admin/db/slo/retrieval/alerts - Config
KYNETRA_ERROR_WEBHOOK_URL, KYNETRA_ERROR_THRESHOLD_PCT, KYNETRA_ERROR_CHECK_INTERVAL_SECS - Config
KYNETRA_SLO_BURN_WEBHOOK_URL, KYNETRA_SLO_BURN_THRESHOLD, KYNETRA_SLO_BURN_CHECK_INTERVAL_SECS, KYNETRA_SLO_BURN_DEDUP_SECS
- Three of the ten default objectives (embedding backlog, stream lag and cache hit rate) have no data source in this edition. Recall appears once something posts evaluation results to the eval route.
- The error-rate alert is labelled as a five-minute rate in its payload, but it compares lifetime request counters and not a rolling window. A long-running instance dilutes a fresh error burst.
- Alert delivery is one POST per firing. A failed delivery is recorded and the cooldown still advances, so this is not durable retry scheduling. The payload is not signed.
- History is bounded per objective, and the number of distinct project scopes is capped.
- The reports and the alert state need platform super administrator authority.
- HTTP
No capability matches those filters. Widen the search or restore a state.