@homeflare/seat-runtime 0.1.0

package/src/seat-model.ts

@@ -0,0 +1,94 @@
+/**
+ * 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';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { joinTags, stampRequest } from './stamp.ts';
+
+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 function clientLayer(options: SeatClientOptions): Layer.Layer<OpenAiClient.OpenAiClient> {
+  const stamp = {
+    tags: joinTags(options.tags),
+    noCache: options.noCache ?? true,
+    metadata: options.metadata,
+  };
+  return OpenAiClient.layer({
+    apiKey: Redacted.isRedacted(options.apiKey) ? options.apiKey : Redacted.make(options.apiKey),
+    apiUrl: options.apiUrl.replace(/\/$/, ''),
+    transformClient: (http) =>
+      HttpClient.mapRequest(http, (request) => stampRequest(request, stamp)),
+  }).pipe(Layer.provide(FetchHttpClient.layer));
+}
+
+/** `LanguageModel` for one LiteLLM alias. */
+export function layer(options: SeatModelOptions): Layer.Layer<LanguageModel.LanguageModel> {
+  return OpenAiLanguageModel.layer({
+    model: options.model,
+    // ★ cf-review's default, and measured here 2026-09-29: compat sends `strict: true` on every
+    //   tool schema unless told otherwise, which the seats' previous client never did; this
+    //   sends `strict: false`. A caller's `config` wins.
+    config: { strictJsonSchema: false, ...options.config },
+  }).pipe(Layer.provide(clientLayer(options)));
+}
+
+/** `EmbeddingModel` (and its `Dimensions`) for one LiteLLM alias. */
+export function embeddingLayer(
+  options: SeatEmbeddingOptions,
+): Layer.Layer<EmbeddingModel.EmbeddingModel | EmbeddingModel.Dimensions> {
+  return Layer.merge(
+    OpenAiEmbeddingModel.layer({ model: options.model, config: options.config }),
+    Layer.succeed(EmbeddingModel.Dimensions, options.dimensions),
+  ).pipe(Layer.provide(clientLayer(options)));
+}

package/src/seat-obs.ts

