@homeflare/alchemy 0.22.0 → 0.24.0

package/src/litellm/pass-through-form.ts

@@ -0,0 +1,136 @@
+/**
+ * The wire body for a `LiteLLM.PassThroughEndpoint`, the comparison that decides whether it needs
+ * writing, and the refusals that stop a plan before it writes anything unsafe.
+ *
+ * ★ EXTRACTED SO IT CAN BE TESTED WITHOUT A SERVER — the same reason netbox keeps `prefix-form.ts`
+ *   beside `prefix.ts` (S32/testing-and-docs.md).
+ *
+ * ⛔ PROPS ARE THE GENERATED TYPE, MINUS THE TWO FIELDS THIS RESOURCE OWNS ITSELF: `id` (a
+ *   deterministic physical name — pass-through-endpoint.ts) and `is_from_config` (response-only;
+ *   the vendor sets it, a declaration never does). Deriving `Props` with `Omit<>` rather than
+ *   hand-typing it means a vendor schema change that adds, removes or narrows a field is felt here
+ *   as a compiler error, not silently ignored.
+ */
+import { deepEqual } from 'alchemy/Diff';
+import type * as Generated from './generated/pass-through.ts';
+
+export type PassThroughEndpointProps = Omit<
+  Generated.PassThroughGenericEndpoint,
+  'id' | 'is_from_config'
+>;
+
+/** What `read` returns: the props plus the two vendor-owned fields, `id` now guaranteed present. */
+export type PassThroughEndpointAttributes = Omit<Generated.PassThroughGenericEndpoint, 'id'> & {
+  readonly id: string;
+};
+
+/** ⚠️ NetBox `settled()`'s pattern: only fields the SCHEMA gives a vendor default for, copied from it (not assumed). */
+export const settled = (props: PassThroughEndpointProps) => ({
+  auth: props.auth ?? true,
+  cost_per_request: props.cost_per_request ?? 0,
+  default_query_params: props.default_query_params ?? {},
+  headers: props.headers ?? {},
+  include_subpath: props.include_subpath ?? false,
+});
+
+/** The three fields whose absence the vendor's `exclude_none` update can never write (see client.ts). */
+export const NULLABLE_FIELDS = ['timeout', 'methods', 'guardrails'] as const;
+
+const isUnset = (value: unknown): boolean => value === undefined || value === null;
+
+/**
+ * ⚠️ BUILT AS A WIDER RECORD AND PRUNED, NOT AS THE GENERATED TYPE DIRECTLY.
+ *   `exactOptionalPropertyTypes` is on (packages/config/tsconfig.base.json), so writing
+ *   `timeout: undefined` into a `{ timeout?: number | null }` is a type error rather than an
+ *   absent key — the same reason `codegen/openapi.ts`'s `prune` exists, and the same fix.
+ */
+const prune = (value: Record<string, unknown>): Record<string, unknown> =>
+  Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+
+/**
+ * Full body for CREATE. `id` is the deterministic physical name (pass-through-endpoint.ts), sent
+ * so a failed create is recoverable by `read` rather than orphaning a second row on retry.
+ */
+export const createBody = (
+  props: PassThroughEndpointProps,
+  id: string,
+): Generated.PassThroughGenericEndpoint =>
+  prune({
+    ...settled(props),
+    guardrails: isUnset(props.guardrails) ? undefined : props.guardrails,
+    id,
+    methods: isUnset(props.methods) ? undefined : props.methods,
+    path: props.path,
+    target: props.target,
+    timeout: isUnset(props.timeout) ? undefined : props.timeout,
+  }) as unknown as Generated.PassThroughGenericEndpoint;
+
+/**
+ * Partial body for UPDATE (`POST /{id}`). ⛔ ONLY FIELDS THIS DECLARATION ACTUALLY SETS — the
+ * vendor merges the parsed body with `model_dump(exclude_none=True)` (measured at v1.100.0), so an
+ * `undefined` OR an explicit `null` here would be dropped by the server anyway; sending neither is
+ * the same outcome with no request made when nothing changed (`Object.keys(body).length === 0`
+ * checked by the caller in pass-through-endpoint.ts).
+ */
+export const updateBody = (
+  props: PassThroughEndpointProps,
+): Partial<Generated.PassThroughGenericEndpoint> =>
+  prune({
+    ...settled(props),
+    guardrails: isUnset(props.guardrails) ? undefined : props.guardrails,
+    methods: isUnset(props.methods) ? undefined : props.methods,
+    path: props.path,
+    target: props.target,
+    timeout: isUnset(props.timeout) ? undefined : props.timeout,
+  }) as Partial<Generated.PassThroughGenericEndpoint>;
+
+/**
+ * Whether ANY of the three nullable fields went from set (in `live`) to unset (in `props`) — the
+ * one case `updateBody` cannot express, because the vendor's `exclude_none` merge silently keeps
+ * the old value instead of clearing it. Detected here so `pass-through-endpoint.ts` can plan a
+ * `replace` (delete-then-create) instead of an update that would look like it worked.
+ */
+export const needsReplace = (
+  live: PassThroughEndpointAttributes,
+  props: PassThroughEndpointProps,
+): boolean => NULLABLE_FIELDS.some((field) => !isUnset(live[field]) && isUnset(props[field]));
+
+/** Whether the live object already says what the declaration says — the `diff` "noop" test. */
+export const matches = (
+  live: PassThroughEndpointAttributes,
+  props: PassThroughEndpointProps,
+): boolean => {
+  const fixed = settled(props);
+  return (
+    live.target === props.target &&
+    live.auth === fixed.auth &&
+    live.cost_per_request === fixed.cost_per_request &&
+    live.include_subpath === fixed.include_subpath &&
+    deepEqual(live.headers, fixed.headers) &&
+    deepEqual(live.default_query_params, fixed.default_query_params) &&
+    (isUnset(props.timeout) ? isUnset(live.timeout) : live.timeout === props.timeout) &&
+    (isUnset(props.methods) ? isUnset(live.methods) : deepEqual(live.methods, props.methods)) &&
+    (isUnset(props.guardrails)
+      ? isUnset(live.guardrails)
+      : deepEqual(live.guardrails, props.guardrails))
+  );
+};
+
+/**
+ * A literal secret in a forwarded header (S25, house rule — not a vendor one; see
+ * pass-through-endpoint.ts). Case-insensitive on the header name; the reference form is LiteLLM's
+ * own, `os.environ/NAME` (`set_env_variables_in_header`, pass_through_endpoints.py:117-160 at the
+ * tag) — a missing variable on the proxy host leaves that literal string in the header, which
+ * nothing in the API can detect, so this is enforced here rather than trusted to the vendor.
+ */
+const SECRET_HEADER_NAMES = new Set(['authorization', 'x-api-key', 'cf-aig-authorization']);
+
+export const literalSecretHeaders = (
+  headers: Readonly<Record<string, unknown>> | undefined,
+): readonly string[] =>
+  Object.entries(headers ?? {})
+    .filter(
+      ([name, value]) =>
+        SECRET_HEADER_NAMES.has(name.toLowerCase()) && !String(value).includes('os.environ/'),
+    )
+    .map(([name]) => name);

