@homeflare/alchemy 0.43.0 → 0.45.0

package/src/valkey/acl.test.ts

@@ -0,0 +1,215 @@
+/**
+ * `Valkey.AclFile` against `fake-valkey.ts`'s recording fake — creating a user, converging a user
+ * tampered with outside the stack, rotating a password, removing a user, missing-password
+ * refusal, and read-back verification. Every case reverts cleanly by reverting `acl-ops.ts`/
+ * `acl-form.ts` locally.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { readWithExecutor } from './acl-ops.ts';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+import { matchesDeclared } from './acl-compare.ts';
+import { buildSetUserArgs, parseAclLine, planAclUsers } from './acl-form.ts';
+import { ValkeyAclPasswordMissing, ValkeyAclReadbackFailed } from './errors.ts';
+import { makeFakeValkey } from './fake-valkey.ts';
+import type { ValkeyAclFileProps, ValkeyAclUser } from './acl-attrs.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const env = { CLAUDE_PW: 'FAKE-seat-password', GROK_PW: 'FAKE-grok-password' };
+const claude: ValkeyAclUser = {
+  name: 'claude',
+  keyPrefix: 'claude:*',
+  profile: 'seat',
+  password: { fromEnv: 'CLAUDE_PW' },
+};
+const props = (over: Partial<ValkeyAclFileProps['users']> = {}): ValkeyAclFileProps => ({
+  instance: 'valkey-seats',
+  users: { claude, ...over },
+});
+
+describe('buildSetUserArgs', () => {
+  test('emits reset-first, on, password, key prefix, channel scope, and the seat deny list', async () => {
+    const args = await run(buildSetUserArgs(claude, 'FAKE-password'));
+    expect(args.slice(0, 4)).toEqual(['ACL', 'SETUSER', 'claude', 'reset']);
+    expect(args).toContain('on');
+    expect(args.some((arg) => /^#[a-f0-9]{64}$/.test(arg))).toBe(true);
+    expect(args.some((arg) => arg.includes('FAKE-password'))).toBe(false);
+    expect(args).toContain('~claude:*');
+    expect(args).toContain('&claude:*');
+    expect(args).toContain('-flushall');
+    expect(args).toContain('-acl');
+    expect(args).toContain('-scan');
+    // reset first: no stale rules survive a rebuild.
+    expect(args.indexOf('reset')).toBeLessThan(args.findIndex((arg) => arg.startsWith('#')));
+  });
+});
+
+describe('parseAclLine', () => {
+  test('parses the measured ACL LIST echo shape', () => {
+    // Seat echo after `reset`: `-@all` survives, and `resetchannels` is a marker, not a rule.
+    // A service user's `allchannels` echoes as `&*`.
+    const seat = parseAclLine(
+      'user claude on #hash ~claude:* resetchannels &claude:* -@all +@read +@write -scan',
+    );
+    expect(seat).toEqual({
+      name: 'claude',
+      on: true,
+      nopass: false,
+      hasPassword: true,
+      keyPatterns: ['~claude:*'],
+      channelPatterns: ['&claude:*'],
+      rules: ['-@all', '+@read', '+@write', '-scan'],
+    });
+    expect(seat.rules).toContain('-@all');
+    expect(seat.rules).not.toContain('resetchannels');
+    const service = parseAclLine('user litellm on #hash ~* &* +@all -@dangerous -scan');
+    expect(service.channelPatterns).toEqual(['&*']);
+    expect(service.rules).not.toContain('allchannels');
+  });
+});
+
+describe('matchesDeclared', () => {
+  test('rejects a user widened with an extra key pattern', () => {
+    const parsed = parseAclLine('user claude on #h ~claude:* ~* &claude:* +@read +@write -scan');
+    expect(matchesDeclared(parsed, claude)).toBe(false);
+  });
+});
+
+describe('planAclUsers', () => {
+  test('splits into create, update, remove — update catches external tampering, not only a prefix change', () => {
+    const declared = {
+      claude,
+      grok: {
+        name: 'grok',
+        keyPrefix: 'grok:*',
+        profile: 'seat',
+        password: { fromEnv: 'Y' },
+      } satisfies ValkeyAclUser,
+    };
+    const live = {
+      claude: parseAclLine('user claude on #h ~claude:OLD:* &claude:* +@read -scan'), // prefix drift
+      grok: parseAclLine('user grok on #h ~grok:* &grok:* +@all -scan'), // widened rules, same prefix
+      stale: parseAclLine('user stale on #h ~stale:* &stale:* +@read -scan'),
+    };
+    const plan = planAclUsers(declared, live, true);
+    expect(plan.create.map((u) => u.name)).toEqual([]);
+    expect(plan.update.map((u) => u.name).sort()).toEqual(['claude', 'grok']);
+    expect(plan.remove).toEqual(['stale']);
+  });
+
+  test('a disabled user is an update, not a silent no-op', () => {
+    const live = {
+      claude: parseAclLine('user claude off #h ~claude:* &claude:* +@read -scan'),
+    };
+    expect(planAclUsers({ claude }, live).update.map((u) => u.name)).toEqual(['claude']);
+  });
+});
+
+describe('reconcile', () => {
+  test('creates a declared user and read-back confirms it with a fresh seal', async () => {
+    const fake = makeFakeValkey({ passwords: {} });
+    const attrs = await run(reconcileWithExecutor(fake, props(), undefined, env));
+    expect(attrs.users.claude?.keyPrefix).toBe('claude:*');
+    expect(attrs.users.claude?.on).toBe(true);
+    expect(attrs.users.claude?.hasPassword).toBe(true);
+    expect(attrs.users.claude?.passwordSeal).toStartWith('scrypt:');
+    expect(fake.commands.some((c) => c.args[0] === 'ACL' && c.args[1] === 'SETUSER')).toBe(true);
+  });
+
+  test('converges a user tampered with outside the stack instead of failing read-back forever', async () => {
+    // Same prefix and password, but widened rules (`+@all` over the seat profile) and an extra
+    // key pattern — exactly the tampering this family exists to undo.
+    const fake = makeFakeValkey({
+      acl: { claude: 'user claude on #h ~claude:* ~* &claude:* +@all -scan' },
+    });
+    const attrs = await run(reconcileWithExecutor(fake, props(), undefined, env));
+    expect(attrs.users.claude?.profile).toBe('seat');
+    expect(attrs.users.claude?.extraKeyPatterns).toEqual([]);
+    expect(attrs.users.claude?.channelPatterns).toEqual(['&claude:*']);
+  });
+
+  test('rotates a password when the stored seal disagrees with the resolved value', async () => {
+    const fake = makeFakeValkey({ passwords: {} });
+    // The first reconcile creates claude from FAKE-seat-password and mints the seal.
+    const first = await run(reconcileWithExecutor(fake, props(), undefined, env));
+    const seal = first.users.claude?.passwordSeal;
+    expect(seal).toStartWith('scrypt:');
+    const setUsers = (): number =>
+      fake.commands.filter((c) => c.args[0] === 'ACL' && c.args[1] === 'SETUSER').length;
+    const writes = setUsers();
+    // Same value again: the seal matches, so nothing is rewritten and the seal is kept.
+    const again = await run(reconcileWithExecutor(fake, props(), first, env));
+    expect(again.users.claude?.passwordSeal).toBe(seal);
+    expect(setUsers()).toBe(writes);
+    // A changed variable makes the stored seal stale: exactly one rewrite, a fresh seal.
+    const rotated = await run(
+      reconcileWithExecutor(fake, props(), first, { ...env, CLAUDE_PW: 'FAKE-rotated-password' }),
+    );
+    expect(rotated.users.claude?.passwordSeal).not.toBe(seal);
+    expect(rotated.users.claude?.passwordSeal).toStartWith('scrypt:');
+    expect(setUsers()).toBe(writes + 1);
+  });
+
+  test('never manages the connection username (the admin) — not read, planned or removed', async () => {
+    // The consuming stack connects as the instance's admin (docs/valkey.md): if the family
+    // planned or removed that user it would delete its own credential and lock itself out.
+    const fake = makeFakeValkey({
+      acl: { admin: 'user admin on >FAKE-seed ~* +@all' },
+    });
+    const attrs = await run(reconcileWithExecutor(fake, props(), undefined, env, 'admin'));
+    expect(attrs.users.admin).toBeUndefined();
+    expect(attrs.users.claude?.keyPrefix).toBe('claude:*');
+    // The admin line survives in the fake, and no DELUSER ever names it.
+    expect(fake.acl.get('admin')).toContain('user admin on');
+    const dels = fake.commands.filter((c) => c.args[0] === 'ACL' && c.args[1] === 'DELUSER');
+    expect(dels.every((c) => !c.args.slice(2).includes('admin'))).toBe(true);
+  });
+
+  test('refuses with a typed error when a password variable is missing', async () => {
+    const fake = makeFakeValkey({});
+    // An explicit empty environment: the refusal must not depend on what this process happens
+    // to hold, and nothing may have been written by the time it fails.
+    const error = await fails(reconcileWithExecutor(fake, props(), undefined, {}));
+    expect(error).toBeInstanceOf(ValkeyAclPasswordMissing);
+    expect((error as ValkeyAclPasswordMissing).variable).toBe('CLAUDE_PW');
+    expect(fake.commands.filter((c) => c.args[0] === 'ACL' && c.args[1] === 'SETUSER')).toEqual([]);
+  });
+
+  test('removes a user no longer declared', async () => {
+    const fake = makeFakeValkey({ acl: { stale: 'user stale on >FAKE-seed ~stale:* +@read' } });
+    const attrs = await run(
+      reconcileWithExecutor(
+        fake,
+        { instance: 'valkey-seats', users: {}, exclusive: true },
+        undefined,
+        env,
+      ),
+    );
+    expect(attrs.users.stale).toBeUndefined();
+    expect(fake.commands.some((c) => c.args[0] === 'ACL' && c.args[1] === 'DELUSER')).toBe(true);
+  });
+
+  test('read-back failure when a write does not stick is a typed failure, not a die', async () => {
+    // A concurrent mutator re-adds `ghost` after every successful write: every SETUSER reply
+    // says OK, so only the read-back — never the write reply — can see the undeclared user.
+    const fake = makeFakeValkey({
+      reAddAfterWrite: { name: 'ghost', line: 'user ghost on >FAKE-seed ~ghost:* +@read' },
+    });
+    const error = await fails(
+      reconcileWithExecutor(fake, { ...props(), exclusive: true }, undefined, env),
+    );
+    expect(error).toBeInstanceOf(ValkeyAclReadbackFailed);
+    expect((error as ValkeyAclReadbackFailed).user).toBe('ghost');
+  });
+});
+
+describe('read', () => {
+  test('reads live ACL users and stores no password value', async () => {
+    const fake = makeFakeValkey({ acl: { claude: 'user claude on >FAKE-seed ~claude:* +@read' } });
+    const attrs = await run(readWithExecutor(fake, 'valkey-seats'));
+    expect(attrs.users.claude?.keyPrefix).toBe('claude:*');
+    expect(attrs.users.claude?.passwordSeal).toBe('');
+  });
+});

package/src/valkey/acl.ts

@@ -0,0 +1,169 @@
+/**
+ * `Valkey.AclFile` — the per-instance ACL users, each limited to a key prefix and a fixed command
+ * profile, with passwords by reference (never in state). The operations live in `acl-ops.ts`
+ * (extracted to keep both files under the cap); this file is the Resource and its handlers.
+ *
+ * ⛔ ONE ACL FILE PER INSTANCE, SEAT USERS ONLY. A shared file would let a seat user exist on the
+ *   LiteLLM cache (:6380) and `litellm` on the seat store (:6381) — every seat could poison the
+ *   response cache. The consuming stack declares one `Valkey.AclFile` per instance, holding only
+ *   that instance's users.
+ * ★ NO OWNERSHIP MARK (H1). `read` answers `Unowned` for a match (the same rule as
+ *   `Postgres.Database`), so an adopted instance's ACL needs `adopt(true)`.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type {
+  ValkeyAclFileAttributes,
+  ValkeyAclFileProps,
+  ValkeyAclUserAttributes,
+} from './acl-attrs.ts';
+import { buildDelUserArgs, passwordState, refusalBeforeWrite } from './acl-form.ts';
+import { sameSet } from './acl-compare.ts';
+import { aclUnreachable } from './acl-connection.ts';
+import { managedUserNames } from './acl-managed.ts';
+import { readAclFileConfig, readParsedUsers, readWithExecutor } from './acl-ops.ts';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+import { declaredChannels, effectiveKeyPrefix } from './acl-profiles.ts';
+import { type ValkeyConnection, withValkey } from './connection.ts';
+import { ValkeyAclFileRendered } from './errors.ts';
+import { resolveAll } from '../secrets/write-only.ts';
+import { ValkeyServerError } from './transport.ts';
+
+export interface ValkeyAclFile extends Resource<
+  'Valkey.AclFile',
+  ValkeyAclFileProps,
+  ValkeyAclFileAttributes
+> {}
+
+export const ValkeyAclFile = Resource<ValkeyAclFile>('Valkey.AclFile', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isValkeyAclFile = (value: unknown): value is ValkeyAclFile =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Valkey.AclFile';
+
+export const makeValkeyAclFileHandlers = (
+  connect: typeof withValkey = withValkey,
+): Provider.ProviderService<
+  ValkeyAclFile,
+  ValkeyConnection,
+  never,
+  never,
+  ValkeyConnection,
+  ValkeyConnection
+> =>
+  ValkeyAclFile.Provider.of({
+    list: () => Effect.succeed([]),
+    nuke: { skip: true },
+
+    read: ({ output, olds }) =>
+      Effect.gen(function* () {
+        const props = output ?? olds;
+        // Catch outside connect: acquisition can fail before the executor callback runs.
+        // AUTH server refusals keep ValkeyServerError; no failure is reported as absence.
+        const live = yield* connect(
+          (ex, config) => readWithExecutor(ex, props.instance, config.username),
+          props.instance,
+        ).pipe(Effect.catchTag('ValkeySocketError', aclUnreachable(props.instance)));
+        // ★ THE STORED SEALS SURVIVE THE RE-READ (`mcp-server.ts`'s rule): a read must never
+        //   mint, replace or drop a seal — it reports live users wearing the seals the store
+        //   already holds, so an unchanged plan stays a no-op instead of churning the row.
+        if (output === undefined) return Unowned(live);
+        const users: Record<string, ValkeyAclUserAttributes> = {};
+        for (const [name, user] of Object.entries(live.users)) {
+          users[name] = { ...user, passwordSeal: output.users[name]?.passwordSeal ?? '' };
+        }
+        return { instance: live.instance, users, managedUsers: managedUserNames(output, olds) };
+      }),
+
+    diff: ({ news, output, olds }) =>
+      Effect.gen(function* () {
+        if (!isResolved(news)) return undefined;
+        const refused = refusalBeforeWrite(news.instance, news.users);
+        if (refused !== undefined) return yield* Effect.fail(refused);
+        if (output === undefined) return undefined;
+        const declared = Object.keys(news.users).sort();
+        // Ownership changes need an apply even if live rules already match or a removed user
+        // is already absent, so the next plan has the correct managed-user inventory.
+        if (!sameSet(declared, [...managedUserNames(output, olds)]))
+          return { action: 'update' } as const;
+        const liveNames = Object.keys(output.users).sort();
+        if (news.exclusive && declared.length !== liveNames.length)
+          return { action: 'update' } as const;
+        for (const [name, user] of Object.entries(news.users)) {
+          const live = output.users[name];
+          if (
+            live === undefined ||
+            live.keyPrefix !== effectiveKeyPrefix(user) ||
+            live.extraKeyPatterns.length > 0 ||
+            !sameSet(live.channelPatterns, [...declaredChannels(user)]) ||
+            live.profile !== user.profile ||
+            !live.on ||
+            live.nopass ||
+            !live.hasPassword
+          ) {
+            return { action: 'update' } as const;
+          }
+          // A password only drifts when this process holds it and the seal disagrees — an unset
+          // variable is `unknown`, and a plan-only environment must not report every user rotated.
+          const { values } = resolveAll({ password: user.password });
+          if (passwordState(live.passwordSeal, values.password) === 'stale') {
+            return { action: 'update' } as const;
+          }
+        }
+        return { action: 'noop' } as const;
+      }),
+
+    reconcile: ({ news, output, olds }) =>
+      // The catch covers connect and the whole operation. A server refusal keeps its own tag:
+      // the server was reached, it refused. A socket failure names the selected endpoint.
+      connect(
+        (ex, config) => reconcileWithExecutor(ex, news, output, process.env, config.username, olds),
+        news.instance,
+      ).pipe(Effect.catchTag('ValkeySocketError', aclUnreachable(news.instance))),
+
+    delete: ({ olds, output }) =>
+      connect(
+        (ex, config) =>
+          Effect.gen(function* () {
+            // ⛔ GATE FIRST (F3): a rendered aclfile is the source of truth, so this family deletes
+            //   nothing there either — the file's renderer re-adds what the kit would DELUSER.
+            const aclfile = yield* readAclFileConfig(ex);
+            if (aclfile !== '') {
+              return yield* Effect.fail(
+                new ValkeyAclFileRendered({ instance: olds.instance, path: aclfile }),
+              );
+            }
+            // Removing the declaration removes every user it managed (the engine runs this only
+            // when a human opts out of retain); the instance itself is untouched, and undeclared
+            // users are preserved (F1). `ACL DELUSER` ignores absent names (Valkey docs);
+            // reading first also avoids an empty DELUSER command on a repeated delete (S14).
+            // ★ OWNERSHIP IS THE STORED RECORD, THE SAME HELPER REVOCATION USES. `olds` is the last
+            //   declaration the engine committed — it is written BEFORE reconcile runs, so after a
+            //   failed update it names users this resource never managed — and `output.users` is
+            //   every observed user. `managedUserNames` reads `output.managedUsers` (written only by
+            //   a successful reconcile) and falls back to `olds` for state that predates it. `live`
+            //   already hides `default` and the connection user, so neither can be a target.
+            const live = yield* readParsedUsers(ex, config.username);
+            const targets = managedUserNames(output, olds).filter(
+              (name) => live[name] !== undefined,
+            );
+            if (targets.length === 0) return;
+            const reply = yield* ex.send(buildDelUserArgs(targets));
+            if (reply.kind === 'error') {
+              return yield* Effect.fail(new ValkeyServerError({ detail: reply.message }));
+            }
+            return;
+          }),
+        olds.instance,
+      ).pipe(Effect.catchTag('ValkeySocketError', aclUnreachable(olds.instance))),
+  });
+
+export const valkeyAclFileHandlers = makeValkeyAclFileHandlers();
+
+export const ValkeyAclFileProvider = () => Provider.succeed(ValkeyAclFile, valkeyAclFileHandlers);

package/src/valkey/connection-service.ts

@@ -0,0 +1,46 @@
+/** Named connections keep each resource on its own server when provider layers are combined. */
+import * as Context from 'effect/Context';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import type { ValkeyConnectionConfig } from './connection.ts';
+
+export class ValkeyConnectionMissing extends Data.TaggedError('ValkeyConnectionMissing')<{
+  readonly instance: string;
+}> {
+  override get message(): string {
+    return `Valkey connection for "${this.instance}" is missing; configure that instance in valkeyProviders.`;
+  }
+}
+
+/** The unnamed service is only for direct transport calls; resources always select a name. */
+export class ValkeyConnection extends Context.Service<
+  ValkeyConnection,
+  Effect.Effect<ValkeyConnectionConfig>
+>()('Valkey.Connection') {}
+
+const connectionService = (
+  instance?: string,
+): Context.Service<ValkeyConnection, Effect.Effect<ValkeyConnectionConfig>> =>
+  instance === undefined
+    ? ValkeyConnection
+    : Context.Service<ValkeyConnection, Effect.Effect<ValkeyConnectionConfig>>(
+        `Valkey.Connection:${instance}`,
+      );
+
+/** Use `Layer.provideMerge` on providers: their handlers resolve this service later. */
+export const valkeyConnection = (config: ValkeyConnectionConfig): Layer.Layer<ValkeyConnection> =>
+  Layer.succeed(connectionService(config.instance), Effect.succeed(config));
+
+export const resolveValkeyConnection = (
+  instance?: string,
+): Effect.Effect<ValkeyConnectionConfig, ValkeyConnectionMissing, ValkeyConnection> =>
+  Effect.gen(function* () {
+    // No unnamed fallback: a typo must never send a seat ACL to another instance's cache.
+    const service = yield* Effect.serviceOption(connectionService(instance));
+    if (Option.isNone(service)) {
+      return yield* Effect.fail(new ValkeyConnectionMissing({ instance: instance ?? '<unnamed>' }));
+    }
+    return yield* service.value;
+  });

