@homeflare/alchemy 0.43.0 → 0.45.0

package/src/valkey/handlers.test.ts

@@ -0,0 +1,205 @@
+/** Exercise actual handlers: a failed read must never become a CREATE or skip adoption. */
+import { expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import { makeValkeyAclFileHandlers } from './acl.ts';
+import { makeValkeyInstanceHandlers } from './instance.ts';
+import { makeFakeValkey } from './fake-valkey.ts';
+import { connection, context, required, run } from './handler-test-fixture.ts';
+import { ValkeyServerError, ValkeySocketError } from './transport.ts';
+import { ValkeyAclParseError } from './errors.ts';
+import type { ValkeyAclFileProps } from './acl-attrs.ts';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+
+const props: ValkeyAclFileProps = { instance: 'scratch', users: {} };
+const attrs = { instance: 'scratch', users: {} };
+const instance = { name: 'scratch', port: 0 };
+const fake = () => makeFakeValkey({ passwords: { admin: 'FAKE-admin' } });
+
+for (const tag of [
+  'ValkeyServerError',
+  'ValkeySocketError',
+  'ValkeyAuthPasswordMissing',
+] as const) {
+  test(`read and ACL delete propagate ${tag}, never absence/success`, async () => {
+    const ex =
+      tag === 'ValkeyAuthPasswordMissing'
+        ? fake()
+        : {
+            send: () =>
+              Effect.fail(
+                tag === 'ValkeyServerError'
+                  ? new ValkeyServerError({ detail: 'WRONGPASS' })
+                  : new ValkeySocketError({ reason: 'connection refused' }),
+              ),
+          };
+    const connect = connection(ex, {});
+    // Server/socket errors occur after resolving a present credential.
+    const session = tag === 'ValkeyAuthPasswordMissing' ? connect : connection(ex);
+    const acl = makeValkeyAclFileHandlers(session);
+    const inst = makeValkeyInstanceHandlers(session);
+    expect(
+      (await run(Effect.flip(required(acl.read)({ ...context, olds: props, output: undefined }))))
+        ._tag,
+    ).toBe(tag === 'ValkeySocketError' ? 'ValkeyInstanceUnreachable' : tag);
+    expect(
+      (
+        await run(
+          Effect.flip(required(inst.read)({ ...context, olds: instance, output: undefined })),
+        )
+      )._tag,
+    ).toBe(tag);
+    expect(
+      (await run(Effect.flip(acl.delete({ ...context, olds: props, output: attrs }))))._tag,
+    ).toBe(tag === 'ValkeySocketError' ? 'ValkeyInstanceUnreachable' : tag);
+  });
+}
+
+test('wrong AUTH reply fails both reads; successful reads retain the adoption gate', async () => {
+  const ex = fake();
+  for (const credentials of [
+    { TEST_VALKEY_ADMIN_PW: 'FAKE-wrong' },
+    { TEST_VALKEY_ADMIN_PW: 'FAKE-admin' },
+  ]) {
+    const acl = makeValkeyAclFileHandlers(connection(ex, credentials));
+    const inst = makeValkeyInstanceHandlers(connection(ex, credentials));
+    if (credentials.TEST_VALKEY_ADMIN_PW === 'FAKE-wrong') {
+      expect(
+        (await run(Effect.flip(required(acl.read)({ ...context, olds: props, output: undefined }))))
+          ._tag,
+      ).toBe('ValkeyServerError');
+      expect(
+        (
+          await run(
+            Effect.flip(required(inst.read)({ ...context, olds: instance, output: undefined })),
+          )
+        )._tag,
+      ).toBe('ValkeyServerError');
+    } else {
+      expect(
+        Unowned.is(await run(required(acl.read)({ ...context, olds: props, output: undefined }))),
+      ).toBe(true);
+      expect(
+        Unowned.is(
+          await run(required(inst.read)({ ...context, olds: instance, output: undefined })),
+        ),
+      ).toBe(true);
+    }
+  }
+});
+
+test('configured ACL file refuses reconcile and delete before SETUSER/DELUSER', async () => {
+  const ex = fake();
+  ex.config.set('aclfile', '/scratch/readonly.acl');
+  const acl = makeValkeyAclFileHandlers(connection(ex));
+  for (const effect of [
+    acl.reconcile({ ...context, news: props, olds: props, output: attrs }),
+    acl.delete({ ...context, olds: props, output: attrs }),
+  ]) {
+    expect((await run(Effect.flip(effect)))._tag).toBe('ValkeyAclFileRendered');
+  }
+  expect(
+    ex.commands.some(({ args }) => ['SETUSER', 'DELUSER', 'SAVE'].includes(args[1] ?? '')),
+  ).toBe(false);
+  expect(await run(required(acl.read)({ ...context, olds: props, output: attrs }))).toEqual({
+    ...attrs,
+    managedUsers: [],
+  });
+});
+
+test('delete is repeatable, removes only declared users and preserves admin/undeclared', async () => {
+  const ex = fake();
+  ex.acl.set('seat', 'user seat on >FAKE-seat -@all');
+  ex.acl.set('monitor', 'user monitor on >FAKE-monitor -@all');
+  const acl = makeValkeyAclFileHandlers(connection(ex));
+  const olds: ValkeyAclFileProps = {
+    ...props,
+    users: {
+      seat: { name: 'seat', profile: 'seat', password: { fromEnv: 'TEST_VALKEY_SEAT_PW' } },
+    },
+  };
+  await run(acl.delete({ ...context, olds, output: attrs }));
+  await run(acl.delete({ ...context, olds, output: attrs }));
+  expect([...ex.acl.keys()]).toEqual(['monitor']);
+  expect(ex.commands.filter(({ args }) => args[1] === 'DELUSER')).toHaveLength(1);
+  const inst = makeValkeyInstanceHandlers(connection(ex));
+  expect(
+    (
+      await run(
+        Effect.flip(
+          inst.delete({
+            ...context,
+            olds: instance,
+            output: {
+              ...instance,
+              version: '9.1.1',
+              maxmemory: '0',
+              maxmemoryPolicy: 'noeviction',
+              appendonly: 'no',
+            },
+          }),
+        ),
+      )
+    )._tag,
+  ).toBe('ValkeyInstanceDeleteRefused');
+});
+
+test('diff compares stored attributes; drift read makes out-of-band channel changes visible', async () => {
+  const ex = fake();
+  const news: ValkeyAclFileProps = {
+    ...props,
+    users: {
+      seat: { name: 'seat', profile: 'seat', password: { fromEnv: 'TEST_VALKEY_SEAT_PW' } },
+    },
+  };
+  const stored = await Effect.runPromise(
+    reconcileWithExecutor(ex, news, undefined, { TEST_VALKEY_SEAT_PW: 'FAKE-seat' }),
+  );
+  const acl = makeValkeyAclFileHandlers(connection(ex));
+  const diff = (output: typeof stored, exclusive = false) =>
+    run(required(acl.diff)({ ...context, olds: news, news: { ...news, exclusive }, output }));
+  expect(await diff(stored)).toEqual({ action: 'noop' });
+  ex.acl.set('seat', required(ex.acl.get('seat')).replace('&seat:*', '&*'));
+  expect(await diff(stored)).toEqual({ action: 'noop' });
+  const live = await run(required(acl.read)({ ...context, olds: news, output: stored }));
+  expect(live?.users.seat?.passwordSeal).toBe(stored.users.seat?.passwordSeal);
+  expect(await diff(required(live))).toEqual({ action: 'update' });
+  const extra = { ...stored, users: { ...stored.users, monitor: required(stored.users.seat) } };
+  expect(await diff(extra)).toEqual({ action: 'noop' });
+  expect(await diff(extra, true)).toEqual({ action: 'update' });
+  const inst = makeValkeyInstanceHandlers(connection(ex));
+  const output = {
+    ...instance,
+    version: '9.1.1',
+    maxmemory: '0',
+    maxmemoryPolicy: 'noeviction',
+    appendonly: 'no',
+  };
+  expect(
+    await run(required(inst.diff)({ ...context, olds: instance, news: instance, output })),
+  ).toEqual({
+    action: 'noop',
+  });
+  expect(
+    await run(
+      required(inst.diff)({ ...context, olds: instance, news: { ...instance, port: 1 }, output }),
+    ),
+  ).toEqual({ action: 'update' });
+});
+
+test('malformed ACL fails read without retaining the hash in message or data', async () => {
+  const ex = fake();
+  const executor = {
+    send: (args: ReadonlyArray<string>) =>
+      args[1] === 'LIST'
+        ? Effect.succeed({ kind: 'array' as const, values: ['invalid #FAKE-hash'] })
+        : ex.send(args),
+  };
+  const acl = makeValkeyAclFileHandlers(connection(executor));
+  const error = await run(
+    Effect.flip(required(acl.read)({ ...context, olds: props, output: undefined })),
+  );
+  expect(error).toBeInstanceOf(ValkeyAclParseError);
+  expect(String(error)).not.toContain('FAKE-hash');
+  expect(JSON.stringify(error)).not.toContain('FAKE-hash');
+});

package/src/valkey/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Valkey providers for Alchemy — `Valkey.Instance` (assert-and-read a running server) and
+ * `Valkey.AclFile` (per-seat ACL users, key-prefix limited, passwords by reference). See
+ * `docs/valkey.md`.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory: `fake-valkey.ts`,
+ *   `transport.ts` and the form internals are test doubles and internals, not something a
+ *   consuming stack should import (the same rule `postgres/index.ts` and `netbox/index.ts` use).
+ */
+export type {
+  ValkeyAclFileAttributes,
+  ValkeyAclFileProps,
+  ValkeyAclProfile,
+  ValkeyAclUser,
+  ValkeyAclUserAttributes,
+} from './acl-attrs.ts';
+export { ValkeyAclFile, ValkeyAclFileProvider, isValkeyAclFile } from './acl.ts';
+export type { ValkeyConnectionConfig } from './connection.ts';
+export {
+  ValkeyConnection,
+  ValkeyConnectionMissing,
+  valkeyConnection,
+  withValkey,
+} from './connection.ts';
+export {
+  ValkeyAclChannelPatterns,
+  ValkeyAclFileRendered,
+  ValkeyAclMonitorKeyPrefix,
+  ValkeyAclNameGlob,
+  ValkeyAclPasswordMissing,
+  ValkeyAclParseError,
+  ValkeyAclReadbackFailed,
+  ValkeyAclReservedUser,
+  ValkeyAclSeatKeyPrefix,
+  ValkeyAclUserNameMismatch,
+  ValkeyAuthPasswordMissing,
+  ValkeyInstanceDrift,
+  ValkeyInstanceUnreachable,
+  type ValkeyError,
+} from './errors.ts';
+export type {
+  ValkeyInstanceAttributes,
+  ValkeyInstanceConfig,
+  ValkeyInstanceInfo,
+  ValkeyInstanceProps,
+} from './instance-attrs.ts';
+export {
+  ValkeyInstance,
+  ValkeyInstanceDeleteRefused,
+  ValkeyInstanceProvider,
+  isValkeyInstance,
+  type ValkeyInstanceError,
+} from './instance.ts';
+export { valkeyProviders } from './providers.ts';

package/src/valkey/instance-attrs.ts

@@ -0,0 +1,48 @@
+/**
+ * `Valkey.Instance` props and attributes.
+ *
+ * ⛔ CREATE-AND-ASSERT, NEVER CREATE. A Valkey instance is a container the `Podman.Container`
+ *   family owns (`homeflare-ct100/src/valkey.ts` already declares the two dormant Quadlets). This
+ *   resource asserts a running instance's identity and configuration — it reads `INFO` and
+ *   `CONFIG GET` — and refuses drift, never issues a `CONFIG SET` that could drop in-flight data.
+ * ⛔ NO PASSWORD AS A PROP (S25). An instance's own admin password is the connection's concern
+ *   (`connection.ts`), not a field stored in state; `Valkey.AclFile` owns the per-seat users.
+ */
+/** Declared, at-most-once-asserted properties of one running Valkey instance. */
+export interface ValkeyInstanceProps {
+  /** The instance's logical identity — matches the Quadlet's `containerName`. */
+  readonly name: string;
+  /** The TCP port the instance listens on (the Quadlet's `--port`). */
+  readonly port: number;
+  /** `maxmemory` (`CONFIG GET maxmemory`). A declaration may be unit form (`"512mb"`);
+   * the live reply is the byte count. Compared with Valkey's `memtoull` rule. */
+  readonly maxmemory?: string | undefined;
+  /** `maxmemory-policy`, one of Valkey's eviction policies. */
+  readonly maxmemoryPolicy?: string | undefined;
+  /** `appendonly` (`yes`/`no`) — seat data is AOF, the LiteLLM cache is not. */
+  readonly appendonly?: string | undefined;
+}
+
+/** Live attributes read back after reconcile. Never holds a password (see file header). */
+export interface ValkeyInstanceAttributes {
+  readonly name: string;
+  readonly port: number;
+  readonly version: string;
+  readonly maxmemory: string;
+  readonly maxmemoryPolicy: string;
+  readonly appendonly: string;
+}
+
+/** The subset of `INFO` fields `read` needs. `port` is `tcp_port`, not the declared prop:
+ * copying the declaration back would make a 6381 claim match a server on 6380. */
+export interface ValkeyInstanceInfo {
+  readonly version: string;
+  readonly port: number;
+}
+
+/** The subset of `CONFIG GET` values `read` needs. */
+export interface ValkeyInstanceConfig {
+  readonly maxmemory: string;
+  readonly maxmemoryPolicy: string;
+  readonly appendonly: string;
+}

package/src/valkey/instance-form.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure helpers for `Valkey.Instance`: parsing `INFO`/`CONFIG GET` replies, building drift checks,
+ * and normalising optional props.
+ *
+ * ⛔ NO SIDE EFFECTS. Everything in this file is a pure function that can be unit-tested without a
+ *   socket or a fake executor.
+ */
+import type {
+  ValkeyInstanceAttributes,
+  ValkeyInstanceConfig,
+  ValkeyInstanceInfo,
+  ValkeyInstanceProps,
+} from './instance-attrs.ts';
+
+/** Parse the `INFO` bulk reply into the fields `Instance` cares about. A missing `tcp_port`
+ * is 0, so a declaration of a real port drifts rather than matching a reply that omitted it. */
+export const parseInfo = (value: string | null): ValkeyInstanceInfo => {
+  const fallback = '0.0.0';
+  if (value === null) return { version: fallback, port: 0 };
+  const match = /valkey_version:([0-9a-zA-Z._-]+)/.exec(value);
+  const port = /tcp_port:([0-9]+)/.exec(value);
+  return {
+    version: match?.[1] ?? fallback,
+    port: port?.[1] === undefined ? 0 : Number(port[1]),
+  };
+};
+
+/** Valkey `memtoull` (`src/util.c`, same on 8.1.10 and 9.1.1). `mb` is 1024², so `512mb` is
+ * 536870912 and `256mb` is 268435456 — the byte string `CONFIG GET` returns for `MEMORY_CONFIG`.
+ * Undefined on a parse error: a zero from the C function is "unlimited" only for the string `0`. */
+const MEMORY_UNITS: Readonly<Record<string, bigint>> = {
+  '': 1n,
+  b: 1n,
+  k: 1000n,
+  kb: 1024n,
+  m: 1_000_000n,
+  mb: 1024n * 1024n,
+  g: 1_000_000_000n,
+  gb: 1024n * 1024n * 1024n,
+};
+
+export const memoryBytes = (value: string): bigint | undefined => {
+  if (value.startsWith('-')) return undefined;
+  const match = /^(\d+)([a-z]*)$/i.exec(value);
+  if (match === null) return undefined;
+  const digits = match[1];
+  const unit = (match[2] ?? '').toLowerCase();
+  const mul = MEMORY_UNITS[unit];
+  if (digits === undefined || mul === undefined) return undefined;
+  return BigInt(digits) * mul;
+};
+
+/** Byte equality for `maxmemory`. An unparseable side does not match, so a typo still drifts. */
+const sameMemory = (declared: string, live: string): boolean => {
+  const left = memoryBytes(declared);
+  const right = memoryBytes(live);
+  return left !== undefined && right !== undefined && left === right;
+};
+
+/** Fill defaults for absent optional config so `diff` and drift checks compare a concrete string. */
+const defaultedConfig = (raw: Partial<ValkeyInstanceConfig>): ValkeyInstanceConfig => ({
+  maxmemory: raw.maxmemory ?? '0',
+  maxmemoryPolicy: raw.maxmemoryPolicy ?? 'noeviction',
+  appendonly: raw.appendonly ?? 'no',
+});
+
+/** Build a live `ValkeyInstanceAttributes` from parsed `INFO` and `CONFIG GET` pairs. */
+export const buildAttributes = (
+  props: Omit<ValkeyInstanceProps, 'maxmemory' | 'maxmemoryPolicy' | 'appendonly'>,
+  info: ValkeyInstanceInfo,
+  config: Partial<ValkeyInstanceConfig>,
+): ValkeyInstanceAttributes => ({
+  name: props.name,
+  port: info.port,
+  version: info.version,
+  ...defaultedConfig(config),
+});
+
+/** Compare every declared assert-once prop against the live row. Returns the first drift, or
+ * `undefined` when every declared prop matches. */
+export const firstDrift = (
+  props: ValkeyInstanceProps,
+  live: ValkeyInstanceAttributes,
+): { readonly prop: string; readonly declared: unknown; readonly live: unknown } | undefined => {
+  const checks: ReadonlyArray<readonly [string, unknown, unknown]> = [
+    ['port', props.port, live.port],
+    ['maxmemory', props.maxmemory, live.maxmemory],
+    ['maxmemoryPolicy', props.maxmemoryPolicy, live.maxmemoryPolicy],
+    ['appendonly', props.appendonly, live.appendonly],
+  ];
+  for (const [prop, declared, liveValue] of checks) {
+    if (declared === undefined) continue;
+    if (
+      prop === 'maxmemory' &&
+      typeof declared === 'string' &&
+      typeof liveValue === 'string' &&
+      sameMemory(declared, liveValue)
+    ) {
+      continue;
+    }
+    if (declared !== liveValue) return { prop, declared, live: liveValue };
+  }
+  return undefined;
+};

package/src/valkey/instance.test.ts

@@ -0,0 +1,108 @@
+/**
+ * `Valkey.Instance` against `fake-valkey.ts`'s recording fake — read of a running instance,
+ * drift refusals, and no writes ever issued. Every case reverts cleanly by reverting
+ * `instance.ts`/`instance-form.ts` locally.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeValkey } from './fake-valkey.ts';
+import { firstDrift, parseInfo } from './instance-form.ts';
+import { readWithExecutor } from './instance.ts';
+import type { ValkeyInstanceProps } from './instance-attrs.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+
+const baseProps: Pick<ValkeyInstanceProps, 'name' | 'port'> = { name: 'valkey-seats', port: 6381 };
+
+describe('read', () => {
+  test('reads INFO and CONFIG GET into attributes', async () => {
+    const fake = makeFakeValkey({
+      port: 6381,
+      config: { maxmemory: '512mb', 'maxmemory-policy': 'noeviction', appendonly: 'yes' },
+    });
+    const attrs = await run(readWithExecutor(fake, baseProps));
+    expect(attrs).toEqual({
+      name: 'valkey-seats',
+      port: 6381,
+      version: '8.1.10',
+      maxmemory: '536870912',
+      maxmemoryPolicy: 'noeviction',
+      appendonly: 'yes',
+    });
+    expect(firstDrift({ ...baseProps, maxmemory: '512mb' }, attrs)).toBeUndefined();
+    expect(fake.commands.map((c) => c.args[0])).toEqual(['INFO', 'CONFIG']);
+  });
+
+  test('defaults absent config to concrete values', async () => {
+    const fake = makeFakeValkey({});
+    const attrs = await run(readWithExecutor(fake, baseProps));
+    expect(attrs.maxmemory).toBe('0');
+    expect(attrs.maxmemoryPolicy).toBe('noeviction');
+    expect(attrs.appendonly).toBe('no');
+  });
+
+  test('port is INFO tcp_port, so a 6381 declaration drifts against a 6380 server', async () => {
+    const fake = makeFakeValkey({ port: 6380 });
+    const attrs = await run(readWithExecutor(fake, { name: 'valkey-seats', port: 6381 }));
+    expect(attrs.port).toBe(6380);
+    expect(firstDrift({ name: 'valkey-seats', port: 6381 }, attrs)).toEqual({
+      prop: 'port',
+      declared: 6381,
+      live: 6380,
+    });
+  });
+});
+
+describe('parseInfo', () => {
+  test('extracts the version line and falls back on garbage', () => {
+    expect(
+      parseInfo('redis_version:7.2.4\nvalkey_version:8.1.10\nredis_mode:standalone').version,
+    ).toBe('8.1.10');
+    expect(parseInfo(null).version).toBe('0.0.0');
+    expect(parseInfo('nothing here').version).toBe('0.0.0');
+  });
+});
+
+describe('firstDrift', () => {
+  const live = {
+    name: 'valkey-seats',
+    port: 6381,
+    version: '8.1.10',
+    maxmemory: '512mb',
+    maxmemoryPolicy: 'noeviction',
+    appendonly: 'yes',
+  };
+
+  test('reports the first mismatched declared prop', () => {
+    expect(firstDrift({ name: 'x', port: 6380 }, live)).toEqual({
+      prop: 'port',
+      declared: 6380,
+      live: 6381,
+    });
+    expect(firstDrift({ name: 'x', port: 6381, maxmemory: '1gb' }, live)).toEqual({
+      prop: 'maxmemory',
+      declared: '1gb',
+      live: '512mb',
+    });
+  });
+
+  test('ignores undefined (unasserted) props', () => {
+    expect(firstDrift({ name: 'x', port: 6381, maxmemory: undefined }, live)).toBeUndefined();
+  });
+
+  test("declaration '512mb' matches the byte count CONFIG GET returns", () => {
+    // Valkey memtoull: 512mb is 536870912, 256mb is 268435456 (8.1.10 and 9.1.1).
+    expect(
+      firstDrift(
+        { name: 'x', port: 6381, maxmemory: '512mb' },
+        { ...live, maxmemory: '536870912' },
+      ),
+    ).toBeUndefined();
+    expect(
+      firstDrift(
+        { name: 'x', port: 6381, maxmemory: '256mb' },
+        { ...live, maxmemory: '268435456' },
+      ),
+    ).toBeUndefined();
+  });
+});

package/src/valkey/instance.ts

@@ -0,0 +1,160 @@
+/**
+ * `Valkey.Instance` — assert-and-read over a running Valkey server, reached over RESP.
+ *
+ * ⛔ ADOPT-AND-ASSERT, NEVER CREATE OR RECONFIGURE. The instance itself is a container the
+ *   `Podman.Container` family owns (`homeflare-ct100/src/valkey.ts` declares the two dormant
+ *   Quadlets). This resource reads `INFO` and `CONFIG GET` to confirm the live instance matches the
+ *   declaration, and refuses drift — it never issues `CONFIG SET` (which could drop in-flight
+ *   data) and never starts a process.
+ * ⛔ `delete` NEVER STOPS AN INSTANCE. `ValkeyInstanceDeleteRefused` and
+ *   `defaultRemovalPolicy: 'retain'` are two independent reasons the engine never shuts a server
+ *   down through this provider.
+ * ★ NO OWNERSHIP MARK (H1). `read` always answers `Unowned` for a match, the same rule
+ *   `Postgres.Database` uses, so every already-live instance needs `adopt(true)` in the stack
+ *   that declares it.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import { type ValkeyConnection, withValkey } from './connection.ts';
+import { type ValkeyError, ValkeyInstanceDrift } from './errors.ts';
+import { type ValkeyInstanceAttributes, type ValkeyInstanceProps } from './instance-attrs.ts';
+import { buildAttributes, firstDrift, parseInfo } from './instance-form.ts';
+import {
+  type ValkeyExecutor,
+  ValkeyServerError,
+  type ValkeyTransportError,
+  arrayPairs,
+} from './transport.ts';
+
+export interface ValkeyInstance extends Resource<
+  'Valkey.Instance',
+  ValkeyInstanceProps,
+  ValkeyInstanceAttributes
+> {}
+
+export const ValkeyInstance = Resource<ValkeyInstance>('Valkey.Instance', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isValkeyInstance = (value: unknown): value is ValkeyInstance =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Valkey.Instance';
+
+/** `delete` never stops an instance; dropping a server is a human act on the host. */
+export class ValkeyInstanceDeleteRefused extends Data.TaggedError('ValkeyInstanceDeleteRefused')<{
+  readonly instance: string;
+}> {
+  override get message(): string {
+    return (
+      `Valkey.Instance "${this.instance}": delete is refused. This provider never stops a ` +
+      'running Valkey server. Stop it by hand on the host if you mean to remove it, then remove ' +
+      'the declaration.'
+    );
+  }
+}
+
+export type ValkeyInstanceError = ValkeyError | ValkeyInstanceDeleteRefused;
+
+/** Read the live instance: `INFO` then `CONFIG GET`, folded into attributes. */
+export const readWithExecutor = (
+  executor: ValkeyExecutor,
+  props: Pick<ValkeyInstanceProps, 'name' | 'port'>,
+): Effect.Effect<ValkeyInstanceAttributes, ValkeyTransportError> =>
+  Effect.gen(function* () {
+    const infoReply = yield* executor.send(['INFO']);
+    if (infoReply.kind === 'error') {
+      return yield* Effect.fail(new ValkeyServerError({ detail: infoReply.message }));
+    }
+    const info = parseInfo(infoReply.kind === 'bulk' ? infoReply.value : null);
+    const configReply = yield* executor.send([
+      'CONFIG',
+      'GET',
+      'maxmemory',
+      'maxmemory-policy',
+      'appendonly',
+    ]);
+    if (configReply.kind === 'error') {
+      return yield* Effect.fail(new ValkeyServerError({ detail: configReply.message }));
+    }
+    const pairs = configReply.kind === 'array' ? arrayPairs(configReply.values) : new Map();
+    return buildAttributes(props, info, {
+      maxmemory: pairs.get('maxmemory') ?? undefined,
+      maxmemoryPolicy: pairs.get('maxmemory-policy') ?? undefined,
+      appendonly: pairs.get('appendonly') ?? undefined,
+    });
+  });
+
+/**
+ * The five lifecycle handlers. Exported separately from the provider layer so tests can call
+ * `valkeyInstanceHandlers.read(...)` directly against the real implementation without standing up
+ * the engine's provider machinery.
+ */
+export const makeValkeyInstanceHandlers = (
+  connect: typeof withValkey = withValkey,
+): Provider.ProviderService<
+  ValkeyInstance,
+  ValkeyConnection,
+  never,
+  never,
+  ValkeyConnection,
+  ValkeyConnection
+> =>
+  ValkeyInstance.Provider.of({
+    // ⚠️ EMPTY, NOT A LIVE SWEEP. A Valkey has no instance enumeration; adoption is one
+    //   declaration at a time, matching `Postgres.Database`.
+    list: () => Effect.succeed([]),
+    nuke: { skip: true },
+
+    read: ({ output, olds }) =>
+      Effect.gen(function* () {
+        const props = output ?? olds;
+        // Neither AUTH failure nor an unreachable endpoint proves absence. Propagate the
+        // typed failure so Plan.ts cannot bypass the adoption gate with a CREATE.
+        return yield* connect(
+          (ex) => Effect.map(readWithExecutor(ex, { name: props.name, port: props.port }), Unowned),
+          props.name,
+        );
+      }),
+
+    diff: ({ news, output }) =>
+      Effect.sync(() => {
+        if (!isResolved(news)) return undefined;
+        if (output === undefined) return undefined;
+        const drift = firstDrift(news, output);
+        return drift !== undefined
+          ? ({ action: 'update' } as const)
+          : ({ action: 'noop' } as const);
+      }),
+
+    reconcile: ({ news }) =>
+      Effect.gen(function* () {
+        const live = yield* connect(
+          (ex) => readWithExecutor(ex, { name: news.name, port: news.port }),
+          news.name,
+        );
+        const drift = firstDrift(news, live);
+        if (drift !== undefined) {
+          return yield* Effect.fail(
+            new ValkeyInstanceDrift({
+              instance: news.name,
+              prop: drift.prop,
+              declared: drift.declared,
+              live: drift.live,
+            }),
+          );
+        }
+        return live;
+      }),
+
+    delete: ({ olds }) => Effect.fail(new ValkeyInstanceDeleteRefused({ instance: olds.name })),
+  });
+
+export const valkeyInstanceHandlers = makeValkeyInstanceHandlers();
+
+export const ValkeyInstanceProvider = () =>
+  Provider.succeed(ValkeyInstance, valkeyInstanceHandlers);