@homeflare/alchemy 0.43.0 → 0.45.0

package/dist/postgres/grants-read-defaults.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The default-privilege half of the grants read: what `pg_default_acl` says the declared
+ * role receives on relations (`defaclobjtype = 'r'`, the only object type this family
+ * declares — `pg_default_acl.h@REL_18_6#DEFACLOBJ_RELATION`) created in the schema,
+ * whatever role created the entry. Extracted from `grants-read.ts` so that file stays
+ * under the 250-line cap; the read still goes through `aclexplode` (see that file's
+ * header for the doctrine), never the `aclitem` text.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+export interface LiveDefault {
+    readonly forRole: string;
+    readonly role: ReadonlyArray<string>;
+}
+export declare const readDefaultAcls: (pg: PgExecutor, schema: string, role: string) => Effect.Effect<ReadonlyArray<LiveDefault>, SqlError>;
+//# sourceMappingURL=grants-read-defaults.d.ts.map

package/dist/postgres/grants-read-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants-read-defaults.d.ts","sourceRoot":"","sources":["../../src/postgres/grants-read-defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAiBpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACtC;AAED,eAAO,MAAM,eAAe,OACtB,UAAU,UACN,MAAM,QACR,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,QAAQ,CAclD,CAAC"}

package/dist/postgres/grants-read.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { type LiveDefault } from './grants-read-defaults.ts';
+export declare const schemaExists: (pg: PgExecutor, schema: string) => Effect.Effect<boolean, SqlError>;
+export interface LiveSchemaAcl {
+    readonly role: ReadonlyArray<string>;
+    readonly public: ReadonlyArray<string>;
+}
+export declare const readSchemaAcl: (pg: PgExecutor, schema: string, role: string) => Effect.Effect<LiveSchemaAcl, SqlError>;
+export interface LiveTable {
+    readonly table: string;
+    readonly relkind: string;
+    readonly role: ReadonlyArray<string>;
+    readonly public: ReadonlyArray<string>;
+}
+export declare const readTableAcls: (pg: PgExecutor, schema: string, role: string) => Effect.Effect<ReadonlyArray<LiveTable>, SqlError>;
+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 declare const readColumnAcls: (pg: PgExecutor, schema: string, role: string) => Effect.Effect<ReadonlyArray<LiveColumn>, SqlError>;
+/** 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 declare const readGrants: (pg: PgExecutor, schema: string, role: string) => Effect.Effect<LiveGrants, SqlError>;
+//# sourceMappingURL=grants-read.d.ts.map

package/dist/postgres/grants-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants-read.d.ts","sourceRoot":"","sources":["../../src/postgres/grants-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,2BAA2B,CAAC;AAK9E,eAAO,MAAM,YAAY,OAAQ,UAAU,UAAU,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAI1F,CAAC;AAaJ,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,eAAO,MAAM,aAAa,OACpB,UAAU,UACN,MAAM,QACR,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,QAAQ,CAInC,CAAC;AAoBN,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,eAAO,MAAM,aAAa,OACpB,UAAU,UACN,MAAM,QACR,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,QAAQ,CAsBhD,CAAC;AAoCJ,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;oGACgG;IAChG,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC5C;AAED,eAAO,MAAM,cAAc,OACrB,UAAU,UACN,MAAM,QACR,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,QAAQ,CA2CjD,CAAC;AAEJ;;;;;+CAK+C;AAC/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED,eAAO,MAAM,UAAU,OACjB,UAAU,UACN,MAAM,QACR,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CASjC,CAAC"}

package/dist/postgres/grants-refuse.d.ts

@@ -0,0 +1,25 @@
+import { type DeclaredGrants } from './grants-declare.ts';
+/** 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;
+};
+export declare const declarationRefusal: (declared: DeclaredGrants) => DeclarationRefusal | 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 declare const grantsNamesRefusal: (declared: DeclaredGrants) => {
+    readonly name: string;
+    readonly byteLength: number;
+    readonly limit: number;
+} | undefined;
+//# sourceMappingURL=grants-refuse.d.ts.map

package/dist/postgres/grants-refuse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants-refuse.d.ts","sourceRoot":"","sources":["../../src/postgres/grants-refuse.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,cAAc,EAAY,MAAM,qBAAqB,CAAC;AAiBpE;;;2CAG2C;AAC3C,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAsBjF,eAAO,MAAM,kBAAkB,aAAc,cAAc,KAAG,kBAAkB,GAAG,SAuClF,CAAC;AAEF;;;6EAG6E;AAC7E,eAAO,MAAM,kBAAkB,aACnB,cAAc,KACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAcnF,CAAC"}

package/dist/postgres/grants-sql.d.ts

@@ -0,0 +1,42 @@
+/** `GRANT` on one relation. `words` are already validated lowercase declared words; a
+ * trailing `*` (WITH GRANT OPTION) becomes the option clause — the list must share one
+ * flag (see the header). */
+export declare const grantTableSql: (schema: string, table: string, role: string, words: ReadonlyArray<string>) => string;
+/** `GRANT` on one column of one relation.
+ *
+ * Each word is emitted as its own synopsis inside one statement — `GRANT select ("col"),
+ * update ("col") ON …`. A column list binds only to the privilege it follows
+ * (gram.y@REL_18_6), so a word list under ONE trailing column list parses as a table-level
+ * grant of every word but the last (which alone lands on the column) — a silent over-grant
+ * the declaration did not name. Repeating the synopsis is the one shape that puts every
+ * declared word on the column and nothing on the relation. */
+export declare const grantColumnSql: (schema: string, table: string, column: string, role: string, words: ReadonlyArray<string>) => string;
+/** `GRANT` on the schema itself (`USAGE` / `CREATE`). */
+export declare const grantSchemaSql: (schema: string, role: string, words: ReadonlyArray<string>) => string;
+/** `ALTER DEFAULT PRIVILEGES FOR ROLE <creator> IN SCHEMA <schema> GRANT … ON TABLES TO
+ * <role>` — the creator is `forRole`, the grantee is always the resource's role. */
+export declare const grantDefaultSql: (schema: string, forRole: string, role: string, words: ReadonlyArray<string>) => string;
+/** `REVOKE ALL ON <schema>.<table> FROM <role>` — the repair's first half for a drifted
+ * table. Revoking a privilege the grantee does not hold is a silent no-op on the server, so
+ * the repair's revoke is idempotent; what the server REFUSES is a revoke that would have to
+ * cascade (see the header). */
+export declare const revokeTableSql: (schema: string, table: string, role: string) => string;
+/** `REVOKE ALL (<column>) ON <schema>.<table> FROM <role>` — same reasoning as
+ * {@link revokeTableSql}. */
+export declare const revokeColumnSql: (schema: string, table: string, column: string, role: string) => string;
+/** `REVOKE ALL ON SCHEMA <schema> FROM <role>` — the repair's first half for the schema's
+ * own privileges. */
+export declare const revokeSchemaSql: (schema: string, role: string) => string;
+/** `ALTER DEFAULT PRIVILEGES FOR ROLE <creator> IN SCHEMA <schema> REVOKE ALL ON TABLES
+ * FROM <role>`. */
+export declare const revokeDefaultSql: (schema: string, forRole: string, role: string) => string;
+/** `REVOKE ALL ON SCHEMA <schema> FROM PUBLIC` — the `revokeFromPublic` half for the
+ * schema itself. PUBLIC is the bare keyword (`aclitem`'s empty grantee, acl.h@REL_18_6
+ * `ACL_ID_PUBLIC`). */
+export declare const revokePublicSchemaSql: (schema: string) => string;
+/** `REVOKE ALL ON ALL TABLES IN SCHEMA <schema> FROM PUBLIC` — the `revokeFromPublic` half
+ * for every relation in the schema, including PUBLIC's column privileges on those relations
+ * (revoke.sgml@REL_18_6: revoking table privileges also revokes the corresponding column
+ * privileges). */
+export declare const revokePublicTablesSql: (schema: string) => string;
+//# sourceMappingURL=grants-sql.d.ts.map

