@homeflare/alchemy 0.43.0 → 0.45.0

package/src/valkey/errors.ts

@@ -0,0 +1,239 @@
+/**
+ * `Valkey` family's failures as typed tags (S21).
+ *
+ * ⛔ NONE OF THESE IS A STATUS-CODE OR MESSAGE MATCH. They are raised by this family's own code
+ *   from facts it already checked — missing env vars, mismatched live state, failed read-back —
+ *   never from sniffing a server error's text. Socket/protocol errors use their own tags in
+ *   `transport.ts`.
+ */
+import * as Data from 'effect/Data';
+
+/** The live instance does not match an asserted property. Like `Postgres.DatabaseDrift`, this
+ * family asserts properties at create and refuses drift rather than silently issuing a
+ * reconfiguration that could drop state. */
+export class ValkeyInstanceDrift extends Data.TaggedError('ValkeyInstanceDrift')<{
+  readonly instance: string;
+  readonly prop: string;
+  readonly declared: unknown;
+  readonly live: unknown;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.Instance "${this.instance}": ${this.prop} is declared as ` +
+      `${JSON.stringify(this.declared)} but the live instance has ${JSON.stringify(this.live)}. ` +
+      'Update the declaration to match the live value, or change it by hand and re-plan.'
+    );
+  }
+}
+
+/** `Valkey.Instance` found the instance unreachable or refused authentication when reading it.
+ * `host` is optional because it is the connection layer's value (`connection.ts`), never a prop
+ * this resource holds — a reconcile that only knows its own declaration names the port. */
+export class ValkeyInstanceUnreachable extends Data.TaggedError('ValkeyInstanceUnreachable')<{
+  readonly instance: string;
+  readonly host?: string;
+  readonly port: number;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.Instance "${this.instance}" at ${this.host === undefined ? '' : `${this.host}:`}` +
+      `${String(this.port)}: could not verify the instance. Check that the Quadlet container is ` +
+      'running and the ACL/password is correct.'
+    );
+  }
+}
+
+/** An ACL LIST line could not be parsed. Neither the message nor error data retain the
+ * raw line: error serialization must not expose its password hash. */
+export class ValkeyAclParseError extends Data.TaggedError('ValkeyAclParseError')<{
+  // No raw ACL data.
+}> {
+  override get message(): string {
+    return (
+      'Valkey.AclFile: cannot parse an ACL LIST line. The line is withheld from this message ' +
+      'because it can carry a password hash.'
+    );
+  }
+}
+
+/** A declared ACL user is missing a referenced password; a user with no password can authenticate
+ * as nobody, which would bypass isolation. */
+export class ValkeyAclPasswordMissing extends Data.TaggedError('ValkeyAclPasswordMissing')<{
+  readonly instance: string;
+  readonly user: string;
+  readonly variable: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": ACL user "${this.user}" references environment ` +
+      `variable ${this.variable}, which is missing or empty at call time.`
+    );
+  }
+}
+
+/** The stack's own connection password is a `{ fromEnv }` reference that resolved to nothing at
+ * call time. Distinct from `ValkeyInstanceUnreachable` (nothing answered on the wire) and from
+ * `ValkeyAclPasswordMissing` (a DECLARED ACL user's password): this one is the credential the
+ * stack itself authenticates with to reach an instance. */
+export class ValkeyAuthPasswordMissing extends Data.TaggedError('ValkeyAuthPasswordMissing')<{
+  readonly username: string | undefined;
+  readonly variable: string;
+}> {
+  override get message(): string {
+    const who = this.username === undefined ? '' : ` as "${this.username}"`;
+    return (
+      `Valkey connection${who}: password environment variable ${this.variable} is missing or ` +
+      'empty at call time. Render the secret into the deploying process environment and re-plan.'
+    );
+  }
+}
+
+/** The live ACL after a reconcile does not match the declaration on read-back — the write was lost
+ * or a concurrent mutator changed it before we could verify. */
+export class ValkeyAclReadbackFailed extends Data.TaggedError('ValkeyAclReadbackFailed')<{
+  readonly instance: string;
+  readonly user: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": ACL reconciliation for "${this.user}" reported success, ` +
+      'but readback contradicts the declared rules or removal. Re-plan.'
+    );
+  }
+}
+
+/** A `seat`-profile user's key prefix escapes its own keyspace. The seat profile exists to pin
+ * each seat to keys beginning with its own name (`~<name>:…`); `keyPrefix` goes on the wire as
+ * `~<keyPrefix>`, so `*` is every key and `grok:*` is another seat's. Refused before any write —
+ * a `service` user is the profile that owns a whole instance. */
+export class ValkeyAclSeatKeyPrefix extends Data.TaggedError('ValkeyAclSeatKeyPrefix')<{
+  readonly instance: string;
+  readonly user: string;
+  readonly keyPrefix: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": ACL user "${this.user}" declares key prefix ` +
+      `"${this.keyPrefix}". A seat user is limited to "${this.user}:*"; a user that owns ` +
+      'every key on the instance declares profile "service".'
+    );
+  }
+}
+
+/** A declaration names `default` or the connection username. `ACL SETUSER` `reset` would replace
+ * the credential this kit authenticates with (`~* +@all`) with a profile that cannot run `ACL`,
+ * and the next `ACL LIST` answers `NOPERM`. Refused before any write. */
+export class ValkeyAclReservedUser extends Data.TaggedError('ValkeyAclReservedUser')<{
+  readonly instance: string;
+  readonly user: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": refusing to manage ACL user "${this.user}". ` +
+      'That name is `default` or the connection username. ACL SETUSER reset would replace the ' +
+      'credential this kit authenticates with, and the next ACL LIST would answer NOPERM.'
+    );
+  }
+}
+
+/** A live or stored ACL user is keyed under one name but its line carries another — the parsed
+ * `user` name disagrees with the record key this family stores it under. The record key is this
+ * family's identity, so the mismatch means the ACL was changed by something else. */
+export class ValkeyAclUserNameMismatch extends Data.TaggedError('ValkeyAclUserNameMismatch')<{
+  readonly instance: string;
+  readonly recordKey: string;
+  readonly user: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": ACL user "${this.user}" was found keyed under ` +
+      `"${this.recordKey}". This family keys every user by its own name; re-plan or fix the ` +
+      'ACL by hand on the instance.'
+    );
+  }
+}
+
+export type ValkeyError =
+  | ValkeyInstanceDrift
+  | ValkeyInstanceUnreachable
+  | ValkeyAclParseError
+  | ValkeyAclPasswordMissing
+  | ValkeyAclReadbackFailed
+  | ValkeyAclUserNameMismatch
+  | ValkeyAclReservedUser
+  | ValkeyAclSeatKeyPrefix
+  | ValkeyAclMonitorKeyPrefix
+  | ValkeyAclNameGlob
+  | ValkeyAclChannelPatterns
+  | ValkeyAclFileRendered
+  | ValkeyAuthPasswordMissing;
+
+/** A `monitor`-profile user was declared with a key prefix. The monitor profile exists for the
+ * key-less `redis_exporter` identity (ct100#117): its rules carry `resetkeys`, and a `~` pattern
+ * next to them would contradict the key-less shape the profile is fixed to. Refused before any
+ * write. */
+export class ValkeyAclMonitorKeyPrefix extends Data.TaggedError('ValkeyAclMonitorKeyPrefix')<{
+  readonly instance: string;
+  readonly user: string;
+  readonly keyPrefix: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": ACL user "${this.user}" declares profile "monitor" ` +
+      `with key prefix "${this.keyPrefix}". The monitor profile is key-less (resetkeys); omit ` +
+      'the keyPrefix.'
+    );
+  }
+}
+
+/** A username carries glob characters (`*`, `?`, `[`, `]`). Names are interpolated into key and
+ * channel patterns (`~<name>:*`, `&<name>:*`), so a glob in the name would widen the patterns
+ * the profile is fixed to — `seat*` would reach `seat2:*`. Refused before any write. */
+export class ValkeyAclNameGlob extends Data.TaggedError('ValkeyAclNameGlob')<{
+  readonly instance: string;
+  readonly user: string;
+  readonly chars: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": ACL user "${this.user}" contains glob characters ` +
+      `(${this.chars}). A name is interpolated into key and channel patterns, so a glob would ` +
+      'widen the isolation the profile fixes. Use a glob-free name.'
+    );
+  }
+}
+
+/** The instance renders its ACL from a file (`--aclfile`, answered by `CONFIG GET aclfile`), so
+ * the FILE is the source of truth and this family cannot manage it: the kit speaks RESP only, it
+ * can neither write the file nor outlast the renderer that owns it (CT100: openbao-agent renders
+ * `/etc/valkey/*-acl.conf` and mounts it read-only — a runtime `ACL SETUSER` there is reverted by
+ * the next render/restart, measured 2026-09-30 as a WRONGPASS seat). Declare those users in the
+ * rendering template instead, or use kit-owned runtime ACL management without a configured ACL file. */
+export class ValkeyAclFileRendered extends Data.TaggedError('ValkeyAclFileRendered')<{
+  readonly instance: string;
+  readonly path: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": the instance loads its ACL from "${this.path}" ` +
+      '(CONFIG GET aclfile), so the file — not this family — is the source of truth. The kit ' +
+      'speaks RESP only and can neither write that file nor survive the renderer that owns it; ' +
+      'a runtime ACL SETUSER there is reverted on the next render or restart. Declare the users ' +
+      'in the rendering template. Adoption also reconciles and is refused. ACL reads require ' +
+      'ACL LIST permission, which CT100 rendered users do not have.'
+    );
+  }
+}
+
+/** A fixed profile cannot widen its channel boundary by declaration. */
+export class ValkeyAclChannelPatterns extends Data.TaggedError('ValkeyAclChannelPatterns')<{
+  readonly instance: string;
+  readonly user: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.AclFile "${this.instance}": invalid channel patterns for "${this.user}". ` +
+      'Seats require <name>:*; monitors require no channels.'
+    );
+  }
+}

package/src/valkey/fake-acl.ts

@@ -0,0 +1,128 @@
+/** ACL state model for the recording fake. Valkey's ACL docs specify additive SETUSER,
+ * reset, hash-only LIST echoes, and channel checks; this is not a complete ACL evaluator. */
+import { createHash } from 'node:crypto';
+/** One user's ACL state — the fake's parsed mirror of what a real server keeps per user. */
+export interface FakeAclUser {
+  on: boolean;
+  nopass: boolean;
+  /** The stored `#<sha256>` tokens, empty when the user has no passwords. */
+  passwords: ReadonlyArray<string>;
+  /** Key patterns with their `~`, e.g. `['~claude:*']`. */
+  keys: ReadonlyArray<string>;
+  /** Channel patterns with their `&`; `['&*']` is what `allchannels` echoes as. */
+  channels: ReadonlyArray<string>;
+  /** The `+`/`-` rule tokens, with the `-@all` baseline the echo keeps. */
+  rules: ReadonlyArray<string>;
+}
+
+export const sha256 = (value: string): string => createHash('sha256').update(value).digest('hex');
+
+/** A user straight out of `reset`: off, no password, no patterns, the `-@all` baseline. */
+export const freshUser = (): FakeAclUser => ({
+  on: false,
+  nopass: false,
+  passwords: [],
+  keys: [],
+  channels: [],
+  rules: ['-@all'],
+});
+
+/** Apply one `ACL SETUSER` rule token, in order — the fake's model of the server's own
+ * incremental semantics (`reset` resets, `+@all` cancels the `-@all` baseline, and so on). */
+export const applyToken = (user: FakeAclUser, token: string): void => {
+  switch (token) {
+    case 'reset':
+      Object.assign(user, freshUser());
+      break;
+    case 'reseton':
+    case 'resetoff':
+      user.on = false;
+      break;
+    case 'resetkeys':
+      user.keys = [];
+      break;
+    case 'resetchannels':
+      user.channels = [];
+      break;
+    case 'resetpass':
+      user.passwords = [];
+      user.nopass = false;
+      break;
+    case 'on':
+      user.on = true;
+      break;
+    case 'off':
+      user.on = false;
+      break;
+    case 'nopass':
+      user.nopass = true;
+      user.passwords = [];
+      break;
+    case 'allkeys':
+      user.keys = ['~*'];
+      break;
+    case 'allchannels':
+      user.channels = ['&*'];
+      break;
+    default:
+      if (token.startsWith('#')) {
+        user.passwords = [...new Set([...user.passwords, token])];
+        user.nopass = false;
+      } else if (token.startsWith('>')) {
+        user.passwords = [...new Set([...user.passwords, `#${sha256(token.slice(1))}`])];
+        user.nopass = false;
+      } else if (token.startsWith('<') || token.startsWith('!')) {
+        const hash = token[0] === '<' ? sha256(token.slice(1)) : token.slice(1);
+        user.passwords = user.passwords.filter((password) => password !== `#${hash}`);
+      } else if (token.startsWith('~')) {
+        user.keys = [...user.keys, token];
+      } else if (token.startsWith('&')) {
+        user.channels = [...user.channels, token];
+      } else if (token === '-@all' || token === '+@all') {
+        user.rules = [token];
+      } else if (token.startsWith('+') || token.startsWith('-')) {
+        const rules = [...user.rules];
+        const i = rules.indexOf(token);
+        if (i >= 0) rules.splice(i, 1);
+        user.rules = [...rules, token];
+      }
+  }
+};
+
+/** The `ACL LIST` echo for one user — the MEASURED shape: flags, password hash, key patterns,
+ * the bare `resetchannels` marker before the channel patterns, then the rule tokens. */
+export const renderUser = (name: string, user: FakeAclUser): string =>
+  [
+    'user',
+    name,
+    user.on ? 'on' : 'off',
+    user.nopass ? 'nopass' : '',
+    ...user.passwords,
+    ...user.keys,
+    'resetchannels',
+    ...user.channels,
+    ...user.rules,
+  ]
+    .filter((part) => part !== '')
+    .join(' ');
+
+/** Tokenize a seeded `ACL LIST` line the way the fake would have stored the SETUSER that made
+ * it, so a seed and a write land in the same shape. */
+export const seedUser = (line: string): FakeAclUser => {
+  const user = freshUser();
+  const parts = line.split(' ');
+  if (parts[2] === 'on' || parts[2] === 'off') applyToken(user, parts[2]);
+  for (const part of parts.slice(3)) applyToken(user, part);
+  return user;
+};
+
+/** Does `channel` match one of the session user's `&` patterns? Glob, the way the server's
+ * `&pat:*` works for PUBLISH. */
+export const channelAllowed = (user: FakeAclUser, channel: string): boolean =>
+  user.channels.some((pattern) => {
+    const glob = pattern
+      .slice(1)
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*/g, '.*');
+    return new RegExp(`^${glob}$`).test(channel);
+  });