package/src/litellm/providers.ts

@@ -0,0 +1,19 @@
+/**
+ * The LiteLLM provider, with its credential source, as one layer for a stack.
+ *
+ *     Layer.mergeAll(litellmProviders(), …the stack's other providers)
+ *
+ * ★ THE DEFAULT READS `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` AT CALL TIME (credentials.ts),
+ *   never at layer build — pass another `Layer.Layer<LitellmCredentials>` (see
+ *   `litellmCredentialsLayerFor` in a test) to source them another way.
+ * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime the same way it is
+ *   for `netboxProviders`-style families in this kit; a stack that already deploys anything over
+ *   HTTP already has one.
+ */
+import * as Layer from 'effect/Layer';
+import { type LitellmCredentials, litellmCredentialsLayer } from './credentials.ts';
+import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
+
+export const litellmProviders = (
+  creds: Layer.Layer<LitellmCredentials> = litellmCredentialsLayer,
+) => LiteLLMPassThroughEndpointProvider().pipe(Layer.provide(creds));

package/src/postgres/connection.ts

@@ -0,0 +1,62 @@
+/**
+ * Where a database's cluster comes from, and how each lifecycle operation gets a client.
+ *
+ * ⛔ NO ESTATE VALUE LIVES HERE. The kit is PUBLIC; the mini's socket path, its user and its
+ *   database names are the CONSUMER's props, passed to `postgresConnection(...)` in a house
+ *   stack — never a default, never a fallback (`docs/postgres.md#path`).
+ * ★ A LAZY `Context.Service` WHOSE VALUE IS AN `Effect` (S24), THE SAME SHAPE THE HOUSE USES FOR
+ *   CREDENTIALS: `yield* yield* PostgresConnection` resolves the config INSIDE each operation,
+ *   never at layer build. Nothing here holds a secret today (`PostgresConnectionConfig` has no
+ *   `password` — S25, and CREATE DATABASE has none to assert either), but the shape is the one a
+ *   later TLS path (`Config.redacted` from the environment) drops into without a rewrite.
+ * ★ THE POOL IS BUILT IN A SCOPE AND CLOSED PER OPERATION. `Effect.provide(op, PgClient.layer(config))`
+ *   already opens a scope for the layer's build and closes it when `op` finishes — one pool per
+ *   `withPg` call, never held across a whole `reconcile`.
+ */
+import * as PgClient from '@effect/sql-pg/PgClient';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+
+/** What a stack passes to reach one cluster. `host` may be a socket directory (one beginning
+ * with `/` expands to `${host}/.s.PGSQL.${port}` — measured in
+ * `node_modules/@effect/sql-pg/src/PgConnection.ts`, the "Details" doc on `Config`) or a TCP
+ * host name; `port` defaults to `@effect/sql-pg`'s own default (5432) when omitted. */
+export interface PostgresConnectionConfig {
+  readonly host: string;
+  readonly port?: number;
+  readonly database: string;
+  readonly username: string;
+  readonly ssl?: boolean;
+}
+
+/** The lazy connection service. Its value is an `Effect` of the config, per S24 — see the file
+ * header for why. */
+export class PostgresConnection extends Context.Service<
+  PostgresConnection,
+  Effect.Effect<PostgresConnectionConfig>
+>()('Postgres.Connection') {}
+
+/** A stack's one-line way to provide a cluster: `Layer.provide(postgresConnection({ … }))` on
+ * `PostgresDatabaseProvider()`, or merged into the stack's own layer tree. */
+export const postgresConnection = (
+  config: PostgresConnectionConfig,
+): Layer.Layer<PostgresConnection> => Layer.succeed(PostgresConnection, Effect.succeed(config));
+
+/**
+ * Run one operation against a freshly built, freshly closed connection pool.
+ *
+ * Every `read`, `reconcile` step and `delete` in this family calls this once for the whole
+ * operation — never once per statement — so a reconcile that runs a `SELECT`, then a `CREATE`,
+ * then a re-read shares one pool and closes it once, while a plan-only `read` still opens and
+ * closes its own.
+ */
+export const withPg = <A, E>(
+  build: (pg: PgClient.PgClient) => Effect.Effect<A, E>,
+): Effect.Effect<A, E | SqlError, PostgresConnection> =>
+  Effect.gen(function* () {
+    const resolveConfig = yield* PostgresConnection;
+    const config = yield* resolveConfig;
+    return yield* Effect.provide(Effect.flatMap(PgClient.PgClient, build), PgClient.layer(config));
+  });