package/dist/postgres/grants-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants-sql.d.ts","sourceRoot":"","sources":["../../src/postgres/grants-sql.ts"],"names":[],"mappings":"AAkDA;;4BAE4B;AAC5B,eAAO,MAAM,aAAa,WAChB,MAAM,SACP,MAAM,QACP,MAAM,SACL,aAAa,CAAC,MAAM,CAAC,KAC3B,MAGF,CAAC;AAEF;;;;;;;8DAO8D;AAC9D,eAAO,MAAM,cAAc,WACjB,MAAM,SACP,MAAM,UACL,MAAM,QACR,MAAM,SACL,aAAa,CAAC,MAAM,CAAC,KAC3B,MAIF,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,cAAc,WACjB,MAAM,QACR,MAAM,SACL,aAAa,CAAC,MAAM,CAAC,KAC3B,MAGF,CAAC;AAEF;oFACoF;AACpF,eAAO,MAAM,eAAe,WAClB,MAAM,WACL,MAAM,QACT,MAAM,SACL,aAAa,CAAC,MAAM,CAAC,KAC3B,MAGF,CAAC;AAEF;;;+BAG+B;AAC/B,eAAO,MAAM,cAAc,WAAY,MAAM,SAAS,MAAM,QAAQ,MAAM,KAAG,MACQ,CAAC;AAEtF;6BAC6B;AAC7B,eAAO,MAAM,eAAe,WAClB,MAAM,SACP,MAAM,UACL,MAAM,QACR,MAAM,KACX,MAC0G,CAAC;AAE9G;qBACqB;AACrB,eAAO,MAAM,eAAe,WAAY,MAAM,QAAQ,MAAM,KAAG,MACQ,CAAC;AAExE;mBACmB;AACnB,eAAO,MAAM,gBAAgB,WAAY,MAAM,WAAW,MAAM,QAAQ,MAAM,KAAG,MACyD,CAAC;AAE3I;;uBAEuB;AACvB,eAAO,MAAM,qBAAqB,WAAY,MAAM,KAAG,MACG,CAAC;AAE3D;;;kBAGkB;AAClB,eAAO,MAAM,qBAAqB,WAAY,MAAM,KAAG,MACiB,CAAC"}