package/src/valkey/fake-valkey.ts

@@ -0,0 +1,224 @@
+/**
+ * A recording fake `ValkeyExecutor` that answers the way a REAL valkey 8.1.10 answers, not the
+ * way this family's code writes (S28: tests read back from the fake's own in-memory state, not
+ * from the command list). No socket, no `node:net` — it re-derives exactly the commands this
+ * family ever issues (`INFO`, `CONFIG GET`, `AUTH`, `ACL LIST/SETUSER/DELUSER/SAVE`, `PING`,
+ * `PUBLISH`) against per-user ACL state, with the echo and error shapes MEASURED against a
+ * disposable 8.1.10 scratch container (2026-09-30):
+ *
+ * ★ `ACL LIST` echoes the server's normalised form, not the SETUSER argument list: the `reset`
+ *   baseline appears as an explicit `-@all` token (cancelled only by `+@all`), `allchannels`
+ *   echoes as `&*`, an empty channel list echoes the bare `resetchannels` marker, `reset` and
+ *   the password VALUE are dropped (only the `#<sha256>` hash echoes).
+ * ★ `AUTH` compares the sha256 of the presented password and refuses with the measured
+ *   WRONGPASS text; `PUBLISH` refuses by CHANNEL with the measured NOPERM text.
+ * ★ `ACL SAVE` errors with the measured "not configured to use an ACL file" text while no
+ *   `aclfile` is configured — which is why the write path never calls it — and answers `OK`
+ *   once `config.aclfile` names a writable file.
+ */
+import {
+  type FakeAclUser,
+  applyToken,
+  channelAllowed,
+  freshUser,
+  renderUser,
+  seedUser,
+  sha256,
+} from './fake-acl.ts';
+import * as Effect from 'effect/Effect';
+import { memoryBytes } from './instance-form.ts';
+import type { ValkeyExecutor, ValkeyReply, ValkeyServerError } from './transport.ts';
+
+export interface RecordedCommand {
+  readonly args: ReadonlyArray<string>;
+}
+
+export interface FakeValkey extends ValkeyExecutor {
+  readonly commands: ReadonlyArray<RecordedCommand>;
+  /** Mutable on purpose: a test seeds a value a "competing" write would have produced before
+   * the fake ever sees it. The `aclfile` entry is what `CONFIG GET aclfile` answers. */
+  readonly config: Map<string, string>;
+  /** The live ACL as `ACL LIST` echoes it, keyed by username — the fake's own report, not the
+   * command list (S28). */
+  readonly acl: Map<string, string>;
+  /** Which usernames the fake accepts an `AUTH` for, and at which plaintext (test fixtures). */
+  readonly passwords: Map<string, string>;
+}
+
+export interface FakeValkeyOptions {
+  readonly config?: Readonly<Record<string, string>>;
+  /** Seed users as `ACL LIST` lines, parsed with the same tokenizer as SETUSER. */
+  readonly acl?: Readonly<Record<string, string>>;
+  readonly passwords?: Readonly<Record<string, string>>;
+  /** Fail the NEXT write (`ACL SETUSER`/`ACL DELUSER`) once, the way a concurrent mutator would. */
+  readonly raceNextWrite?: boolean;
+  /** Re-add this user after EVERY successful ACL write — a concurrent mutator that survives the
+   * reconcile's writes, so the read-back (never the write reply) is what catches it. */
+  readonly reAddAfterWrite?: { readonly name: string; readonly line: string };
+  /** The version `INFO` reports as `valkey_version` (with a `redis_version` fallback line). */
+  readonly version?: string;
+  /** `INFO` `tcp_port`. Defaults to 0, the reply a server that omitted the line would give. */
+  readonly port?: number;
+}
+
+export const makeFakeValkey = (options: FakeValkeyOptions = {}): FakeValkey => {
+  const commands: RecordedCommand[] = [];
+  const config = new Map(Object.entries({ aclfile: '', ...options.config }));
+  const users = new Map<string, FakeAclUser>(
+    Object.entries(options.acl ?? {}).map(([name, line]) => [name, seedUser(line)]),
+  );
+  const passwords = new Map(Object.entries(options.passwords ?? {}));
+  const acl = new Map<string, string>();
+  const resync = (): void => {
+    acl.clear();
+    for (const [name, user] of users) acl.set(name, renderUser(name, user));
+  };
+  resync();
+  let raceRemaining = options.raceNextWrite === true ? 1 : 0;
+  const reAdd = options.reAddAfterWrite;
+  const afterWrite = (): void => {
+    if (reAdd !== undefined) {
+      users.set(reAdd.name, seedUser(reAdd.line));
+      resync();
+    }
+  };
+  let session = 'default';
+
+  const reply = (value: string | null | ReadonlyArray<string | null>): ValkeyReply =>
+    typeof value === 'string' || value === null
+      ? ({ kind: 'bulk', value } as const)
+      : ({ kind: 'array', values: value } as const);
+  const error = (message: string): ValkeyReply => ({ kind: 'error', message }) as const;
+
+  const send = (args: ReadonlyArray<string>): Effect.Effect<ValkeyReply, ValkeyServerError> =>
+    Effect.sync(() => {
+      commands.push({ args });
+      users.clear();
+      for (const [name, line] of acl) users.set(name, seedUser(line));
+      const [cmd, ...rest] = args;
+
+      switch (cmd) {
+        case 'PING':
+          return reply('PONG');
+
+        case 'AUTH': {
+          const [user, pass] = rest.length > 1 ? rest : ['default', rest[0]];
+          if (pass === undefined) {
+            return error('ERR wrong number of arguments for AUTH');
+          }
+          const known = users.get(user ?? 'default');
+          const configured = passwords.get(user ?? 'default');
+          const ok =
+            known !== undefined
+              ? known.on && (known.nopass || known.passwords.includes(`#${sha256(pass)}`))
+              : configured !== undefined && configured === pass;
+          if (!ok) return error('WRONGPASS invalid username-password pair or user is disabled.');
+          session = user ?? 'default';
+          return reply('OK');
+        }
+
+        case 'INFO': {
+          const version = options.version ?? '8.1.10';
+          const port = options.port ?? 0;
+          return reply(
+            [
+              '# Server',
+              `valkey_version:${version}`,
+              'redis_version:7.2.4',
+              'redis_mode:standalone',
+              `tcp_port:${String(port)}`,
+              '# Persistence',
+              'loading:0',
+              '# Keyspace',
+            ].join('\r\n'),
+          );
+        }
+
+        case 'CONFIG': {
+          if (rest[0] !== 'GET') {
+            return error(`ERR CONFIG ${rest[0]} not supported by fake`);
+          }
+          const out: Array<string | null> = [];
+          for (const key of rest.slice(1)) {
+            const raw = config.get(key);
+            if (raw === undefined) continue; // a real server omits keys it has no answer for
+            out.push(key);
+            if (key === 'maxmemory') {
+              const bytes = memoryBytes(raw);
+              out.push(bytes === undefined ? raw : String(bytes));
+            } else {
+              out.push(raw);
+            }
+          }
+          return reply(out);
+        }
+
+        case 'PUBLISH': {
+          const [channel] = rest;
+          const me = users.get(session);
+          if (me === undefined || session === 'default') return reply('0');
+          const mayRun = me.rules.includes('+@all') || me.rules.includes('+@pubsub');
+          if (!mayRun) {
+            return error(`NOPERM User ${session} has no permissions to run the 'publish' command`);
+          }
+          if (!channelAllowed(me, channel ?? '')) {
+            return error('NOPERM No permissions to access a channel');
+          }
+          return reply('0');
+        }
+
+        case 'ACL': {
+          const sub = rest[0];
+          if (sub === 'LIST') {
+            return reply([...acl.values()] as Array<string | null>);
+          }
+          if (sub === 'SETUSER') {
+            if (raceRemaining > 0) {
+              raceRemaining -= 1;
+              return error('ERR fake race');
+            }
+            const username = rest[1];
+            if (username === undefined) {
+              return error('ERR wrong number of arguments for SETUSER');
+            }
+            const user = users.get(username) ?? freshUser();
+            for (const token of rest.slice(2)) applyToken(user, token);
+            users.set(username, user);
+            resync();
+            afterWrite();
+            return reply('OK');
+          }
+          if (sub === 'DELUSER') {
+            if (raceRemaining > 0) {
+              raceRemaining -= 1;
+              return error('ERR fake race');
+            }
+            let removed = 0;
+            for (const name of rest.slice(1)) {
+              if (users.delete(name)) removed += 1;
+            }
+            resync();
+            afterWrite();
+            return reply(String(removed));
+          }
+          if (sub === 'SAVE') {
+            if ((config.get('aclfile') ?? '') === '') {
+              return error(
+                'ERR This instance is not configured to use an ACL file. You may want to ' +
+                  'specify users via the ACL SETUSER command and then issue a CONFIG REWRITE ' +
+                  '(assuming you have a configuration file set) in order to store users in the ' +
+                  'configuration.',
+              );
+            }
+            return reply('OK');
+          }
+          return error(`ERR ACL ${sub} not supported by fake`);
+        }
+
+        default:
+          return error(`ERR unknown command '${cmd}'`);
+      }
+    });
+
+  return { send, commands, config, acl, passwords };
+};

