@homeflare/alchemy 0.43.0 → 0.45.0

package/docs/postgres-schema.md

@@ -0,0 +1,139 @@
+# PostgreSQL — `Postgres.Schema`
+
+One schema inside a self-hosted PostgreSQL 18 cluster: create-and-assert over `pg_namespace`,
+walked against the same `REL_18_6` tree as `Postgres.Database` (see [postgres.md](./postgres.md)
+for the measured path and quoting rules). This is the first seat-wiring resource for the CT100
+`agents` database: each seat's group role owns a `<seat>` schema, and the shared `ledger.events`
+lives under FORCE RLS (spec §5).
+
+## The locked shape
+
+Create-and-assert only. Plain `CREATE SCHEMA` is the only create this family issues.
+There is no `ALTER SCHEMA` of any kind: Postgres's `ALTER SCHEMA` only renames or changes the
+owner, and neither is implemented — a name change is refused at plan and apply
+(`PostgresSchemaRenameRefused`), a `database` change is refused the same way
+(`PostgresSchemaDatabaseRefused`), and an owner or comment mismatch against the live row is a
+typed `PostgresSchemaDrift` refusal, the same rule `Postgres.Database` applies to its asserted
+props.
+
+## Props and mapping
+
+| prop       | `CREATE SCHEMA` / statement                    | live source                            |
+| ---------- | ---------------------------------------------- | -------------------------------------- |
+| `name`     | the schema name (single `ColId`, `quoteIdent`) | `pg_namespace.nspname`                 |
+| `database` | which database the handlers open               | `SELECT current_database()`            |
+| `owner`    | `AUTHORIZATION` clause                         | `pg_get_userbyid(nspowner)`            |
+| `comment`  | `COMMENT ON SCHEMA … IS`                       | `obj_description(oid, 'pg_namespace')` |
+
+`owner` and `comment` are the only asserted props; both are compared against the live row on
+every plan. `owner` must already exist as a role — checked with a `pg_roles` lookup before the
+`CREATE SCHEMA`, so a missing role fails with `PostgresSchemaOwnerMissing` before any write.
+An omitted `owner` is not "leave the live owner alone": a fresh `CREATE SCHEMA` without
+`AUTHORIZATION` is owned by `current_user`, so the re-read compares `live.owner` to that role
+and drifts on a mismatch. A concurrent creator is refused with
+`PostgresSchemaExistsRefused` even when its owner matches; no comment is written.
+
+## `database` (required)
+
+The schema lives in one database of the cluster, and the resource is pinned to it. The family
+connection points at a maintenance database — a brand-new database cannot be connected to on a
+cold plan ([postgres.md](./postgres.md), measured path) — so the handlers open
+`props.database` themselves: the runner transport swaps the `psql -d` target, the socket
+transport swaps the pool's `database`. The swap is proven, never trusted: every read row
+carries `current_database()`, `reconcile` and `delete` compare it against the declaration
+before any write, and a mismatch fails with `PostgresSchemaWrongDatabase` — so a seat schema
+meant for `agents` can never be created, read or dropped in the maintenance database by a
+mis-wired connection. `read` refuses with the same tag when the row's own database differs.
+
+A change of `database` is refused at plan and apply (`PostgresSchemaDatabaseRefused`): a schema is not
+moved between databases — declare a new resource instead. A schema's `database` must be the
+database it lives in, but on a cold plan that database may not exist yet. Pass it as an Output:
+`Postgres.Schema({ database: db.name, ... })` where `db` is the `Postgres.Database` resource.
+An unresolved Output makes a cold plan skip `read`'s live probe and plan a create, and Alchemy
+orders the `Database` create before the `Schema` because the declaration references it.
+Apply still checks for an existing schema: without persisted output it refuses with
+`PostgresSchemaExistsRefused`, even if the owner matches (including `public`). Re-plan with
+`--adopt` / `adopt(true)` to adopt it explicitly. An interrupted create uses this same adoption
+path; a matching owner is never proof that this stack created it. A
+literal database name (`database: 'agents'`) is safe only when the database already exists:
+`read` and `delete` treat a missing declared database as "schema absent" (they probe
+`pg_database` over the family connection first, so the untyped connect never happens), but
+`reconcile` still requires it to exist.
+
+## `name`
+
+At most 63 UTF-8 bytes (`NAMEDATALEN`), refused at plan with `PostgresSchemaNameRefused` —
+exactly the `nameByteRefusal` rule `Postgres.Database` uses, because the server would silently
+truncate past it (same `truncate_identifier` in `scansup.c`) and a later read would never find
+the schema again.
+
+## `comment`
+
+An empty string IS "no comment": Postgres stores `COMMENT ON SCHEMA … IS ''` as NULL, so
+`comment: ''` is normalized to "no comment" — no `COMMENT ON` is issued, and the declaration
+never drifts against the NULL the server stores. A comment mismatch is a drift refusal, and an
+undeclared comment leaves an existing live comment alone (the declaration asserts what it
+declares, nothing more). `COMMENT ON` is issued only after the re-read's owner has been
+asserted. A race winner is refused first, so their schema is never commented: the kit role is
+superuser, the comment would land, and the drift failure does not roll it back.
+
+## `delete` — drop only what it can prove it created
+
+Unlike `Postgres.Database` (which never drops), a schema can be dropped — but only when it is
+empty, or when `cascade: true` is declared.
+
+- Delete re-reads `pg_namespace` before any `DROP`. The engine does not re-read before a delete
+  that has state (alchemy `Apply.ts`), so `delete` receives the last asserted `oid` + `owner`
+  and nothing fresh. The handler matches the live row against that persisted proof: an absent
+  schema is idempotent success, and a live row whose `oid` or `owner` no longer matches fails
+  with `PostgresSchemaDeleteForeignRefused` — no `DROP` is issued, `CASCADE` included. This is
+  the guard for a schema dropped out of band and recreated under the same name by another
+  role, whose objects must survive the delete.
+- `cascade` defaults to `false`, so `DROP SCHEMA` refuses a non-empty schema with
+  `PostgresSchemaDropNotEmptyError`. The emptiness check is one `SELECT` over four catalogs —
+  `pg_class` (relations), `pg_proc` (functions), `pg_type` (types/enums/domains) and
+  `pg_operator` — so a schema holding only functions or enums is still refused. Whatever the
+  catalogs miss is still safe: the server's own `2BP01` dependent-objects refusal is classified
+  as the same typed tag. `2BP01` is class `2B`, so both transports wrap it as `UnknownError`
+  with the raw code on `reason.cause.code` — the classifier reads that code, not the tag.
+- With `cascade: true` the drop is `DROP SCHEMA IF EXISTS … CASCADE` and removes the schema's
+  objects too. The `IF EXISTS` makes delete idempotent.
+- A `cascade` change is a real change: it answers `update` (compared against the previous
+  declaration's persisted props), so the flipped value reaches state and the eventual drop
+  uses it — a schema first declared `cascade: true` stops dropping with CASCADE once the
+  declaration says false.
+- The `retain` default means `RemovalPolicy.destroy()` is required before any delete runs — the
+  same two-layer guard the database family documents.
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                                                                                                                                                       |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | `name` is the logical id. A changed `name` or `database` is refused at plan and apply (never `ALTER … RENAME`, never a silent move).                                                                                                                                                                       |
+| Adopt       | A schema carries no ownership mark (H1), so `read` answers `Unowned` for a match and an already-live schema needs `adopt(true)`. Apply without output refuses takeover.                                                                                                                                    |
+| Removal     | `defaultRemovalPolicy: 'retain'`; opt in with `RemovalPolicy.destroy()`. Delete re-reads before any `DROP`: absent is idempotent, and a live row whose `oid` or `owner` fails the persisted proof refuses the delete with `PostgresSchemaDeleteForeignRefused`. Drop refuses non-empty without `cascade`.  |
+| Read        | One bound `SELECT` on `pg_namespace` (name, owner, comment, `oid`, `current_database() AS database`). `undefined` when absent — and a declared database missing from `pg_database`, probed over the family connection first, counts as absent.                                                             |
+| Write check | Re-reads after `CREATE` (S10): a schema still absent after a successful create fails with `PostgresSchemaCreateVanished`; every re-read row is asserted against the declaration (an omitted `owner` against `current_user`), a duplicate CREATE (42P06) is a typed adoption refusal before any COMMENT ON. |
+
+## Not alterable, not modelled
+
+`ALTER SCHEMA`'s two operations — rename and owner change — are deliberately absent (see above).
+No other `pg_namespace` property (`nspacl` access-control list) is asserted: grants are a separate
+seat resource (`Postgres.Grants`), not part of `Postgres.Schema`. The schema's `oid` is read back
+for provenance, never declared. Read and reconcile compare the live oid to persisted output
+and fail with `PostgresSchemaIdentityRefused` if the name was recycled out of band. Reconcile
+cannot refresh away the proof that delete relies on; the oid and asserted owner persist for
+that later comparison.
+
+## PostgreSQL 18 semantics checked
+
+- [CREATE SCHEMA](https://www.postgresql.org/docs/18/sql-createschema.html): `IF NOT EXISTS`
+  does nothing even with a different owner. The provider deliberately uses plain CREATE;
+  [REL_18_6 pg_namespace.c](https://github.com/postgres/postgres/blob/REL_18_6/src/backend/catalog/pg_namespace.c)
+  raises `duplicate_schema` (42P06) for an existing name.
+- [DROP SCHEMA](https://www.postgresql.org/docs/18/sql-dropschema.html): RESTRICT is the default;
+  nonempty schemas require CASCADE. The fake preserves this refusal and seeds `public`.
+- [Escape strings](https://www.postgresql.org/docs/18/sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-ESCAPE):
+  comments and all shared literal callers emit `E'…'`, doubling backslashes and quotes, under
+  either `standard_conforming_strings` setting. Database options, Role literals, and the psql
+  executor's inlined parameters use the same escaper; Grants uses it through that executor.

package/docs/postgres.md

@@ -142,6 +142,23 @@ rule; the consuming stack's runner does.
 - `CREATE DATABASE … TEMPLATE "template0"` is the runner default (`template` overrides):
   CT100's `template1` is ParadeDB's and would copy postgis/pg_ivm/paradedb objects. The socket
   path adds no `TEMPLATE` clause, unchanged.
-- Not covered: there is no `Postgres.Role` resource in the kit yet, so the owner role must
-  exist (`PostgresDatabaseOwnerMissing` otherwise). NetBox's 11 lost triggers on `pg_restore`
-  are a restore concern, out of this resource's scope.
+- `Postgres.Role` (`docs/postgres-role.md`) manages the roles themselves — declare the owner
+  role with it before `Postgres.Database` adopts a database it owns. NetBox's 11 lost triggers
+  on `pg_restore` are a restore concern, out of this resource's scope.
+
+`Postgres.Schema` ([postgres-schema.md](./postgres-schema.md)) rides the same two transports —
+`postgresProviders` and `postgresRunnerProviders` both merge its provider alongside
+`Postgres.Database`'s, so one connection serves the family. Schema opens its own declared
+`database` on that connection (`withPg`'s database override) rather than the family's
+maintenance database, proven per statement via `current_database()`.
+
+## `Postgres.Grants` (2026-09-30)
+
+A second resource on the same runner transport: 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, optional clearing of PUBLIC — computed as a diff against
+the catalogs through `aclexplode` so a re-run with nothing changed writes nothing and drift is
+repaired. See `docs/postgres-grants.md` for the vocabulary (pinned against `acl.h` and
+`grant.sgml` at `REL_18_6`), the convergence proof, and the refusal surface; a per-seat
+worked example (the `agents` group role writes its own schema and selects only from the
+shared ledger view) lives in `docs/postgres-grants-example.md`.

package/docs/valkey-transport.md

@@ -0,0 +1,29 @@
+# Why this provider keeps its bounded RESP client
+
+Source audit: `alchemy@2.0.0-beta.79`, 2026-10-01. Upstream **does** export
+`connect(url)` and typed `Redis.CommandError`; the earlier claim that no reusable client
+existed was incomplete. The exception is the provider's bounds, not missing commands.
+
+- [`Redis/Protocol.ts:287–311`](https://github.com/alchemy-run/alchemy/blob/v2.0.0-beta.79/packages/alchemy/src/Redis/Protocol.ts#L287)
+  waits on `Queue.take` without a deadline. `connect` (lines 321–346) accepts only a URL,
+  uses an unbounded event queue and constructs its parser internally. There is no timeout or
+  byte-limit option. An Effect timeout could bound elapsed time, but cannot inspect or bound
+  allocations inside that parser before a reply completes.
+- [`Redis/Resp.ts:63–65`](https://github.com/alchemy-run/alchemy/blob/v2.0.0-beta.79/packages/alchemy/src/Redis/Resp.ts#L63)
+  caps individual bulks at 512 MiB and aggregates at 1,000,000 elements. These are real caps,
+  but not the provider's 1 MiB / 10,000 element caps. `Parser.push` (lines 563–575) appends
+  bytes before decoding, with no total reply cap.
+- [`Redis/Protocol.ts:54–64`](https://github.com/alchemy-run/alchemy/blob/v2.0.0-beta.79/packages/alchemy/src/Redis/Protocol.ts#L54)
+  builds a URL containing the password; `connect` parses that string to authenticate. The
+  provider keeps credentials separate from endpoint strings and never puts them in state.
+  A URL can be kept in memory, so this alone would not prevent adoption of the helper.
+
+Measured by `src/valkey/upstream-bounds.test.ts`: the pinned upstream parser accepts a bulk
+above 1 MiB and an array above 10,000 elements. This test needs no network listener. The
+provider's `transport-bounds.test.ts` verifies its stricter refusals and deadlines. Replacing
+it with upstream plus a post-decode size check would remove the pre-allocation protection.
+
+The exception can go away when upstream exposes configurable connect/read deadlines and
+parser/queue caps (or a bounded transport injection point). Until then `transport.ts` and
+`resp.ts` remain internal, with typed `ValkeyServerError` / `ValkeySocketError`, and one
+socket per scoped operation. This is not a general-purpose Redis client.

package/docs/valkey.md

@@ -0,0 +1,187 @@
+# Valkey — `@homeflare/alchemy/valkey`
+
+Two resources for the seat-wiring data plane (seat-wiring-spec §5), built 2026-09-29, walked
+against Valkey 8.1.10 (the image already pinned on CT100) and 9.1.1 (the scratch instance used to
+prove the ACL rules). There is no `@distilled.cloud/valkey` package (registry 404, checked
+2026-09-29). The bounded RESP client remains intentionally separate from `alchemy/Redis` at
+beta.79: upstream has no configurable deadlines or provider-sized reply caps, and its auth API
+requires a password-bearing URL. See [the source audit and executable cap evidence](./valkey-transport.md).
+
+- `Valkey.Instance` — **assert-and-read** a running server. It never creates, never reconfigures,
+  and never stops one.
+- `Valkey.AclFile` — **kit-owned instances only, without `--aclfile`**: per-instance ACL users, each limited to a key prefix and a fixed
+  command allow-list, with passwords by reference (never in state).
+
+Both are `defaultRemovalPolicy: 'retain'` and answer `Unowned` on read (H1), so a live instance and
+its ACL each need `adopt(true)` in the stack that declares them.
+
+## `Valkey.Instance`: assert, never mutate
+
+The instance itself is a container the `Podman.Container` family owns — CT100's two dormant
+Quadlets live in `homeflare-ct100/src/valkey.ts`. This resource reads `INFO` and `CONFIG GET` and
+refuses drift; it never issues `CONFIG SET` (which could drop in-flight data) and never starts a
+process. `delete` raises `ValkeyInstanceDeleteRefused` and, independently, `defaultRemovalPolicy`
+is `retain` — two reasons the engine never shuts a server down through this provider.
+
+```ts
+import { ValkeyInstance } from '@homeflare/alchemy/valkey';
+
+export class Seats extends ValkeyInstance('Seats', {
+  name: 'valkey-seats', // the Quadlet's containerName
+  port: 6381,
+  maxmemory: '512mb',
+  maxmemoryPolicy: 'noeviction',
+  appendonly: 'yes',
+}) {}
+```
+
+Asserted props are `port`, `maxmemory`, `maxmemoryPolicy`, `appendonly`; omitted props are not
+checked. `diff` reports an update on the first drift; `reconcile` re-reads and raises
+`ValkeyInstanceDrift` naming the prop. The version line (`valkey_version:` in `INFO`, not the Redis compatibility version) is read into
+attributes but never asserted.
+
+## `Valkey.AclFile`: seat users, key-prefix scoped
+
+One `Valkey.AclFile` per instance, holding the users the declaration manages. The
+header comment in `src/valkey/acl.ts` states the constraint: a shared file would let a seat user
+exist on the LiteLLM cache (`:6380`) and `litellm` on the seat store (`:6381`) — every seat could
+poison the response cache. `valkey-seats` carries the seat users; `valkey-litellm` carries the
+single `litellm` application user. Both can also carry the key-less `monitor` exporter user.
+
+Users this resource **never managed are preserved and reported** by default; `exclusive: true`
+allows their removal. Removing a previously declared user plans an update and revokes it with
+`ACL DELUSER`, including in non-exclusive mode. Attributes record the managed usernames
+separately from observed users. `default` and the connection username are always protected.
+
+```ts
+import { ValkeyAclFile } from '@homeflare/alchemy/valkey';
+
+export class SeatsAcl extends ValkeyAclFile('SeatsAcl', {
+  instance: 'valkey-seats',
+  users: {
+    claude: {
+      name: 'claude',
+      keyPrefix: 'claude:*',
+      profile: 'seat',
+      password: { fromEnv: 'VALKEY_CLAUDE_PW' },
+    },
+    grok: {
+      name: 'grok',
+      keyPrefix: 'grok:*',
+      profile: 'seat',
+      password: { fromEnv: 'VALKEY_GROK_PW' },
+    },
+  },
+}) {}
+```
+
+- **Password by reference (S25).** `password` is `{ fromEnv }`; the value exists only in the
+  deploying process's memory; SETUSER sends only `#<sha256>`. State stores a scrypt **seal** so the next plan can
+  tell whether the value changed, without holding anything a reader could send to Valkey.
+- **The key prefix is the isolation.** `~claude:*` limits a seat to its own keyspace — the
+  pattern `homeflare-ct100/src/valkey-acl.ts` already renders (`~${user}:*`) — and
+  `resetchannels` plus `&<user>:*` limits pub/sub to its own channels. A `service` defaults
+  to `&<keyPrefix>`; `channelPatterns: ['namespace:*']` declares separate channel globs
+  (without `&`), and `[]` grants none. No unconditional `allchannels` rule replaces the declared scope. A seat whose
+  `keyPrefix` is not `<name>:*` is refused before any write (`ValkeyAclSeatKeyPrefix`); `*`
+  is a `service` pattern only. Glob characters in usernames are rejected. A seat gets `WRITE` only where its job writes.
+- **Fixed command allow-list, not a prop.** A seat gets `+@read +@write` plus the data-type
+  categories, and is denied `-@dangerous -@admin` plus the keyless/admin commands
+  (`-keys -flushall -flushdb -monitor -acl -config -shutdown -debug`) and
+  `-scan -randomkey -dbsize -pubsub` (keyspace/channel enumeration). This mirrors
+  `homeflare-ct100/src/valkey-acl.ts`'s `SEAT_COMMANDS`; it is not a per-declaration surface
+  because widening it would let a seat request `FLUSHALL` or `ACL SETUSER`.
+- **Monitor profile.** `profile: 'monitor'` with no key prefix or channels matches ct100#117:
+  `-@all +ping +client|setname +info +command|info +commandlog|len +config|get`
+  `+latency|latest +latency|histogram +slowlog|get +slowlog|len`. It grants no key access,
+  pub/sub, configuration writes or ACL administration.
+- **Reconcile re-reads (S10).** After `ACL SETUSER`/`ACL DELUSER`, it reads `ACL LIST` back and
+  fails `ValkeyAclReadbackFailed` if a declared user's rules, flags or patterns disagree, or an undeclared
+  user remains under `exclusive: true`. `delete` removes every declared user (the engine runs it only when a human opts out of
+  retain); the instance is untouched.
+
+## Connection
+
+`valkeyProviders({ instance, host, port, username, password })` registers a named connection.
+Each operation selects it by `Valkey.Instance.name` or `Valkey.AclFile.instance`; a missing name
+fails with `ValkeyConnectionMissing`. The connection stays available to lifecycle handlers through
+`Layer.provideMerge`. `host`/`port` carry no secret; `password` is a `FromEnv` reference resolved at call time (a missing variable is the typed
+`ValkeyAuthPasswordMissing`, and a username without a password is unrepresentable). `withValkey`
+opens one `node:net` socket per operation and closes it after — never held across a whole
+reconcile. Connect, each read, and the socket idle timer share `timeoutMs` (default 10s); a
+reply longer than 1 MiB or an array longer than 10,000 elements fails `ValkeySocketError`.
+
+```ts
+import { valkeyProviders } from '@homeflare/alchemy/valkey';
+
+const providers = valkeyProviders({
+  instance: 'valkey-seats',
+  host: '127.0.0.1',
+  port: 6381,
+  username: 'admin',
+  password: { fromEnv: 'VALKEY_ADMIN_PW' },
+});
+```
+
+⛔ **The admin user is a prerequisite, not something this kit creates.** The connection needs
+`INFO`, `CONFIG GET`, `ACL LIST`, `ACL SETUSER` and `ACL DELUSER`. Seat/service/monitor profiles
+cannot administer ACLs. The admin is provisioned separately and skipped in every ACL read;
+declaring its name or `default` raises `ValkeyAclReservedUser` before writes. Wrong AUTH,
+missing credentials, protocol and connection failures propagate as typed failures from `read`;
+none means “not found” or permits the engine to skip adoption.
+
+## Source of truth and drift
+
+**Configured ACL file ⇒ unsupported by `Valkey.AclFile`.** Before reconcile or delete, `CONFIG GET aclfile`
+is checked. Any non-empty path raises `ValkeyAclFileRendered` before mutation. RESP cannot
+reliably distinguish a writable file from a read-only mount or a competing renderer, so this
+conservative gate refuses **all** configured files. This includes CT100's read-only OpenBao
+files: add users to that rendering template, then use its ACL LOAD/restart workflow. Adding an
+admin does not bypass the gate. Adoption is also refused: beta.79 `Plan.ts` forces reconcile
+after adoption, even for a no-op diff. CT100's rendered users have no `ACL LIST` permission,
+so ACL reads fail there too. CT100's ACLs remain owned by `homeflare-ct100`'s templates.
+`Valkey.Instance` assertions require a connection with the necessary `INFO`/`CONFIG GET` rights.
+
+**Kit-owned instance, no ACL file ⇒ runtime-only management.** SETUSER/DELUSER change the live ACL. No ACL SAVE is
+issued: it requires a configured ACL file. This mode is for instances whose operator accepts
+that ACLs must be reapplied after restart; AOF persistence does not persist this ACL declaration.
+A deployment with unchanged props is not proof that credentials survived a restart.
+
+**Ordinary plan diff uses stored attributes**, not a fresh live ACL or the ACL file. Only
+`alchemy drift` automatically calls `read` on an already managed resource (beta.79 `Drift.ts`),
+then compares live attributes and reconciles to persisted props. Reconcile itself always reads
+live state. A drift run needs the declared password variables to recreate missing users. Drift
+against a configured file fails the write gate; fix its owning template instead.
+See [Valkey ACL persistence](https://valkey.io/topics/acl/#use-an-external-acl-file) and
+[ACL SAVE](https://valkey.io/commands/acl-save/).
+
+## Historical CT100 activation evidence (2026-09-29)
+
+At that measurement the containers were declared `started: false` in `homeflare-ct100/src/valkey.ts`; this kit only
+declared the resources. This is historical context, not an activation instruction for this provider. The orchestrator's activation order, in the order each step depends on:
+
+1. **Secrets in OpenBao.** `kv/data/apps/valkey/seats` with fields `claude_password`,
+   `claude2_password`, `grok_password`, `cf_harness_password`; `kv/data/apps/valkey/litellm` with
+   `litellm_password`. (Rendered by openbao-agent fragments/95 and 96 — the templates in
+   `homeflare-ct100/src/valkey-acl.ts`.)
+2. **ACL files.** openbao-agent renders `VALKEY_SEATS_ACL_PATH` (`/etc/valkey/seats-acl.conf`) and
+   `VALKEY_LITELLM_ACL_PATH` (`/etc/valkey/litellm-acl.conf`); each container bind-mounts its own
+   file read-only as `--aclfile`. Both start with `user default off` — no keyless access.
+3. **First proof command**, after the Quadlets are started (`systemctl --user start
+valkey-seats.service valkey-litellm.service`):
+
+   ```sh
+   valkey-cli -h 127.0.0.1 -p 6381 --user claude --pass "$VALKEY_CLAUDE_PW" PING
+   # -> PONG, and a write outside the prefix is refused:
+   valkey-cli -h 127.0.0.1 -p 6381 --user claude --pass "$VALKEY_CLAUDE_PW" SET grok:x 1
+   # -> (error) NOPERM this user has no permissions to access one of the keys used as arguments
+   ```
+
+   The `default off` line means the same `PING` without `--user` answers
+   `(error) NOAUTH Authentication required.`
+
+## Version
+
+Valkey 8.1.10 (CT100's pinned image, `VALKEY_VERSION`) and 9.1.1 (scratch proof). The ACL rules —
+`-scan -randomkey -dbsize -pubsub` closing keyspace/channel enumeration, and `resetchannels` as
+the pub/sub boundary — were measured on both (seat-wiring-spec §5).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -120,6 +120,10 @@
       "types": "./dist/opnsense/index.d.ts",
       "default": "./dist/opnsense/index.js"
     },
+    "./valkey": {
+      "types": "./dist/valkey/index.d.ts",
+      "default": "./dist/valkey/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -128,7 +132,7 @@
   "dependencies": {
     "@distilled.cloud/caddy": "npm:@homeflare/distilled-caddy@0.2.2",
     "@distilled.cloud/grafana": "npm:@homeflare/distilled-grafana@0.2.0",
-    "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.3.0",
+    "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.4.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/openbao": "npm:@homeflare/distilled-openbao@0.2.2",
     "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.3.0",

package/src/ceph/ceph-argv.test.ts

@@ -208,7 +208,7 @@ describe('K-A4 finding 4: configValueProblem never accepts a flag-shaped value',
     ['a short flag', '-n'],
     ['a file-overwrite flag glued to its argument', '-o/etc/ceph/ceph.conf'],
     ['a long flag with =', '--admin-daemon=/var/run/ceph/ceph-mon.a.asok'],
-    ['another long flag', '--conf=/tmp/x'],
+    ['another long flag', '--conf=/tmp/x'], // tmp-allow: refused argv, not a directory this test creates
     ['the empty string', ''],
     ['a bare dash', '-'],
   ])('refuses %s (%j)', (_name, value) => {

package/src/launchd/sudo-allowlist.test.ts

@@ -15,7 +15,7 @@ import {
 } from './sudo-allowlist.ts';
 
 const DAEMONS = '/Library/LaunchDaemons';
-const context = { prefixes: [DAEMONS, '/opt/example'], staged: '/tmp/hf-sudo-x/staged' };
+const context = { prefixes: [DAEMONS, '/opt/example'], staged: '/tmp/hf-sudo-x/staged' }; // tmp-allow: in-memory staging path, not a directory this test creates
 const allowed = (argv: string[]) => privilegedProblem(argv, context);
 const PLIST = `${DAEMONS}/com.example.a.plist`;
 
@@ -66,7 +66,7 @@ describe('launchctl shapes', () => {
     ['bootstrap of two plists', [LAUNCHCTL, 'bootstrap', 'system', PLIST, PLIST]],
     [
       'bootstrap outside every prefix',
-      [LAUNCHCTL, 'bootstrap', 'system', '/tmp/com.example.a.plist'],
+      [LAUNCHCTL, 'bootstrap', 'system', '/tmp/com.example.a.plist'], // tmp-allow: refused argv, not a directory this test creates
     ],
     ['bootstrap of a non-plist', [LAUNCHCTL, 'bootstrap', 'system', `${DAEMONS}/com.example.a`]],
     // ★ Only where launchd loads daemons at boot: anywhere else is a job that vanishes on restart.

package/src/linux/sudo-allowlist.test.ts

@@ -22,7 +22,7 @@ import {
 } from './sudo-allowlist.ts';
 
 const PREFIXES = ['/etc/systemd/system', '/usr/local/bin'];
-const STAGED = '/tmp/hf-sudo-1/staged';
+const STAGED = '/tmp/hf-sudo-1/staged'; // tmp-allow: in-memory staging path, not a directory this test creates
 const TEMP = '/etc/systemd/system/.thing.service.hf-abcdef012345.tmp';
 const context: AllowContext = { prefixes: PREFIXES, staged: STAGED, temp: TEMP };
 const allowed = (argv: string[]) => privilegedProblem(argv, context);
@@ -51,7 +51,7 @@ describe('install shapes', () => {
       'a target that is not the derived temp',
       [INSTALL, '-m', '0644', '-T', '--', STAGED, '/etc/systemd/system/x.service'],
     ],
-    ['a temp outside every prefix', [INSTALL, '-m', '0644', '-T', '--', STAGED, '/tmp/x.tmp']],
+    ['a temp outside every prefix', [INSTALL, '-m', '0644', '-T', '--', STAGED, '/tmp/x.tmp']], // tmp-allow: refused argv, not a directory this test creates
     ['no -T', [INSTALL, '-m', '0644', '--', STAGED, TEMP]],
     ['a three-digit mode', [INSTALL, '-m', '644', '-T', '--', STAGED, TEMP]],
     ['-S (the Mac flag)', [INSTALL, '-S', '-m', '0644', '-T', '--', STAGED, TEMP]],
@@ -103,7 +103,7 @@ describe('mv and rm shapes', () => {
     ['mv without -T', [MV, '-f', '--', TEMP, '/etc/systemd/system/thing.service']],
     ['rm -r', [RM, '-rf', '--', TEMP]],
     ['rm without --', [RM, '-f', TEMP]],
-    ['rm outside every prefix', [RM, '-f', '--', '/tmp/x']],
+    ['rm outside every prefix', [RM, '-f', '--', '/tmp/x']], // tmp-allow: refused argv, not a directory this test creates
     ['sudo in argv', ['/usr/bin/sudo', '-n', RM, '-f', '--', TEMP]],
   ])('refuses %s', (_name, argv) => {
     expect(allowed(argv)).toBeString();

package/src/linux/sudo-runner.test.ts

@@ -52,7 +52,7 @@ describe('writeFileAtomic under a prefix', () => {
     for (const line of logs) expect(line.startsWith('homeflare/linux sudo -n ')).toBe(true);
     // No temp file left behind, and the staging directory is gone too.
     expect([...fake.files.keys()].some((path) => path.includes('.hf-'))).toBe(false);
-    expect([...fake.dirs.keys()].some((path) => path.startsWith('/tmp/hf-sudo-'))).toBe(false);
+    expect([...fake.dirs.keys()].some((path) => path.startsWith('/tmp/hf-sudo-'))).toBe(false); // tmp-allow: in-memory fake path from fake-sudo, not a directory this test creates
   });
 
   test('a failed mv removes the temp it just installed, then still throws', async () => {
@@ -68,7 +68,7 @@ describe('writeFileAtomic under a prefix', () => {
     expect(calls[2]?.at(-1)).toBe(calls[0]?.at(-1));
     expect(fake.files.has(DEST)).toBe(false);
     expect([...fake.files.keys()].some((path) => path.includes('.hf-'))).toBe(false);
-    expect([...fake.dirs.keys()].some((path) => path.startsWith('/tmp/hf-sudo-'))).toBe(false);
+    expect([...fake.dirs.keys()].some((path) => path.startsWith('/tmp/hf-sudo-'))).toBe(false); // tmp-allow: in-memory fake path from fake-sudo, not a directory this test creates
   });
 
   // 🔴 Adversarial review, round 2: a failed CLEANUP rm after a failed mv used to be swallowed

package/src/litellm/access-group-form.ts

@@ -0,0 +1,105 @@
+/**
+ * Wire bodies, comparison and refusals for `LiteLLM.AccessGroup`, testable without a server.
+ *
+ * ★ THE UPDATE IS A PARTIAL ONE, so it sends only what differs. `update_access_group` builds its
+ *   write from `data.model_dump(exclude_unset=True)` (`access_group_endpoints.py`, 1.103.0), and turns
+ *   a `null` list into `[]`. Nothing here relies on an omitted field being kept beyond that rule.
+ * ★ THE ROW READ BACK IS THE WHOLE TABLE, through `GET /v1/unified_access_group`. That route has no
+ *   filter and no by-name form, and it answers absence unambiguously, which a by-id `GET` (a 404 the
+ *   SDK does not declare for this tag) does not.
+ */
+import type * as ag from '@distilled.cloud/litellm/access_groups';
+import {
+  asRow,
+  canonical,
+  firstBadEntry,
+  firstDuplicate,
+  isBlank,
+  sameSet,
+  stringOrNull,
+  stringsOf,
+} from './registry-support.ts';
+import type { AccessGroupAttributes, AccessGroupProps } from './access-group-types.ts';
+
+/** The first reason a declaration is refused, or `undefined`. Runs before any request. */
+export const firstProblem = (props: AccessGroupProps): string | undefined => {
+  if (isBlank(props.accessGroupName) || props.accessGroupName !== props.accessGroupName.trim()) {
+    return '`accessGroupName` must be a non-blank name with no leading or trailing space';
+  }
+  if (props.description !== undefined && isBlank(props.description)) {
+    return '`description` is blank; leave it out to keep the live text';
+  }
+  for (const [field, values] of [
+    ['modelNames', props.modelNames ?? []],
+    ['mcpServerIds', props.mcpServerIds ?? []],
+  ] as const) {
+    const bad = firstBadEntry(values);
+    if (bad !== undefined)
+      return `\`${field}\` has a blank or padded entry (${JSON.stringify(bad)})`;
+    const twice = firstDuplicate(values);
+    if (twice !== undefined) return `\`${field}\` lists ${JSON.stringify(twice)} twice`;
+  }
+  return undefined;
+};
+
+/** One row of the list. `undefined` is "not a row": the caller refuses the whole answer. */
+export const toAttributes = (value: unknown): AccessGroupAttributes | undefined => {
+  const row = asRow(value);
+  if (row === undefined) return undefined;
+  const accessGroupId = row['access_group_id'];
+  const accessGroupName = row['access_group_name'];
+  if (typeof accessGroupId !== 'string' || typeof accessGroupName !== 'string') return undefined;
+  return {
+    accessGroupId,
+    accessGroupName,
+    description: stringOrNull(row['description']),
+    mcpServerIds: canonical(stringsOf(row['access_mcp_server_ids'])),
+    modelNames: canonical(stringsOf(row['access_model_names'])),
+  };
+};
+
+/**
+ * Wire names of the fields where live and declared disagree. The description counts only when
+ * declared; the two grant lists always count, an undeclared one meaning "grants nothing".
+ */
+export const differing = (
+  live: AccessGroupAttributes,
+  props: AccessGroupProps,
+): readonly string[] => {
+  const fields: string[] = [];
+  if (live.accessGroupName !== props.accessGroupName) fields.push('access_group_name');
+  if (props.description !== undefined && live.description !== props.description) {
+    fields.push('description');
+  }
+  if (!sameSet(live.modelNames, props.modelNames ?? [])) fields.push('access_model_names');
+  if (!sameSet(live.mcpServerIds, props.mcpServerIds ?? [])) fields.push('access_mcp_server_ids');
+  return fields;
+};
+
+/** Create body: the name and both grant lists always (a create with none would be an empty group). */
+export const createBody = (
+  props: AccessGroupProps,
+): ag.CreateAccessGroupV1UnifiedAccessGroupPostRequest => ({
+  access_group_name: props.accessGroupName,
+  access_mcp_server_ids: [...(props.mcpServerIds ?? [])],
+  access_model_names: [...(props.modelNames ?? [])],
+  ...(props.description === undefined ? {} : { description: props.description }),
+});
+
+/** Update body: only the fields that differ, so nothing the declaration does not manage is sent. */
+export const updateBody = (
+  props: AccessGroupProps,
+  live: AccessGroupAttributes,
+): Omit<ag.UpdateAccessGroupV1UnifiedAccessGroupAccessGroupIdPutRequest, 'access_group_id'> => {
+  const changed = new Set(differing(live, props));
+  return {
+    ...(changed.has('access_group_name') ? { access_group_name: props.accessGroupName } : {}),
+    ...(changed.has('description') ? { description: props.description ?? null } : {}),
+    ...(changed.has('access_model_names')
+      ? { access_model_names: [...(props.modelNames ?? [])] }
+      : {}),
+    ...(changed.has('access_mcp_server_ids')
+      ? { access_mcp_server_ids: [...(props.mcpServerIds ?? [])] }
+      : {}),
+  };
+};