package/dist/postgres/grants-words.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The vocabulary primitives of `Postgres.Grants`: the aclexplode row as it crosses the
+ * wire, the word it encodes, the word set a read answers — and the `relkind` vocabulary
+ * the PUBLIC-tables clear is scoped to. Pure — no client, no `Effect` — so the reads
+ * (`grants-read.ts`), the plans (`grants-plan.ts`, `grants-diff.ts`) and the test fake
+ * (`fake-grants-read.ts`) all share one definition of what a word is.
+ */
+/** One aclexplode row as it crosses the wire: lowercase declared word with `*` appended
+ * when the privilege carries WITH GRANT OPTION (`is_grantable`). */
+export interface AclRow {
+    readonly public: boolean;
+    readonly privilege: string;
+    readonly grantable: boolean;
+}
+/** Lowercase word, `*` appended when the privilege carries WITH GRANT OPTION. */
+export declare const encodeWord: (row: {
+    readonly privilege: string;
+    readonly grantable: boolean;
+}) => string;
+/** Union of one grantee's distinct words over all its aclexplode rows, sorted — two reads
+ * of the same state must compare equal, which the re-run-is-a-no-op rule needs. */
+export declare const wordsOf: (rows: ReadonlyArray<AclRow>, wantPublic: boolean) => ReadonlyArray<string>;
+/** The relkinds `GRANT/REVOKE … ON ALL TABLES IN SCHEMA` covers — every pg_class relation
+ * class except sequences (`S`), composite types (`c`) and indexes (`i`), per
+ * `revoke.sgml@REL_18_6` ("ALL TABLES also affects views and foreign tables") and measured
+ * on PG 18.6. */
+export declare const PUBLIC_REVOCABLE_RELKINDS: ReadonlyArray<string>;
+export declare const relkindIsPublicRevocable: (relkind: string) => boolean;
+//# sourceMappingURL=grants-words.d.ts.map