package/src/postgres/database-attrs.ts

@@ -0,0 +1,87 @@
+/**
+ * `Postgres.Database` props and attributes, and the one prop-level check that runs before any
+ * statement: the name's byte length against `NAMEDATALEN`.
+ *
+ * ⛔ EVERY ASSERTED PROP HERE HAS A CITED COLUMN. `docs/postgres.md#mapping` and
+ *   `database-provenance.test.ts` are what make that true rather than asserted: the test parses
+ *   the two committed fixtures (`create_database.sgml`'s synopsis, `pg_database.h`'s struct) and
+ *   fails if a prop here has no synopsis option or no catalog column behind it.
+ * ⛔ NO PASSWORD, EVER. A database has none in `pg_database` (S25) — `CREATE DATABASE` has no
+ *   password option at all (`gram.y@REL_18_6#createdb_opt_name`, measured: `IDENT | CONNECTION
+ *   LIMIT | ENCODING | LOCATION | OWNER | TABLESPACE | TEMPLATE`).
+ */
+
+/** NAMEDATALEN (`pg_config_manual.h@REL_18_6` line 29) minus the C string terminator: the
+ * longest name the server stores without truncating. */
+export const POSTGRES_NAME_MAX_BYTES = 63;
+
+/** UTF-8 byte length, the same unit `NAMEDATALEN` counts in (`scansup.c@REL_18_6#truncate_identifier`
+ * clips by `pg_mbcliplen`, a byte-oriented, multibyte-aware clip — never a JS `.length`, which
+ * counts UTF-16 code units and would pass a 63-byte multibyte name that is really 70+ bytes, or
+ * refuse a 63-byte name whose `.length` looks smaller). */
+export const utf8ByteLength = (value: string): number => new TextEncoder().encode(value).byteLength;
+
+/**
+ * Declared, at-most-once-asserted properties of one database.
+ *
+ * Every prop here maps to a `CREATE DATABASE` `WITH` option `create_database.sgml` documents
+ * AND a `pg_database` column that stores it (`database-provenance.test.ts`). `TEMPLATE`,
+ * `STRATEGY` and `OID` are excluded because nothing in `pg_database` reads them back once the
+ * database exists; `ICU_RULES` and `COLLATION_VERSION` are excluded for having no consumer in
+ * this family today. See `docs/postgres.md#excluded`.
+ */
+export interface PostgresDatabaseProps {
+  /** At most 63 UTF-8 bytes — refused at plan past that (`PostgresDatabaseNameRefused`). The
+   * identity: a name change is a plan-time refusal, never a replace. */
+  readonly name: string;
+  /** A role name in `pg_roles`, asserted before create (`PostgresDatabaseOwnerMissing`) and
+   * compared against `pg_get_userbyid(datdba)` on every plan thereafter. */
+  readonly owner: string;
+  /** `pg_encoding_to_char(datdatabase.encoding)`, e.g. `"UTF8"`. @default the template's. */
+  readonly encoding?: string;
+  /** `'builtin' | 'icu' | 'libc'` — `pg_database.datlocprovider` decoded
+   * (`pg_collation.h@REL_18_6#collprovider_name`). @default the template's. */
+  readonly localeProvider?: 'builtin' | 'icu' | 'libc';
+  /** `pg_database.datcollate`. @default the template's. */
+  readonly lcCollate?: string;
+  /** `pg_database.datctype`. @default the template's. */
+  readonly lcCtype?: string;
+  /** `pg_database.datallowconn`. @default `true`. */
+  readonly allowConnections?: boolean;
+  /** `pg_database.datconnlimit`; `-1` means unlimited. @default `-1`. */
+  readonly connectionLimit?: number;
+  /** `pg_database.datistemplate`. @default `false`. */
+  readonly isTemplate?: boolean;
+  /** A tablespace name in `pg_tablespace`. @default the template's (usually `pg_default`). */
+  readonly tablespace?: string;
+}
+
+/** Live attributes, read back after every reconcile. No `password` — see the file header. */
+export interface PostgresDatabaseAttributes {
+  readonly name: string;
+  readonly oid: number;
+  readonly owner: string;
+  readonly encoding: string;
+  readonly localeProvider: 'builtin' | 'icu' | 'libc';
+  readonly collate: string;
+  readonly ctype: string;
+  readonly allowConnections: boolean;
+  readonly connectionLimit: number;
+  readonly isTemplate: boolean;
+  readonly tablespace: string;
+}
+
+/**
+ * Refuse a name the server would truncate, before any statement is built.
+ *
+ * ★ CALLED FROM `diff` (so a plan fails, never a deploy) AND FROM `reconcile` (so a fake or a
+ *   direct call gets the same refusal, never just a broken statement).
+ */
+export const nameByteRefusal = (
+  name: string,
+): { readonly byteLength: number; readonly limit: number } | undefined => {
+  const byteLength = utf8ByteLength(name);
+  return byteLength > POSTGRES_NAME_MAX_BYTES
+    ? { byteLength, limit: POSTGRES_NAME_MAX_BYTES }
+    : undefined;
+};