package/src/valkey/connection.ts

@@ -0,0 +1,180 @@
+/**
+ * Where a Valkey instance's socket comes from, and how each lifecycle operation gets an executor.
+ *
+ * ⛔ NO ESTATE VALUE LIVES HERE. The kit is PUBLIC; CT100's host, the two ports (6380/6381) and the
+ *   ACL user a seat authenticates as are the CONSUMING stack's values, passed to
+ *   `valkeyConnection(...)` in a house stack — never a default, never a fallback. The mini's own
+ *   Valkey, or any later host, is a different `valkeyConnection` call, not a constant.
+ * ★ A LAZY `Context.Service` WHOSE VALUE IS AN `Effect` (S24) — the same shape `PostgresConnection`
+ *   uses. `host` and `port` carry no secret; the ACL user's PASSWORD is not a prop here (S25): the
+ *   `Valkey.AclFile` resource seals passwords by reference, and the connection itself authenticates
+ *   with `AUTH` only when a stack supplies a password through `valkeyConnection`'s `password`
+ *   reference — resolved at call time, never stored.
+ * ★ ONE SOCKET PER OPERATION, OPENED AND CLOSED IN A SCOPE. `withValkey` opens a `node:net` socket
+ *   for the operation, runs it, and closes the socket when it finishes — one connection per
+ *   `reconcile`, never held across a whole plan.
+ */
+import * as Effect from 'effect/Effect';
+import {
+  type ValkeyConnection,
+  type ValkeyConnectionMissing,
+  resolveValkeyConnection,
+} from './connection-service.ts';
+export {
+  ValkeyConnection,
+  ValkeyConnectionMissing,
+  valkeyConnection,
+} from './connection-service.ts';
+import { type Socket, connect } from 'node:net';
+import { type Environment, type FromEnv, resolveAll } from '../secrets/write-only.ts';
+import { ValkeyAuthPasswordMissing } from './errors.ts';
+import {
+  DEFAULT_SOCKET_TIMEOUT_MS,
+  type ValkeyExecutor,
+  ValkeyServerError,
+  ValkeySocketError,
+  type ValkeyTransportError,
+  makeSocketExecutor,
+} from './transport.ts';
+
+/** What a stack passes to reach one instance. `host`/`port` are the TCP endpoint; the ACL
+ * `username` and optional `password` (a `FromEnv` reference, never a value) are the credentials a
+ * stack authenticates with. Omitting both sends no `AUTH` — a bare `default` connection, which is
+ * correct only for a scratch instance a test owns.
+ *
+ * ⛔ A USERNAME REQUIRES A PASSWORD. The discriminated union makes `username` without `password`
+ *   unrepresentable: on an instance whose `default` user is off (CT100's ACL files ship `user
+ *   default off`), a username-only connection cannot authenticate at all, and silently skipping
+ *   `AUTH` would surface much later as a confusing `NOAUTH` from the first command. The bare
+ *   branch carries `username?: undefined` — a type marker, not a prop — so `config.username`
+ *   reads on the whole union without narrowing first.
+ *
+ * `timeoutMs` bounds connect, each read, and the socket idle timer (default 10s). A blackholed
+ * host must stall a plan no longer than that deadline. */
+export type ValkeyConnectionConfig = {
+  /** Resource routing key: required by valkeyProviders; omit only for direct transport calls. */
+  readonly instance?: string;
+  readonly host: string;
+  readonly port: number;
+  /** Per-connect/per-read deadline in ms. */
+  readonly timeoutMs?: number;
+} & (
+  | { readonly username?: undefined }
+  | {
+      readonly username?: string;
+      readonly password: FromEnv;
+    }
+);
+
+const openSocket = (
+  host: string,
+  port: number,
+  timeoutMs: number,
+): Effect.Effect<Socket, ValkeySocketError> =>
+  Effect.tryPromise({
+    try: (signal) =>
+      new Promise<Socket>((resolve, reject) => {
+        const socket = connect({ host, port });
+        let settled = false;
+        const onConnect = () => {
+          if (settled) return;
+          settled = true;
+          socket.off('error', onError);
+          socket.off('timeout', onTimeout);
+          signal.removeEventListener('abort', onAbort);
+          clearTimeout(timer);
+          socket.setTimeout(0);
+          resolve(socket);
+        };
+        const onError = (error: Error) => {
+          if (settled) return;
+          settled = true;
+          socket.off('connect', onConnect);
+          socket.off('timeout', onTimeout);
+          signal.removeEventListener('abort', onAbort);
+          clearTimeout(timer);
+          socket.destroy();
+          reject(new ValkeySocketError({ reason: error.message }));
+        };
+        const onTimeout = () => onError(new Error('connect timed out'));
+        const onAbort = () => onError(new Error('connect interrupted'));
+        // `node:net`'s own connect timeout is minutes-long and not configurable. Both the
+        // abort and `socket.setTimeout` bound the handshake; the read deadline is separate
+        // (a host that accepts and then sends nothing has already connected).
+        const timer = setTimeout(onTimeout, timeoutMs);
+        timer.unref();
+        socket.setTimeout(timeoutMs);
+        signal.addEventListener('abort', onAbort);
+        socket.once('connect', onConnect);
+        socket.once('error', onError);
+        socket.once('timeout', onTimeout);
+      }),
+    catch: (cause) =>
+      cause instanceof ValkeySocketError ? cause : new ValkeySocketError({ reason: String(cause) }),
+  });
+
+/** `AUTH` when the config carries a password, resolved at call time; a missing or empty variable
+ * is the typed `ValkeyAuthPasswordMissing` (S21: a fact this family checked, not a sniffed server
+ * reply). A password without a username authenticates as `default`. */
+export const auth = (
+  executor: ValkeyExecutor,
+  config: ValkeyConnectionConfig,
+  env: Environment,
+): Effect.Effect<void, ValkeyTransportError | ValkeyAuthPasswordMissing> => {
+  if (!('password' in config)) return Effect.void;
+  const { username, password } = config;
+  return Effect.gen(function* () {
+    const { values, missing } = resolveAll({ password }, env);
+    const value = values.password;
+    if (missing.length > 0 || value === undefined) {
+      return yield* Effect.fail(
+        new ValkeyAuthPasswordMissing({ username, variable: password.fromEnv }),
+      );
+    }
+    const reply = yield* executor.send(
+      username === undefined ? ['AUTH', value] : ['AUTH', username, value],
+    );
+    if (reply.kind === 'error')
+      return yield* Effect.fail(new ValkeyServerError({ detail: 'Valkey AUTH was refused' }));
+  });
+};
+
+/**
+ * Run one operation against a freshly opened, freshly closed socket. Every `read` and `reconcile`
+ * in this family calls this once for the whole operation, never once per command.
+ */
+export const withValkey = <A, E>(
+  build: (
+    executor: ValkeyExecutor,
+    config: ValkeyConnectionConfig,
+  ) => Effect.Effect<A, E | ValkeyTransportError>,
+  instance?: string,
+): Effect.Effect<
+  A,
+  E | ValkeyTransportError | ValkeyAuthPasswordMissing | ValkeyConnectionMissing,
+  ValkeyConnection
+> =>
+  Effect.gen(function* () {
+    const config = yield* resolveValkeyConnection(instance);
+    const timeoutMs = config.timeoutMs ?? DEFAULT_SOCKET_TIMEOUT_MS;
+    const socket = yield* openSocket(config.host, config.port, timeoutMs);
+    // Listener first, then the idle deadline. A timeout destroys with an error, and Node
+    // exits the process if that `error` event has no listener.
+    const executor = makeSocketExecutor(socket, timeoutMs);
+    socket.setTimeout(timeoutMs);
+    const onIdle = () => {
+      socket.destroy(new Error('socket timed out'));
+    };
+    socket.on('timeout', onIdle);
+    return yield* Effect.ensuring(
+      Effect.gen(function* () {
+        yield* auth(executor, config, process.env);
+        return yield* build(executor, config);
+      }),
+      Effect.sync(() => {
+        socket.setTimeout(0);
+        socket.off('timeout', onIdle);
+        socket.destroy();
+      }),
+    );
+  });