package/dist/postgres/grants-words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants-words.d.ts","sourceRoot":"","sources":["../../src/postgres/grants-words.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;oEACoE;AACpE,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,iFAAiF;AACjF,eAAO,MAAM,UAAU,QAAS;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B,KAAG,MAAqE,CAAC;AAE1E;mFACmF;AACnF,eAAO,MAAM,OAAO,SAAU,aAAa,CAAC,MAAM,CAAC,cAAc,OAAO,KAAG,aAAa,CAAC,MAAM,CACT,CAAC;AAEvF;;;iBAGiB;AACjB,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,MAAM,CAA6B,CAAC;AAE1F,eAAO,MAAM,wBAAwB,YAAa,MAAM,KAAG,OACd,CAAC"}

package/dist/postgres/grants.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `Postgres.Grants` — one declarative grant set for one role in one schema of one database:
+ * schema USAGE/CREATE, per-table privileges, per-column privileges, default privileges for
+ * future tables per creator role, and an optional clear of PUBLIC. Computed as a diff
+ * against the catalogs (`grants-read.ts`, through `aclexplode`), so a re-run with nothing
+ * changed emits nothing, and drift on any NAMED object is repaired. The lifecycle cores
+ * against any client live in `grants-ops.ts`; the refusals in `grants-refuse.ts`; the
+ * repair plans in `grants-plan.ts` and the offline diff in `grants-diff.ts`.
+ *
+ * ★ A GRANT SET CARRIES NO OWNERSHIP MARK (H1, same as `Postgres.Database`): `read` answers
+ *   `Unowned` for a match, so already-live grants need `adopt(true)` in the stack that
+ *   declares them. A target that holds NOTHING anywhere reads as ABSENT — that is a first
+ *   create, never an adoption of an empty schema.
+ * ★ OBJECTS THE DECLARED ROLE OWNS ARE LEFT ALONE (H2): the owner holds every privilege
+ *   implicitly and a `REVOKE` cannot take that away, so the repair and the delete skip
+ *   objects the catalogs say the role owns (grants-plan.ts, measured on PG 18.6).
+ * ⛔ SCOPE IS EXACTLY THE DECLARATION. Objects the declaration does not name are never
+ *   touched; removing an entry from the declaration is a DRIFT the reconcile repairs — the
+ *   removed names are revoked before the new declaration's plan runs, so taking an entry
+ *   away takes the privilege away. `delete` revokes what the LAST declaration named. PUBLIC
+ *   is only ever cleared, only when `revokeFromPublic: true`, and never re-granted.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import type { PostgresGrantsAttributes, PostgresGrantsProps } from './grants-attrs.ts';
+import type { PostgresConnection } from './connection.ts';
+export interface PostgresGrants extends Resource<'Postgres.Grants', PostgresGrantsProps, PostgresGrantsAttributes, never, PostgresConnection> {
+}
+export declare const PostgresGrants: import("alchemy").ResourceClass<PostgresGrants>;
+/** Same dual `typeof` guard as `isPostgresDatabase` (see `database.ts` for the measured
+ * regression it exists to prevent). */
+export declare const isPostgresGrants: (value: unknown) => value is PostgresGrants;
+/** The five lifecycle handlers. Exported on its own so a test drives the real implementation
+ * (see `database.ts` for why that matters). */
+export declare const postgresGrantsHandlers: Provider.ProviderService<PostgresGrants, PostgresConnection, never, never, PostgresConnection, PostgresConnection, never, never, never>;
+export declare const PostgresGrantsProvider: () => import("effect/Layer").Layer<Provider.Provider<PostgresGrants>, never, PostgresConnection>;
+//# sourceMappingURL=grants.d.ts.map

