@homeflare/alchemy 0.43.0 → 0.45.0

package/docs/litellm-tool-policy.md

@@ -0,0 +1,90 @@
+# LiteLLM — `LiteLLM.ToolPolicy`
+
+The input and output trust policy of one tool in LiteLLM's tool registry (`LiteLLM_ToolTable`,
+`POST /v1/tool/policy`). Typed calls come from `@distilled.cloud/litellm/tools`, generated from LiteLLM
+**v1.103.0**; credentials and the family's other refusals are in [litellm.md](./litellm.md).
+
+Everything marked "read" was read from the **live 1.103.0 container's source** on 2026-09-30 (no request was
+sent to a proxy). No docs page for tool policy was found (docs.litellm.ai/docs/tool_policy and
+/docs/proxy/tool_policy are both 404).
+
+## ⛔ It does nothing until the `tool_policy` guardrail is configured
+
+The rows are data. The only reader is `guardrails/guardrail_hooks/tool_policy/tool_policy_guardrail.py`, a
+guardrail the proxy's **own config** must enable (its docstring: `guardrails: - guardrail_name: "tool_policy",
+litellm_params: { guardrail: tool_policy, mode: post_call }`). Declaring a policy without it is an inert row,
+not a control.
+
+Measured 2026-09-30: `grep -c tool_policy /opt/homeflare/litellm-ct100/config.yaml` is **0**, so on the live
+CT100 proxy these rows are not enforced today. Adding the guardrail is a config change this PR does not make.
+
+## The distilled operations it uses
+
+| step  | operation (`@distilled.cloud/litellm/tools`) | route                                  |
+| ----- | -------------------------------------------- | -------------------------------------- |
+| read  | `getToolV1ToolToolNameGet`                   | `GET /v1/tool/{tool_name:path}`        |
+| write | `updateToolPolicyV1ToolPolicyPost`           | `POST /v1/tool/policy` (an **upsert**) |
+
+## Example
+
+```ts
+import { LiteLLMToolPolicy, litellmProviders } from '@homeflare/alchemy/litellm';
+
+// LiteLLM discovers tools as requests use them; a tool it has seen needs --adopt.
+export class NoShell extends LiteLLMToolPolicy('NoShell', {
+  toolName: 'estate_shell-run',
+  inputPolicy: 'blocked',
+}) {}
+
+// Only what is declared is compared and sent.
+export class Trusted extends LiteLLMToolPolicy('Trusted', {
+  toolName: 'Memos_CF-search',
+  inputPolicy: 'trusted',
+  outputPolicy: 'trusted',
+}) {}
+```
+
+Input: `untrusted` (default), `trusted` (blocked if the conversation holds output of an `untrusted` tool),
+`blocked`. Output: `untrusted` (default), `trusted` (`TOOL_POLICY_OPTIONS`, `tool_management_endpoints.py`).
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                                                          |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | `toolName`. A different name is a different row: a `replace`, create-first, the old one retained.                                                                                                             |
+| Create      | The write is an **upsert** on `tool_name` (`update_tool_policy`): a new row takes a sent field, else `untrusted`. So there is no separate create, and a tool never seen is created by it.                     |
+| Adopt       | A tool LiteLLM already discovered has a live row with no state: `Unowned`, so it needs `--adopt` (a row at the defaults is adopted the same way).                                                             |
+| Update      | Only the **declared** fields are compared and sent, and only those that differ. Declare at least one (LiteLLM answers 400 to neither).                                                                        |
+| Removal     | `defaultRemovalPolicy: 'retain'`. There is **no delete route** for a tool row or its global policy, so `delete` **resets** the managed fields that are not already `untrusted`. It re-opens a `blocked` tool. |
+| Write check | Reconcile reads back and fails (`LitellmRegistryNotConvergedError` / `…AbsentAfterWriteError`) if a declared field did not land.                                                                              |
+
+⛔ **A "not found" is not proof of absence.** `db_get_tool` (`db/tool_registry_writer.py` lines 175-189)
+catches every exception, logs it and returns `None`, which the route turns into a 404. A database error reads
+exactly like a tool that was never seen. Nothing depends on it: the write is an upsert, so a wrong "absent"
+ends in a write that succeeds, and the read back decides what the deploy reports.
+
+## Team and key overrides are not modelled
+
+`POST /v1/tool/policy` with a `team_id` or `key_hash` does not touch the tool row: it adds the tool to that
+team's or key's `object_permission.blocked_tools` (`add_tool_to_object_permission_blocked`), the same list
+`LiteLLM.Team` manages through `objectPermission.blockedTools`. Two resources writing one list would fight,
+so this resource never sends either field. Block a tool for a team on the team, and for a key on the key.
+
+## Refused before any request
+
+A blank or padded `toolName`; a name the route table answers itself (`list`, `spend`, `policy/options`,
+anything ending `/detail` or `/logs`: those routes are registered before `GET /v1/tool/{tool_name:path}`, so
+such a tool could never be read back); neither policy declared; an `inputPolicy` or `outputPolicy` outside
+the lists above (`dual_llm` exists in the type but is not an input or output value the route accepts).
+
+## Licence gating (measured)
+
+None in the routes: `tool_management_endpoints.py` and `db/tool_registry_writer.py` have no `premium_user`
+reference (`grep -ci premium`: 0 in both). The `tool_policy` guardrail module has none either (0), so whether
+a community proxy enforces it once configured is **UNVERIFIED** (nothing was run).
+
+## Unmeasured at 1.103.0
+
+No live proxy was contacted. The fake (`fake-tool-litellm.ts`) is built from the source; each choice is in its
+header. The typed fix for this tag's undeclared 404 is a distilled patch, which belongs in the distilled clone
+and is not part of this change.

package/docs/litellm-toolset.md

@@ -0,0 +1,92 @@
+# LiteLLM — `LiteLLM.Toolset`
+
+One row of LiteLLM's MCP toolset table (`/v1/mcp/toolset`): a named selection of `{ server_id, tool_name }`
+pairs a key or team can be granted instead of whole servers. Typed calls come from
+`@distilled.cloud/litellm/mcp_management`, generated from LiteLLM **v1.103.0**; credentials and the
+family's other refusals are in [litellm.md](./litellm.md).
+
+Everything marked "read" was read from the **live 1.103.0 container's source** on 2026-09-30 (no request was
+sent to a proxy). The docs page is docs.litellm.ai/docs/mcp_toolsets.
+
+## The distilled operations it uses
+
+Nothing is hand-rolled: every call is one of these, through `toolset-operations.ts`.
+
+| step   | operation (`@distilled.cloud/litellm/mcp_management`) | route                                       |
+| ------ | ----------------------------------------------------- | ------------------------------------------- |
+| list   | `fetchMcpToolsetsV1McpToolsetGet`                     | `GET /v1/mcp/toolset`                       |
+| read   | `fetchMcpToolsetV1McpToolsetToolsetIdGet`             | `GET /v1/mcp/toolset/{toolset_id}`          |
+| create | `addMcpToolsetV1McpToolsetPost`                       | `POST /v1/mcp/toolset` (201)                |
+| update | `editMcpToolsetV1McpToolsetPut`                       | `PUT /v1/mcp/toolset`                       |
+| delete | `removeMcpToolsetV1McpToolsetToolsetIdDelete`         | `DELETE /v1/mcp/toolset/{toolset_id}` (202) |
+
+## Example
+
+```ts
+import { LiteLLMToolset, litellmProviders } from '@homeflare/alchemy/litellm';
+
+export class Web extends LiteLLMToolset('Web', {
+  toolsetName: 'estate-web',
+  description: 'Search and fetch only',
+  tools: [
+    { serverId: search.serverId, toolName: 'query' }, // LiteLLM.MCPServer outputs
+    { serverId: docs.serverId, toolName: 'fetch' },
+  ],
+}) {}
+
+// A team or key is granted it by ID (not name), through its object permission:
+//   LiteLLM.Team('Estate', { objectPermission: { mcpToolsets: [Web.toolsetId] }, … })
+```
+
+Then provide `litellmProviders()` alongside the stack's other providers. A toolset is served at
+`/toolset/{toolset_name}/mcp` and as `litellm_proxy/mcp/<toolset_name>`.
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                        |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | `toolset_name` is unique (a create or rename onto a taken name is a 409). The id is a uuid the **proxy** issues (`create_mcp_toolset`); the create request has no id field. |
+| Adopt       | A live row with no state is `Unowned` and needs `--adopt`; found by name from the list. A matching row writes nothing.                                                      |
+| Rename      | An update of the same row, never a replace.                                                                                                                                 |
+| Tools       | Always compared, as a set of pairs; an adopted toolset with more is corrected. `[]` is an explicit empty selection. Required, so the declaration always says.               |
+| Description | Compared only when declared: adopting never clears text a person wrote. Blank is refused.                                                                                   |
+| Update      | Partial: absent keeps, `null` clears, **except** a `null` name or `tools`, which change nothing. So `tools` is only ever sent as a list, and only when it differs.          |
+| Removal     | `defaultRemovalPolicy: 'retain'`. Opt in with `RemovalPolicy.destroy()`. Deleting a toolset does **not** detach it: a team or key holding its id keeps a dangling grant.    |
+| Delete      | Idempotent by a real read: a failed DELETE is swallowed only when a by-id read says the row is gone. A 403 (PROXY_ADMIN only) re-raises the original error.                 |
+| Write check | Reconcile reads back **by id** and fails (`LitellmRegistryNotConvergedError` / `…AbsentAfterWriteError`) if a declared field did not land or the row is not there.          |
+
+## The list cannot prove absence, so nothing but adoption uses it
+
+⛔ Measured in the source (`toolset_db.py` lines 111-117, `mcp_management_endpoints.py`): `list_mcp_toolsets`
+wraps its query in `except Exception: … return []`, so a **database error answers an empty list with a 200**;
+and the route narrows the list to the caller's granted toolsets unless the caller is an admin. The by-id
+route reads the table (`get_mcp_toolset`, a `find_unique`) and answers 404 only for a missing row.
+
+So the list is used **only to adopt by name**, and every read of a toolset this stack already owns is by id.
+A wrong "absent" from the list can only end in a create, which a unique name turns into a 409 that fails the
+deploy (`toolset.test.ts`).
+
+## Refused before any request
+
+A blank or padded `toolsetName`; a name containing `/` (a toolset is served at `/toolset/{toolset_name}/mcp`,
+`proxy_server.py` line 19346, so that name could never be addressed; LiteLLM itself accepts one); a blank
+`description`; a `tools` that is not a list; a blank or padded `serverId` or `toolName`; the same pair twice.
+
+## Licence gating (measured)
+
+None. `mcp_management_endpoints.py` and `toolset_db.py` have no `premium_user` reference (`grep -ci premium`:
+0 in both), and the docs page makes no Enterprise statement. Writes need PROXY_ADMIN (403 otherwise).
+
+## Not modelled
+
+Nothing: the table has no other column a write reaches. What is **not validated by LiteLLM**, and so not by
+this resource: that a `serverId` exists, or that the server has a tool of that name. A dangling pair is stored
+and silently grants nothing.
+
+## Unmeasured at 1.103.0
+
+No live proxy was contacted. The fake (`fake-toolset-litellm.ts`) is built from the source; each choice is in
+its header. Not exercised: the caller-scoped narrowing of the list, and how the SDK's `{ body: unknown }`
+typing meets a real 201 with a body (the fake answers 201 and the tests pass through the real SDK decode).
+The typed fix for this tag's undeclared 404 and 409 is a distilled patch, which belongs in the distilled
+clone and is not part of this change.

package/docs/litellm.md

@@ -16,13 +16,22 @@ against the tag's committed `schema.d.ts`; NOT a live read, because the referenc
 Measured at 1.100.0 (`schema.prisma`, `pass_through_endpoints.py`, and the mini's own
 `settings.yaml` `store_model_in_db: true`):
 
-| Family                                                                                                  | Managed by this resource?                                        |
-| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| Pass-through endpoints                                                                                  | Yes — this package                                               |
-| Budgets (`/budget/*`)                                                                                   | Yes — `LiteLLM.Budget`, [litellm-budget.md](./litellm-budget.md) |
-| Models, virtual keys, teams, credentials, access groups                                                 | DB-backed, API-managed, but no kit resource yet                  |
-| `router_settings`, `litellm_settings`, `general_settings.master_key`/`database_url`/`store_model_in_db` | config-file only — read-only through the API                     |
-| A `config.yaml` pass-through entry (`is_from_config: true`)                                             | Read-only through this resource — see Refusals                   |
+| Family                                                                                                  | Managed by this resource?                                                                        |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| Pass-through endpoints                                                                                  | Yes — this package                                                                               |
+| Budgets (`/budget/*`)                                                                                   | Yes — `LiteLLM.Budget`, [litellm-budget.md](./litellm-budget.md)                                 |
+| MCP servers (`/v1/mcp/server`)                                                                          | Yes — `LiteLLM.MCPServer`, [litellm-mcp.md](./litellm-mcp.md)                                    |
+| Teams (`/team/*`)                                                                                       | Yes — `LiteLLM.Team`, [litellm-team.md](./litellm-team.md)                                       |
+| Unified access groups (`/v1/unified_access_group`)                                                      | Yes — `LiteLLM.AccessGroup`, [litellm-access-group.md](./litellm-access-group.md)                |
+| MCP toolsets (`/v1/mcp/toolset`)                                                                        | Yes — `LiteLLM.Toolset`, [litellm-toolset.md](./litellm-toolset.md)                              |
+| Guardrail policies (`/policies`)                                                                        | Yes — `LiteLLM.Policy`, [litellm-policy.md](./litellm-policy.md)                                 |
+| Policy attachments (`/policies/attachments`)                                                            | Yes — `LiteLLM.PolicyAttachment`, [litellm-policy-attachment.md](./litellm-policy-attachment.md) |
+| Tool policies (`/v1/tool/policy`)                                                                       | Yes — `LiteLLM.ToolPolicy`, [litellm-tool-policy.md](./litellm-tool-policy.md)                   |
+| Virtual keys (`/key/*`)                                                                                 | Yes — `LiteLLM.Key`, [litellm-key.md](./litellm-key.md)                                          |
+| Models (`/model/*`)                                                                                     | Yes — `LiteLLM.Model`, [litellm-model.md](./litellm-model.md)                                    |
+| Credentials (`/credentials/*`)                                                                          | Yes — `LiteLLM.Credential`, [litellm-credential.md](./litellm-credential.md)                     |
+| `router_settings`, `litellm_settings`, `general_settings.master_key`/`database_url`/`store_model_in_db` | config-file only — read-only through the API                                                     |
+| A `config.yaml` pass-through entry (`is_from_config: true`)                                             | Read-only through this resource — see Refusals                                                   |
 
 ## Credentials
 
@@ -123,8 +132,6 @@ export class AiGateway extends LiteLLMPassThroughEndpoint('AiGateway', {
 
 ## Not covered
 
-- **Models, virtual keys, teams, credentials, access groups.** DB-backed and API-managed at
-  1.100.0, but no kit resource yet — deferred; see the unit's own trigger notes.
 - **The Claude OAuth model/key/team slice.** Needs estate answers only Tim can give.
 - **Runtime behaviour of a route forced into the schema for the dashboard.** The byte-identical
   cross-check proves the REQUEST/RESPONSE BODY SHAPES match the tag exactly. It does not prove

package/docs/peers.md

@@ -16,16 +16,25 @@ Effect's `rc` line is not semver-compatible with itself. Alchemy 78's peer is
 `effect >= 4.0.0-rc.115`; an unlocked `@effect/platform-node-shared` still floats to the
 next rc and breaks at import. Pin the whole set.
 
-| what resolves                                                 | what happens                                           |
-| ------------------------------------------------------------- | ------------------------------------------------------ |
-| Alchemy 77 + `effect` → rc.115 (measured 2026-09-16)          | `TypeError: Config.string is not a function` at import |
-| `@effect/platform-node-shared` newer than the pinned `effect` | `Cannot find module 'effect/ByteSize'`                 |
-| `rolldown` → 1.2.9 via vite's `~1.2.6` (measured 2026-09-16)  | `GET …/rolldown-1.2.9.tgz - 404` at `bun add`          |
-| no `mime` (measured 2026-09-17 against Alchemy 78)            | `Cannot find package 'mime'` from cloudflare-runtime   |
+| what resolves                                                                               | what happens                                                                                             |
+| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Alchemy 77 + `effect` → rc.115 (measured 2026-09-16)                                        | `TypeError: Config.string is not a function` at import                                                   |
+| `@effect/platform-node-shared` newer than the pinned `effect`                               | `Cannot find module 'effect/ByteSize'`                                                                   |
+| `rolldown` → 1.2.9 via vite's `~1.2.6` (measured 2026-09-16)                                | `GET …/rolldown-1.2.9.tgz - 404` at `bun add`                                                            |
+| no `mime` (measured 2026-09-17 against Alchemy 78)                                          | `Cannot find package 'mime'` from cloudflare-runtime                                                     |
+| `redis` → 6.3.0 via the `>=5.0.0 <7.0.0` peer of platform-node/sql-pg (measured 2026-09-30) | `No version matching "6.3.0" found for specifier "@redis/time-series" (but package exists)` at `bun add` |
 
 Alchemy 78 adapted to rc.115 — that first row is why we used to pin 112, not a reason to
 stay there. The override is still the only thing that holds the set together.
 
+⛔ **`redis` (added 2026-09-30) is exact in `overrides` for the same class of gap.**
+`redis@6.3.0` hit npm at 11:03Z minutes before its own exact dependency
+`@redis/time-series@6.3.0` was published, so a lockfile-less install floating the
+`>=5.0.0 <7.0.0` peer of `@effect/platform-node`/`@effect/sql-pg` to the dist-tag latest
+failed outright for that window. The line completed the same hour — every `@redis/*`
+sub-package published at 6.3.0 (measured 11:12:19Z) — and the pin moved onto that complete
+set. The pin stays exact because the same class of gap can recur with any future redis minor.
+
 ⚠️ `@effect/platform-node` is **required, not optional**: Alchemy's module graph reaches
 `Cloudflare/Workers/WorkerBridge → @effect/platform-node/NodeServices` even when you only
 import the Proxmox subpath.

package/docs/postgres-grants-example.md

@@ -0,0 +1,55 @@
+# PostgreSQL grants — the per-seat worked example
+
+<!-- Split out of `postgres-grants.md` (2026-09-30) so both pages stay under the
+     200-line doc cap: that page keeps the semantics, this one keeps the example. -->
+
+## The per-seat shape (the example this family exists for)
+
+One seat, one group role, one schema it owns the keys to, and read-only sight of the
+shared ledger. The family connection may point at a maintenance database; each
+resource opens its `database` (`agents` below) and proves `current_database()` before
+writing. The write half is OWNERSHIP, not ACL rows: the operator creates the
+schema (and its tables) with the seat as owner, so the seat holds `CREATE` on the
+schema and every privilege on its own tables implicitly — this resource recognizes
+the catalogs' ownership facts (`pg_namespace.nspowner`, `pg_class.relowner`), records
+them in state (`schemaOwnedByRole`, `ownedTables`), and issues nothing for those
+objects. What the seat needs ACL rows FOR is other people's objects:
+
+```ts
+import { PostgresGrants, postgresProviders } from '@homeflare/alchemy/postgres';
+
+// …provide `postgresProviders(config)` alongside the stack's other providers.
+
+// The seat's own schema: the declarations below state the intent, and ownership
+// satisfies them — the repair and the delete skip the owned schema and `notes`
+// entirely (measured on PG 18.6: a REVOKE on them would strip the recorded ACL
+// entries to `{}` while the rights continue, converging on nothing). PUBLIC's
+// defaults are PUBLIC's, so the clear still runs:
+class SeatClaude2Own extends PostgresGrants('grants/seat-claude2-own', {
+  role: 'seat_claude2', // NOLOGIN group role, membership owned by a human
+  database: 'agents', // the CT100 agents database this grant set lives in
+  schema: 'claude2', // the seat's OWN schema — ownership carries the rights
+  schemaUsage: true,
+  schemaCreate: true,
+  tables: [{ table: 'notes', privileges: ['select', 'insert', 'update', 'delete'] }],
+  revokeFromPublic: true, // nothing in the seat's schema is world-readable
+}) {}
+
+// Select-only sight of the shared ledger, granted where it lives (the `ledger` schema
+// in the same database, FORCE RLS'd at the table — this resource only writes ACL rows):
+class SeatClaude2LedgerRead extends PostgresGrants('grants/seat-claude2-ledger-read', {
+  role: 'seat_claude2',
+  database: 'agents',
+  schema: 'ledger',
+  schemaUsage: true,
+  schemaCreate: false,
+  tables: [{ table: 'events', privileges: ['select'] }],
+  revokeFromPublic: false, // PUBLIC's ledger defaults are the ledger stack's call
+}) {}
+```
+
+The seat group role can write its own `claude2` schema (it owns the schema and its
+tables — `SeatClaude2Own` records that in state) and only SELECT from the shared
+ledger view. Column-level grants work the same way when a role must see one column of
+a wide table — the estate read role `hf_agent`'s column-level SELECT on
+`LiteLLM_SpendLogs` is the estate's own example.

package/docs/postgres-grants.md

@@ -0,0 +1,157 @@
+# PostgreSQL grants — `@homeflare/alchemy/postgres` `Postgres.Grants`
+
+One declarative grant set: one role, one schema, in one database of a cluster you run
+yourself. Schema `USAGE`/`CREATE`, per-table privileges, per-column privileges, default
+privileges for future tables per creator role, and an optional clear of PUBLIC — nothing
+else. Walked against PostgreSQL 18.6 (`REL_18_6`, commit `724edf9b`); every vocabulary
+and statement shape is pinned by committed fixtures in
+`src/postgres/fixtures/` (`grants-provenance.test.ts`, `grants-acl.test.ts`).
+
+## Why the kit builds this
+
+The seat-wiring spec (landscape `docs/plans/2026-09-29-seat-wiring-spec.md`, B12) needs
+one resource that states, in one place, what a seat's group role may do in Postgres —
+today that is `bash` run by hand, unversioned and unreviewable. Upstream
+`alchemy@2.0.0-beta.79` has no self-hosted Postgres grant resource (only vendor-API
+Postgres), and no `@distilled.cloud/postgres` package exists (registry 404, checked
+2026-09-23). This family rides the same runner transport `Postgres.Database` shipped
+in kit#324: same `withPg` pooled socket path, same `postgresRunnerProviders` psql
+transport — only the statements differ.
+
+## Scope
+
+`Postgres.Grants` writes ACL rows and nothing else. What that means operationally:
+
+- **Objects are containers that already exist.** The grantee role (and every
+  default-privileges `forRole`) must be in `pg_roles`, and the schema in `pg_namespace`
+  (`PostgresGrantsRoleMissing` / `PostgresGrantsSchemaMissing` otherwise). Roles come
+  from the operator or a future role resource; this family creates nothing.
+- **Only the three table-class vocabularies are expressible.** Schema grants are
+  `USAGE`/`CREATE` (`ACL_ALL_RIGHTS_SCHEMA`), table grants the eight relation words
+  (`ACL_ALL_RIGHTS_RELATION`), column grants the four words the synopsis' column form
+  accepts. No role membership, no ownership, no `SUPERUSER`/`CREATEROLE`/`BYPASSRLS`, no
+  sequence/function/database/type/schema-of-database grants — a word outside the
+  vocabulary is refused at plan (`PostgresGrantsPrivilegeRefused`).
+- **Objects the declared role OWNS are left alone.** An owner holds every privilege
+  implicitly — the ACL rows are not what carries those rights — and the catalogs say
+  who owns what (`pg_namespace.nspowner`, `pg_class.relowner`). The repair and the
+  delete skip owned objects entirely (measured on PG 18.6: a `REVOKE ALL` on a table
+  the declared role owns strips its recorded ACL entries to `{}` while the owner's
+  rights continue, so repairing them would only churn rows the state can never
+  converge on). The projection records the ownership facts (`schemaOwnedByRole`,
+  `ownedTables`). This resource still cannot make anyone an owner.
+- **The declared objects are the whole write surface.** Objects the declaration does
+  not name are never granted to or revoked from — and removing an entry from the
+  declaration is itself a drift: the reconcile revokes the removed names (where the
+  catalogs still show the role's words) before running the new declaration's plan, so
+  taking an entry away takes the privilege away. PUBLIC is only ever cleared, only
+  when `revokeFromPublic: true`, and never re-granted.
+- **The declared database is opened, then proved.** The family connection points at a
+  maintenance database. `read` and `delete` probe `pg_database` there first: a database
+  that does not exist is absent (`read` returns nothing; `delete` is a no-op) instead of
+  a failed connect. When it exists, the handlers open it (`withPg`'s override) and refuse
+  unless `current_database()` is that name (`PostgresGrantsDatabaseMismatch`).
+
+## Words, marks and letters
+
+A privilege is a lowercase word: `select`, `insert`, `update`, `delete`, `truncate`,
+`references`, `trigger`, `maintain` (tables); `usage`, `create` (schemas); `select`,
+`insert`, `update`, `references` (columns). A trailing `*` marks WITH GRANT OPTION for
+that word — `select*` and `select` are different states, and the repair converges on the
+declared one. The letters the server actually stores (`acl.h`'s `ACL_*_CHR` defines)
+live only in code and tests: attributes record words, so a persisted state file reads as
+what was declared. Case is meaningful in the letter map — `C` is CREATE (schemas), `c` is
+CONNECT (databases, out of scope).
+
+A declaration may not name the same table, column pair or `forRole` twice
+(`PostgresGrantsDuplicateObject`), and every name must fit `NAMEDATALEN`'s 63 UTF-8
+bytes (`PostgresGrantsNameRefused` — the server would truncate and only NOTICE).
+
+## Convergence: diff against the catalogs
+
+Live state is read through `aclexplode` — one row per granted privilege, PUBLIC at
+grantee oid zero — never by parsing `aclitem` text (`func.sgml`, committed fixture).
+Reconcile is read → plan → execute → re-read → re-plan; an empty second plan is the
+proof the repair landed (`PostgresGrantsRepairRefused` carries the surviving statements
+when it did not — typically a grant made by a third grantor, which only that grantor or
+the object's owner can revoke). A destroy runs the same proof after its revokes: a grant
+the resource cannot revoke fails the delete loud with the same refusal instead of leaving
+the grantee holding privileges a delete claimed to take away.
+
+- **Re-run with nothing changed writes nothing.** Every class whose live set already
+  equals the declaration contributes no statement.
+- **Drift is repaired per class:** `REVOKE ALL` (clears extras and grant options), then
+  `GRANT` the declared words — split into one plain grant and one
+  `WITH GRANT OPTION` grant when the declaration mixes the two, because one option
+  clause would grant the option to every listed privilege.
+- **A multi-word column grant repeats the synopsis per word:** `GRANT select ("col"),
+update ("col")` — one trailing column list binds only to the privilege it follows
+  (gram.y@REL_18_6), so `GRANT select, update ("col")` would be a table-level grant of
+  every word but the last; each word carries its own list, which puts all of them on the
+  column and nothing on the relation.
+- **A table revoke re-grants the column entries it clears, in the same pass:** the
+  server's table-level `REVOKE ALL` also clears that grantee's column privileges
+  (revoke.sgml@REL_18_6) — including when the table is removed from the declaration.
+  Only entries the revoking role or the table's owner made are re-granted; a third
+  grantor's entry survives the revoke and is left as it was. Declared columns are
+  granted again after the revoke. One pass converges.
+- **Default privileges are per creator role:** `ALTER DEFAULT PRIVILEGES FOR ROLE …
+IN SCHEMA … GRANT … ON TABLES`, for future tables only (`defaclobjtype = 'r'`). A
+  `forRole` is never inferred; every entry names the role whose future objects get the
+  privileges.
+- **PUBLIC clearing is one-directional and schema-wide:** `revokeFromPublic: true` adds
+  `REVOKE ALL ON SCHEMA … FROM PUBLIC` and `REVOKE ALL ON ALL TABLES IN SCHEMA … FROM
+PUBLIC` when live reads still show PUBLIC holding something. That tables statement
+  clears PUBLIC on every table in the schema, including tables the declaration does not
+  name (and their column privileges — revoke.sgml@REL_18_6). Live PUBLIC privileges with
+  the flag off are never drift; the attributes record the one-directional fact
+  (`publicSchemaRevoked`, `publicTablesRevoked`).
+- **The repair's writes are one transaction.** Removal revokes and the new declaration's
+  grants are planned against one read and run in one `BEGIN`…`COMMIT` (`pg.transaction`):
+  one reserved connection on the socket, one `psql` script on the runner. A live grantee
+  does not observe the gap between a `REVOKE ALL` and the grants that restore it. The
+  convergence re-read runs after that commit.
+
+The diff is offline against persisted attributes (no live connection at plan time),
+so it answers `update` or `noop` and never previews live drift by itself; the exact
+GRANT/REVOKE statements appear at apply, and `alchemy drift` is the path that
+re-reads the live catalogs.
+
+`read` answers `Unowned` (a grant set carries no ownership mark) — a stack declaring
+already-live grants needs `adopt(true)`. With no stored output, an all-empty read is
+`undefined` too: that is a first create, never the adoption of an empty schema (H1 —
+only grants mark a target as live). When the resource already has applied state, the
+same all-empty read is a real projection: the grantee may own everything outright, so
+`aclexplode` has no rows to report, and answering `undefined` there would flip the next
+apply into a first create. Retargeting `role`, `database` or `schema` is
+refused at plan (`PostgresGrantsRetargetRefused`): those three name what the grant set
+is about, so a new target is a new logical id.
+
+## Delete
+
+`defaultRemovalPolicy` is `retain` — most grant sets manage adopted, already-live
+grants, and a destroy is a deliberate act. A `delete` revokes exactly what the last
+declaration named, via the same repair plan with every word list emptied: one
+`REVOKE ALL` per named object where the catalogs still show the role's words, nothing
+for PUBLIC, nothing for objects the declaration never named, nothing for objects the
+declared role owns (an owner's implicit rights are not this resource's to revoke),
+never `CASCADE` (a revoke whose grantee re-granted onward surfaces as the server's own
+`2BP01`), a missing database (probed on the family connection), grantee or schema means
+there is nothing left to revoke and the delete is a no-op, and the delete proves its
+revokes landed the same way `reconcile`
+does — re-read, re-plan, refuse with `PostgresGrantsRepairRefused` when a grant the
+resource cannot revoke (a third grantor's, say) survives the pass.
+
+## The per-seat shape (the example this family exists for)
+
+The worked example — one seat, one group role, its own schema, read-only sight of the
+shared ledger — lives in [`postgres-grants-example.md`](./postgres-grants-example.md).
+
+## Not covered
+
+Sequences, functions, databases, large objects and types are out of scope by name
+(each with its synopsis reason, asserted in `grants-provenance.test.ts`); `Postgres.Role`
+and `Postgres.Schema` do not exist yet, so the grantee role and the schema must come
+from the operator; RLS policies are table structure, not ACL rows, so they belong to the
+schema/table family and to migrations — `FORCE RLS` is declared where the ledger table
+is created, never here.

package/docs/postgres-role.md

@@ -0,0 +1,126 @@
+# `Postgres.Role` — `@homeflare/alchemy/postgres`: create / adopt / alter / drop of a LOGIN or NOLOGIN role on a self-hosted PostgreSQL 18.6 cluster, walked against `REL_18_6` (commit `724edf9b`).
+
+## Why the kit builds this instead of using upstream
+
+Upstream `alchemy@2.0.0-beta.79` ships no role resource for a self-hosted cluster. Its only
+`PostgresRole` is `Planetscale/Postgres/PostgresRole.ts`, built on the `@distilled.cloud/planetscale`
+SDK and its `Credentials` — a vendor-API row that cannot `CREATE ROLE` against the cluster you
+run yourself. The `Postgres.Database` resource in this kit already binds `@effect/sql-pg`'s
+`PgClient` over the same transports; `Postgres.Role` reuses that client and the runner
+(`psql-executor.ts`), so it stays host-independent and portable to CT100's own Postgres.
+
+## Locked shape
+
+- **Alter-capable, unlike `Postgres.Database`.** `LOGIN`/`NOLOGIN`, `INHERIT`/`NOINHERIT`,
+  `CONNECTION LIMIT`, and `VALID UNTIL` each have a safe atomic `ALTER ROLE` form, so a drifted
+  live row is brought back to the declaration, never refused. A rename is still refused
+  (`PostgresRoleRenameRefused`); `diff` answers `update` or `noop`, never `replace`.
+- **The password is a reference, never a value.** Declared as `{ fromEnv: 'PG_SEAT_WIDGET_PASSWORD' }`.
+  The variable name lands in state; the value is resolved from the deploying process's environment
+  at reconcile time, held as `Redacted`, and sent only as a client-side SCRAM-SHA-256 verifier
+  (`SCRAM-SHA-256$4096:<salt>$<StoredKey>:<ServerKey>`, the form `psql \password` sends, which
+  PostgreSQL stores as-is) inside the one `ALTER ROLE … PASSWORD` statement — so the statement
+  text that reaches Effect's SQL span, `pg_stat_statements` and a failed `ALTER`'s server log never
+  holds the plain value. State remembers only a `scrypt:<salt>:<digest>` seal, so a reconcile
+  re-sends the secret only when the environment value differs from the one last written — a plan
+  never re-sends a secret that already matches, and never stores one. A create that declares a
+  password but whose variable is unset refuses before any write
+  (`PostgresRolePasswordEnvUnsetError`), including the retry of a create whose password statement
+  never sealed. Non-ASCII passwords fail typed before writes (`PostgresRolePasswordNonAsciiRefused`):
+  PostgreSQL applies SASLprep, and this provider does not implement that normalization.
+- **Membership is `pg_auth_members`, compared as a sorted set.** `memberOf` omitted leaves live
+  memberships alone; `[]` ensures none. Moves run through one-parent `GRANT`/`REVOKE`
+  (`alter_role.sgml`: "there are no options for adding or removing memberships; use GRANT and
+  REVOKE"). A plain `REVOKE` only removes the session grantor's row (`plan_single_revoke` matches
+  `grantor`); each unwanted row is `REVOKE … GRANTED BY` its own grantor. A wanted row that is
+  `WITH ADMIN`, still `SET TRUE`, or `INHERIT TRUE` when `inherit:false` is declared is repaired
+  with `REVOKE ADMIN/SET/INHERIT OPTION FOR … GRANTED BY … RESTRICT`. Unwanted-row revokes commit
+  first, then each retained row's options share a repair transaction. SQLSTATE 2BP01/42501 becomes
+  `PostgresRoleMembershipUnrepaired` naming that parent and grantor, preserving refused options
+  and dependent rows without rolling back unwanted-row revokes. No CASCADE is issued.
+  Option repair was measured once by hand on a throwaway PostgreSQL 17.11 (2026-10-02);
+  automated tests stub the 2BP01/42501 responses. Semantics: PostgreSQL
+  [16 GRANT](https://www.postgresql.org/docs/16/sql-grant.html) / [REVOKE](https://www.postgresql.org/docs/16/sql-revoke.html),
+  [17 GRANT](https://www.postgresql.org/docs/17/sql-grant.html) / [REVOKE](https://www.postgresql.org/docs/17/sql-revoke.html),
+  [18 GRANT](https://www.postgresql.org/docs/18/sql-grant.html) / [REVOKE](https://www.postgresql.org/docs/18/sql-revoke.html).
+  `buildRepairMembershipSql` now requires the grantor and option (`ADMIN`, `SET` or `INHERIT`).
+  A null grantor is a defensive inconsistent-catalog case, not an ordinary DROP ROLE outcome,
+  and fails `PostgresRoleMembershipUnrepaired`. A missing parent fails
+  `PostgresRoleParentMissing` before any statement.
+- **`defaultRemovalPolicy: 'retain'`.** A seat group role may own objects and be granted across
+  databases. A destroy is still implemented in full (`DROP ROLE IF EXISTS`, idempotent), opted in
+  with `.pipe(RemovalPolicy.destroy())`. A role that still owns objects fails the drop with the
+  server's own `2BP01` (`dependent_objects_still_exist`; class `2B` is `2B000`), surfaced as the
+  client's `SqlError`. An adopt or alter that finds `SUPERUSER`, `CREATEROLE`, `CREATEDB`,
+  `REPLICATION` or `BYPASSRLS` set refuses (`PostgresRolePrivilegedRefused`) before any write:
+  those flags are not inherited, and `SET ROLE` to the parent exercises them. A seat `GRANT`
+  says `WITH SET FALSE`. Create runs `CREATE`, the password `ALTER` and the seat `GRANT`s in one
+  transaction, so a later statement failure does not leave a LOGIN role behind. `diff` reads
+  `pg_auth_members` live — stored attributes omit the option rows, and the engine passes stored
+  attributes — so unsafe `ADMIN`, `SET` or `INHERIT` plans as `update`. Privileged catalog flags also plan
+  `update`, reaching the typed reconcile refusal. `read` omits membership option rows just as
+  reconcile does, so an unchanged role does not report structural drift. A live oid that is not the stored oid
+  is `PostgresRoleIdentityRefused` on read, diff, reconcile and delete: the name was recreated
+  out of band and is not dropped or altered.
+
+## Props → `CREATE ROLE` / `ALTER ROLE` → catalog mapping
+
+`role-provenance.test.ts` proves this against the committed fixtures
+(`create_role.sgml`, `alter_role.sgml`, `pg_authid.h`, `pg_auth_members.h`).
+
+| prop              | `CREATE ROLE` / `ALTER ROLE` option          | catalog column                       |
+| ----------------- | -------------------------------------------- | ------------------------------------ |
+| `name`            | role name (identifier)                       | `pg_roles.rolname`                   |
+| `login`           | `LOGIN` / `NOLOGIN`                          | `pg_roles.rolcanlogin`               |
+| `inherit`         | `INHERIT` / `NOINHERIT`                      | `pg_roles.rolinherit`                |
+| `connectionLimit` | `CONNECTION LIMIT n` (`-1` unlimited)        | `pg_roles.rolconnlimit`              |
+| `validUntil`      | `VALID UNTIL 'timestamp'`                    | `pg_roles.rolvaliduntil`             |
+| `memberOf`        | `GRANT parent TO member`                     | `pg_auth_members.member` / `roleid`  |
+| `password`        | `PASSWORD '…'` (via `ALTER ROLE`, reference) | `pg_authid.rolpassword` (never read) |
+
+`login` and `inherit` are required: the resource configures a LOGIN or NOLOGIN role with INHERIT
+explicit, per the seat-wiring spec's group-role-per-seat shape (NOLOGIN, member of `hf_agent`,
+owning its own schema).
+
+## Identifier quoting and literals
+
+`CREATE ROLE`/`ALTER ROLE` take no bind parameters; every value is an inlined, hand-quoted
+literal. The role `name` is a `ColId` (one token), so `quoteIdent` quotes and doubles an embedded
+`"` — unlike `Effect`'s `sql(value)`, which would rewrite `"a.b"` into a two-token
+schema-qualified name and produce a syntax error. `quoteStringLiteral` wraps in `'` and doubles an
+embedded `'`, never emits a backslash.
+
+## Plan-time refusals
+
+- **Name over 63 UTF-8 bytes** (`PostgresRoleNameRefused`): `NAMEDATALEN` 64, so 63 bytes is the
+  last name that survives whole. `truncate_identifier` clips at 63 bytes and emits only a NOTICE;
+  a create would succeed against the truncated name and the next plan would look for the original
+  name and find nothing, forever. Same hazard as `PostgresDatabaseNameRefused`.
+- **Zone-free `validUntil`** (`PostgresRoleValidUntilRefused`): PostgreSQL reads `VALID UNTIL
+'2027-01-01'` as midnight in the session's time zone; the deploying process parses the same
+  string as UTC. The instants differ, so the value read back would never equal the declaration and
+  every plan would re-issue the same `ALTER`. A string ECMAScript cannot parse reaches the same
+  refusal; PostgreSQL would reject it too, only later and as an unclassified statement error.
+  Declare an ISO 8601 string carrying `Z` (or a numeric offset).
+- **Rename** (`PostgresRoleRenameRefused`): the declared name differs from the live row's name.
+
+## Reading back (`S10`)
+
+Every write is re-read. The seal is state-only (`pg_roles` answers no password), so the last
+written seal rides back into the attributes the engine compares and stores, `diff` reads the
+environment in-process and answers `update` when the resolved value no longer matches it, and
+`reconcile` compares against that state seal — never against a cluster read. `validUntil` is
+serialised server-side to `...Z`; comparison uses `Date.parse` on both sides, so millisecond
+`.000Z` churn is equality, not drift. A create whose re-read answers `undefined` fails typed
+(`PostgresRoleCreateVanished`). A `creating` row with no attributes is `noteUnfinished` in `diff`,
+and `read` answers the live role as ours only when `ownedRead` can prove it matches that row
+(`PostgresRoleParentMissing` and the create transaction are what keep a failed `GRANT` from
+needing that recovery).
+
+## Providers
+
+- `postgresRoleProviders({ host, database, username })` — the socket transport, same cluster
+  parameter shape as `postgresProviders`. The cluster is a parameter, never a default.
+- `postgresRoleRunnerProviders({ run, database, username })` — the same reconcile over a
+  caller-supplied `PsqlRunner` (loopback-only cluster, `ssh <host> sudo -n podman exec -i postgres
+…`).