@@ -0,0 +1,103 @@
+/**
+ * Traces, logs and metrics from any Effect seat to VictoriaMetrics on CT100, from one
+ * environment block.
+ *
+ * ★ `layerFromConfig`, NOT `Otlp.layer`. The combined layer takes ONE base URL and appends
+ *   `/v1/traces` and friends, and the three Victoria services each mount OTLP at a different
+ *   path (measured 2026-09-29, README). The per-signal layers read the per-signal env the
+ *   Claude Code seats already carry, so one block wires every seat.
+ * ⛔ WITH NO ENVIRONMENT `layerFromConfig` EXPORTS NOTHING, SILENTLY. It returns a bare
+ *   flusher unless `OTEL_<SIGNAL>_EXPORTER` names `otlp` and an endpoint is set. So the CT100
+ *   defaults below are not a convenience, they are what makes this layer emit at all.
+ */
+import * as Config from 'effect/Config';
+import * as ConfigProvider from 'effect/ConfigProvider';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import {
+  type OtlpExporter,
+  OtlpLogger,
+  OtlpMetrics,
+  OtlpSerialization,
+  OtlpTracer,
+} 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 const CT100_ENDPOINTS: {
+  readonly traces: string;
+  readonly logs: string;
+  readonly metrics: string;
+} = {
+  traces: 'http://10.100.1.4:10428/insert/opentelemetry/v1/traces',
+  logs: 'http://10.100.1.4:9428/insert/opentelemetry/v1/logs',
+  metrics: 'http://10.100.1.4:8428/opentelemetry/v1/metrics',
+};
+
+/**
+ * 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 const DEFAULT_SERVICE_NAME = 'seat-runtime';
+
+/**
+ * `OTEL_RESOURCE_ATTRIBUTES` read the way Effect reads it (`OtlpResource.fromConfig`, rc.115:
+ * `key=value` pairs, both sides URI-decoded), so "has a `service.name`" means what Effect means.
+ */
+const resourceAttributes = Config.Record(
+  Schema.StringFromUriComponent,
+  Schema.StringFromUriComponent,
+  'OTEL_RESOURCE_ATTRIBUTES',
+).pipe(Config.withDefault(undefined));
+
+/**
+ * The fallback config source, computed against the CURRENT provider.
+ *
+ * ⛔ EVERYTHING HERE IS A FALLBACK. The environment is tried first, so `OTEL_SDK_DISABLED=true`,
+ *   `OTEL_TRACES_EXPORTER=none` and every endpoint the operator sets win.
+ * ⚠️ THE PER-SIGNAL DEFAULTS STEP ASIDE FOR A BASE ENDPOINT. Effect reads
+ *   `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` and only then `OTEL_EXPORTER_OTLP_ENDPOINT`, so a
+ *   per-signal default would shadow an operator's base URL and send their traces to CT100.
+ * ⚠️ THE SERVICE NAME STEPS ASIDE FOR `service.name` IN `OTEL_RESOURCE_ATTRIBUTES` FOR THE SAME
+ *   REASON. Effect resolves `OTEL_SERVICE_NAME`, then that attribute, then fails, so an injected
+ *   `OTEL_SERVICE_NAME` would win over the operator's attribute and Effect then drops the
+ *   attribute, leaving their seat mislabelled `seat-runtime` in Victoria with nothing to say why.
+ */
+const defaults: Effect.Effect<ConfigProvider.ConfigProvider> = Effect.gen(function* () {
+  const current = yield* ConfigProvider.ConfigProvider;
+  const base = yield* current.load(['OTEL_EXPORTER_OTLP_ENDPOINT']);
+  const attributes = yield* resourceAttributes.parse(current);
+  const named = attributes?.['service.name'] !== undefined;
+  return ConfigProvider.fromUnknown({
+    OTEL_TRACES_EXPORTER: 'otlp',
+    OTEL_LOGS_EXPORTER: 'otlp',
+    OTEL_METRICS_EXPORTER: 'otlp',
+    ...(named ? {} : { OTEL_SERVICE_NAME: DEFAULT_SERVICE_NAME }),
+    ...(base === undefined
+      ? {
+          OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: CT100_ENDPOINTS.traces,
+          OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: CT100_ENDPOINTS.logs,
+          OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: CT100_ENDPOINTS.metrics,
+        }
+      : {}),
+  });
+}).pipe(Effect.orDie);
+
+/**
+ * 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 const layer: Layer.Layer<OtlpExporter.Flusher> = Layer.mergeAll(
+  OtlpTracer.layerFromConfig(),
+  OtlpLogger.layerFromConfig(),
+  OtlpMetrics.layerFromConfig(),
+).pipe(
+  Layer.provide(OtlpSerialization.layerProtobuf),
+  Layer.provide(FetchHttpClient.layer),
+  Layer.provide(ConfigProvider.layerAdd(defaults)),
+);

package/src/seat-state.ts

@@ -0,0 +1,53 @@
+/**
+ * `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,
+  postgres,
+  postgresFromEnv,
+} from './state-postgres.ts';
+import {
+  type ValkeyFromEnvOptions,
+  type ValkeyOptions,
+  valkey,
+  valkeyFromEnv,
+} from './state-valkey.ts';
+
+export * from './state-postgres.ts';
+export * from './state-valkey.ts';
+// ★ RE-EXPORTED so a consumer under pnpm's strict resolution can name `PgClient` (for `.json`,
+//   `.listen`, `.notify`) without also depending on `@effect/sql-pg` itself.
+export { PgClient } from '@effect/sql-pg';
+
+/** Both stores, each built from an explicit URL. */
+export const layer = (options: {
+  readonly postgres: PostgresOptions;
+  readonly valkey: ValkeyOptions;
+}): Layer.Layer<
+  PgClient.PgClient | SqlClient.SqlClient | Redis.Redis,
+  SqlError | Redis.RedisError
+> => Layer.mergeAll(postgres(options.postgres), valkey(options.valkey));
+
+/** Both stores, each URL read from its environment variable (`SEAT_POSTGRES_URL`, `SEAT_VALKEY_URL`). */
+export const layerFromEnv = (options?: {
+  readonly postgres?: PostgresFromEnvOptions | undefined;
+  readonly valkey?: ValkeyFromEnvOptions | undefined;
+}): Layer.Layer<
+  PgClient.PgClient | SqlClient.SqlClient | Redis.Redis,
+  SqlError | Redis.RedisError | Config.ConfigError
+> => Layer.mergeAll(postgresFromEnv(options?.postgres), valkeyFromEnv(options?.valkey));

package/src/stamp.ts