package/dist/postgres/grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../../src/postgres/grants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAQvF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAK1D,MAAM,WAAW,cAAe,SAAQ,QAAQ,CAC9C,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,EACL,kBAAkB,CACnB;CAAG;AAEJ,eAAO,MAAM,cAAc,iDAEzB,CAAC;AAEH;uCACuC;AACvC,eAAO,MAAM,gBAAgB,UAAW,OAAO,KAAG,KAAK,IAAI,cAGD,CAAC;AAE3D;+CAC+C;AAC/C,eAAO,MAAM,sBAAsB,yIA8CjC,CAAC;AAEH,eAAO,MAAM,sBAAsB,kGACuB,CAAC"}

package/dist/postgres/index.d.ts

@@ -1,9 +1,13 @@
 /**
- * PostgreSQL providers for Alchemy — `Postgres.Database`, create-and-assert over a self-hosted
- * cluster, walked against PostgreSQL 18.6. See `docs/postgres.md`.
+ * PostgreSQL providers for Alchemy — `Postgres.Database` (create-and-assert over one
+ * self-hosted cluster), `Postgres.Schema` (create-and-assert over one schema inside one),
+ * `Postgres.Role` (create / adopt / alter / drop of a LOGIN or NOLOGIN role whose password is a
+ * reference) and `Postgres.Grants` (declarative grant set diffed against the catalogs), walked
+ * against PostgreSQL 18.6. See `docs/postgres.md`, `docs/postgres-schema.md`,
+ * `docs/postgres-role.md` and `docs/postgres-grants.md`.
  *
- * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory: `fake-sql.ts` is a
- *   test double, not something a consuming stack should import.
+ * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory: `fake-sql.ts` and
+ *   `fake-grants-sql.ts` are test doubles, not something a consuming stack should import.
  */
 export type { PostgresConnectionConfig, PostgresRunnerConfig } from './connection.ts';
 export { PostgresConnection, postgresConnection, postgresRunnerConnection, withPg, } from './connection.ts';
@@ -11,8 +15,29 @@ export type { PsqlResult, PsqlRunner } from './psql-executor.ts';
 export { inlineParams, makePsqlExecutor } from './psql-executor.ts';
 export type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
 export { POSTGRES_NAME_MAX_BYTES, nameByteRefusal, utf8ByteLength } from './database-attrs.ts';
-export { buildCreateDatabaseSql, firstDrift, isDuplicateDatabaseRace, quoteIdent, quoteStringLiteral, roleExists, selectDatabase, } from './database-sql.ts';
+export { buildCreateDatabaseSql, databaseExists, firstDrift, isDuplicateDatabaseRace, quoteIdent, quoteStringLiteral, roleExists, selectDatabase, } from './database-sql.ts';
 export { PostgresDatabase, PostgresDatabaseProvider, isPostgresDatabase } from './database.ts';
+export type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+export { normalizedComment, schemaNameByteRefusal } from './schema-attrs.ts';
+export { buildCommentSchemaSql, buildCreateSchemaSql, buildDropSchemaSql, currentDatabase, currentUser, isDependentObjectsError, schemaIsEmpty, selectSchema, } from './schema-sql.ts';
+export { PostgresSchema, PostgresSchemaProvider, diffPostgresSchema, isPostgresSchema, } from './schema.ts';
+export { PostgresSchemaCreateVanished, PostgresSchemaExistsRefused, PostgresSchemaIdentityRefused, PostgresSchemaDatabaseRefused, PostgresSchemaDeleteForeignRefused, PostgresSchemaDrift, PostgresSchemaDropNotEmptyError, PostgresSchemaNameRefused, PostgresSchemaOwnerMissing, PostgresSchemaRenameRefused, PostgresSchemaWrongDatabase, type PostgresSchemaError, } from './schema-errors.ts';
 export { PostgresDatabaseDrift, PostgresDatabaseDropRefused, PostgresDatabaseNameRefused, PostgresDatabaseOwnerMissing, PostgresDatabaseRenameRefused, type PostgresDatabaseError, } from './errors.ts';
