@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/grants-read.ts

@@ -0,0 +1,250 @@
+/**
+ * The read half of `Postgres.Grants`: what the catalogs say the declared role and PUBLIC
+ * may do on one schema, its relations, its columns and its default privileges — plus the
+ * existence check the plan refuses on before any statement runs. The ownership facts
+ * (`nspowner`/`relowner`) live in `grants-ownership.ts`; the word vocabulary and the
+ * PUBLIC relkind set live in `grants-words.ts`.
+ *
+ * ★ READS GO THROUGH `aclexplode`, NOT THE `aclitem` TEXT. Measured at
+ *   `func.sgml@REL_18_6` ("Access Privilege Inquiry Functions", committed as
+ *   `fixtures/pg-REL_18_6-aclexplode-func.txt`): `aclexplode(aclitem[])` returns
+ *   `(grantor oid, grantee oid, privilege_type text, is_grantable boolean)`, one row per
+ *   granted privilege, with the PUBLIC pseudo-role at grantee oid zero — so the read path
+ *   never parses `grantee=privs/grantor` letters at all. The letters still appear in
+ *   `grants-provenance.test.ts`, where the declared words are traced to the `ACL_*_CHR`
+ *   constants the server really stores, but no shipped query depends on them.
+ * ★ `grantee = (SELECT oid FROM pg_roles WHERE rolname = $1)` IS MISSING-ROLE-SAFE BY
+ *   CONSTRUCTION: a role that does not exist yields `NULL`, `NULL = anything` is `NULL`,
+ *   and `WHERE NULL` selects nothing — the role simply reads as holding no privileges.
+ * ★ `relkind` IS NOT FILTERED. A schema's `pg_class` rows carry `relacl` whether the
+ *   relation is a table, a view or a sequence, and the seat model grants SELECT on a
+ *   shared ledger VIEW in another schema through the same `GRANT … ON` statement the docs'
+ *   table form accepts for views (`grant.sgml@REL_18_6`: "ALL TABLES also affects views
+ *   and foreign tables"). A word the relkind cannot hold (e.g. INSERT on a sequence) is
+ *   refused by the server itself as a statement error, never by a word check: deciding
+ *   that at plan time would need a second relkind query this family does not read.
+ * ★ `relkind` IS CAST TO TEXT (`c.relkind::text`) BECAUSE THE COLUMN IS TYPE `"char"`
+ *   (OID 18), which `@effect/sql-pg`'s socket transport does not decode: `PgTypes` has
+ *   no codec for OID 18, so the raw `bytea`-shaped bytes arrive (a plain table reads as
+ *   `Uint8Array([114])`, never `'r'`) and `relkindIsPublicRevocable` (`grants-words.ts`)
+ *   would say PUBLIC holds nothing a `REVOKE ALL ON ALL TABLES IN SCHEMA` reaches.
+ *   `::text` returns OID 25, which decodes as a string. Same trap as the `datlocprovider`
+ *   CASE in `database-sql.ts`, which casts `"char"` columns to text for the same reason.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import { readOwnedTables, readSchemaOwnership } from './grants-ownership.ts';
+import { type LiveDefault, readDefaultAcls } from './grants-read-defaults.ts';
+import { type AclRow, encodeWord, wordsOf } from './grants-words.ts';
+
+const SCHEMA_PRESENT_SQL = 'SELECT 1 AS present FROM pg_namespace WHERE nspname = $1';
+
+export const schemaExists = (pg: PgExecutor, schema: string): Effect.Effect<boolean, SqlError> =>
+  Effect.map(
+    pg.unsafe<{ readonly present: number }>(SCHEMA_PRESENT_SQL, [schema]),
+    (rows) => rows.length > 0,
+  );
+
+/** Schema-level rows for the declared role and for PUBLIC in one query: the repair target
+ * (`role`) and the `revokeFromPublic` check (`public`) share one round trip. */
+const SCHEMA_ACL_SQL = `SELECT
+    a.grantee = 0 AS public,
+    a.privilege_type AS privilege,
+    a.is_grantable AS grantable
+  FROM pg_namespace n
+  CROSS JOIN LATERAL aclexplode(n.nspacl) AS a
+  WHERE n.nspname = $1
+    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_roles WHERE rolname = $2))`;
+
+export interface LiveSchemaAcl {
+  readonly role: ReadonlyArray<string>;
+  readonly public: ReadonlyArray<string>;
+}
+
+export const readSchemaAcl = (
+  pg: PgExecutor,
+  schema: string,
+  role: string,
+): Effect.Effect<LiveSchemaAcl, SqlError> =>
+  Effect.map(pg.unsafe<AclRow>(SCHEMA_ACL_SQL, [schema, role]), (rows) => ({
+    role: wordsOf(rows, false),
+    public: wordsOf(rows, true),
+  }));
+
+/** One row per relation in the schema that holds ANY acl entry for the declared role or
+ * PUBLIC, with each grantee's words and the relation's `relkind` — sorted by table name.
+ * The relkind is NOT a filter on what is read (see the header): it scopes the
+ * `revokeFromPublic` CHECK to the relations `REVOKE ALL ON ALL TABLES IN SCHEMA` actually
+ * reaches (measured on PG 18.6: a PUBLIC grant on a sequence survives that statement, so
+ * counting it would refuse to converge). */
+const TABLES_SQL = `SELECT
+    c.relname AS table,
+    c.relkind::text AS relkind,
+    a.grantee = 0 AS public,
+    a.privilege_type AS privilege,
+    a.is_grantable AS grantable
+  FROM pg_class c
+  CROSS JOIN LATERAL aclexplode(c.relacl) AS a
+  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
+    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_roles WHERE rolname = $2))
+  ORDER BY c.relname`;
+
+export interface LiveTable {
+  readonly table: string;
+  readonly relkind: string;
+  readonly role: ReadonlyArray<string>;
+  readonly public: ReadonlyArray<string>;
+}
+
+export const readTableAcls = (
+  pg: PgExecutor,
+  schema: string,
+  role: string,
+): Effect.Effect<ReadonlyArray<LiveTable>, SqlError> =>
+  Effect.map(
+    pg.unsafe<AclRow & { readonly table: string; readonly relkind: string }>(TABLES_SQL, [
+      schema,
+      role,
+    ]),
+    (rows) => {
+      const byTable = new Map<string, { relkind: string; role: string[]; public: string[] }>();
+      for (const row of rows) {
+        const entry = byTable.get(row.table) ?? { relkind: row.relkind, role: [], public: [] };
+        entry[row.public ? 'public' : 'role'].push(encodeWord(row));
+        byTable.set(row.table, entry);
+      }
+      return [...byTable.entries()]
+        .map(([table, entry]) => ({
+          table,
+          relkind: entry.relkind,
+          role: [...new Set(entry.role)].sort(),
+          public: [...new Set(entry.public)].sort(),
+        }))
+        .sort((a, b) => a.table.localeCompare(b.table));
+    },
+  );
+
+/** One row per column ACL in the schema (user columns only: `attnum > 0`, not dropped),
+ * for the declared role and PUBLIC — sorted by table then column. PUBLIC column rows are
+ * read so `revokeFromPublic` converges on them too: `REVOKE ALL ON ALL TABLES IN SCHEMA`
+ * clears them in the same statement, but only grants made by the revoking role or by the
+ * owner (which holds every grant option) — a third grantor's grant would otherwise survive
+ * past a repair with nothing re-read to notice it.
+ *
+ * `grantor` is selected for the same rule on a table-level `REVOKE ALL` (revoke.sgml@REL_18_6:
+ * a role revokes only what it granted; a superuser's REVOKE is performed as the owner).
+ * `restorable` is those words — the collateral re-grant restores them and leaves a third
+ * grantor's entry where the revoke left it, instead of adding an owner grant on top.
+ * `revoker_as_owner` gates the `grantor === owner` arm: the revoker clears the owner's grant
+ * only when it revokes AS the owner — a superuser or a member of the owning role
+ * (`pg_has_role(..., 'USAGE')`, `select_best_grantor` acl.c@REL_18_6). A non-superuser,
+ * non-member revoker clears only grants it made, so an owner grant marked restorable would be re-granted over an entry the revoke never removed. */
+const COLUMNS_SQL = `SELECT
+    c.relname AS table,
+    v.attname AS column,
+    a.grantee = 0 AS public,
+    a.privilege_type AS privilege,
+    a.is_grantable AS grantable,
+    pg_get_userbyid(a.grantor) AS grantor,
+    pg_get_userbyid(c.relowner) AS owner,
+    current_user AS revoker,
+    pg_has_role(current_user, c.relowner, 'USAGE') AS revoker_as_owner
+  FROM pg_attribute v
+  JOIN pg_class c ON c.oid = v.attrelid
+  CROSS JOIN LATERAL aclexplode(v.attacl) AS a
+  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
+    AND v.attnum > 0
+    AND NOT v.attisdropped
+    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_roles WHERE rolname = $2))
+  ORDER BY c.relname, v.attname`;
+
+export interface LiveColumn {
+  readonly table: string;
+  readonly column: string;
+  readonly role: ReadonlyArray<string>;
+  readonly public: ReadonlyArray<string>;
+  /** Role words granted by `current_user`, or by the relation owner when this session revokes
+   * AS the owner (superuser or owner-member) — what a table `REVOKE ALL` here actually clears. */
+  readonly restorable: ReadonlyArray<string>;
+}
+
+export const readColumnAcls = (
+  pg: PgExecutor,
+  schema: string,
+  role: string,
+): Effect.Effect<ReadonlyArray<LiveColumn>, SqlError> =>
+  Effect.map(
+    pg.unsafe<
+      AclRow & {
+        readonly table: string;
+        readonly column: string;
+        readonly grantor: string;
+        readonly owner: string;
+        readonly revoker: string;
+        readonly revoker_as_owner: boolean;
+      }
+    >(COLUMNS_SQL, [schema, role]),
+    (rows) => {
+      const byColumn = new Map<
+        string,
+        { role: string[]; public: string[]; restorable: string[] }
+      >();
+      for (const row of rows) {
+        const key = `${row.table}\u0000${row.column}`;
+        const entry = byColumn.get(key) ?? { role: [], public: [], restorable: [] };
+        const word = encodeWord(row);
+        entry[row.public ? 'public' : 'role'].push(word);
+        if (
+          !row.public &&
+          (row.grantor === row.revoker || (row.grantor === row.owner && row.revoker_as_owner))
+        ) {
+          entry.restorable.push(word);
+        }
+        byColumn.set(key, entry);
+      }
+      return [...byColumn.entries()]
+        .map(([key, entry]) => {
+          const [table, column] = key.split('\u0000');
+          return {
+            table: table as string,
+            column: column as string,
+            role: [...new Set(entry.role)].sort(),
+            public: [...new Set(entry.public)].sort(),
+            restorable: [...new Set(entry.restorable)].sort(),
+          };
+        })
+        .sort((a, b) => a.table.localeCompare(b.table) || a.column.localeCompare(b.column));
+    },
+  );
+
+/** Everything the reconcile and diff paths need about one schema, read in one bounded
+ * burst of parallel queries (one pool per operation — `withPg` opens and closes it).
+ * `schemaOwnedByRole`/`ownedTables` are the ownership facts (pg_namespace.nspowner,
+ * pg_class.relowner, `grants-ownership.ts`) the repair needs so it can LEAVE objects the
+ * declared role owns alone: an owner holds every privilege implicitly, and a `REVOKE`
+ * cannot take that away (`grants-plan.ts`). */
+export interface LiveGrants {
+  readonly schemaExists: boolean;
+  readonly schema: LiveSchemaAcl;
+  readonly tables: ReadonlyArray<LiveTable>;
+  readonly columns: ReadonlyArray<LiveColumn>;
+  readonly defaults: ReadonlyArray<LiveDefault>;
+  readonly schemaOwnedByRole: boolean;
+  readonly ownedTables: ReadonlyArray<string>;
+}
+
+export const readGrants = (
+  pg: PgExecutor,
+  schema: string,
+  role: string,
+): Effect.Effect<LiveGrants, SqlError> =>
+  Effect.all({
+    schemaExists: schemaExists(pg, schema),
+    schema: readSchemaAcl(pg, schema, role),
+    tables: readTableAcls(pg, schema, role),
+    columns: readColumnAcls(pg, schema, role),
+    defaults: readDefaultAcls(pg, schema, role),
+    schemaOwnedByRole: readSchemaOwnership(pg, schema, role),
+    ownedTables: readOwnedTables(pg, schema, role),
+  });