package/src/postgres/database-bigint-serialization.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Regression for the critical finding: `SELECT_DATABASE_SQL` casting `oid`/`datconnlimit` to
+ * `::int8` makes `@effect/sql-pg`'s binary-protocol codec decode them as JS `bigint`, and
+ * alchemy's `encodeState` has no `bigint` branch — so `JSON.stringify`ing the persisted state
+ * throws on every successful `reconcile`, and a matching declared `connectionLimit` reads as
+ * permanent drift (`bigint !== number`).
+ *
+ * ⛔ THIS DOES NOT HIT A LIVE SOCKET. It stays faithful to the real defect by driving the exact
+ *   query TEXT `selectDatabase` sends (`fake-sql.ts`'s recorder does not decode types at all, so
+ *   it cannot see this bug) through `@effect/sql-pg/PgTypes`'s own public `encode`/`decode`
+ *   (the same codec table the real driver looks up by OID — measured `PgTypes.ts@4.0.0-rc.115`)
+ *   and through alchemy's own `encodeState` (`alchemy/State/StateEncoding`, what `LocalState.js`
+ *   calls before every `JSON.stringify`). If a column is cast to `::int8` in the production SQL,
+ *   this fake decodes it exactly as the real wire would: a genuine `bigint`, round-tripped
+ *   through the vendor's own codec, not a hand-simulated one.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Result from 'effect/Result';
+import * as PgTypes from '@effect/sql-pg/PgTypes';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import { encodeState } from 'alchemy/State/StateEncoding';
+import { reconcileWithClient } from './database.ts';
+import { PostgresDatabaseDrift } from './errors.ts';
+import type { PostgresDatabaseProps } from './database-attrs.ts';
+import type { PgExecutor } from './database-sql.ts';
+
+/** Round-trip `value` through the real `@effect/sql-pg` codec for `oid` — encode, then decode
+ * the resulting wire bytes back — so the JS type this returns is whatever the real driver would
+ * hand back for that OID, not an assumption about it. */
+const wireRoundtrip = (value: number, oid: number): number | bigint => {
+  const encoded = PgTypes.encode(oid === PgTypes.OID.int8 ? BigInt(value) : value, oid);
+  if (!Result.isSuccess(encoded)) throw new Error(`fixture: encode failed for OID ${String(oid)}`);
+  const decoded = PgTypes.decode(encoded.success, oid, 1);
+  if (!Result.isSuccess(decoded)) throw new Error(`fixture: decode failed for OID ${String(oid)}`);
+  return decoded.success as number | bigint;
+};
+
+const baseRow = {
+  name: 'widgets',
+  owner: 'tim',
+  encoding: 'UTF8',
+  localeProvider: 'libc',
+  collate: 'C',
+  ctype: 'C',
+  allowConnections: true,
+  isTemplate: false,
+  tablespace: 'pg_default',
+};
+
+/** A `pg_database` row decoded exactly as the production `SELECT_DATABASE_SQL` TEXT dictates:
+ * `oid`/`connectionLimit` come back as `bigint` only when that text casts them to `::int8` —
+ * the same condition that flips the real driver's codec lookup. */
+const wireAccurateRow = (text: string, oid: number, connectionLimit: number) => ({
+  ...baseRow,
+  oid: wireRoundtrip(oid, text.includes('d.oid::int8 AS oid') ? PgTypes.OID.int8 : PgTypes.OID.oid),
+  connectionLimit: wireRoundtrip(
+    connectionLimit,
+    text.includes('d.datconnlimit::int8 AS "connectionLimit"')
+      ? PgTypes.OID.int8
+      : PgTypes.OID.int4,
+  ),
+});
+
+/** A `PgExecutor` that answers `SELECT_DATABASE_SQL` with a wire-accurate row (see above) and
+ * every other statement the way `fake-sql.ts`'s own fake does. `seed`, when given, is the row
+ * already "on the cluster" — so `reconcileWithClient` takes the already-present/drift-check
+ * branch instead of create. With no seed, a `CREATE DATABASE` statement makes one up (oid
+ * 30000, the default `connectionLimit` of -1) so the mandatory post-create re-read has a row to
+ * decode — mirroring `fake-sql.ts`'s own greenfield bookkeeping. */
+const wireAccuratePg = (seed?: {
+  readonly oid: number;
+  readonly connectionLimit: number;
+}): PgExecutor => {
+  let created: { readonly oid: number; readonly connectionLimit: number } | undefined = seed;
+  return {
+    unsafe: <A extends object>(text: string, params: ReadonlyArray<unknown> = []) =>
+      Effect.suspend(() => {
+        if (text.startsWith('SELECT 1 AS present FROM pg_roles')) {
+          return Effect.succeed([{ present: 1 }] as unknown as ReadonlyArray<A>);
+        }
+        if (text.includes('FROM pg_database')) {
+          if (created === undefined) return Effect.succeed([] as unknown as ReadonlyArray<A>);
+          const row = wireAccurateRow(text, created.oid, created.connectionLimit);
+          return Effect.succeed([row] as unknown as ReadonlyArray<A>);
+        }
+        if (text.startsWith('CREATE DATABASE')) {
+          created = { oid: 30000, connectionLimit: -1 };
+          return Effect.succeed([] as unknown as ReadonlyArray<A>);
+        }
+        throw new Error(`wireAccuratePg: unrecognised statement: ${text}`);
+      }) as Effect.Effect<ReadonlyArray<A>, SqlError>,
+  };
+};
+
+const baseProps: PostgresDatabaseProps = { name: 'widgets', owner: 'tim' };
+
+describe('measured: @effect/sql-pg int8 vs native-width codecs (PgTypes.ts@4.0.0-rc.115)', () => {
+  test('OID.int8 decodes to a JS bigint', () => {
+    expect(typeof wireRoundtrip(20000, PgTypes.OID.int8)).toBe('bigint');
+  });
+
+  test('OID.oid and OID.int4 — the columns’ real pg_database.h widths — decode to a JS number', () => {
+    expect(typeof wireRoundtrip(20000, PgTypes.OID.oid)).toBe('number');
+    expect(typeof wireRoundtrip(-1, PgTypes.OID.int4)).toBe('number');
+  });
+});
+
+describe('reconcileWithClient: state must survive alchemy’s real encodeState + JSON.stringify', () => {
+  test('greenfield create-and-reread never returns a value the state encoder cannot serialize', async () => {
+    const pg = wireAccuratePg();
+    const attrs = await Effect.runPromise(reconcileWithClient(pg, baseProps));
+
+    expect(typeof attrs.oid).toBe('number');
+    expect(typeof attrs.connectionLimit).toBe('number');
+
+    let json: string | undefined;
+    expect(() => {
+      json = JSON.stringify(encodeState(attrs), null, 2);
+    }).not.toThrow();
+    expect(JSON.parse(json as string)).toMatchObject({ oid: attrs.oid, connectionLimit: -1 });
+  });
+
+  test('a declared connectionLimit that matches the live value is a no-op, not a false-positive drift', async () => {
+    const pg = wireAccuratePg({ oid: 30000, connectionLimit: 5 });
+    const attrs = await Effect.runPromise(
+      reconcileWithClient(pg, { ...baseProps, connectionLimit: 5 }),
+    );
+    expect(attrs.connectionLimit).toBe(5);
+  });
+
+  test('PostgresDatabaseDrift.message never throws building itself, even when a mismatch is real', async () => {
+    const pg = wireAccuratePg({ oid: 30000, connectionLimit: 5 });
+    const error = await Effect.runPromise(
+      Effect.flip(reconcileWithClient(pg, { ...baseProps, connectionLimit: 10 })),
+    );
+    expect(error).toBeInstanceOf(PostgresDatabaseDrift);
+    expect(() => (error as PostgresDatabaseDrift).message).not.toThrow();
+  });
+});