@@ -0,0 +1,88 @@
+/**
+ * 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;
+};
+
+/**
+ * ⛔ A TAG IS A TOKEN, NOT A SENTENCE. LiteLLM splits `x-litellm-tags` on commas and this
+ *   package joins with them, so a comma inside a tag would silently become two tags, and a
+ *   control character in a header value is header injection. Printable ASCII, no comma, no
+ *   space; `host:ct100` and `seat:cf-coding` are the shape.
+ */
+const TAG = /^[\x21-\x2b\x2d-\x7e]{1,128}$/;
+
+/** Validate and join. Throws at layer construction, where the mistake is one line away. */
+export function joinTags(tags: string | ReadonlyArray<string>): string {
+  const list = typeof tags === 'string' ? tags.split(',') : [...tags];
+  if (list.length === 0) throw new TypeError('seat tags: at least one tag is required');
+  for (const tag of list) {
+    if (!TAG.test(tag)) {
+      throw new TypeError(
+        `seat tags: ${JSON.stringify(tag)} is not a tag (1-128 printable ASCII, no comma or space)`,
+      );
+    }
+  }
+  return list.join(',');
+}
+
+/** The JSON body as an object, or undefined for anything this must leave alone. */
+function jsonObject(
+  request: HttpClientRequest.HttpClientRequest,
+): Record<string, unknown> | undefined {
+  const body = request.body;
+  if (body._tag !== 'Uint8Array' || !body.contentType.includes('json')) return undefined;
+  // ⚠️ `text` is only "the original text retained for adapters that can skip encoding"
+  //   (HttpBody.d.ts): a body built from bytes has none. Decoding the bytes keeps the stamp
+  //   from becoming a silent no-op, which is the failure that would leave the LiteLLM cache
+  //   ON for a seat that asked for it off.
+  const text = body.text ?? new TextDecoder().decode(body.body);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+  return parsed as Record<string, unknown>;
+}
+
+/** Headers and body fields for one request. Pure: the same request in, a new one out. */
+export function stampRequest(
+  request: HttpClientRequest.HttpClientRequest,
+  stamp: SeatStamp,
+): HttpClientRequest.HttpClientRequest {
+  const headers = stamp.noCache
+    ? { 'x-litellm-tags': stamp.tags, 'cache-control': 'no-cache, no-store' }
+    : { 'x-litellm-tags': stamp.tags };
+  const tagged = HttpClientRequest.setHeaders(request, headers);
+  const body = jsonObject(request);
+  if (body === undefined) return tagged;
+  return HttpClientRequest.bodyJsonUnsafe(tagged, {
+    ...body,
+    // ⚠️ THE HEADER ALONE DOES NOT TURN THE CACHE OFF. Measured 2026-09-25 (cf-review PR 22,
+    //   LiteLLM 1.100.0): `cache: {"no-cache": true}` skips the read and `"no-store": true`
+    //   skips the write; `caching: false` in the body is a no-op, and a repeat answered from
+    //   the cache reads as agreement. The Cache-Control header is sent as well, for the
+    //   Cloudflare AI Gateway below LiteLLM, and is not what LiteLLM honours.
+    ...(stamp.noCache ? { cache: { 'no-cache': true, 'no-store': true } } : {}),
+    // ★ ZERO, ALWAYS. A seat retries in Effect, where the attempt is a span; LiteLLM retrying
+    //   behind it would multiply attempts invisibly (and bill each one).
+    num_retries: 0,
+    ...(stamp.metadata !== undefined && !('metadata' in body) ? { metadata: stamp.metadata } : {}),
+  });
+}

package/src/state-dsn.ts

