@voltro/kv 0.86.0 → 0.87.0

package/dist/connection.d.ts

@@ -1,12 +1,384 @@
+import { CircuitState } from '@voltro/shared';
 import { Config } from 'effect';
+import { ConfigProvider } from 'effect';
 import { Context } from 'effect';
 import { Duration } from 'effect/Duration';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
 import { Schedule } from 'effect';
 import { Schema } from 'effect';
+import { Scope } from 'effect';
+import { SqlClient } from 'effect/sql';
+import { Stream } from 'effect';
 import { YieldableError } from 'effect/Cause';
 
+declare interface AggregateQuery {
+    readonly event: string;
+    readonly filter?: PropertyFilter;
+    readonly metric: AnalyticsMetric;
+    readonly range: TimeRange;
+    /**
+     * Restrict the read to one tenant's events. `useAnalytics()` injects the
+     * caller's `subject.tenantId` automatically, so handler code never sets
+     * this; a sink that honours it (e.g. analytics-postgres) then AND-filters
+     * by tenant so a query can't read across tenants. `null`/absent = unscoped
+     * (system/cross-tenant read).
+     */
+    readonly tenantId?: string | null;
+}
+
+declare interface AnalyticsBucket {
+    readonly bucketStart: Date;
+    readonly value: number;
+}
+
+/**
+ * The sink doesn't implement this capability. PostHog returns this
+ * for `aggregate`/`timeseries`/`topN`. Callers typically
+ * `Effect.catchTag('AnalyticsCapabilityNotSupported', ...)` to fall
+ * back to a different sink or report the missing feature.
+ */
+declare class AnalyticsCapabilityNotSupported extends AnalyticsCapabilityNotSupported_base {
+}
+
+declare const AnalyticsCapabilityNotSupported_base: Schema.Class<AnalyticsCapabilityNotSupported, Schema.TaggedStruct<"AnalyticsCapabilityNotSupported", {
+    readonly provider: Schema.String;
+    readonly capability: Schema.String;
+}>, YieldableError>;
+
+declare interface AnalyticsConnectionBatch {
+    readonly maxSize?: number;
+    readonly flushIntervalMs?: number;
+}
+
+export declare type AnalyticsConnectionConfig = AnalyticsOptions & ConnectionMetadata & {
+    readonly source?: 'config' | 'environment' | 'override';
+};
+
+export declare type AnalyticsConnectionConnector = (config: AnalyticsConnectionConfig) => Effect.Effect<AnalyticsConnectionTransport, KvError>;
+
+export declare type AnalyticsConnectionDefinition = DeclareEach<AnalyticsOptions> & ConnectionMetadata;
+
+/** Physical transport returned only to the registry, never to a consumer. */
+export declare interface AnalyticsConnectionTransport {
+    readonly sink: AnalyticsSinkImpl;
+    readonly probe: Effect.Effect<void, KvError>;
+    readonly close: Effect.Effect<void>;
+}
+
+/**
+ * The underlying sink raised an error. `cause` is stringified for
+ * round-trip safety across the rpc boundary.
+ */
+declare class AnalyticsError extends AnalyticsError_base {
+    get message(): string;
+}
+
+declare const AnalyticsError_base: Schema.Class<AnalyticsError, Schema.TaggedStruct<"AnalyticsError", {
+    readonly provider: Schema.String;
+    readonly operation: Schema.String;
+    readonly cause: Schema.String;
+}>, YieldableError>;
+
+/**
+ * One analytics event. `properties` must be JSON-serialisable —
+ * individual sinks validate at write time (Postgres stores as JSONB;
+ * ClickHouse encodes as a JSON string; PostHog forwards verbatim).
+ */
+declare interface AnalyticsEvent {
+    /** Event name (e.g. `'match_completed'`, `'page_viewed'`). */
+    readonly name: string;
+    /** Subject id (typically `ctx.request.subject.id`) — anonymous when null. */
+    readonly subjectId?: string | null;
+    /**
+     * Owning tenant. Normally you DON'T set this by hand — `useAnalytics()`
+     * stamps it from the caller's `subject.tenantId` so every event is
+     * tenant-attributable + every read is tenant-scoped (the multi-tenant
+     * isolation default). Set it explicitly only for a cross-tenant system
+     * write. `null` = no tenant (system/anonymous).
+     */
+    readonly tenantId?: string | null;
+    /** Property bag. Values must be JSON-serialisable. */
+    readonly properties: Readonly<Record<string, unknown>>;
+    /** When the event occurred. Defaults to server-now when omitted. */
+    readonly occurredAt?: Date;
+}
+
+declare type AnalyticsFailure = AnalyticsError | AnalyticsCapabilityNotSupported;
+
+/** Metric to compute. `count` = row count, `unique` = distinct subjectId,
+ *  `sum` / `avg` = numeric aggregation on a property field. */
+declare type AnalyticsMetric = 'count' | 'unique' | {
+    readonly sum: string;
+} | {
+    readonly avg: string;
+};
+
+/**
+ * Optional CDC-mirror capability. A sink that declares `mirror` opts in
+ * to receiving the main DataStore's reactive-table changes, so
+ * analytical queries can JOIN warehouse events against live user data
+ * (`SELECT … FROM voltro_events e JOIN users u ON …`).
+ *
+ * The framework subscribes to `DataStore.onChange` once at boot, filters
+ * to the tables the sink lists in `tables`, and routes each change here.
+ * Inserts/updates `upsert` by primary key; deletes `remove`. Every call
+ * MUST be idempotent — the same change may be re-delivered after a
+ * reconnect, and the upsert is keyed on `primaryKey` so re-applying a
+ * row is a no-op-equivalent overwrite.
+ *
+ * Idempotent is not enough on its own: re-delivery can also arrive OUT
+ * OF ORDER, so both methods additionally receive a {@link MirrorVersion}
+ * and MUST ignore a write whose version is not greater than the version
+ * already stored for that key (ClickHouse gets this from
+ * `ReplacingMergeTree(version)`; DuckDB from an `ON CONFLICT … WHERE
+ * excluded.version > version` guard).
+ */
+declare interface AnalyticsMirrorImpl {
+    /** Reactive tables this sink mirrors. The framework only forwards
+     *  changes whose `table` is in this set. */
+    readonly tables: ReadonlyArray<string>;
+    /** Primary-key column the sink upserts/deletes by. Defaults to `'id'`
+     *  when omitted. */
+    readonly primaryKey?: string;
+    /** Apply an insert/update. Idempotent upsert keyed on `primaryKey`,
+     *  version-guarded by `write.version`. */
+    readonly upsert: (write: AnalyticsMirrorUpsert) => Effect.Effect<void, AnalyticsFailure>;
+    /** Apply a delete. Idempotent — removing an absent key is a no-op —
+     *  and version-guarded by `write.version`. */
+    readonly remove: (write: AnalyticsMirrorRemove) => Effect.Effect<void, AnalyticsFailure>;
+    /**
+     * The highest version this sink has PERSISTED for one key — `null` when
+     * the key has never been written (a tombstoned key still reports its
+     * tombstone's version; both warehouse sinks keep tombstones for exactly
+     * this reason).
+     *
+     * This is the fleet-scope seed read: a replica that joins mid-stream has
+     * no per-key history of its own, so before its first write to a key it
+     * asks the warehouse where the fleet already is and continues from
+     * there. Without it a joiner would restart the key's versions low and
+     * every write it produced would be silently rejected by the sink's own
+     * `version >` guard. Called at most once per key per process (off the
+     * commit path, inside the per-key drain worker), never per change.
+     */
+    readonly maxVersion: (input: {
+        readonly table: string;
+        readonly primaryKeyValue: unknown;
+    }) => Effect.Effect<MirrorVersion | null, AnalyticsFailure>;
+}
+
+/** One delete to apply to the mirror. */
+declare interface AnalyticsMirrorRemove {
+    readonly table: string;
+    /** Primary-key value of the removed row. */
+    readonly primaryKeyValue: unknown;
+    /** See {@link MirrorVersion}. A delete is ordered against upserts of
+     *  the same key by exactly this number. */
+    readonly version: MirrorVersion;
+}
+
+/** One insert/update to apply to the mirror. */
+declare interface AnalyticsMirrorUpsert {
+    readonly table: string;
+    /** Post-image of the changed row. */
+    readonly row: Readonly<Record<string, unknown>>;
+    /** See {@link MirrorVersion} — persist it, compare against it, never
+     *  replace it with a local clock reading. */
+    readonly version: MirrorVersion;
+}
+
+declare type AnalyticsOptions = ({
+    readonly provider: 'duckdb';
+    readonly path?: string;
+} & MirrorOptions) | ({
+    readonly provider: 'clickhouse';
+    readonly url: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly database?: string;
+    readonly table?: string;
+    readonly batch?: AnalyticsConnectionBatch | false;
+} & MirrorOptions) | {
+    readonly provider: 'tinybird';
+    readonly token: string;
+    readonly apiUrl?: string;
+    readonly region?: string;
+    readonly datasource?: string;
+    readonly pipes?: {
+        readonly aggregate?: string;
+        readonly timeseries?: string;
+        readonly topN?: string;
+    };
+} | {
+    readonly provider: 'posthog';
+    readonly apiKey: string;
+    readonly host?: string;
+    readonly batch?: AnalyticsConnectionBatch;
+};
+
+/**
+ * The runtime contract every analytics provider implements. Plugins
+ * build a value of this shape inside their factory function and the
+ * framework wires it under `AnalyticsSink` for handler code to consume.
+ */
+declare interface AnalyticsSinkImpl {
+    readonly info: AnalyticsSinkInfo;
+    readonly track: (event: AnalyticsEvent) => Effect.Effect<void, AnalyticsFailure>;
+    readonly aggregate: (query: AggregateQuery) => Effect.Effect<number, AnalyticsFailure>;
+    readonly timeseries: (query: TimeseriesQuery) => Effect.Effect<ReadonlyArray<AnalyticsBucket>, AnalyticsFailure>;
+    readonly topN: (query: TopNQuery) => Effect.Effect<ReadonlyArray<AnalyticsTopEntry>, AnalyticsFailure>;
+    /**
+     * Present when the sink mirrors reactive tables (opt-in via the
+     * plugin's `mirrorTables` config). Absent → no mirroring; the
+     * framework skips wiring `DataStore.onChange` for this sink.
+     */
+    readonly mirror?: AnalyticsMirrorImpl;
+}
+
+/**
+ * Per-sink metadata surfaced via the manifest endpoint + dashboard.
+ * Lets the operator see at a glance which provider is wired + what
+ * it supports without grepping app.config.ts.
+ */
+declare interface AnalyticsSinkInfo {
+    readonly provider: string;
+    readonly capabilities: {
+        readonly track: boolean;
+        readonly aggregate: boolean;
+        readonly timeseries: boolean;
+        readonly topN: boolean;
+        /** True when the sink mirrors reactive tables into the warehouse so
+         *  analytical queries can JOIN events against live user data. */
+        readonly mirror: boolean;
+    };
+    /** Optional plugin-supplied detail (`{ ingestBufferDepth: 42 }`,
+     *  `{ url: 'https://eu.posthog.com' }`, etc.) — surfaced verbatim. */
+    readonly detail?: Readonly<Record<string, unknown>>;
+}
+
+declare interface AnalyticsTopEntry {
+    readonly key: string;
+    readonly value: number;
+}
+
+/** Select one dynamic definition; tenant identity is passed separately to its resolver. */
+export declare const byTenant: (target: ConnectionRef<"redis">) => ConnectionRoute;
+
+declare type ByteStream = Stream.Stream<Uint8Array, StorageError>;
+
+/** One cache program. Every accessed key is declared; memberships are versioned. */
+export declare const CACHE_ATOMIC_SCRIPT: string;
+
+/**
+ * How long an invalidation's epoch stays observable. A compute that runs longer
+ * than this can no longer prove no invalidation overtook it, so `Cache.wrap`
+ * does not store its result.
+ */
+export declare const CACHE_FENCE_RETENTION_MS = 900000;
+
+/** Empty Lua arrays encode as {}; this applies only to known metadata arrays. */
+export declare const cacheAtomicArray: (input: unknown) => ReadonlyArray<unknown>;
+
+export declare type CacheAtomicCommand = {
+    readonly op: 'revision';
+} | {
+    readonly op: 'fence';
+} | {
+    readonly op: 'inspect';
+    readonly key: string;
+} | {
+    readonly op: 'inspect-values';
+    readonly keys: ReadonlyArray<string>;
+} | {
+    readonly op: 'read';
+    readonly key: string;
+    readonly snapshot: CacheAtomicSnapshot | null;
+} | {
+    readonly op: 'tag';
+    readonly tag: string;
+} | {
+    readonly op: 'scan';
+    readonly cursor: string;
+} | {
+    readonly op: 'write';
+    readonly key: string;
+    readonly snapshot: CacheAtomicSnapshot | null;
+    readonly version: string;
+    readonly revision: string;
+    readonly tags: ReadonlyArray<string>;
+    readonly value: string;
+    readonly ttlMs: number | null;
+    readonly fence: number | null;
+} | {
+    readonly op: 'remove';
+    readonly key: string;
+    readonly snapshot: CacheAtomicSnapshot | null;
+    readonly revision: string;
+} | {
+    readonly op: 'invalidate';
+    readonly tag: string;
+    readonly members: ReadonlyArray<string>;
+    readonly snapshots: ReadonlyArray<CacheAtomicValueSnapshot>;
+    readonly revision: string;
+} | {
+    readonly op: 'clear';
+    readonly keys: ReadonlyArray<string>;
+    readonly revision: string | null;
+};
+
+/** JSON before UTF-8 preserves distinct JS strings containing lone surrogates. */
+export declare const cacheAtomicComponent: (value: string) => string;
+
+/** All keys accessed by Lua are declared here, including prior tag memberships. */
+export declare const cacheAtomicKeys: (root: string, command: CacheAtomicCommand) => ReadonlyArray<string>;
+
+export declare const cacheAtomicMember: (input: unknown) => {
+    readonly version: string;
+    readonly key: string;
+};
+
+/** Replaced values have independent membership identities, never a bare key. */
+export declare const cacheAtomicMembership: (key: string, valueVersion: string) => string;
+
+export declare interface CacheAtomicPolicy {
+    readonly maxTagMembers?: number;
+    readonly maxReplyBytes?: number;
+}
+
+/** Shared command admission for native cache scripts, local transport and broker. */
+export declare class CacheAtomicProtocolError extends Error {
+    constructor();
+}
+
+export declare interface CacheAtomicReply {
+    readonly status: 'ok' | 'conflict' | 'limit';
+    readonly value: unknown;
+}
+
+/** Every cache namespace owns one Redis Cluster hash slot. */
+export declare const cacheAtomicRoot: (prefix: string) => string;
+
+export declare const cacheAtomicScanPage: (root: string, input: unknown) => {
+    readonly cursor: string;
+    readonly keys: ReadonlyArray<string>;
+};
+
+export declare interface CacheAtomicSnapshot {
+    readonly version: string;
+    readonly tags: ReadonlyArray<string>;
+}
+
+export declare const cacheAtomicSnapshot: (input: unknown) => CacheAtomicSnapshot | null;
+
+export declare const cacheAtomicTtl: (ttlMs: number | undefined) => number | null;
+
+export declare interface CacheAtomicValueSnapshot {
+    readonly key: string;
+    readonly snapshot: CacheAtomicSnapshot | null;
+}
+
+export declare const cacheAtomicValueSnapshots: (input: unknown) => ReadonlyArray<CacheAtomicValueSnapshot>;
+
 /** Bounded retry for transient command failures (network blip). Connect is
  *  NOT retried — a bad url should fail loud at boot. Re-exported so consumers
  *  wrap their own command runners consistently. */
