KyroDB docs

Freshness and scope

How KyroDB decides whether context is fresh, scoped, and safe to serve.

KyroDB exists to serve the right context at the right time when underlying business knowledge is changing.

That requires two contracts that are enforced together:

Contract	Question KyroDB resolves
Freshness	Has the source knowledge changed since this context was safe to serve?
Scope	Is this caller allowed to retrieve or reuse this context?

Freshness without scope can leak data. Scope without freshness can serve old facts confidently. KyroDB treats both as runtime correctness requirements.

Freshness modes

Mode	Runtime behavior
`strict`	Serve only when ownership and connector certification are strict-eligible. If strict evidence fails, return `stale_blocked`. Non-production `best_effort` can downgrade to `balanced` with `served_mode` and warnings; production rejects `best_effort` configuration.
`balanced`	Bypass stale cache first. If a fresh backend fetch fails, stale reusable context may be served as `degraded` with explicit warnings and trace diagnostics.
`eventual`	May serve stale reusable context without a fresh fetch. Stale reuse is surfaced in warnings, trace diagnostics, and diagnosis.

Use strict for flows where stale responses create customer harm, compliance risk, or operational incidents.

Use balanced when the product can tolerate explicit degraded behavior, such as showing a warning, routing to human review, or asking the user to confirm.

Use eventual only when stale context is acceptable and the caller still wants traceability.

Scope model

A retrieve request includes a scope:

{
  "tenant_id": "acme",
  "namespace": "kb",
  "app_id": "support-agent",
  "locale": "en-US",
  "auth_scope": ["support"],
  "entitlement_boundary": "pro",
  "embedding_model_id": "text-embedding-3-small",
  "reranker_version": "reranker-v2",
  "prompt_template_version": "support-v4"
}

The minimum production scope is tenant_id plus namespace.

Those fields must become executable backend filters. They cannot be comments, naming conventions, or dashboard labels.

Use additional fields when they affect safe reuse:

app_id when multiple agents have different retrieval semantics.
locale when language changes document visibility or interpretation.
auth_scope for caller permission boundaries.
entitlement_boundary for product or customer entitlement boundaries.
embedding_model_id when vector dimensions or embedding semantics differ.
reranker_version when reranking changes result ordering.
prompt_template_version when context packing changes with prompt behavior.

Top-level filters also participate in reuse isolation through the metadata filter fingerprint. freshness_mode changes serving decisions, not the reuse partition.

If two requests differ on any field that changes visibility, ranking, or interpretation, they must not share a reuse partition.

Change ownership

Freshness strength depends on what KyroDB can observe and acknowledge.

Ownership mode	What KyroDB can prove	When to use it
Write-through	Mutations are passed through KyroDB and return scoped ACK evidence.	Strongest boundary for apps that can route writes through the runtime and have a connector certified for scoped mutation ACKs.
Event-feed	Source systems emit durable scoped events that KyroDB acknowledges idempotently.	Best fit for existing business systems with reliable webhooks, CDC, jobs, or application events.
Snapshot-bundle	Retrieval is pinned to an immutable published snapshot or bundle version.	Only for connectors or deployments explicitly certified for immutable bundle support. Current pgvector and Qdrant paths should use event-feed or write-through.
Best-effort	KyroDB can retrieve, trace, and diagnose, but freshness proof is intentionally weak.	Local development or early evaluation only. Production `serve` rejects `ownership_mode=best_effort`.

For event feeds, source_event_id is required in production and is the event idempotency key. Retries should reuse it only for the same payload and must not advance freshness twice.

Failure behavior

KyroDB makes failure explicit instead of making stale context look successful.

Condition	Runtime behavior
Strict freshness cannot be proven	Return `stale_blocked`.
Fresh backend fetch fails in `balanced` mode	May serve stale cache as `degraded` with warnings if stale reuse is allowed.
`eventual` mode reuses stale context	May return `complete`, but warnings, trace diagnostics, and diagnosis expose stale reuse.
Proof-invalidating diagnostics appear	`strict` returns `stale_blocked`; `balanced` and `eventual` return `degraded` unless stale reuse is explicitly allowed, with warnings and trace diagnostics.
Console or billing is unavailable	Do not silently weaken runtime freshness.

The application should treat packet status as product logic, not logging detail.

Next guideConnectors