@homeflare/seat-runtime 0.1.0

package/dist/rounds.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The one round loop every seat shares: model turn, tool results, model turn, until the model
+ * stops asking for tools or the cap fires — and a cap that fires is followed by ONE more turn
+ * with the toolkit taken away, so a run ends with an answer instead of a truncated transcript.
+ *
+ * ★ WHAT THE SDK DOES AND DOES NOT DO. `Chat.generateText` with a toolkit resolves the tool
+ *   calls of ONE model turn and returns; it never re-prompts, and Effect AI ships no
+ *   `maxRounds` or `stopWhen` (grep of LanguageModel.d.ts and Chat.d.ts, 2026-09-29). The
+ *   documented multi-round agent is a `while` over `session.generateText({ prompt: [], toolkit })`
+ *   (compat's ai-docs, 30_chat.ts). This file is that `while`, once, with the cap.
+ * ⛔ THE CAP IS HARD AND FINITE. `maxRounds` must be a positive integer: `Infinity`, `0`, a
+ *   fraction or `NaN` is a programming error and dies with a `RangeError` before any model
+ *   call, because a loop a bad config can un-cap is a loop that spends until something else
+ *   stops it (LiteLLM's budget hit the claude2 fleet that way, 2026-09-28).
+ * ⚠️ THE FORCED TURN SENDS NO TOOLS. No toolkit, and `toolChoice: 'none'` stated anyway: the SDK
+ *   already defaults `toolChoice` to `'none'` for a call with no toolkit (LanguageModel.js,
+ *   `providerOptions`, measured by mutation 2026-09-29: dropping the option changed no test), so
+ *   it is kept for what it says and for the `toolChoice` attribute on the turn's span. compat
+ *   then sends neither `tools` nor `tool_choice` (prepareTools returns both undefined for an
+ *   empty tool list, rc.115), because an OpenAI-shaped API refuses a `tool_choice` with no
+ *   `tools`. The history still carries the earlier tool calls and results, and cf-code accepted
+ *   exactly that: one live call through CT100's LiteLLM (:4100), 2026-09-29, a history of
+ *   system, user, assistant tool call and tool result, no `tools`, `toolChoice: 'none'`, came
+ *   back `finishReason: 'stop'` with text and no tool call. One sample, one alias.
+ * ⚠️ `capped` MEANS THE MODEL STILL WANTED TOOLS after `maxRounds` tool rounds. A model that
+ *   answers on round `maxRounds` exactly is `capped: false`: the cap did not fire.
+ * 🔴 THE FORCED TURN CAN BE REFUSED, AND THEN THE RUN DOES NOT DIE OF IT. A provider that asks for
+ *   a tool although none was offered (a gateway that adds a dummy tool for a history full of
+ *   tool calls does exactly that) answers a turn the SDK cannot use, and the SDK says so with one
+ *   of TWO `AiError` reasons, depending on WHO rejects the tool call:
+ *   - `ToolNotFoundError`: @effect/ai-openai-compat (`SeatModel`'s provider) rejects it first,
+ *     while it maps the reply (`transformToolCallParams`: "Tool ... not found. Available tools:
+ *     none"). Measured 2026-09-29 (review of PR 328, of the round 2 fix), `SeatModel` against a loopback
+ *     LiteLLM stand-in that answered every call with a tool call: 3 model calls, tools offered
+ *     [true, true, false], then the whole run failed with every round already spent. Round 2's
+ *     fix caught only the reason below and so did nothing for this provider.
+ *   - `InvalidOutputError` raised by `LanguageModel` (module `LanguageModel`): the SDK's own decode
+ *     of the provider's parts ("Expected ... text | reasoning ..."), reached by a provider that hands
+ *     the SDK a tool-call part itself (the scripted model in tests/fake-model.ts). The same reason
+ *     raised by `OpenAiClient` (an empty, truncated or non-completion body, a dropped stream) is NOT
+ *     a refusal and fails the run (tests/seat-broken-forced.test.ts).
+ *   Either is caught: the result is `capped` and `unanswered`, its `response` is the LAST TOOL
+ *   ROUND's (whose calls did run), `rounds` stays `maxRounds`, and a warning, a span error and
+ *   `seat_rounds_unanswered_total` say what happened. Any OTHER failure of the forced turn
+ *   (network, rate limit, a handler) still fails the run.
+ */
+import * as Effect from 'effect/Effect';
+import type * as Chat from 'effect/unstable/ai/Chat';
+import type * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import type * as Tool from 'effect/unstable/ai/Tool';
+import type * as Toolkit from 'effect/unstable/ai/Toolkit';
+/**
+ * A turn's response: with the toolkit, or the forced one without.
+ * ⚠️ The two modes differ because the SDK's own types do: a call with a toolkit answers
+ *   `'opaque'` tool parameters, a call without one answers the default `'decoded'`.
+ */
+type Response<Tools extends Record<string, Tool.Any>> = LanguageModel.GenerateTextResponse<Tools, 'opaque'> | LanguageModel.GenerateTextResponse<{}, 'decoded'>;
+/** One model turn, as `onRound` and the result see it. A refused forced final turn is not reported. */
+export type Round<Tools extends Record<string, Tool.Any>> = {
+    /** 1-based. The forced final turn, when there is one, is `maxRounds + 1`. */
+    readonly round: number;
+    /** True only for the forced final turn: no toolkit, `toolChoice: 'none'`. */
+    readonly forced: boolean;
+    readonly response: Response<Tools>;
+};
+export type RoundsOptions<Tools extends Record<string, Tool.Any>> = {
+    /**
+     * The conversation, already holding the opening prompt (`Chat.fromPrompt`) or a resumed
+     * history that ends in a user message or tool results. Every round sends an EMPTY prompt:
+     * `Chat` appends the model's turn and its tool results to `history` itself.
+     */
+    readonly chat: Chat.Chat;
+    /**
+     * Tools WITH their handlers. A `Toolkit.make(...)` is an Effect that needs its handlers from
+     * context: `yield*` it where they are provided, and pass the result. (Typing it as the
+     * Effect would hide its requirements, which `generateText` itself cannot track either.)
+     */
+    readonly toolkit: Toolkit.WithHandler<Tools>;
+    /** The most tool rounds allowed. A positive integer; see the header. */
+    readonly maxRounds: number;
+    /** After every model turn, the forced one included. Runs inside that turn's span. */
+    readonly onRound?: ((round: Round<Tools>) => Effect.Effect<void>) | undefined;
+};
+export type RoundsResult<Tools extends Record<string, Tool.Any>> = {
+    /** The last model turn: the answer, or the forced final turn when the cap fired. */
+    readonly response: Response<Tools>;
+    /** Model turns that returned, the forced one included when it did. */
+    readonly rounds: number;
+    /** The cap fired and `response` is the forced final turn (or see `unanswered`). */
+    readonly capped: boolean;
+    /**
+     * The forced turn was refused (a provider that still asks for a tool) and `response` is the
+     * last TOOL round's: it holds no answer, and its tool calls ran. Only ever true with `capped`;
+     * `rounds` then counts the turns that returned, so it is `maxRounds`. See the header.
+     */
+    readonly unanswered: boolean;
+};
+/**
+ * Run the loop. Fails with whatever a model turn fails with (`AiError`, a tool handler's own
+ * failure); nothing is retried here — the caller wraps `Effect.retry` where it wants one.
+ */
+export declare function runRounds<Tools extends Record<string, Tool.Any>>(options: RoundsOptions<Tools>): Effect.Effect<RoundsResult<Tools>, LanguageModel.ExtractError<{
+    readonly toolkit: Toolkit.WithHandler<Tools>;
+}>, LanguageModel.LanguageModel | LanguageModel.ExtractServices<{
+    readonly toolkit: Toolkit.WithHandler<Tools>;
+}>>;
+export {};
+//# sourceMappingURL=rounds.d.ts.map

package/dist/rounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rounds.d.ts","sourceRoot":"","sources":["../src/rounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,KAAK,IAAI,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,KAAK,aAAa,MAAM,kCAAkC,CAAC;AAEvE,OAAO,KAAK,KAAK,IAAI,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,KAAK,OAAO,MAAM,4BAA4B,CAAC;AA6B3D;;;;GAIG;AACH,KAAK,QAAQ,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,IAChD,aAAa,CAAC,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,GACnD,aAAa,CAAC,oBAAoB,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;AAEtD,uGAAuG;AACvG,MAAM,MAAM,KAAK,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI;IAC1D,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI;IAClE;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC7C,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;CAC/E,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI;IACjE,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,EAC9D,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,GAC5B,MAAM,CAAC,MAAM,CACd,YAAY,CAAC,KAAK,CAAC,EACnB,aAAa,CAAC,YAAY,CAAC;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;CAAE,CAAC,EAC1E,aAAa,CAAC,aAAa,GAC3B,aAAa,CAAC,eAAe,CAAC;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;CAAE,CAAC,CAClF,CAiEA"}

package/dist/seat-model.d.ts

@@ -0,0 +1,59 @@
+/**
+ * LiteLLM as an Effect `LanguageModel` and `EmbeddingModel`, on the chat-completions wire.
+ *
+ * ★ ONE CLIENT SHAPE FOR EVERY SEAT. `@effect/ai-openai-compat` builds the HTTP client;
+ *   this file adds only what LiteLLM needs to attribute and control a seat's calls (tags,
+ *   the response cache, retries, metadata — see stamp.ts) and pins `strictJsonSchema: false`.
+ * ⛔ THE COMPAT PACKAGE POSTS `/chat/completions` AND `/embeddings`, NOT `/responses`. The
+ *   responses wire fails on cf-code with `missing field sequence_number` (landscape PR 165),
+ *   so nothing here points at it.
+ */
+import { OpenAiClient, OpenAiEmbeddingModel, OpenAiLanguageModel } from '@effect/ai-openai-compat';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import * as EmbeddingModel from 'effect/unstable/ai/EmbeddingModel';
+import type * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+export type SeatClientOptions = {
+    /** LiteLLM's OpenAI-compatible base, e.g. `http://127.0.0.1:4100/v1`. Required: no host default. */
+    readonly apiUrl: string;
+    /** A per-seat LiteLLM virtual key. Held `Redacted`; this package never logs or reads it from disk. */
+    readonly apiKey: string | Redacted.Redacted<string>;
+    /** Spend-log attribution, e.g. `['host:ct100', 'lane:cfcode', 'seat:cf-coding']`. */
+    readonly tags: string | ReadonlyArray<string>;
+    /**
+     * Skip LiteLLM's response cache, read and write. Defaults to TRUE.
+     * ⚠️ LiteLLM caches every completion for every key, so a seat that repeats a call gets the
+     *   old answer back at a tenth of the latency — an agent loop would replay itself.
+     */
+    readonly noCache?: boolean | undefined;
+    /** Written into the request body only when the body carries none (compat drops it). */
+    readonly metadata?: Readonly<Record<string, string>> | undefined;
+};
+/** Compat's own per-model config (`temperature`, `max_output_tokens`, custom body keys). */
+type ModelConfig = NonNullable<Parameters<typeof OpenAiLanguageModel.layer>[0]['config']>;
+type EmbeddingConfig = NonNullable<Parameters<typeof OpenAiEmbeddingModel.layer>[0]['config']>;
+export type SeatModelOptions = SeatClientOptions & {
+    /** The LiteLLM alias, e.g. `cf-code`. */
+    readonly model: string;
+    readonly config?: ModelConfig | undefined;
+};
+export type SeatEmbeddingOptions = SeatClientOptions & {
+    /** The LiteLLM alias, e.g. `embeddings`. */
+    readonly model: string;
+    /**
+     * What `EmbeddingModel.Dimensions` reports to a vector store. NOT sent to LiteLLM.
+     * ⚠️ compat's own `OpenAiEmbeddingModel.model(name, { dimensions })` puts the number in the
+     *   request body too, and a provider that has no `dimensions` parameter (a llama.cpp bge-m3
+     *   behind LiteLLM) can refuse it. Pass `config: { dimensions }` to send it deliberately.
+     */
+    readonly dimensions: number;
+    readonly config?: EmbeddingConfig | undefined;
+};
+/** The client: bearer key, tag header, cache and retry fields, over `fetch`. */
+export declare function clientLayer(options: SeatClientOptions): Layer.Layer<OpenAiClient.OpenAiClient>;
+/** `LanguageModel` for one LiteLLM alias. */
+export declare function layer(options: SeatModelOptions): Layer.Layer<LanguageModel.LanguageModel>;
+/** `EmbeddingModel` (and its `Dimensions`) for one LiteLLM alias. */
+export declare function embeddingLayer(options: SeatEmbeddingOptions): Layer.Layer<EmbeddingModel.EmbeddingModel | EmbeddingModel.Dimensions>;
+export {};
+//# sourceMappingURL=seat-model.d.ts.map

package/dist/seat-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seat-model.d.ts","sourceRoot":"","sources":["../src/seat-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACnG,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,cAAc,MAAM,mCAAmC,CAAC;AACpE,OAAO,KAAK,KAAK,aAAa,MAAM,kCAAkC,CAAC;AAKvE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,oGAAoG;IACpG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sGAAsG;IACtG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpD,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;CAClE,CAAC;AAEF,4FAA4F;AAC5F,KAAK,WAAW,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC1F,KAAK,eAAe,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAE/F,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG;IACjD,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG;IACrD,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CAC/C,CAAC;AAEF,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,CAAC,CAY9F;AAED,6CAA6C;AAC7C,wBAAgB,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,aAAa,CAAC,CAQzF;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAC5B,OAAO,EAAE,oBAAoB,GAC5B,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,GAAG,cAAc,CAAC,UAAU,CAAC,CAKxE"}

package/dist/seat-obs.d.ts

@@ -0,0 +1,23 @@
+import * as Layer from 'effect/Layer';
+import { type OtlpExporter } from 'effect/unstable/observability';
+/**
+ * CT100's Victoria services, one path each. Verified 2026-09-29 by GET against the live
+ * ports (no payload sent): a mounted path answers, an unmounted sibling answers
+ * `unsupported path requested`; the counters carry `format="protobuf"` for traces and logs.
+ */
+export declare const CT100_ENDPOINTS: {
+    readonly traces: string;
+    readonly logs: string;
+    readonly metrics: string;
+};
+/**
+ * Shown when a process names itself neither with `OTEL_SERVICE_NAME` nor with a `service.name`
+ * in `OTEL_RESOURCE_ATTRIBUTES`; set one per seat.
+ */
+export declare const DEFAULT_SERVICE_NAME = "seat-runtime";
+/**
+ * OTLP tracer, logger and metrics over `fetch`, protobuf on the wire (what VictoriaTraces,
+ * VictoriaLogs and VictoriaMetrics ingest, and what the Claude Code seats already send).
+ */
+export declare const layer: Layer.Layer<OtlpExporter.Flusher>;
+//# sourceMappingURL=seat-obs.d.ts.map

package/dist/seat-obs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seat-obs.d.ts","sourceRoot":"","sources":["../src/seat-obs.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,EACL,KAAK,YAAY,EAKlB,MAAM,+BAA+B,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAK1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AA6CnD;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAQnD,CAAC"}

package/dist/seat-state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `SeatState`: a seat's Postgres and Valkey as Effect services, one layer each, in the trace of
+ * the run that uses them.
+ *
+ * ⛔ THE LIBRARY HOLDS NO HOST. Every URL comes from the consumer (a value, or an environment
+ *   variable it names), as `Redacted`; there is no default address here to point a seat at the
+ *   wrong store, and nothing reads a credential from disk.
+ * ★ THE SERVICES ARE EFFECT'S, NOT OURS: `SqlClient` (`effect/unstable/sql/SqlClient`) for
+ *   Postgres and `Redis` (`effect/unstable/persistence/Redis`) for Valkey, so a consumer writes
+ *   ordinary Effect SQL and Redis code and this package adds only how they are built.
+ */
+import * as Layer from 'effect/Layer';
+import type * as Redis from 'effect/unstable/persistence/Redis';
+import type * as SqlClient from 'effect/unstable/sql/SqlClient';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { Config } from 'effect';
+import type { PgClient } from '@effect/sql-pg';
+import { type PostgresFromEnvOptions, type PostgresOptions } from './state-postgres.ts';
+import { type ValkeyFromEnvOptions, type ValkeyOptions } from './state-valkey.ts';
+export * from './state-postgres.ts';
+export * from './state-valkey.ts';
+export { PgClient } from '@effect/sql-pg';
+/** Both stores, each built from an explicit URL. */
+export declare const layer: (options: {
+    readonly postgres: PostgresOptions;
+    readonly valkey: ValkeyOptions;
+}) => Layer.Layer<PgClient.PgClient | SqlClient.SqlClient | Redis.Redis, SqlError | Redis.RedisError>;
+/** Both stores, each URL read from its environment variable (`SEAT_POSTGRES_URL`, `SEAT_VALKEY_URL`). */
+export declare const layerFromEnv: (options?: {
+    readonly postgres?: PostgresFromEnvOptions | undefined;
+    readonly valkey?: ValkeyFromEnvOptions | undefined;
+}) => Layer.Layer<PgClient.PgClient | SqlClient.SqlClient | Redis.Redis, SqlError | Redis.RedisError | Config.ConfigError>;
+//# sourceMappingURL=seat-state.d.ts.map

package/dist/seat-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seat-state.d.ts","sourceRoot":"","sources":["../src/seat-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,KAAK,KAAK,MAAM,mCAAmC,CAAC;AAChE,OAAO,KAAK,KAAK,SAAS,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EAGrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAGnB,MAAM,mBAAmB,CAAC;AAE3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,oDAAoD;AACpD,eAAO,MAAM,KAAK,YAAa;IAC7B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC,KAAG,KAAK,CAAC,KAAK,CACb,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAC,SAAS,GAAG,KAAK,CAAC,KAAK,EACrD,QAAQ,GAAG,KAAK,CAAC,UAAU,CAC0C,CAAC;AAExE,yGAAyG;AACzG,eAAO,MAAM,YAAY,aAAc;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;CACpD,KAAG,KAAK,CAAC,KAAK,CACb,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAC,SAAS,GAAG,KAAK,CAAC,KAAK,EACrD,QAAQ,GAAG,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC,WAAW,CACqC,CAAC"}

package/dist/stamp.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The per-request marks a seat puts on every LiteLLM call, applied as an `HttpClient`
+ * transform because `@effect/ai-openai-compat` gives no other place to set them.
+ *
+ * ★ WHY A TRANSFORM AND NOT MODEL CONFIG. The compat mapper forwards unknown config keys
+ *   into the body but DROPS `metadata` (it is a known Responses-API field with no
+ *   chat-completions place), and no config key can set a header. Measured in
+ *   packages/seat-runtime/tests/stamp.test.ts against the installed rc.115.
+ * ★ IT IS THE SAME TRANSFORM AS cf-harness (landscape PR 165, cf-harness/src/request.ts),
+ *   which is where the header and the body fields were measured against LiteLLM.
+ */
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+export type SeatStamp = {
+    /** Already validated and joined: LiteLLM reads one comma-separated header. */
+    readonly tags: string;
+    readonly noCache: boolean;
+    readonly metadata: Readonly<Record<string, string>> | undefined;
+};
+/** Validate and join. Throws at layer construction, where the mistake is one line away. */
+export declare function joinTags(tags: string | ReadonlyArray<string>): string;
+/** Headers and body fields for one request. Pure: the same request in, a new one out. */
+export declare function stampRequest(request: HttpClientRequest.HttpClientRequest, stamp: SeatStamp): HttpClientRequest.HttpClientRequest;
+//# sourceMappingURL=stamp.d.ts.map

package/dist/stamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamp.d.ts","sourceRoot":"","sources":["../src/stamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,iBAAiB,MAAM,wCAAwC,CAAC;AAE5E,MAAM,MAAM,SAAS,GAAG;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;CACjE,CAAC;AAUF,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAWrE;AAuBD,yFAAyF;AACzF,wBAAgB,YAAY,CAC1B,OAAO,EAAE,iBAAiB,CAAC,iBAAiB,EAC5C,KAAK,EAAE,SAAS,GACf,iBAAiB,CAAC,iBAAiB,CAoBrC"}

package/dist/state-dsn.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Reading a connection string without ever printing it.
+ *
+ * ⛔ A DSN CARRIES A PASSWORD, so nothing here returns, throws or formats the string itself: a
+ *   caller gets back the few non-secret fields (host, port, database, user name) or `undefined`.
+ * 🔴 WHY THIS EXISTS AT ALL. Measured 2026-09-29 (`@effect/sql-pg` rc.115, Bun 1.4.0): a DSN that
+ *   `new URL` cannot parse fails as `SqlError` -> `ConnectionError` whose `cause` is the URL
+ *   `TypeError`, and that error's text carries the WHOLE string, password included. Three of the
+ *   six bad DSNs tried leaked it through `JSON.stringify` and `Bun.inspect` alike. Parsing here
+ *   first, with the same `new URL`, means a string that would leak never reaches the driver:
+ *   what the driver still rejects (a wrong scheme, an `sslmode` it lacks) echoes only that one
+ *   token, not the string.
+ * 🔴 THE SECOND REASON: `@effect/sql-pg` labels every query span from its discrete config fields
+ *   and IGNORES the URL for that. A client built from `url` alone exports
+ *   `server.address: localhost`, `server.port: 5432` and `db.namespace: postgres` for EVERY
+ *   query whatever it is connected to (measured 2026-09-29 against CT100's Postgres through a
+ *   tunnel), so a trace would point at the wrong database. `postgresFields` hands the driver the
+ *   same host, port, database and user the URL names, decoded the way the driver decodes them.
+ */
+/** The non-secret fields a Postgres URL names; a field the URL leaves out is absent. */
+export type PostgresFields = {
+    readonly host?: string | undefined;
+    readonly port?: number | undefined;
+    readonly database?: string | undefined;
+    readonly username?: string | undefined;
+};
+/** The non-secret fields a Valkey URL names; `port` defaults to 6379 for a TCP scheme. */
+export type ValkeyFields = {
+    readonly host?: string | undefined;
+    readonly port?: number | undefined;
+    /** The logical database index (`redis://host/1`), when there is one. */
+    readonly database?: string | undefined;
+};
+/**
+ * `undefined` when `dsn` is not a URL at all (the one case the driver would leak on); otherwise
+ * the fields it names, or none when the URL is one the driver should read alone.
+ */
+export declare function postgresFields(dsn: string): PostgresFields | undefined;
+/** `undefined` when `raw` is not a URL of a scheme `Bun.RedisClient` takes. */
+export declare function valkeyFields(raw: string): ValkeyFields | undefined;
+//# sourceMappingURL=state-dsn.d.ts.map

package/dist/state-dsn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-dsn.d.ts","sourceRoot":"","sources":["../src/state-dsn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AA2BF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAqBtE;AAaD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAWlE"}

package/dist/state-postgres.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Postgres as Effect's own `SqlClient`, through `@effect/sql-pg`.
+ *
+ * ★ THE SDK'S OWN LAYER, NOT A WRAPPER OF IT. `PgClient` opens the pool and creates one
+ *   `sql.execute` client span per statement carrying `db.system.name: postgresql`,
+ *   `db.namespace`, `server.address`, `server.port` and `db.query.text` (measured 2026-09-29
+ *   against CT100's Postgres), so state lands in the seat's trace with no `withSpan` of ours.
+ *   ⚠️ `db.query.text` is the statement with its `$1` placeholders: parameter VALUES are not in
+ *   the span (tests/state-postgres.test.ts asserts a canary value never leaves).
+ * ⛔ WHAT THIS ADDS is the two things the driver leaves to the caller, both measured
+ *   2026-09-29 and both in state-dsn.ts: a DSN that will not parse never reaches the driver (its
+ *   error carries the string, password included), and the URL's host, port, database and user are
+ *   passed as discrete fields so the spans name the database that was actually reached (from `url`
+ *   alone they say `localhost:5432`, database `postgres`).
+ * ⛔ BUILDING THE LAYER RUNS `select 1`. The pool is lazy (a bad host or password otherwise fails
+ *   at the first query), so a seat that starts against a dead or refusing Postgres is told at
+ *   startup, as `SqlError`, within `connectTimeout`.
+ * ⚠️ PORTABLE. `@effect/sql-pg` rc.115 speaks the wire protocol itself over `node:net`, with no
+ *   driver package, so this half runs under Bun and Node alike (the Valkey half needs Bun).
+ */
+import { PgClient } from '@effect/sql-pg';
+import * as Config from 'effect/Config';
+import * as Duration from 'effect/Duration';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import type * as SqlClient from 'effect/unstable/sql/SqlClient';
+import { SqlError } from 'effect/unstable/sql/SqlError';
+export type PostgresOptions = {
+    /**
+     * `postgres://<user>:<password>@<host>:<port>/<database>` (or `postgresql://`), the user and
+     * password percent-encoded. Held `Redacted`; never in a span, log or error. Required: this
+     * package holds no host. `sslmode=require|verify-ca|verify-full|disable` is read; the driver
+     * refuses `prefer` and `allow`.
+     */
+    readonly url: string | Redacted.Redacted<string>;
+    /** Pool ceiling; the driver's default when absent. */
+    readonly maxConnections?: number | undefined;
+    /** How long to wait for a connection, and for the startup `select 1`. Driver default 5 s. */
+    readonly connectTimeout?: Duration.Input | undefined;
+    /** Shown in `pg_stat_activity`; the driver's default when absent. */
+    readonly applicationName?: string | undefined;
+};
+/** The environment variable `postgresFromEnv` reads unless told another. Not a host. */
+export declare const POSTGRES_URL_VARIABLE = "SEAT_POSTGRES_URL";
+/**
+ * `SqlClient` and `PgClient` against one Postgres. The pool closes with the layer's scope.
+ */
+export declare const postgres: (options: PostgresOptions) => Layer.Layer<PgClient.PgClient | SqlClient.SqlClient, SqlError>;
+export type PostgresFromEnvOptions = Omit<PostgresOptions, 'url'> & {
+    /** The variable holding the URL. Default `SEAT_POSTGRES_URL`. */
+    readonly variable?: string | undefined;
+};
+/**
+ * `postgres`, its URL read from an environment variable as a `Redacted` secret. A missing
+ * variable fails as `ConfigError`, naming the variable and nothing else.
+ */
+export declare const postgresFromEnv: (options?: PostgresFromEnvOptions) => Layer.Layer<PgClient.PgClient | SqlClient.SqlClient, SqlError | Config.ConfigError>;
+//# sourceMappingURL=state-postgres.d.ts.map

package/dist/state-postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-postgres.d.ts","sourceRoot":"","sources":["../src/state-postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,KAAK,SAAS,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAmB,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAGzE,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjD,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,6FAA6F;IAC7F,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;IACrD,qEAAqE;IACrE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAwCzD;;GAEG;AACH,eAAO,MAAM,QAAQ,YACV,eAAe,KACvB,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAC,SAAS,EAAE,QAAQ,CACJ,CAAC;AAE7D,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,GAAG;IAClE,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,aAChB,sBAAsB,KAC/B,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAC,SAAS,EAAE,QAAQ,GAAG,MAAM,CAAC,WAAW,CAOpF,CAAC"}

package/dist/state-valkey-connection.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Keeping one `Bun.RedisClient` connected for as long as its layer lives.
+ *
+ * 🔴 BUN GIVES UP, AND A CLIENT THAT HAS GIVEN UP STAYS DEAD. Measured 2026-09-29 (Bun 1.4.0, a raw
+ *   client with `enableOfflineQueue: false` and the default `maxRetries` of 20, the server killed
+ *   for 60 s, then restarted): Bun retried on its own for 31 s (commands failed `Connection is
+ *   closed and offline queue is disabled`), then GAVE UP: `onclose` ran once and every command
+ *   after failed `Connection has failed`, still so 10 s after the server was back. Only calling
+ *   `connect()` again revived it (it resolved at once and `PING` answered). The budget is a sum of
+ *   backoffs, so it is not one number: the review that found this measured recovery after 30 s and
+ *   none after 45 s. A seat whose Valkey restarts for a minute (a container restart, CT100 booting)
+ *   would keep a dead client until the process restarted, and no retry in Effect could help, since
+ *   every retry hit the same dead client.
+ * ★ SO THE LAYER RECONNECTS ITSELF, off `onclose`: single-flight, each attempt bounded by
+ *   `connectionTimeout` (which does not bound DNS; see state-valkey.ts), backing off 250 ms up to
+ *   5 s between attempts, one `valkey reconnect` span per attempt and a warning and an info line
+ *   around the outage. It stops when the layer's scope closes.
+ * ⚠️ `onclose` IS A HINT AND `connected` IS THE FACT. Measured on the same client: `onclose` also
+ *   runs for every `connect()` that fails (each rejected after ~155 ms with `Connection closed`)
+ *   and for the client's own `close()`, so a reconnect that trusted it would start itself. The
+ *   loop therefore runs only while `connected` is false, and a wake-up that arrives after a
+ *   successful reconnect finds nothing to do.
+ * ⚠️ COMMANDS STILL FAIL AT ONCE WHILE IT IS DOWN (the offline queue is off on purpose): the
+ *   caller's retry is what spans an outage, and from now on the retry is answered once this loop
+ *   has reconnected, within the pause plus one attempt of the server coming back.
+ */
+import type { RedisClient } from 'bun';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
+/** What this file needs of `Bun.RedisClient`. */
+export type Reconnectable = Pick<RedisClient, 'connected' | 'connect' | 'onclose'>;
+export type KeepOptions = {
+    /** How long one reconnect attempt may take before it is abandoned and retried. */
+    readonly connectionTimeout: Duration.Input;
+    /** Span attributes every attempt carries: the server address, no secrets. */
+    readonly attributes: Readonly<Record<string, unknown>>;
+    /** The pause after the first failed attempt, doubled up to `longestPause`. Default 250 ms. */
+    readonly firstPause?: Duration.Input | undefined;
+    /** The longest pause between attempts. Default 5 s. */
+    readonly longestPause?: Duration.Input | undefined;
+};
+/**
+ * Reconnect `client` whenever Bun gives up on it, for the life of the enclosing scope. Call it
+ * AFTER the first `connect()` succeeded, so a wrong URL or password still fails the layer's build
+ * instead of being retried forever.
+ */
+export declare const keepConnected: (client: Reconnectable, options: KeepOptions) => Effect.Effect<void, never, Scope.Scope>;
+//# sourceMappingURL=state-valkey-connection.d.ts.map

package/dist/state-valkey-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-valkey-connection.d.ts","sourceRoot":"","sources":["../src/state-valkey-connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC;AAEnF,MAAM,MAAM,WAAW,GAAG;IACxB,kFAAkF;IAClF,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,KAAK,CAAC;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,8FAA8F;IAC9F,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;IACjD,uDAAuD;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;CACpD,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,CAC1B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,WAAW,KACjB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAuDzC,CAAC"}

package/dist/state-valkey-scrub.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What a Valkey error may say once it has left the layer.
+ *
+ * 🔴 THE SERVER'S ERROR TEXT ECHOES THE ARGUMENTS OF THE CALL THAT FAILED. Measured 2026-09-29
+ *   (Valkey 9.1.1, through `Bun.RedisClient`, with canary values):
+ *     ERR unknown command 'JSON.SET', with args beginning with: 'seat:key-…' '$' '{"secret":…}'
+ *     ERR unknown subcommand 'seat:key-…'. Try OBJECT HELP.
+ *   Keys are seat data and values are whatever the seat stored, and Effect's `OtlpTracer` exports
+ *   every FAILED span's error as `exception.message` and `exception.stacktrace` (with the whole
+ *   `cause` chain, `includeCauseInStack: true`), so those two errors put a key and a value into
+ *   the exported trace: the OTLP payload a Victoria service would receive held both (a wire test
+ *   in tests/state-error-text.test.ts asserts it now does not). A `Logger` that prints a failed
+ *   call does the same.
+ * ★ SO THE ERROR THAT LEAVES THE LAYER IS A NEW `Error` WITH THE ARGUMENTS CUT OUT, and the
+ *   original is not chained (a `cause` would carry its text straight back into the stack). Kept:
+ *   Bun's `code` and `name`, and the server's own words up to the first quote that opens
+ *   something other than the command that was sent. That keeps `NOPERM User seat has no
+ *   permissions to run the 'flushall' command` whole (so `isPermissionDenied` and the wording are
+ *   unchanged) and cuts `unknown command 'JSON.SET', with args beginning with: ` at the first
+ *   argument, even when an argument holds a quote itself.
+ * ⚠️ WHAT THIS DOES NOT COVER, said plainly: a server text that echoes an argument WITHOUT quotes,
+ *   and the text a Lua script raises itself (`error(...)` comes back as `ERR user_script:1: <text>`;
+ *   measured). Bun's own errors (`Connection closed`, a timeout) quote nothing.
+ */
+/** What replaces the arguments. */
+export declare const OMITTED = "[arguments omitted]";
+/**
+ * `message` up to the first quoted thing that is not `command` (or one of its subcommands, which
+ * the server writes `command|sub`), with `OMITTED` where the rest was.
+ */
+export declare function cutArguments(message: string, command: string): string;
+/**
+ * The client's rejection as an `Error` that is safe to put in a span, a log or a `RedisError`:
+ * a fresh one, keeping Bun's `name` and `code`, with the arguments cut out of the text.
+ */
+export declare function scrubbedError(cause: unknown, command: string): Error;
+//# sourceMappingURL=state-valkey-scrub.d.ts.map

package/dist/state-valkey-scrub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-valkey-scrub.d.ts","sourceRoot":"","sources":["../src/state-valkey-scrub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,mCAAmC;AACnC,eAAO,MAAM,OAAO,wBAAwB,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAYrE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CASpE"}

package/dist/state-valkey-send.d.ts

@@ -0,0 +1,35 @@
+/**
+ * One Valkey command as a span, with a deadline, failing as `RedisError`.
+ *
+ * ⛔ A SPAN NAMES THE COMMAND, NEVER ITS ARGUMENTS. Keys are seat data and values are whatever the
+ *   seat stored; `AUTH` and `HELLO ... AUTH` carry a password. Only the upper-cased command name
+ *   (`SET`, `GET`) is recorded, so the span is low-cardinality and holds nothing to redact.
+ * 🔴 NOR IS THE ERROR TEXT: the server quotes the arguments of a call it refuses (`unknown command
+ *   'X', with args beginning with: '<key>' '<value>'`), and a failed span exports its error, so
+ *   what a caller receives is `scrubbedError`, never Bun's own (state-valkey-scrub.ts).
+ * 🔴 THE DEADLINE IS NOT OPTIONAL. Measured 2026-09-29 (Bun 1.4.0): a `Bun.RedisClient` on its
+ *   defaults that has lost its server QUEUES every command and never answers it until the server
+ *   is back (a `send` sat unresolved past 8 s against a dead port; after a restart the queued
+ *   command completed ~5 s later). With the offline queue off (`state-valkey.ts` sets it) a dropped
+ *   connection fails at once, but a peer that holds the socket open and says nothing would still
+ *   wedge a seat forever, so every command carries `commandTimeout` too.
+ */
+import * as Effect from 'effect/Effect';
+import * as Redis from 'effect/unstable/persistence/Redis';
+import type * as Duration from 'effect/Duration';
+/** What this file needs of a client: `Bun.RedisClient` has this exact `send`. */
+export type ValkeyCall = {
+    readonly send: (command: string, args: Array<string>) => Promise<unknown>;
+};
+/** `send` as `Redis.make` wants it. */
+export type Send = <A = unknown>(command: string, ...args: ReadonlyArray<string>) => Effect.Effect<A, Redis.RedisError>;
+export type SendOptions = {
+    /** How long one command may take before it fails as `RedisError`. */
+    readonly commandTimeout: Duration.Input;
+    /** The command deadline in milliseconds, for the message only. */
+    readonly commandTimeoutMs: number;
+    /** Span attributes every command carries: `db.system.name`, the server address, no secrets. */
+    readonly attributes: Readonly<Record<string, unknown>>;
+};
+export declare function instrumentedSend(client: ValkeyCall, options: SendOptions): Send;
+//# sourceMappingURL=state-valkey-send.d.ts.map

package/dist/state-valkey-send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-valkey-send.d.ts","sourceRoot":"","sources":["../src/state-valkey-send.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,mCAAmC,CAAC;AAC3D,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAGjD,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E,CAAC;AAEF,uCAAuC;AACvC,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,EAC7B,OAAO,EAAE,MAAM,EACf,GAAG,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;AAExC,MAAM,MAAM,WAAW,GAAG;IACxB,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxD,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAyB/E"}

package/dist/state-valkey.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Valkey as Effect's own `Redis` service, over `Bun.RedisClient`.
+ *
+ * ★ `Redis.make` OVER THE BUILT-IN CLIENT, NOT `@effect/platform-bun`'s `BunRedis`. Rc.115 ships
+ *   `BunRedis.layer`, and it would do; but a dependency on `@effect/platform-bun` drags
+ *   `@effect/platform-node-shared ^rc.115` in behind it, which resolves to rc.118 on a fresh
+ *   install and kills the process at import, and only a ROOT `overrides` fixes that (docs/pairing.md,
+ *   measured 2026-09-29). A library cannot ship one. So this is the same ~30 lines (`send` over
+ *   `client.send`), with the two things `BunRedis` lacks: a connection that must succeed before the
+ *   layer is built, and a deadline on every command.
+ * ⛔ THE URL CARRIES THE ACL USER (`redis://seat:<password>@host:port`, percent-encoded), measured
+ *   2026-09-29 against a scratch Valkey with `user default off`: an unauthenticated client is
+ *   refused `NOAUTH`; the seat user reads and writes its own prefix; a write outside it fails
+ *   `NOPERM No permissions to access a key`, and a command outside its categories fails
+ *   `NOPERM User seat has no permissions to run the 'flushall' command`. All of them arrive as
+ *   `RedisError`, and `isPermissionDenied` names the two `NOPERM` ones.
+ * ⛔ NO `subscribe`. `Redis.subscribe` here fails with `RedisError`: a Valkey subscriber needs a
+ *   connection of its own that this layer does not open. (`BunRedis` opens one, with no reconnect;
+ *   a caller that needs pub/sub can use it beside this layer.)
+ * ⚠️ BUN ONLY, AND SAID SO AT THE FIRST USE. `Bun.RedisClient` is loaded with `import('bun')`, so
+ *   importing this module under Node still works (the Postgres half is portable); BUILDING the
+ *   Valkey layer there fails with a `RedisError` naming the reason.
+ * 🔴 `connectionTimeout` DOES NOT BOUND DNS. Measured 2026-09-29: with `connectionTimeout: 700`, a
+ *   host name that does not resolve failed after 31 s. `connect()` therefore also runs under an
+ *   Effect timeout of the same length.
+ * 🔴 BUN'S OWN RECONNECT ENDS, AND THE CLIENT THEN STAYS DEAD (about 31 s of outage here): the layer
+ *   reconnects it itself, off `onclose` (state-valkey-connection.ts holds the measurement).
+ */
+import * as Config from 'effect/Config';
+import * as Duration from 'effect/Duration';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import * as Redis from 'effect/unstable/persistence/Redis';
+export type ValkeyOptions = {
+    /**
+     * `redis://<user>:<password>@<host>:<port>[/<db>]` (or `valkey://`, `rediss://` for TLS), the
+     * user and password percent-encoded. Held `Redacted`; never in a span, log or error. Required:
+     * this package holds no host.
+     */
+    readonly url: string | Redacted.Redacted<string>;
+    /**
+     * How long to wait to connect and authenticate when the layer is built, and for each reconnect
+     * attempt after Bun gives up. Default 5 s (Bun's own is 10 s). ⚠️ A finite positive duration of at
+     * most 2 ** 31 - 1 ms, or a `RangeError` defect.
+     */
+    readonly connectionTimeout?: Duration.Input | undefined;
+    /** How long one command may take. Default 10 s; same limits as `connectionTimeout`. */
+    readonly commandTimeout?: Duration.Input | undefined;
+    /**
+     * How many times Bun retries a lost connection before it gives up (its default is 20, about 30
+     * s of outage). After that THE LAYER reconnects until the server is back, so this only sets
+     * when its own loop takes over. A non-negative integer, or a `RangeError` defect.
+     */
+    readonly maxRetries?: number | undefined;
+};
+export declare const DEFAULT_CONNECTION_TIMEOUT: Duration.Duration;
+export declare const DEFAULT_COMMAND_TIMEOUT: Duration.Duration;
+/**
+ * Whether `error` is the server's `NOPERM`: a key outside the user's prefix, or a command outside
+ * its categories. ⚠️ It reads the message, because Bun reports both as one `code`
+ * (`ERR_REDIS_SERVER_ERROR`) and the server's own text is the only thing that tells them apart
+ * from a real server fault.
+ */
+export declare function isPermissionDenied(error: unknown): boolean;
+/**
+ * The `Redis` service against one Valkey. ⛔ BUILDING IT CONNECTS AND AUTHENTICATES, so a wrong
+ * URL, user or password fails at startup as `RedisError`, not at the first command (Bun reports a
+ * refused password as `Connection closed`, the same text as a server that is down).
+ * The client is closed when the layer's scope closes.
+ */
+export declare const valkey: (options: ValkeyOptions) => Layer.Layer<Redis.Redis, Redis.RedisError>;
+/** The environment variable `valkeyFromEnv` reads unless told another. Not a host. */
+export declare const VALKEY_URL_VARIABLE = "SEAT_VALKEY_URL";
+export type ValkeyFromEnvOptions = Omit<ValkeyOptions, 'url'> & {
+    /** The variable holding the URL. Default `SEAT_VALKEY_URL`. */
+    readonly variable?: string | undefined;
+};
+/**
+ * `valkey`, its URL read from an environment variable as a `Redacted` secret. A missing variable
+ * fails as `ConfigError`, naming the variable and nothing else.
+ */
+export declare const valkeyFromEnv: (options?: ValkeyFromEnvOptions) => Layer.Layer<Redis.Redis, Redis.RedisError | Config.ConfigError>;
+//# sourceMappingURL=state-valkey.d.ts.map

package/dist/state-valkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-valkey.d.ts","sourceRoot":"","sources":["../src/state-valkey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,KAAK,MAAM,mCAAmC,CAAC;AAK3D,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;IACxD,uFAAuF;IACvF,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;IACrD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,QAA8B,CAAC;AACjF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,QAA+B,CAAC;AAe/E;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK1D;AAuED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,YAAa,aAAa,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAItF,CAAC;AAEJ,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,GAAG;IAC9D,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,aACd,oBAAoB,KAC7B,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC,WAAW,CAOhE,CAAC"}