@@ -0,0 +1,112 @@
+/**
+ * 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;
+};
+
+/**
+ * Query keys that OVERRIDE the authority in `@effect/sql-pg`'s own parser (rc.115 `parseUrl`).
+ * ⚠️ When a URL carries one, the fields below would be a second, conflicting answer (explicit
+ *   config wins over the URL), so none are derived and the driver's reading stands.
+ */
+const OVERRIDING_KEYS: ReadonlySet<string> = new Set(['host', 'port', 'user', 'dbname']);
+
+/** `decodeURIComponent` that reports failure as `undefined` instead of throwing its message. */
+function decode(value: string): string | undefined {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return undefined;
+  }
+}
+
+/** `new URL` that reports failure as `undefined`: its `TypeError` carries the string. */
+function parse(raw: string): URL | undefined {
+  try {
+    return new URL(raw);
+  } catch {
+    return 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 function postgresFields(dsn: string): PostgresFields | undefined {
+  const url = parse(dsn);
+  if (url === undefined) return undefined;
+  for (const key of url.searchParams.keys()) if (OVERRIDING_KEYS.has(key)) return {};
+  const hostname =
+    url.hostname.startsWith('[') && url.hostname.endsWith(']')
+      ? url.hostname.slice(1, -1)
+      : decode(url.hostname);
+  const database = decode(url.pathname.replace(/^\//, ''));
+  const username = decode(url.username);
+  const port = url.port === '' ? undefined : Number(url.port);
+  // ⚠️ A piece that will not decode or parse is left to the driver, which fails with its own
+  //   message (it names a port or a component, never the string).
+  if (hostname === undefined || database === undefined || username === undefined) return {};
+  if (port !== undefined && !(Number.isInteger(port) && port >= 1 && port <= 65535)) return {};
+  return {
+    host: hostname === '' ? undefined : hostname,
+    port,
+    database: database === '' ? undefined : database,
+    username: username === '' ? undefined : username,
+  };
+}
+
+/** The URL schemes `Bun.RedisClient` accepts (its own error names exactly these seven). */
+const VALKEY_SCHEMES: ReadonlySet<string> = new Set([
+  'redis:',
+  'valkey:',
+  'rediss:',
+  'valkeys:',
+  'redis+tls:',
+  'redis+unix:',
+  'redis+tls+unix:',
+]);
+
+/** `undefined` when `raw` is not a URL of a scheme `Bun.RedisClient` takes. */
+export function valkeyFields(raw: string): ValkeyFields | undefined {
+  const url = parse(raw);
+  if (url === undefined || !VALKEY_SCHEMES.has(url.protocol)) return undefined;
+  if (url.protocol.endsWith('+unix:')) return {};
+  const host = url.hostname.startsWith('[') ? url.hostname.slice(1, -1) : url.hostname;
+  const database = url.pathname.replace(/^\//, '');
+  return {
+    host: host === '' ? undefined : host,
+    port: url.port === '' ? 6379 : Number(url.port),
+    database: database === '' ? undefined : database,
+  };
+}

package/src/state-postgres.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import type * as SqlClient from 'effect/unstable/sql/SqlClient';
+import { ConnectionError, SqlError } from 'effect/unstable/sql/SqlError';
+import { postgresFields } from './state-dsn.ts';
+
+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 const POSTGRES_URL_VARIABLE = 'SEAT_POSTGRES_URL';
+
+const DEFAULT_CONNECT_TIMEOUT: Duration.Duration = Duration.seconds(5);
+
+/** A failure that names the reason and never the DSN. */
+const refused = (message: string): SqlError =>
+  new SqlError({
+    reason: new ConnectionError({
+      cause: new Error(message),
+      message: `SeatState postgres: ${message}`,
+      operation: 'connect',
+    }),
+  });
+
+const acquire = Effect.fnUntraced(function* (options: PostgresOptions) {
+  const dsn = Redacted.value(
+    typeof options.url === 'string' ? Redacted.make(options.url) : options.url,
+  );
+  const fields = postgresFields(dsn);
+  if (fields === undefined) return yield* refused('the URL is not a postgres:// URL');
+  const connectTimeout = options.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT;
+  const client = yield* PgClient.make({
+    url: Redacted.make(dsn),
+    ...fields,
+    maxConnections: options.maxConnections,
+    connectTimeout,
+    applicationName: options.applicationName,
+  });
+  yield* client`select 1`.pipe(
+    Effect.timeoutOrElse({
+      duration: connectTimeout,
+      orElse: () =>
+        Effect.fail(
+          refused(`did not answer within ${String(Duration.toMillis(connectTimeout))} ms`),
+        ),
+    }),
+  );
+  return client;
+});
+
+/**
+ * `SqlClient` and `PgClient` against one Postgres. The pool closes with the layer's scope.
+ */
+export const postgres = (
+  options: PostgresOptions,
+): Layer.Layer<PgClient.PgClient | SqlClient.SqlClient, SqlError> =>
+  PgClient.layerFrom(Effect.suspend(() => acquire(options)));
+
+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 const postgresFromEnv = (
+  options?: PostgresFromEnvOptions,
+): Layer.Layer<PgClient.PgClient | SqlClient.SqlClient, SqlError | Config.ConfigError> => {
+  const { variable, ...rest } = options ?? {};
+  return Layer.unwrap(
+    Config.Redacted(variable ?? POSTGRES_URL_VARIABLE).pipe(
+      Effect.map((url) => postgres({ ...rest, url })),
+    ),
+  );
+};