-export { postgresProviders, postgresRunnerProviders } from './providers.ts';
+export type { PostgresGrantsAttributes, PostgresGrantsAttributesColumn, PostgresGrantsAttributesDefault, PostgresGrantsAttributesTable, PostgresGrantsColumn, PostgresGrantsDefault, PostgresGrantsProps, PostgresGrantsTable, } from './grants-attrs.ts';
+export { COLUMN_PRIVILEGES, SCHEMA_PRIVILEGES, TABLE_PRIVILEGES, grantsNameByteRefusal, letterForPrivilege, } from './grants-attrs.ts';
+export { grantColumnSql, grantDefaultSql, grantSchemaSql, grantTableSql, revokeColumnSql, revokeDefaultSql, revokePublicSchemaSql, revokePublicTablesSql, revokeSchemaSql, revokeTableSql, } from './grants-sql.ts';
+export { PostgresGrants, PostgresGrantsProvider, isPostgresGrants } from './grants.ts';
+export { PostgresGrantsDatabaseMismatch, PostgresGrantsDatabaseMissing, PostgresGrantsDuplicateObject, PostgresGrantsNameRefused, PostgresGrantsPrivilegeRefused, PostgresGrantsRepairRefused, PostgresGrantsRetargetRefused, PostgresGrantsRoleMissing, PostgresGrantsSchemaMissing, PostgresGrantsTableMissing, PostgresGrantsColumnMissing, type PostgresGrantsError, } from './grants-errors.ts';
+export type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+export { sameValidUntil, validUntilRefusal } from './role-attrs.ts';
+export { buildAlterRoleSql, buildCreateRoleSql, buildDropRoleSql, buildSetPasswordSql, scalarDrift, selectRole, } from './role-sql.ts';
+export { buildGrantMembershipSql, buildRepairMembershipSql, buildRevokeGrantorMembershipSql, membershipDrift, selectRoleMemberships, syncMemberships, unsafeMemberships, } from './role-membership-sql.ts';
+export type { MembershipRow } from './role-membership-sql.ts';
+export { PostgresRole, isPostgresRole } from './role.ts';
+export { PostgresRoleProvider } from './role-provider.ts';
+export { resolvePassword } from './role-secrets.ts';
+export type { ResolvedPassword } from './role-secrets.ts';
+export type { FromEnv } from '../secrets/write-only.ts';
+export { PostgresRoleCreateVanished, PostgresRoleIdentityRefused, PostgresRoleMembershipUnrepaired, PostgresRoleNameRefused, PostgresRoleParentMissing, PostgresRolePasswordEnvUnsetError, PostgresRolePasswordNonAsciiRefused, PostgresRolePrivilegedRefused, PostgresRoleRenameRefused, PostgresRoleValidUntilRefused, type PostgresRoleError, } from './role-errors.ts';
+export { postgresProviders, postgresRoleProviders, postgresRoleRunnerProviders, postgresRunnerProviders, } from './providers.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/postgres/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/postgres/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,MAAM,GACP,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACpE,YAAY,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EACL,sBAAsB,EACtB,UAAU,EACV,uBAAuB,EACvB,UAAU,EACV,kBAAkB,EAClB,UAAU,EACV,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,EAC7B,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/postgres/index.ts"],"names":[],"mappings":"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"}