@voltro/kv 0.86.0 → 0.87.0

package/README.md

@@ -24,3 +24,113 @@ deliberately short so there is nothing here to drift out of date.
 
 Proprietary. © 2026 Voltro UG. Your use is governed by the
 [Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.
+## Native Redis topologies
+
+RESP connection URLs distinguish standalone Redis, Cluster seeds and Sentinel
+master groups. Secure schemes retain certificate verification; Sentinel can use
+separate control credentials. Default and batch reads stay on primaries, scans visit
+discovered primaries and cross-slot deletion has no cross-key atomicity promise.
+Scheme names are case insensitive. Static, environment and tenant-resolved
+credentials share metadata admission before transport acquisition.
+Nonzero standalone/Sentinel databases require confirmed SELECT on every socket;
+failed selection closes the transport instead of allowing database-zero commands.
+Owned Pub/Sub sockets report gaps and acknowledge restored subscriptions before
+reconnection. See [connections](https://docs.voltro.dev/docs/caching/connections)
+for URL admission, migration, ownership and explicit eventual reads. Individual
+HotStore reads may request `consistency: 'eventual'`; the connection selects
+`readFrom: 'primary' | 'replica' | 'nearest'` through an owned read-only
+port. Native/HTTP Lua uses EVAL_RO. `nearest` probes fresh roundtrip times.
+Readers share tenant prefixes, rotation, leases and shutdown with the primary.
+A lost mutation response is an unknown outcome and never authorizes replay.
+
+## Named Analytics
+
+Declare analytical destinations under `connections.analytics` and select the
+app-wide sink with `analytics: { connection: 'analytics:warehouse' }`. The
+app owns the pool; handlers and plugins borrow it. Install the selected
+provider package in the app. DuckDB does not require an application SQL store.
+
+```ts
+import { env } from '@voltro/kv/connection'
+
+export default {
+  name: 'analyticsApp',
+  type: 'api',
+  store: 'memory',
+  connections: {
+    analytics: {
+      warehouse: { provider: 'duckdb', path: env('DUCKDB_PATH') },
+    },
+    defaults: { analytics: 'warehouse' },
+  },
+  analytics: { connection: 'analytics:warehouse' },
+}
+```
+
+Declarations use `provider: 'duckdb' | 'clickhouse' | 'tinybird' | 'posthog'`.
+Endpoints and credentials use `env()`; DuckDB paths may use strings or `env()`.
+Operator overrides use `CONNECTIONS_ANALYTICS_<NAME>_<FIELD>`, including
+`URL`, `USERNAME`, `PASSWORD`, `PATH`, `TOKEN`, `API_URL`, `API_KEY` and `HOST`.
+The provider, identifiers, mirror tables and batching policy remain declared.
+Production network destinations require HTTPS. Missing credentials refuse boot.
+
+DuckDB and ClickHouse initialize their event schema before the read-only
+readiness query; Tinybird checks the configured aggregate pipe without emitting
+an event. PostHog acquisition currently refuses: its capture-key read-only probe
+is unfinished. It is not a silent noop or an event-writing health check.
+
+`dynamicAnalytics(resolve, { ttlMs })` declares a tenant-owned destination.
+Borrow it with `registry.analytics('analytics:tenant', { tenantId })`; declaration
+validation and inventory do not invoke the resolver. App-wide Analytics selection
+requires a static declaration. A tenant-scoped destination must be borrowed in
+its tenant context. The registry owns TTL/LRU bounds and disposal.
+
+Borrowed sinks follow `registry.reload` and the app owner's SIGHUP handling.
+Replacement readiness, provider, capabilities and mirror schema are checked
+before switching; failure retains the old generation. Accepted calls retain
+their generation until completion. Sink disposal never closes another consumer's
+shared pool. Closing the app owner refuses new operations and awaits cleanup.
+
+Connection inventory, the shared Connections panel and `voltro doctor
+--connections` include Analytics references without paths, endpoints,
+credentials or tenant IDs. Doctor probes initialize the provider schema before
+measuring a read-only query; they do not prove event delivery or capacity.
+Dynamic operator probes require an explicit tenant context.
+
+Tests can inject an `AnalyticsConnectionConnector` into the registry or pass
+`connectAnalytics` in `withConnections` options. The connector returns a sink,
+read-only probe and owned close Effect. Tests must still supply valid declarations.
+The browser-safe port and errors are exported from `@voltro/kv/analytics`; the
+runtime re-exports the same contract without a second error implementation.
+
+## Unavailable read policy
+
+Plugin connection roles declare `onUnavailable: 'degrade' | 'fail'`; omitted
+policy means `fail`. The app passes each admitted role policy into plugin
+lifecycle and store-binding contexts and shows it in connection inventory.
+`readHotStoreWithFallback` from `@voltro/kv/hot/contract` exposes only HotStore
+read methods. Under `degrade`, a typed unavailable read selects the caller's
+explicit fallback once. SQL remains the durable source; the helper does not
+write, rebuild or retry. Other failures and interruption remain failures.
+Never invoke it from a Room tick.
+
+## Conditional lease ownership
+
+`HotStore.compareDelete` and `compareExpire` atomically compare a `setNx` lease
+value before removal or TTL renewal. Missing, expired and mismatched values
+return false without changing a successor. Other structures fail with wrongType.
+Use a fresh server-owned value per acquisition, outside ticks. Temporary leases
+do not replace durable SQL revision/epoch fencing. Replacement ports must implement
+both operations and their atomic batch variants; migration
+`0.87.0/67_hot-store-conditional-leases` reports the contract. See the bilingual
+[HotStore guide](https://docs.voltro.dev/docs/caching/hot-store).
+
+## Native command timeouts
+
+RESP declarations, resolved dynamic configuration and direct `connect` accept
+`connectTimeoutMs` and `commandTimeoutMs`. Values are integer milliseconds from
+1 through 2147483647; HTTP/memory refuse them. Native primary, reader and
+subscriber construction shares these settings. A timed-out write remains an
+unknown outcome, not cancelled or safe to replay. Existing ownership and
+no-resend behavior remain authoritative. These are per-transport limits, not
+an aggregate business-operation deadline. See the bilingual connections guide.