@@ -20,9 +392,256 @@ export declare const commandRetry: Schedule.Schedule< Duration, unknown, never,
  */
 export declare const connect: (config: RedisConnectionConfig) => Effect.Effect<RespClient, KvError>;
 
-export declare const connectionConfig: (name: string) => Effect.Effect<RedisConnectionConfig, Config.ConfigError>;
+/** Resolve an explicit kind:name, a configured default, or the established env convention. */
+export declare function connectionConfig(reference: string): Effect.Effect<RedisConnectionConfig, Config.ConfigError>;
+
+export declare function connectionConfig(reference: string, definitions: RedisConnectionsConfig, context?: ConnectionContext): Effect.Effect<RedisConnectionConfig, Config.ConfigError | KvError>;
+
+export declare interface ConnectionContext {
+    readonly tenantId: string;
+}
+
+/** Reject malformed runtime configuration before reading declarations or opening sockets. */
+export declare const connectionDefinitionsProblem: (config: ConnectionsConfig) => string | undefined;
+
+/** An environment declaration, never the environment value itself. */
+export declare interface ConnectionEnv {
+    readonly _tag: 'ConnectionEnv';
+    readonly name: string;
+}
+
+/** A connection's kind is part of its reference, so consumers cannot mix ports. */
+export declare type ConnectionKind = 'redis' | 'nats' | 'storage' | 'analytics' | 'sql';
+
+export declare interface ConnectionMetadata {
+    readonly tls?: 'auto' | 'required';
+    readonly persistence?: 'required' | 'optional' | 'none';
+    readonly keyPrefix?: string;
+    /** Explicit opt-in when a production connection intentionally uses a shared namespace. */
+    readonly allowSharedNamespace?: boolean;
+    readonly region?: string;
+    readonly label?: string;
+    readonly acl?: string;
+}
+
+export declare interface ConnectionNamespaceIdentity {
+    readonly appName: string;
+    readonly environment: string;
+}
+
+export declare interface ConnectionPoolSnapshot {
+    readonly reference: string;
+    readonly dynamic: boolean;
+    readonly activeCommands: number;
+    readonly activeSubscriptions: number;
+    readonly subscribedChannels: number;
+    readonly commands: number;
+    readonly errors: number;
+    readonly latencyMs: number | null;
+    readonly state: CircuitState;
+    readonly source: 'config' | 'environment' | 'override';
+    readonly label?: string;
+    readonly region?: string;
+    readonly persistence?: RedisConnectionConfig['persistence'];
+}
+
+/** Borrowed Pub/Sub port. A consumer owns registrations, never broker sockets. */
+export declare interface ConnectionPubSub {
+    readonly publish: (channel: string, payload: string) => Effect.Effect<void, KvError>;
+    readonly subscribe: (channel: string, handler: (payload: string) => void) => Effect.Effect<Effect.Effect<void>, KvError>;
+    readonly onTransportEvent: (listener: (event: ConnectionTransportEvent) => void) => () => void;
+    readonly close: Effect.Effect<void>;
+}
+
+export declare type ConnectionRef<K extends ConnectionKind = ConnectionKind> = `${K}:${string}`;
+
+export declare class ConnectionRegistry extends ConnectionRegistry_base {
+}
+
+declare const ConnectionRegistry_base: Context.ServiceClass<ConnectionRegistry, "@voltro/ConnectionRegistry", ConnectionRegistryShape>;
+
+export declare interface ConnectionRegistryOptions {
+    readonly connections?: ConnectionsConfig;
+    readonly requirements?: ReadonlyArray<ConnectionRequirement>;
+    /** App identity for declared connection namespaces; low-level registries may supply it explicitly. */
+    readonly namespaceIdentity?: ConnectionNamespaceIdentity;
+    /** Raw driver injection; namespace wrapping belongs to the registry, not the transport. */
+    readonly connect?: (config: RedisConnectionConfig) => Effect.Effect<RespClient, KvError>;
+    readonly connectStorage?: StorageConnectionConnector;
+    readonly connectAnalytics?: AnalyticsConnectionConnector;
+    readonly connectSql?: SqlConnectionConnector;
+    readonly connectNats?: (config: NatsConnectionConfig) => Effect.Effect<NatsTransport, KvError>;
+    readonly connectSubscriber?: (config: RedisConnectionConfig) => Effect.Effect<RespSubscriber, KvError>;
+    readonly failureThreshold?: number;
+    readonly resetTimeoutMs?: number;
+    /** Completed, redacted whole-registry attempts. Observers cannot change admission. */
+    readonly onRotation?: (event: ConnectionRotationEvent) => void;
+}
+
+export declare interface ConnectionRegistryShape {
+    readonly validate: (reference: ConnectionRef<'redis' | 'nats' | 'storage' | 'analytics' | 'sql'> | '') => Effect.Effect<ConnectionValidation, Config.ConfigError>;
+    readonly client: (reference: ConnectionRef<'redis'> | '', context?: ConnectionContext) => Effect.Effect<RespClient, KvError | Config.ConfigError>;
+    readonly config: {
+        (reference: ConnectionRef<'redis'> | '', context?: ConnectionContext): Effect.Effect<RedisConnectionConfig, Config.ConfigError>;
+        (reference: ConnectionRef<'nats'>, context?: ConnectionContext): Effect.Effect<NatsConnectionConfig, Config.ConfigError>;
+        (reference: ConnectionRef<'storage'>, context?: ConnectionContext): Effect.Effect<StorageConnectionConfig, Config.ConfigError>;
+        (reference: ConnectionRef<'analytics'>, context?: ConnectionContext): Effect.Effect<AnalyticsConnectionConfig, Config.ConfigError>;
+        (reference: ConnectionRef<'sql'>, context?: ConnectionContext): Effect.Effect<SqlConnectionConfig, Config.ConfigError>;
+        (reference: ConnectionRef<'redis' | 'nats' | 'storage' | 'analytics' | 'sql'> | '', context?: ConnectionContext): Effect.Effect<RedisConnectionConfig | NatsConnectionConfig | StorageConnectionConfig | AnalyticsConnectionConfig | SqlConnectionConfig, Config.ConfigError>;
+    };
+    readonly sql: (reference: ConnectionRef<'sql'>, context?: ConnectionContext) => Effect.Effect<SqlConnection, KvError | Config.ConfigError>;
+    readonly analytics: (reference: ConnectionRef<'analytics'>, context?: ConnectionContext) => Effect.Effect<AnalyticsSinkImpl, KvError | Config.ConfigError>;
+    readonly storage: (reference: ConnectionRef<'storage'>, context?: ConnectionContext) => Effect.Effect<StorageProvider, KvError | Config.ConfigError>;
+    readonly pubsub: (reference: ConnectionRef<'redis' | 'nats'> | '', context?: ConnectionContext) => Effect.Effect<ConnectionPubSub, KvError | Config.ConfigError>;
+    /** Read-only native round trip; never a store write or event publication. */
+    readonly probe: (reference: ConnectionRef<'redis' | 'nats' | 'storage' | 'analytics' | 'sql'> | '', context?: ConnectionContext) => Effect.Effect<void, KvError | Config.ConfigError>;
+    /** Prepare every replacement, swap atomically, then drain old generations. */
+    readonly reload: Effect.Effect<void, KvError | Config.ConfigError>;
+    /** Redacted operational metadata: never URLs, credentials or tenant IDs. */
+    readonly inspect: Effect.Effect<ReadonlyArray<ConnectionPoolSnapshot>>;
+    readonly redis: RespConnections;
+}
+
+export declare interface ConnectionRequirement extends Omit<RedisConnectionRequirement, 'reference'> {
+    readonly reference: ConnectionRef<'redis' | 'nats' | 'storage' | 'analytics' | 'sql'> | '';
+}
+
+export declare interface ConnectionRotationEvent {
+    readonly sequence: number;
+    readonly startedAt: number;
+    readonly durationMs: number;
+    readonly outcome: 'succeeded' | 'failed';
+}
+
+export declare interface ConnectionRoute {
+    readonly _tag: 'ConnectionRoute';
+    /** Stateful allocation routes cannot address existing keys in a HotStore. */
+    readonly keyAffinity?: boolean;
+    readonly connections: ReadonlyArray<ConnectionRef<'redis'>>;
+    readonly select: (context: {
+        readonly key: string;
+        readonly tenantId?: string;
+    }) => ConnectionRef<'redis'>;
+}
+
+/** App registry configuration; protocol-specific command APIs retain their narrower config. */
+export declare interface ConnectionsConfig extends RedisConnectionsConfig {
+    readonly nats?: Readonly<Record<string, NatsConnectionDefinition | DynamicNatsConnection>>;
+    readonly storage?: Readonly<Record<string, StorageConnectionDefinition | DynamicStorageConnection>>;
+    readonly analytics?: Readonly<Record<string, AnalyticsConnectionDefinition | DynamicAnalyticsConnection>>;
+    readonly sql?: Readonly<Record<string, SqlConnectionDefinition | DynamicSqlConnection>>;
+    readonly defaults?: {
+        readonly redis?: string;
+        readonly nats?: string;
+        readonly storage?: string;
+        readonly analytics?: string;
+        readonly sql?: string;
+    };
+}
+
+/** Physical subscription adapter. Logical consumer ownership belongs to the registry. */
+export declare interface ConnectionSubscriberTransport {
+    readonly subscribe: (channel: string) => Promise<void>;
+    readonly unsubscribe: (channel: string) => Promise<void>;
+    readonly onMessage: (listener: (channel: string, payload: string) => void) => () => void;
+    readonly onTransportEvent: (listener: (event: ConnectionTransportEvent) => void) => () => void;
+    readonly close: () => Promise<void>;
+}
+
+/** Facts shared by native broker transports; no broker promises event replay. */
+export declare interface ConnectionTransportEvent {
+    readonly kind: 'disconnected' | 'reconnected';
+}
+
+/** Consumers choose an explicit read fallback or preserve an unavailable failure. */
+export declare type ConnectionUnavailablePolicy = 'degrade' | 'fail';
+
+/** Declaration admission without resolving tenant-owned credentials or opening a socket. */
+export declare interface ConnectionValidation {
+    readonly reference: string;
+    readonly tenantScoped: boolean;
+}
+
+/** Dedicated RESP transport. The registry owns sockets and reconnect attempts.
+ * Restore acknowledgements precede reconnected; a gap never promises replay. */
+export declare const connectRedisSubscriber: (config: RedisConnectionConfig) => Effect.Effect<RespSubscriber, KvError>;
+
+/** No endpoint, token or resolved tenant credential is part of this manifest. */
+export declare const declaredConnectionEnv: (config: ConnectionsConfig) => ReadonlyArray<string>;
+
+declare type DeclareEach<T> = T extends AnalyticsOptions ? DeclareOptions<T> : never;
+
+declare type DeclareOptions<T> = {
+    readonly [K in keyof T]: K extends 'url' | 'username' | 'password' | 'token' | 'apiUrl' | 'apiKey' | 'host' ? ConnectionEnv | Extract<T[K], undefined> : K extends 'path' ? string | ConnectionEnv | Extract<T[K], undefined> : T[K];
+};
+
+export declare const decodeCacheAtomicCommand: (input: unknown) => CacheAtomicCommand;
+
+export declare const decodeCacheAtomicPolicy: (input: unknown) => CacheAtomicPolicy;
+
+export declare const decodeCacheAtomicReply: (raw: unknown) => CacheAtomicReply;
+
+/** Dynamic credentials stay server-side; resolution belongs to the registry scope. */
+export declare const dynamic: (resolve: DynamicRedisConnection["resolve"], options?: {
+    readonly ttlMs?: number;
+}) => DynamicRedisConnection;
+
+/** Resolve tenant-owned credentials lazily; the registry owns cache and rotation. */
+export declare const dynamicAnalytics: (resolve: DynamicAnalyticsConnection["resolve"], options?: {
+    readonly ttlMs?: number;
+}) => DynamicAnalyticsConnection;
+
+export declare interface DynamicAnalyticsConnection {
+    readonly _tag: 'DynamicAnalyticsConnection';
+    readonly resolve: (context: ConnectionContext) => Effect.Effect<AnalyticsConnectionConfig, KvError>;
+    readonly ttlMs: number;
+}
+
+/** Tenant-owned NATS credentials, resolved lazily within the app registry. */
+export declare const dynamicNats: (resolve: DynamicNatsConnection["resolve"], options?: {
+    readonly ttlMs?: number;
+}) => DynamicNatsConnection;
+
+export declare interface DynamicNatsConnection {
+    readonly _tag: 'DynamicNatsConnection';
+    readonly resolve: (context: ConnectionContext) => Effect.Effect<NatsConnectionConfig, KvError>;
+    readonly ttlMs: number;
+}
+
+export declare interface DynamicRedisConnection {
+    readonly _tag: 'DynamicRedisConnection';
+    readonly resolve: (context: ConnectionContext) => Effect.Effect<RedisConnectionConfig, KvError>;
+    readonly ttlMs: number;
+}
+
+/** Tenant resolution is lazy and owned by the existing bounded registry. */
+export declare const dynamicSql: (resolve: DynamicSqlConnection["resolve"], options?: {
+    readonly ttlMs?: number;
+}) => DynamicSqlConnection;
+
+export declare interface DynamicSqlConnection {
+    readonly _tag: 'DynamicSqlConnection';
+    readonly resolve: (context: ConnectionContext) => Effect.Effect<SqlConnectionConfig, KvError>;
+    readonly ttlMs: number;
+}
+
+export declare const dynamicStorage: (resolve: DynamicStorageConnection["resolve"], options?: {
+    readonly ttlMs?: number;
+}) => DynamicStorageConnection;
+
+export declare interface DynamicStorageConnection {
+    readonly _tag: 'DynamicStorageConnection';
+    readonly resolve: (context: ConnectionContext) => Effect.Effect<StorageConnectionConfig, KvError>;
+    readonly ttlMs: number;
+}
+
+/** Declare a credential or endpoint without reading it during module import. */
+export declare const env: (name: string) => ConnectionEnv;
+
+export declare const isCacheAtomicRead: (command: CacheAtomicCommand) => boolean;
 
 declare class KvError extends KvError_base {
+    get message(): string;
 }
 
 declare const KvError_base: Schema.Class<KvError, Schema.TaggedStruct<"KvError", {
@@ -35,6 +654,9 @@ declare const KvError_base: Schema.Class<KvError, Schema.TaggedStruct<"KvError",
     readonly cause: Schema.String;
 }>, YieldableError>;
 