package/src/valkey/handler-test-fixture.ts

@@ -0,0 +1,43 @@
+/** Test-only connection injection: no listener, module mock or live endpoint. */
+import * as Effect from 'effect/Effect';
+import {
+  type ValkeyConnection,
+  type ValkeyConnectionConfig,
+  auth,
+  type withValkey,
+} from './connection.ts';
+import type { Environment } from '../secrets/write-only.ts';
+import type { ValkeyExecutor } from './transport.ts';
+import { valkeyConnection } from './connection.ts';
+
+export const config: ValkeyConnectionConfig = {
+  instance: 'scratch',
+  host: '127.0.0.1',
+  port: 0,
+  username: 'admin',
+  password: { fromEnv: 'TEST_VALKEY_ADMIN_PW' },
+};
+export const env: Environment = { TEST_VALKEY_ADMIN_PW: 'FAKE-admin' };
+export const connection =
+  (executor: ValkeyExecutor, credentials: Environment = env): typeof withValkey =>
+  (build) =>
+    Effect.gen(function* () {
+      yield* auth(executor, config, credentials);
+      return yield* build(executor, config);
+    });
+export const run = <A, E>(effect: Effect.Effect<A, E, ValkeyConnection>): Promise<A> =>
+  Effect.runPromise(effect.pipe(Effect.provide(valkeyConnection(config))));
+export const context = {
+  id: 'scratch',
+  fqn: 'scratch',
+  instanceId: 'scratch',
+  session: undefined as never,
+  bindings: [],
+  oldBindings: [],
+  newBindings: [],
+};
+
+export const required = <T>(value: T | undefined): T => {
+  if (value === undefined) throw new Error('missing test fixture or handler');
+  return value;
+};