package/src/postgres/database-lifecycle.test.ts

@@ -0,0 +1,113 @@
+/**
+ * `reconcile` and `read` against `fake-sql.ts`'s recording fake — greenfield, no-drift, drift,
+ * a `42P04` race, a missing owner role, and exact quoting for hostile names. Every case reverts
+ * cleanly by reverting `database.ts`/`database-sql.ts` locally: these tests fail on `origin/main`
+ * because the files do not exist there.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeSql } from './fake-sql.ts';
+import { readWithClient, reconcileWithClient } from './database.ts';
+import { PostgresDatabaseDrift, PostgresDatabaseOwnerMissing } from './errors.ts';
+import type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-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 baseProps: PostgresDatabaseProps = { name: 'widgets', owner: 'tim' };
+
+const liveRow = (over: Partial<PostgresDatabaseAttributes> = {}): PostgresDatabaseAttributes => ({
+  name: 'widgets',
+  oid: 30000,
+  owner: 'tim',
+  encoding: 'UTF8',
+  localeProvider: 'libc',
+  collate: 'C',
+  ctype: 'C',
+  allowConnections: true,
+  connectionLimit: -1,
+  isTemplate: false,
+  tablespace: 'pg_default',
+  ...over,
+});
+
+describe('reconcile: greenfield', () => {
+  test('issues exactly one CREATE, quoted, with an OWNER clause, and nothing before the role check', async () => {
+    const fake = makeFakeSql({ roles: ['tim'] });
+    const attrs = await run(reconcileWithClient(fake, baseProps));
+    expect(attrs.name).toBe('widgets');
+    expect(attrs.owner).toBe('tim');
+    const creates = fake.statements.filter((s) => s.text.startsWith('CREATE DATABASE'));
+    expect(creates.length).toBe(1);
+    expect(creates[0]?.text).toBe('CREATE DATABASE "widgets" WITH OWNER "tim"');
+  });
+
+  test('refuses before any CREATE when the owner role does not exist', async () => {
+    const fake = makeFakeSql({ roles: [] });
+    const error = await fails(reconcileWithClient(fake, baseProps));
+    expect(error).toBeInstanceOf(PostgresDatabaseOwnerMissing);
+    expect(fake.statements.some((s) => s.text.startsWith('CREATE DATABASE'))).toBe(false);
+  });
+
+  test('a 42P04 race (something else created it first) converges instead of failing', async () => {
+    const fake = makeFakeSql({ roles: ['tim'], raceNextCreate: true });
+    // Seed the row a "competing" create would have produced, so the post-race re-read finds it.
+    fake.databases.set('widgets', liveRow());
+    const attrs = await run(reconcileWithClient(fake, baseProps));
+    expect(attrs.name).toBe('widgets');
+  });
+
+  test('hostile names are quoted exactly: embedded quote and a hyphen', async () => {
+    const fake = makeFakeSql({ roles: ['tim'] });
+    await run(reconcileWithClient(fake, { name: 'a"b-c', owner: 'tim' }));
+    const create = fake.statements.find((s) => s.text.startsWith('CREATE DATABASE'));
+    expect(create?.text).toBe('CREATE DATABASE "a""b-c" WITH OWNER "tim"');
+  });
+});
+
+describe('reconcile: already present', () => {
+  test('no drift records zero write statements', async () => {
+    const fake = makeFakeSql({ roles: ['tim'], databases: [liveRow()] });
+    const attrs = await run(reconcileWithClient(fake, baseProps));
+    expect(attrs).toEqual(liveRow());
+    expect(
+      fake.statements.every((s) => !s.text.startsWith('CREATE') && !s.text.startsWith('ALTER')),
+    ).toBe(true);
+  });
+
+  test('an owner mismatch fails with the typed drift tag and issues no ALTER', async () => {
+    const fake = makeFakeSql({
+      roles: ['tim', 'someone-else'],
+      databases: [liveRow({ owner: 'someone-else' })],
+    });
+    const error = await fails(reconcileWithClient(fake, baseProps));
+    expect(error).toBeInstanceOf(PostgresDatabaseDrift);
+    expect((error as PostgresDatabaseDrift).prop).toBe('owner');
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+  });
+
+  test('an asserted-prop mismatch fails with the typed drift tag naming that prop', async () => {
+    const fake = makeFakeSql({ roles: ['tim'], databases: [liveRow({ isTemplate: true })] });
+    const error = await fails(reconcileWithClient(fake, { ...baseProps, isTemplate: false }));
+    expect(error).toBeInstanceOf(PostgresDatabaseDrift);
+    expect((error as PostgresDatabaseDrift).prop).toBe('isTemplate');
+  });
+
+  test('no recorded statement ever runs inside BEGIN', async () => {
+    const fake = makeFakeSql({ roles: ['tim'], databases: [liveRow()] });
+    await run(reconcileWithClient(fake, baseProps));
+    expect(fake.statements.some((s) => /\bBEGIN\b/.test(s.text))).toBe(false);
+  });
+});
+
+describe('read', () => {
+  test('answers undefined when the database is absent', async () => {
+    const fake = makeFakeSql();
+    expect(await run(readWithClient(fake, 'widgets'))).toBeUndefined();
+  });
+
+  test("answers the live row when present (ownership branding is the caller's job)", async () => {
+    const fake = makeFakeSql({ databases: [liveRow()] });
+    expect(await run(readWithClient(fake, 'widgets'))).toEqual(liveRow());
+  });
+});