+/** Install the configured registry and its existing command-consumer port together. */
+export declare const layerConfiguredConnections: (options?: ConnectionRegistryOptions) => Layer.Layer<ConnectionRegistry | RedisConnections, Config.ConfigError>;
+
 /**
  * `Layer<RedisConnections>` — the pooled registry. Each named connection is
  * opened lazily on first `client(name)`, cached, and closed when the layer's
@@ -44,14 +666,120 @@ declare const KvError_base: Schema.Class<KvError, Schema.TaggedStruct<"KvError",
  */
 export declare const layerConnections: Layer.Layer<RedisConnections>;
 
-export declare interface RedisConnectionConfig {
-    /** `redis://…` / `rediss://…` for the `resp` driver, the REST url for `http`. */
+/** Construct a scoped registry. Even a previously handed-out client follows rotation. */
+export declare const makeConnectionRegistry: (options?: ConnectionRegistryOptions) => Effect.Effect<ConnectionRegistryShape, Config.ConfigError, Scope.Scope>;
+
+export declare const memory: (options?: {
+    readonly now?: () => number;
+}) => MemoryRedisConnection;
+
+/** A local registry entry. Its clock is injectable; it opens no transport. */
+export declare interface MemoryRedisConnection {
+    readonly _tag: 'MemoryRedisConnection';
+    readonly now?: () => number;
+}
+
+declare interface MirrorOptions {
+    readonly mirrorTables?: ReadonlyArray<string>;
+    readonly mirrorPrimaryKey?: string;
+}
+
+/**
+ * Ordering token for one mirrored write.
+ *
+ * **The sink MUST persist this and MUST NOT invent its own.** It is
+ * assigned by the framework at the moment the change leaves the store's
+ * change channel — i.e. in COMMIT order — so a write with a lower
+ * version is, by construction, an older image of that row. Stamping a
+ * version at sink-call time instead (a `Date.now()` inside `upsert`)
+ * makes a late-arriving STALE image outrank the fresh one and win
+ * permanently; that is the bug this type exists to make unrepresentable.
+ *
+ * How the number is derived depends on the store's `changeScope`:
+ *
+ *   - `'local'` (one process observes each change): a hybrid clock —
+ *     wall-clock microseconds forced strictly upward, so it orders within
+ *     a millisecond and keeps increasing across a restart.
+ *   - `'fleet'` (every replica observes every change): derived from the
+ *     CHANGE, not from the receiving process — the warehouse's own max
+ *     version for the key (read once via {@link AnalyticsMirrorImpl.maxVersion})
+ *     plus the change's per-key position in the totally-ordered fleet
+ *     stream. N replicas mirroring the same change therefore stamp the
+ *     SAME number, and the sink's version guard dedupes the N duplicate
+ *     writes for free — no leader, no clock, no skew hazard.
+ */
+declare type MirrorVersion = number;
+
+export declare interface NatsConnectionConfig extends Omit<ConnectionMetadata, 'persistence'> {
     readonly url: string;
-    readonly driver: 'resp' | 'http';
+    readonly token?: string;
+    readonly user?: string;
+    readonly pass?: string;
+    readonly source?: 'config' | 'environment' | 'override';
+}
+
+export declare interface NatsConnectionDefinition extends Omit<ConnectionMetadata, 'persistence'> {
+    readonly url: ConnectionEnv;
+    readonly token?: ConnectionEnv;
+    readonly user?: ConnectionEnv;
+    readonly pass?: ConnectionEnv;
+}
+
+/** Physical core-NATS transport. Only registry generations may own this port. */
+export declare interface NatsTransport extends ConnectionSubscriberTransport {
+    readonly publish: (subject: string, payload: string) => Promise<void>;
+    readonly flush: () => Promise<void>;
+}
+
+declare interface ObjectMeta {
+    readonly size: number;
+    readonly etag?: string;
+    /** Read-only metadata for lazy, leased streaming reads. */
+    readonly contentType?: string;
+}
+
+/** Exact-match property filter. Values are AND'd. */
+declare type PropertyFilter = Readonly<Record<string, string | number | boolean | null>>;
+
+export declare interface RedisConnectionConfig extends ConnectionMetadata, RedisTimeouts {
+    /** Native Redis, Cluster/Sentinel seed URLs, or the REST URL for HTTP. */
+    readonly url: string;
+    readonly driver: 'resp' | 'http' | 'memory';
+    readonly memoryClock?: () => number;
     /** Auth token — `http` (Upstash REST) driver only. */
     readonly token?: string;
     /** Optional key namespace a deployment may layer its own prefix under. */
-    readonly keyPrefix?: string;
+    readonly cluster?: boolean;
+    readonly replicas?: ReadonlyArray<string>;
+    readonly readFrom?: 'primary' | 'replica' | 'nearest';
+    readonly maxmemoryPolicyHint?: string;
+    readonly source?: 'config' | 'environment' | 'override';
+}
+
+export declare interface RedisConnectionDefinition extends ConnectionMetadata, RedisTimeouts {
+    readonly url: ConnectionEnv;
+    readonly driver?: 'resp' | 'http';
+    readonly token?: ConnectionEnv;
+    readonly cluster?: boolean;
+    readonly replicas?: ReadonlyArray<ConnectionEnv>;
+    readonly readFrom?: 'primary' | 'replica' | 'nearest';
+    readonly maxmemoryPolicyHint?: string;
+}
+
+export declare interface RedisConnectionDiagnostics {
+    /** Every current Cluster primary, or the single standalone/Sentinel primary. */
+    readonly nodes: ReadonlyArray<RedisNodeDiagnostics>;
+}
+
+/** Transport admission requirements, attached to the same selected generation as acquisition. */
+export declare interface RedisConnectionRequirement {
+    readonly onUnavailable?: ConnectionUnavailablePolicy;
+    readonly reference: ConnectionRef<'redis'> | '';
+    readonly consumer: string;
+    readonly role: string;
+    readonly crossNode?: boolean;
+    readonly pubsub?: boolean;
+    readonly atomicMulti?: boolean;
 }
 
 export declare class RedisConnections extends RedisConnections_base {
@@ -59,11 +787,46 @@ export declare class RedisConnections extends RedisConnections_base {
 
 declare const RedisConnections_base: Context.ServiceClass<RedisConnections, "@voltro/RedisConnections", RespConnections>;
 
-/** The minimal command surface both ioredis and @upstash/redis satisfy —
- *  the superset the framework's command-only RESP consumers (cache, rate
- *  limiter, KV) need. `eval` runs a Lua script server-side (numKeys splits
- *  KEYS from ARGV, the ioredis convention); `zrange` reads a full sorted set. */
+export declare interface RedisConnectionsConfig {
+    readonly redis?: Readonly<Record<string, RedisConnectionDefinition | DynamicRedisConnection | MemoryRedisConnection>>;
+    readonly defaults?: {
+        readonly redis?: string;
+    };
+    /** App-owned selection by plugin name and declared role; plugins never choose endpoints. */
+    readonly bindings?: Readonly<Record<string, Readonly<Record<string, ConnectionRef>>>>;
+    readonly maxDynamicPools?: number;
+    readonly rotationGraceMs?: number;
+}
+
+/** Only enumerated server settings leave the transport; never raw INFO/errors. */
+export declare interface RedisNodeDiagnostics {
+    readonly persistence: 'aof' | 'snapshot' | 'none' | 'unknown';
+    readonly maxmemoryPolicy: 'noeviction' | 'allkeys-lru' | 'allkeys-lfu' | 'allkeys-random' | 'volatile-lru' | 'volatile-lfu' | 'volatile-random' | 'volatile-ttl' | 'unknown';
+}
+
+/** A consumer owns its registrations; closing it never closes shared sockets. */
+export declare interface RedisPubSub extends ConnectionPubSub {
+}
+
+/** Optional native RESP transport deadlines in integer milliseconds. */
+export declare interface RedisTimeouts {
+    /** TCP/TLS connection establishment limit; does not prove command completion. */
+    readonly connectTimeoutMs?: number;
+    /** Limit for a command reply. A write may still complete after this expires. */
+    readonly commandTimeoutMs?: number;
+}
+
+export declare interface RedisTransportEvent extends ConnectionTransportEvent {
+}
+
 export declare interface RespClient {
+    readonly readOnly?: RespReadClient;
+    /** False for a local test connection. PING never turns it into a network backend. */
+    readonly crossNode?: boolean;
+    /** Read-only round-trip probe. Custom drivers may omit it; no readiness is inferred. */
+    readonly ping?: () => Promise<string>;
+    /** Explicit read-only server-settings observation. Missing/denied fields stay unknown. */
+    readonly diagnostics?: () => Promise<RedisConnectionDiagnostics>;
     readonly get: (key: string) => Promise<string | null>;
     readonly set: (key: string, value: string) => Promise<unknown>;
     readonly psetex: (key: string, ms: number, value: string) => Promise<unknown>;
@@ -75,6 +838,8 @@ export declare interface RespClient {
         readonly cursor: string;
         readonly keys: ReadonlyArray<string>;
     }>;
+    /** Native command transport is ready again after reconnect. Registry-owned. */
+    readonly onReconnect?: (listener: () => void) => () => void;
     readonly close: () => Promise<void>;
 }
 
@@ -88,4 +853,220 @@ export declare interface RespConnections {
     readonly config: (name: string) => Effect.Effect<RedisConnectionConfig, Config.ConfigError>;
 }
 
+/** The minimal command surface both ioredis and @upstash/redis satisfy —
+ *  the superset the framework's command-only RESP consumers (cache, rate
+ *  limiter, KV) need. `eval` runs a Lua script server-side (numKeys splits
+ *  KEYS from ARGV, the ioredis convention); `zrange` reads a full sorted set. */
+/** Read-only commands. Native and HTTP Lua use EVAL_RO, never writable EVAL. */
+export declare interface RespReadClient {
+    readonly get: (key: string) => Promise<string | null>;
+    readonly exists: (key: string) => Promise<number>;
+    readonly zrange: (key: string) => Promise<ReadonlyArray<string>>;
+    readonly eval: (script: string, numKeys: number, ...args: ReadonlyArray<string | number>) => Promise<unknown>;
+}
+
+/** Dedicated RESP subscriber transport. Only the connection registry owns it. */
+export declare interface RespSubscriber extends ConnectionSubscriberTransport {
+}
+
+/** Round-robin is for independent staging keys, never a distributed key's identity. */
+export declare const roundRobin: (targets: ReadonlyArray<ConnectionRef<"redis">>) => ConnectionRoute;
+
+/** A stable, explicitly keyed shard mapping; changing its targets requires a rebuild. */
+export declare const shardBy: (options: {
+    readonly key: (key: string) => string;
+    readonly to: ReadonlyArray<ConnectionRef<"redis">>;
+}) => ConnectionRoute;
+
+/** A whole operation (including its transaction) borrows one physical generation.
+ * Do not return the client, a deferred statement or a stream from use: execute it
+ * inside the callback. Use stream for a lazy result that must retain its lease. */
+export declare interface SqlConnection {
+    readonly dialect: SqlConnectionConfig['dialect'];
+    readonly use: <A, E, R>(run: (client: SqlClient.SqlClient) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | KvError | Config.ConfigError, R>;
+    readonly stream: <A, E, R>(run: (client: SqlClient.SqlClient) => Stream.Stream<A, E, R>) => Stream.Stream<A, E | KvError | Config.ConfigError, R>;
+}
+
+/** Additional SQL target. The primary DataStore retains its own configuration. */
+export declare interface SqlConnectionConfig {
+    readonly dialect: SqlConnectionDialect;
+    readonly url: string;
+    readonly tls?: 'auto' | 'required';
+    readonly maxConnections?: number;
+    readonly acquireTimeoutMs?: number;
+    readonly acquireQueueLimit?: number;
+    readonly statementTimeoutMs?: number;
+    readonly schema?: string;
+    readonly label?: string;
+    readonly region?: string;
+    readonly source?: 'config' | 'override';
+}
+
+export declare type SqlConnectionConnector = (config: SqlConnectionConfig) => Effect.Effect<SqlConnectionTransport, KvError>;
+
+export declare interface SqlConnectionDefinition extends Omit<SqlConnectionConfig, 'url' | 'source'> {
+    readonly url: ConnectionEnv;
+}
+
+declare type SqlConnectionDialect = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' | 'turso';
+
+/** Connector-owned resources; a consumer never receives physical disposal. */
+export declare interface SqlConnectionTransport {
+    readonly client: SqlClient.SqlClient;
+    readonly probe: Effect.Effect<void, KvError>;
+    readonly close: Effect.Effect<void>;
+}
+
+/** Resolved values stay server-side and never enter inspection snapshots. */
+export declare interface StorageConnectionConfig extends ConnectionMetadata {
+    readonly provider: StorageProviderName;
+    readonly bucket?: string;
+    readonly root?: string;
+    readonly endpoint?: string;
+    readonly accessKeyId?: string;
+    readonly secretAccessKey?: string;
+    readonly accountName?: string;
+    readonly accountKey?: string;
+    readonly connectionString?: string;
+    readonly cdnBaseUrl?: string;
+    readonly forcePathStyle?: boolean;
+    readonly publicAcl?: boolean;
+    readonly source?: 'config' | 'environment' | 'override';
+}
+
+export declare type StorageConnectionConnector = (config: StorageConnectionConfig, context: StorageConnectionOpenContext) => Effect.Effect<StorageConnectionTransport, StorageError>;
+
+export declare interface StorageConnectionDefinition extends ConnectionMetadata {
+    readonly provider: StorageProviderName;
+    readonly bucket?: string | ConnectionEnv;
+    readonly root?: string | ConnectionEnv;
+    readonly endpoint?: ConnectionEnv;
+    readonly accessKeyId?: ConnectionEnv;
+    readonly secretAccessKey?: ConnectionEnv;
+    readonly accountName?: string | ConnectionEnv;
+    readonly accountKey?: ConnectionEnv;
+    readonly connectionString?: ConnectionEnv;
+    readonly cdnBaseUrl?: string | ConnectionEnv;
+    readonly forcePathStyle?: boolean;
+    readonly publicAcl?: boolean;
+}
+
+declare interface StorageConnectionOpenContext {
+    /** Local state belongs to this registry identity, preserved across physical rotation. */
+    readonly memory?: Map<string, StoredObject>;
+}
+
+/** A transport is created lazily; only the registry owns its physical disposal. */
+export declare interface StorageConnectionTransport {
+    readonly provider: StorageProvider;
+    readonly probe: Effect.Effect<void, StorageError>;
+    readonly close: Effect.Effect<void>;
+}
+
+/** The object transport error, shared with the storage plugin's wire contract. */
+declare class StorageError extends StorageError_base {
+}
+
+declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<"StorageError", {
+    readonly provider: Schema.String;
+    readonly message: Schema.String;
+    readonly transient: Schema.Boolean;
+    readonly status: Schema.optional<Schema.Number>;
+    /** Cleanup was not confirmed; inspect the destination before another write. */
+    readonly outcome: Schema.optional<Schema.Literal<"unknown">>;
+}>, YieldableError>;
+
+/** Server-side physical identity; never serialize a namespace into inspection. */
+declare interface StorageObjectLocation {
+    readonly namespace: string | object;
+    readonly key: string;
+}
+
+/** Opaque keyed bytes; policy and durable references belong to the plugin. */
+export declare interface StorageProvider {
+    /** Stable, credential-independent SHA-256 identity of this physical key namespace. */
+    readonly objectNamespace: Effect.Effect<string, StorageError>;
+    /** Canonical container and physical key, including connection prefixes. */
+    readonly objectLocation?: (key: string) => Effect.Effect<StorageObjectLocation, StorageError>;
+    readonly root?: string;
+    readonly name: string;
+    readonly presigns: boolean;
+    readonly put: (key: string, bytes: Uint8Array, meta: {
+        readonly contentType: string;
+        readonly public?: boolean;
+    }) => Effect.Effect<ObjectMeta, StorageError>;
+    readonly get: (key: string) => Effect.Effect<StoredObject, StorageError>;
+    readonly delete: (key: string) => Effect.Effect<void, StorageError>;
+    readonly getUrl: (key: string, expiresInSec: number) => Effect.Effect<string, StorageError>;
+    readonly publicUrl?: (key: string) => string | null;
+    readonly setObjectPublic?: (key: string, isPublic: boolean) => Effect.Effect<void, StorageError>;
+    readonly getUploadUrl?: (key: string, expiresInSec: number, contentType: string) => Effect.Effect<string, StorageError>;
+    readonly createMultipartUpload?: (key: string, contentType: string, opts?: {
+        readonly public?: boolean;
+    }) => Effect.Effect<{
+        readonly uploadId: string;
+    }, StorageError>;
+    readonly presignUploadPart?: (key: string, uploadId: string, partNumber: number, expiresInSec: number) => Effect.Effect<string, StorageError>;
+    readonly completeMultipartUpload?: (key: string, uploadId: string, parts: ReadonlyArray<{
+        readonly partNumber: number;
+        readonly etag: string;
+    }>) => Effect.Effect<{
+        readonly etag?: string;
+    }, StorageError>;
+    readonly abortMultipartUpload?: (key: string, uploadId: string) => Effect.Effect<void, StorageError>;
+    readonly head: (key: string) => Effect.Effect<ObjectMeta | null, StorageError>;
+    readonly getStream?: (key: string) => Effect.Effect<StoredStream, StorageError>;
+    readonly putStream?: (key: string, stream: ByteStream, meta: {
+        readonly contentType: string;
+        readonly public?: boolean;
+        readonly totalSize?: number;
+    }) => Effect.Effect<ObjectMeta, StorageError>;
+    readonly getRange?: (key: string, start: number, endInclusive: number) => Effect.Effect<Uint8Array, StorageError>;
+    readonly bindDataStore?: (store: unknown) => void;
+}
+
+declare type StorageProviderName = 's3' | 'minio' | 'azure' | 'filesystem' | 'memory' | 'database';
+
+declare interface StoredObject {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+}
+
+declare interface StoredStream {
+    readonly stream: ByteStream;
+    readonly contentType: string;
+    readonly size?: number;
+    /** Release an opened body even if cancellation precedes its first pull. */
+    readonly close?: Effect.Effect<void>;
+}
+
+declare type TimeBucket = 'minute' | 'hour' | 'day' | 'week' | 'month';
+
+/** Time window. `to` defaults to now. */
+declare interface TimeRange {
+    readonly from: Date;
+    readonly to?: Date;
+}
+
+declare interface TimeseriesQuery extends AggregateQuery {
+    readonly bucket: TimeBucket;
+}
+
+declare interface TopNQuery {
+    readonly event: string;
+    /** Property to group by (must be a string-valued property). */
+    readonly groupBy: string;
+    readonly metric: 'count' | {
+        readonly sum: string;
+    };
+    readonly n: number;
+    readonly range: TimeRange;
+    readonly filter?: PropertyFilter;
+    /** Tenant scope — injected by `useAnalytics()`; see {@link AggregateQuery.tenantId}. */
+    readonly tenantId?: string | null;
+}
+
+/** Preserve operator and tenant configuration when borrowed Effects cross runtimes. */
+export declare const withConnectionRegistryConfigProvider: (registry: ConnectionRegistryShape, provider: ConfigProvider.ConfigProvider) => ConnectionRegistryShape;
+
 export { }