package/src/postgres/grants-refusals.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Every plan-time refusal and the `diff` sweep, checked without a client: the retarget
+ * refusal (role/database/schema), `diff` never answering `replace`, the privilege/duplicate/
+ * name refusals through `diff`, and `defaultRemovalPolicy: 'retain'` declared in source.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import * as Effect from 'effect/Effect';
+import { diffPostgresGrants } from './grants-ops.ts';
+import type { PostgresGrantsAttributes, PostgresGrantsProps } from './grants-attrs.ts';
+import {
+  PostgresGrantsDuplicateObject,
+  PostgresGrantsNameRefused,
+  PostgresGrantsPrivilegeRefused,
+  PostgresGrantsRetargetRefused,
+} from './grants-errors.ts';
+
+const base: PostgresGrantsProps = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+};
+
+const output: PostgresGrantsAttributes = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+  schemaPrivileges: ['usage'],
+  tables: [{ table: 'widgets', privileges: ['select'] }],
+  columns: [],
+  defaults: [],
+  publicSchemaRevoked: true,
+  publicTablesRevoked: true,
+  schemaOwnedByRole: false,
+  ownedTables: [],
+};
+
+describe('diff: retarget refusals', () => {
+  test('a changed role, database or schema is refused, never a silent update', async () => {
+    for (const [prop, value] of [
+      ['role', 'other_role'],
+      ['database', 'other_db'],
+      ['schema', 'other_schema'],
+    ] as const) {
+      const error = await Effect.runPromise(
+        Effect.flip(diffPostgresGrants({ ...base, [prop]: value }, output)),
+      );
+      expect(error, prop).toBeInstanceOf(PostgresGrantsRetargetRefused);
+      expect((error as PostgresGrantsRetargetRefused).prop).toBe(prop);
+    }
+  });
+});
+
+describe('diff: declarations', () => {
+  test('a declaration matching the attributes answers noop', async () => {
+    const result = await Effect.runPromise(
+      diffPostgresGrants(
+        { ...base, tables: [{ table: 'widgets', privileges: ['select'] }] },
+        output,
+      ),
+    );
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  test('any word change, new table or new PUBLIC revoke answers update, NEVER replace', async () => {
+    const variants: ReadonlyArray<Partial<PostgresGrantsProps>> = [
+      { tables: [{ table: 'widgets', privileges: ['select', 'insert'] }] },
+      {
+        tables: [
+          { table: 'widgets', privileges: ['select'] },
+          { table: 'gadgets', privileges: ['select'] },
+        ],
+      },
+      { schemaUsage: false },
+      { columnGrants: [{ table: 'widgets', column: 'id', privileges: ['select'] }] },
+      { defaultPrivileges: [{ forRole: 'owner', privileges: ['select'] }] },
+    ];
+    for (const variant of variants) {
+      const result = await Effect.runPromise(
+        diffPostgresGrants(
+          { ...base, tables: [{ table: 'widgets', privileges: ['select'] }], ...variant },
+          output,
+        ),
+      );
+      expect(result?.action, `variant ${JSON.stringify(variant)}`).toBe('update');
+      expect(result).not.toEqual({ action: 'replace' });
+    }
+  });
+
+  test('the plan-time refusals surface through diff: privilege, duplicate, name', async () => {
+    const privilege = await Effect.runPromise(
+      Effect.flip(
+        diffPostgresGrants(
+          { ...base, tables: [{ table: 'widgets', privileges: ['execute'] }] },
+          output,
+        ),
+      ),
+    );
+    expect(privilege).toBeInstanceOf(PostgresGrantsPrivilegeRefused);
+
+    const duplicate = await Effect.runPromise(
+      Effect.flip(
+        diffPostgresGrants(
+          {
+            ...base,
+            tables: [
+              { table: 'widgets', privileges: ['select'] },
+              { table: 'widgets', privileges: ['insert'] },
+            ],
+          },
+          output,
+        ),
+      ),
+    );
+    expect(duplicate).toBeInstanceOf(PostgresGrantsDuplicateObject);
+
+    // The over-long name must not also be a retarget (role/database/schema), so the byte
+    // limit is exercised through a table name while identity stays unchanged.
+    const name = await Effect.runPromise(
+      Effect.flip(
+        diffPostgresGrants(
+          { ...base, tables: [{ table: 'a'.repeat(64), privileges: ['select'] }] },
+          output,
+        ),
+      ),
+    );
+    expect(name).toBeInstanceOf(PostgresGrantsNameRefused);
+  });
+});
+
+describe('removal policy', () => {
+  test('defaultRemovalPolicy is retain (declared alongside PostgresGrants, checked in source)', () => {
+    const source = readFileSync(new URL('./grants.ts', import.meta.url), 'utf8');
+    expect(source).toContain("defaultRemovalPolicy: 'retain'");
+  });
+});

package/src/postgres/grants-refuse.ts

@@ -0,0 +1,119 @@
+/**
+ * The plan-time refusals of `Postgres.Grants`, checked without a client: a word outside
+ * its vocabulary, a word declared both plain and `*`-marked, a duplicate object and the
+ * over-long name. Pure — no client, no `Effect` — so `reconcile` and the engine's `diff`
+ * refuse exactly the same way.
+ */
+import {
+  COLUMN_PRIVILEGES,
+  SCHEMA_PRIVILEGES,
+  TABLE_PRIVILEGES,
+  grantsNameByteRefusal,
+} from './grants-attrs.ts';
+import { type DeclaredGrants, baseWord } from './grants-declare.ts';
+
+/** The first refusal inside one word list: a word outside the vocabulary (the base word of
+ * a `*`-marked one, and a bare `*` is never a privilege). `undefined` when the list is
+ * in scope. */
+const wordRefusal = (
+  words: ReadonlyArray<string>,
+  vocabulary: ReadonlyArray<string>,
+): string | undefined => {
+  for (const word of words) {
+    if (word === '*') return word;
+    const bare = baseWord(word);
+    if (!vocabulary.includes(bare as never)) return bare;
+  }
+  return undefined;
+};
+
+/** One refusal inside the resolved declaration, already discriminated for its typed error.
+ * Words are checked against their vocabulary; names are checked for duplicates (two
+ * entries for one table, one column pair, or one `forRole` would silently merge in the
+ * sort and hide an operator's mistake). */
+export type DeclarationRefusal =
+  | { readonly kind: 'privilege'; readonly prop: string; readonly word: string }
+  | { readonly kind: 'duplicate'; readonly prop: string; readonly name: string };
+
+/** One refusal inside one validated word list: first a word outside its vocabulary, then
+ * a base word declared both plain and `*`-marked — the server keeps ONE aclitem per
+ * grantee per grantor, so `select` and `select*` cannot both hold and the set could never
+ * converge (`grants-plan.test.ts` pins the refusal). */
+const listRefusal = (
+  words: ReadonlyArray<string>,
+  vocabulary: ReadonlyArray<string>,
+  prop: string,
+): DeclarationRefusal | undefined => {
+  const word = wordRefusal(words, vocabulary);
+  if (word !== undefined) return { kind: 'privilege', prop, word };
+  const seen = new Set<string>();
+  for (const entry of words) {
+    const base = baseWord(entry);
+    if (seen.has(base)) return { kind: 'duplicate', prop, name: base };
+    seen.add(base);
+  }
+  return undefined;
+};
+
+export const declarationRefusal = (declared: DeclaredGrants): DeclarationRefusal | undefined => {
+  const schema = listRefusal(declared.schemaPrivileges, SCHEMA_PRIVILEGES, 'schemaPrivileges');
+  if (schema !== undefined) return schema;
+  for (const table of declared.tables) {
+    const refusal = listRefusal(table.privileges, TABLE_PRIVILEGES, `tables.${table.table}`);
+    if (refusal !== undefined) return refusal;
+  }
+  for (const column of declared.columns) {
+    const refusal = listRefusal(
+      column.privileges,
+      COLUMN_PRIVILEGES,
+      `columnGrants.${column.table}.${column.column}`,
+    );
+    if (refusal !== undefined) return refusal;
+  }
+  for (const entry of declared.defaults) {
+    const refusal = listRefusal(
+      entry.privileges,
+      TABLE_PRIVILEGES,
+      `defaultPrivileges.${entry.forRole}`,
+    );
+    if (refusal !== undefined) return refusal;
+  }
+  const duplicate = (names: ReadonlyArray<string>): string | undefined => {
+    const seen = new Set<string>();
+    for (const name of names) {
+      if (seen.has(name)) return name;
+      seen.add(name);
+    }
+    return undefined;
+  };
+  const table = duplicate(declared.tables.map((entry) => entry.table));
+  if (table !== undefined) return { kind: 'duplicate', prop: 'tables', name: table };
+  const column = duplicate(declared.columns.map((entry) => `${entry.table}\0${entry.column}`));
+  if (column !== undefined)
+    return { kind: 'duplicate', prop: 'columnGrants', name: column.replace('\0', '.') };
+  const forRole = duplicate(declared.defaults.map((entry) => entry.forRole));
+  if (forRole !== undefined) return { kind: 'duplicate', prop: 'defaultPrivileges', name: forRole };
+  return undefined;
+};
+
+/** Refuse the first declared name the server would silently truncate — the grantee role,
+ * the database, the schema, every table, every table-and-column pair, every `forRole`
+ * (roles, schemas, tables and columns are all `NameData`; the same limit
+ * `Postgres.Database` enforces). `undefined` when every name is in range. */
+export const grantsNamesRefusal = (
+  declared: DeclaredGrants,
+): { readonly name: string; readonly byteLength: number; readonly limit: number } | undefined => {
+  const names = [
+    declared.role,
+    declared.database,
+    declared.schema,
+    ...declared.tables.map((table) => table.table),
+    ...declared.columns.flatMap((column) => [column.table, column.column]),
+    ...declared.defaults.map((entry) => entry.forRole),
+  ];
+  for (const name of names) {
+    const refusal = grantsNameByteRefusal(name);
+    if (refusal !== undefined) return { name, ...refusal };
+  }
+  return undefined;
+};

package/src/postgres/grants-relkind-wire.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Regression for the critical finding: `TABLES_SQL` selecting `c.relkind` raw made
+ * `@effect/sql-pg`'s socket transport hand back the `"char"` column (OID 18) as raw
+ * bytes — `PgTypes` has no codec for that OID, so a plain table read as
+ * `Uint8Array([114])`, never `'r'` — and `relkindIsPublicRevocable` (`grants-words.ts`)
+ * then saw nothing a `REVOKE … ON ALL TABLES IN SCHEMA` reaches: the PUBLIC clear was
+ * never planned and `attributesOf` recorded `publicTablesRevoked: true` while PUBLIC
+ * still held its words. The fix casts `c.relkind::text` (OID 25, decoded as a string),
+ * same shape as the `datlocprovider` CASE in `database-sql.ts`.
+ *
+ * ⛔ THIS DOES NOT HIT A LIVE SOCKET. It stays faithful to the real defect by pinning
+ *   the vendor's own decode for both OIDs (`PgTypes.decode` returns the raw bytes
+ *   unchanged for the codec-less OID 18 — measured `PgTypes.ts@4.0.0-rc.115`) and by
+ *   driving the production `readGrants` through `makeFakeGrants`, whose tables branch
+ *   (`fake-grants-read.ts`) shapes `relkind` per the query TEXT exactly as the wire
+ *   would: a string only because the SQL casts `::text`. Reverting the cast makes the
+ *   fake answer raw bytes again, and every assertion below fails.
+ */
+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 { readGrants } from './grants-read.ts';
+import { planRepair } from './grants-plan.ts';
+import { attributesOf } from './grants-diff.ts';
+import { declaredNames, resolveProps } from './grants-declare.ts';
+import { makeFakeGrants } from './fake-grants-sql.ts';
+
+const declared = resolveProps({
+  role: 'seat_writer',
+  database: 'widgets',
+  schema: 'app',
+  tables: [{ table: 'widgets', privileges: ['select'] }],
+  revokeFromPublic: true,
+});
+
+/** PUBLIC holds SELECT on a plain table (`relkind` `'r'`): the exact state the raw-bytes
+ * bug misread. */
+const makeFake = () =>
+  makeFakeGrants({
+    schemas: ['app'],
+    roles: ['seat_writer'],
+    tables: [{ schema: 'app', table: 'widgets', columns: ['id'], relkind: 'r' }],
+    acl: [
+      {
+        object: { schema: 'app', table: 'widgets' },
+        grantee: 'PUBLIC',
+        grantor: 'postgres',
+        words: ['select'],
+      },
+    ],
+  });
+
+describe('measured: the "char" relkind column decodes raw on the socket transport', () => {
+  test('PgTypes.decode returns the raw bytes for OID 18 — there is no "char" codec', () => {
+    const decoded = PgTypes.decode(new Uint8Array([114]), 18, 1);
+    if (!Result.isSuccess(decoded)) throw new Error('fixture: decode failed for OID 18');
+    expect(decoded.success instanceof Uint8Array).toBe(true);
+    expect(decoded.success).not.toBe('r');
+  });
+
+  test('the same byte string decodes as a string through the OID 25 text codec', () => {
+    const decoded = PgTypes.decode(new Uint8Array([114]), PgTypes.OID.text, 1);
+    if (!Result.isSuccess(decoded)) throw new Error('fixture: decode failed for OID 25');
+    expect(decoded.success).toBe('r');
+  });
+});
+
+describe('readGrants: the ::text cast is what makes relkind a string', () => {
+  test('the tables read selects c.relkind::text and answers a string relkind', async () => {
+    const fake = makeFake();
+    const live = await Effect.runPromise(readGrants(fake, 'app', 'seat_writer'));
+
+    const tablesRead = fake.statements.find((statement) =>
+      statement.text.includes('aclexplode(c.relacl)'),
+    );
+    expect(tablesRead?.text).toContain('c.relkind::text AS relkind');
+
+    expect(live.tables).toHaveLength(1);
+    const row = live.tables[0] as (typeof live.tables)[number];
+    expect(typeof row.relkind).toBe('string');
+    expect(row.relkind).toBe('r');
+    expect(row.public).toEqual(['select']);
+  });
+
+  test('a PUBLIC grant on a plain table is planned for revoke and recorded as not-yet-revoked', async () => {
+    const live = await Effect.runPromise(readGrants(makeFake(), 'app', 'seat_writer'));
+
+    expect(planRepair(declared, live)).toContain(
+      'REVOKE ALL ON ALL TABLES IN SCHEMA "app" FROM PUBLIC',
+    );
+    expect(attributesOf(live, declaredNames(declared)).publicTablesRevoked).toBe(false);
+  });
+
+  test('the raw-bytes row shape the uncast column produces would hide the PUBLIC grant again', async () => {
+    const live = await Effect.runPromise(readGrants(makeFake(), 'app', 'seat_writer'));
+    // What the pre-fix SQL received on the socket: relkind as the codec-less OID 18 bytes.
+    const buggyLive = {
+      ...live,
+      tables: live.tables.map((table) => ({
+        ...table,
+        relkind: new Uint8Array([114]) as unknown as string,
+      })),
+    };
+
+    expect(planRepair(declared, buggyLive)).not.toContain(
+      'REVOKE ALL ON ALL TABLES IN SCHEMA "app" FROM PUBLIC',
+    );
+    expect(attributesOf(buggyLive, declaredNames(declared)).publicTablesRevoked).toBe(true);
+  });
+});