@homeflare/alchemy 0.23.0 → 0.25.0

package/dist/release/tar.d.ts

@@ -6,8 +6,15 @@ export type TarContents = {
     /** Every entry name, in archive order — so a refusal can say what the archive did hold. */
     readonly names: readonly string[];
 };
-/** A push parser: `push` each chunk of the unzipped stream, then `finish`. Either may throw. */
-export declare const tarReader: (wanted: ReadonlySet<string>) => {
+/**
+ * A push parser: `push` each chunk of the unzipped stream, then `finish`. Either may throw.
+ *
+ * @param root When given, exactly one typeflag-'5' entry named `<root>/`, size 0, is accepted and
+ *   dropped rather than refused as a directory; every OTHER entry name must begin with the SEGMENT
+ *   `<root>/` (a `<root>-evil/x` sibling does not) and is reported, matched and kept under that
+ *   prefix stripped off. Omitted, behaviour is byte-identical to a reader with no root at all.
+ */
+export declare const tarReader: (wanted: ReadonlySet<string>, root?: string) => {
     finish: () => TarContents;
     push: (chunk: Uint8Array) => void;
 };

package/dist/release/tar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tar.d.ts","sourceRoot":"","sources":["../../src/release/tar.ts"],"names":[],"mappings":"AAqFA,0CAA0C;AAC1C,eAAO,MAAM,WAAW,UAAW,SAAS,UAAU,EAAE,KAAG,UAQ1D,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,mGAAmG;IACnG,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClD,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,CAAC;AAEF,gGAAgG;AAChG,eAAO,MAAM,SAAS,WAAY,WAAW,CAAC,MAAM,CAAC;kBAoFhC,WAAW;kBAlCT,UAAU,KAAG,IAAI;CAwCvC,CAAC"}
+{"version":3,"file":"tar.d.ts","sourceRoot":"","sources":["../../src/release/tar.ts"],"names":[],"mappings":"AAoGA,0CAA0C;AAC1C,eAAO,MAAM,WAAW,UAAW,SAAS,UAAU,EAAE,KAAG,UAQ1D,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,mGAAmG;IACnG,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClD,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,WAAY,WAAW,CAAC,MAAM,CAAC,SAAS,MAAM;kBA6H/C,WAAW;kBAlCT,UAAU,KAAG,IAAI;CA2CvC,CAAC"}

package/docs/litellm.md

@@ -0,0 +1,110 @@
+# LiteLLM — `@homeflare/alchemy/litellm`
+
+`LiteLLM.PassThroughEndpoint` declares one row of LiteLLM's `/config/pass_through_endpoint`
+family: a route on the proxy that forwards requests to an upstream target, generated from
+LiteLLM **1.100.0**'s own OpenAPI document (`codegen/manifest.json`'s `litellm-openapi` entry —
+vendor code at tag `v1.100.0`, dumped by the vendor's own `gen-api-types.mjs`, cross-checked
+byte-identically against the tag's committed `schema.d.ts`; NOT a live read, because the reference
+proxy's `/openapi.json` could not be reached when this was walked — see the manifest entry's note).
+
+## What is DB-backed and API-managed, versus config-file only
+
+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                              |
+| 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  |
+
+## Credentials
+
+Reads `LITELLM_PROXY_URL` and `LITELLM_PROXY_API_KEY` at call time — LiteLLM's own variable
+names, the ones its `litellm` CLI reads (`litellm/proxy/client/cli/main.py` at the tag). No
+default URL. The key must be LiteLLM's master key or another `PROXY_ADMIN` key:
+`update_config_general_settings`, the function every mutation goes through, is `PROXY_ADMIN`
+only. Never a prop — see [docs/credentials.md](./credentials.md) for the house rule.
+
+## Refusals
+
+This resource refuses a plan rather than writing something it cannot safely undo:
+
+- **A path already held by an `is_from_config` row.** A DB row on the same path overrides the
+  config file at runtime, so creating one would silently take over a route the operator declared
+  in `config.yaml`. Change the config file instead, or pick a different path.
+- **A DB row LiteLLM did not give an `id`.** LiteLLM identifies some pass-through endpoints by
+  path alone, for backwards compatibility. Update and delete are both id-keyed, so this resource
+  cannot address a row like that — it is refused rather than silently adopted into a lifecycle
+  that cannot actually manage it.
+- **A literal secret in a forwarded header.** `Authorization`, `x-api-key` and
+  `cf-aig-authorization` must contain LiteLLM's own `os.environ/NAME` reference form
+  (`set_env_variables_in_header`, `pass_through_endpoints.py` at the tag), never a literal value —
+  a house rule (not a vendor one), because a missing variable on the proxy host would otherwise
+  leave the literal string in the header with nothing in the API able to detect it.
+
+A foreign DB row on the same path that LiteLLM DID give an id is `Unowned`: `read` finds it and
+the plan needs `--adopt` before it is bound.
+
+## Nullable fields: `timeout`, `methods`, `guardrails`
+
+LiteLLM's update route merges the parsed body with `exclude_none` (measured at 1.100.0), so it
+can never clear a field that is already set — sending neither `null` nor omitting it changes
+anything already stored. Clearing one of these three fields is therefore planned as a
+**replace**: delete the row, then create it again without the field. There is a brief window
+with the route absent, and it exists because the alternative — create-before-delete — would put
+two rows on the same path, which this resource never allows.
+
+## The whole-field write, and why every mutation is serialised
+
+Every pass-through endpoint lives in ONE `general_settings.pass_through_endpoints` list. Create,
+update and delete are each a read-modify-write of that WHOLE list. `client.ts` wraps every
+mutating call in a per-base-URL `Effect` semaphore, so two of THIS PROCESS's own calls never
+race each other — two endpoints declared in the same deploy both survive.
+
+⛔ **What the semaphore does not cover.** It serialises this package's own writes within one
+process. It cannot serialise against the LiteLLM UI, another stack, or a second concurrent
+`alchemy deploy` — the field has no ETag and no vendor-side locking. `reconcile` reads the row
+back after every write rather than trusting the call that just returned, so a lost update is
+visible on the NEXT plan (as drift) even though it cannot be prevented on this one.
+
+## Example
+
+Estate values — the account id, the gateway id, the upstream key's variable name — are never kit
+constants; they are props your own stack supplies. Placeholders below, per the TypeSafe plugin's
+`ai-gateway.md` reference (Cloudflare's `/accounts/{account_id}/ai/run`, a Workers-AI-scoped
+Bearer token, `cf-aig-gateway-id` and `cf-aig-no-wholesale: true`):
+
+```ts
+import { LiteLLMPassThroughEndpoint, litellmProviders } from '@homeflare/alchemy/litellm';
+
+export class AiGateway extends LiteLLMPassThroughEndpoint('AiGateway', {
+  path: '/cloudflare-ai',
+  target: 'https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run',
+  headers: {
+    Authorization: 'os.environ/CF_AI_GATEWAY_TOKEN',
+    'cf-aig-gateway-id': '<GATEWAY_ID>',
+    'cf-aig-no-wholesale': 'true',
+  },
+  timeout: 60,
+}) {}
+```
+
+```ts
+// …then provide `litellmProviders()` alongside the stack's other providers.
+```
+
+## 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
+  every route the dashboard's generator forces into the schema (`include_in_schema = True`) is
+  actually served the same way in production, or that the mini's own `config.yaml`/
+  `general_settings` match what `schema.prisma`/`proxy_server.py` assume.
+- **More than one uvicorn worker.** Pass-through routes register themselves on the worker that
+  handled the registering request (`add_*_route` on `request.app`); with more than one worker,
+  the others' routes are unmeasured by this package.

package/docs/paperless.md

@@ -0,0 +1,115 @@
+# Paperless — `@homeflare/alchemy/paperless`
+
+Four resources — `Paperless.Tag`, `Paperless.DocumentType`, `Paperless.StoragePath`,
+`Paperless.CustomField` — the taxonomy Paperless-ngx writes through Django's internal models,
+create-or-update and never deleted by default. Workflows and mail accounts are a later slice.
+
+## Credentials
+
+Two environment variables, read **at call time**, never props:
+
+| variable          | holds                                                     |
+| ----------------- | --------------------------------------------------------- |
+| `PAPERLESS_URL`   | the instance origin, e.g. `https://paperless.example.com` |
+| `PAPERLESS_TOKEN` | a scoped Paperless-ngx API token                          |
+
+⛔ **Neither has a default.** A package that fell back to a loopback address would let a consumer
+who forgot the variable watch every call fail against a machine that is not theirs.
+
+⚠️ **`Authorization: Token <value>`, not `Bearer`** — Paperless-ngx's own `securitySchemes`
+states the "Token" prefix explicitly.
+
+⚠️ **Every call carries `Accept: application/json; version=10`**, pinned to the API version this
+family was walked against (`REST_FRAMEWORK.DEFAULT_VERSION` at v3.1.1). An estate upgrade that
+moves the default cannot silently change what this package receives without that assertion
+failing first.
+
+## Every create carries `owner`, null when undeclared
+
+🔴 **This is the one behaviour that had to be measured, not guessed.**
+`OwnedObjectSerializer.create` (Paperless-ngx `documents/serialisers.py:495-502` at v3.1.1) sets
+the owner to the TOKEN USER whenever the field is absent from the body. Omitting an undeclared
+prop the way you might expect — `Netbox.Prefix`'s pattern for an undeclared foreign key — would
+silently create an object owned by whichever credential ran the deploy: invisible to every other
+user, and a second row beside the estate's `owner: null` one on the next apply. So `Tag`,
+`DocumentType` and `StoragePath` always send `owner: null` unless `owner` is declared.
+
+⛔ `Paperless.CustomField` has **no owner field at all** — its wire body is exactly `{name,
+data_type, extra_data}`, measured against the schema. It is not `OwnedObjectSerializer`-based.
+
+## Adopt is never silent (H1)
+
+★ **`read` answers `Unowned(attrs)` on every match**, never plain attributes. Paperless has no
+ownership marker this package can check — `owner` is the estate's own prop, not proof of who
+created a row — so, per the house's 2026-09-21 decision, identical is not ours. `--adopt` (or
+`.pipe(adopt(true))`) is required to bind an existing tag, document type, storage path or custom
+field, the same posture as any other marker-less API.
+
+## `CustomField.dataType` is create-only
+
+⛔ **A change is refused at plan time, never a PATCH and never a replace.** Changing a custom
+field's data type in Paperless deletes that field's value on every document that carries it — a
+replace (delete + recreate) is exactly as destructive as a PATCH would be, just under a different
+name. Declaring a different `dataType` against a live object fails the plan with both values
+named; retire the old field and create a new one instead.
+
+⚠️ The reconciler this family replaces asserted "Paperless forbids a data_type change" — that
+claim is **unverified** at v3.1.1 (`CustomFieldSerializer.validate` and `CustomFieldViewSet`
+contain no such refusal). This package refuses the change regardless, because the destructive
+side effect is real whether or not the vendor also refuses it.
+
+## Removal is `retain`
+
+Every family defaults to `retain` — a tag, document type, storage path or custom field id is
+referenced by every document that carries it, and Paperless does not offer a "detach first"
+option. `delete` is fully implemented; dropping a declaration does not delete the object unless
+the caller opts into `.pipe(RemovalPolicy.destroy())`.
+
+## Locate is by name only before there is state; identity is the stored id after
+
+`MatchingModel` (Paperless-ngx `models.py:79-89`) has `UniqueConstraint(name, owner)` plus a
+unique name where owner is null. Before a declaration has ever been deployed — a genuine first
+create, or the engine's own `--adopt` probe — `matching.ts` locates candidates with a
+case-insensitive `name__iexact` filter, wide enough to see every case-variant Paperless holds,
+and then narrows to the exact-case, exact-owner row in this process (the same locate-then-identify
+split `Netbox.Prefix` uses for its VRF). A locate that matches more than the 20-row page it reads
+is refused as "not a natural key".
+
+⛔ **Once a declaration has state, identity is the stored numeric id, not `(name, owner)`.**
+Renaming a tag, or re-owning any of the three owned families, is an ordinary edit — and locating
+by the _new_ name/owner would miss the row this declaration already wrote, PATCHing nothing and
+POSTing a second object under the new name while the original sat there permanently orphaned
+(`list()` always answers `[]` by design, so `nuke` can never find it either). `diff`/`reconcile`
+locate by the id Alchemy's engine already has on hand (`output.id`) instead: a changed name/owner
+becomes an in-place PATCH of that same id — Paperless allows renaming all four types by PATCH, and
+every document keeps its tag/type/path/field because the id never changes. If that id no longer
+exists live (deleted out of band), the plan refuses loudly rather than silently creating a
+replacement; adopt the live object back or drop it from state first.
+
+`destroy` locates the same way — by `output.id` once state exists, so a row renamed out of band
+after its last deploy is still found and deleted by id rather than silently missed by a
+now-stale name. Unlike `diff`/`reconcile`, a missing `output.id` at delete time is not a refusal:
+the object being already gone is exactly the idempotent success `delete` reports.
+
+## Generated, not hand-typed
+
+`generated/types/*.ts` and `generated/constraints/*.ts` come from `bun codegen/paperless.ts`
+against Paperless-ngx 3.1.1's own served OpenAPI document — see
+[`codegen/paperless.md`](../../../codegen/paperless.md) for the full provenance chain. A prop's
+enum-shaped fields (`matchingAlgorithm`, `dataType`) are typed by indexing into the generated
+request interface (`PaperlessTagRequest['matching_algorithm']`), never retyped by hand.
+
+## Usage
+
+```ts
+import { paperlessProviders, Tag } from '@homeflare/alchemy/paperless';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+// PAPERLESS_URL and PAPERLESS_TOKEN in the deploy's environment.
+export default async () => {
+  const app = await alchemy('paperless-taxonomy');
+  const invoices = await Tag('invoices', { name: 'Invoices', color: '#a6cee3' });
+  await app.finalize();
+};
+// wire the stack: Layer.mergeAll(paperlessProviders(), …).pipe(Layer.provide(FetchHttpClient.layer))
+```

package/docs/peers.md

@@ -7,7 +7,7 @@ The install line for `@homeflare/alchemy`, and why every peer on it and every en
 ```sh
 bun add @homeflare/alchemy alchemy@2.0.0-beta.79 effect@4.0.0-rc.115 \
         @effect/platform-node@4.0.0-rc.115 cloudflare@4.5.0 mime@4.1.0 \
-        @distilled.cloud/cloudflare@1.0.0-rc.12
+        @distilled.cloud/cloudflare@1.0.0-rc.12 @effect/sql-pg@4.0.0-rc.115
 ```
 
 🔴 **Why, measured 2026-09-16 on 0.1.0 and re-checked 2026-09-17 against Alchemy 78.**
@@ -37,3 +37,10 @@ that followed the 78 README does not drop a required line.
 subpath would degrade without it — measured 2026-09-16, the subpath does not load at all:
 `Cannot find package 'cloudflare'`. An optional peer should mean a feature is absent, not
 that an import fails.
+
+⚠️ **`@effect/sql-pg` (added for `/postgres`, 2026-09-23) is required too, for the same
+reason, not because every subpath imports it.** This package has one flat peer set for the
+whole install, not one per subpath — `peers.test.ts`'s "no peer is marked optional" test
+enforces it. `@effect/sql-pg` is optional on `alchemy`'s own manifest (its module graph
+does not reach `SQL/Postgres` unless a stack imports it); here it stays a plain peer like
+every other one.

package/docs/postgres.md

@@ -0,0 +1,125 @@
+# PostgreSQL — `@homeflare/alchemy/postgres`
+
+`Postgres.Database`: create-and-assert over a self-hosted cluster, walked against PostgreSQL
+18.6 (`REL_18_6`, commit `724edf9b`). It retires `org.nixos.postgres-reconcile`, a 38-line bash
+loop over 19 databases run against the trust socket.
+
+## Why the kit builds this instead of using upstream
+
+Upstream `alchemy@2.0.0-beta.79` has no resource for a database in a self-hosted cluster —
+measured against `v2.0.0-beta.79`'s full tree: it ships vendor-API Postgres resources
+(`Planetscale.Postgres.*`, `Neon.PostgresOrigin`, `Prisma.Postgres`, `Fly.Postgres`,
+`Railway.Postgres`) and the runtime binding `alchemy/SQL/Postgres` over `@effect/sql-pg`, but
+nothing that issues `CREATE DATABASE` against a cluster you run yourself. No
+`@distilled.cloud/postgres` or `@distilled.cloud/postgresql` package exists either (registry
+404, checked 2026-09-23). This family builds on the same `@effect/sql-pg` `PgClient` upstream's
+own binding uses, so it stays host-independent and portable — CT100's own Postgres (vault
+decision 21) can use it later, and it is shaped to upstream.
+
+## The locked shape
+
+Create-and-assert only. `delete` always refuses. There is no `ALTER OWNER` and no `ALTER
+DATABASE` of any kind. There is no password prop — a database carries none in `pg_database`.
+
+## Measured path (2026-09-23)
+
+Read `pg_hba_file_rules` and `pg_settings` over the trust socket: `listen_addresses` is
+`10.100.1.1`, `ssl` is `on` (min `TLSv1.2`), and the `hostssl` rules cover only `netbox`,
+`discord`, `litellm`, `teslamate` and one `homeflare-*` app group — **no TCP rule reaches the
+`postgres` maintenance database.** Line 1 of `pg_hba_file_rules` is `local all all trust`. So
+today only a stack that deploys on the mini, over the Unix socket at
+`/opt/homeflare/postgres/sockets` (mode `0755`, owner `tim`), can create a database.
+
+**A JS client reaches that socket.** Measured live with `@effect/sql-pg@4.0.0-rc.115` under
+Bun, from scratch space, never committed: `PgClient.layer({ host:
+'/opt/homeflare/postgres/sockets', port: 5432, database: 'postgres', username: 'tim' })`
+connects and `SELECT version()` answers `PostgreSQL 18.6 on aarch64-apple-darwin25.6.0…`. The
+catalog SELECT this family issues answered all 24 live non-template databases. `SHOW
+standard_conforming_strings` is `on` — the assumption `quoteStringLiteral` (`database-sql.ts`)
+rests on.
+
+The reconciler being retired, `/nix/store/…-postgres-reconcile.sh`, runs `psql -h
+/opt/homeflare/postgres/sockets -U tim -d postgres`; for each of 19 databases it runs `CREATE
+DATABASE "$db" OWNER tim` when missing and asserts `pg_get_userbyid(datdba) = tim`. It never
+drops anything.
+
+## `name`
+
+At most 63 UTF-8 bytes (`NAMEDATALEN` 64, `pg_config_manual.h` line 29), refused at plan.
+Measured at `scansup.c`'s `truncate_identifier`: past that length the server clips the name with
+`pg_mbcliplen` (byte-oriented, multibyte-aware) and raises only a `NOTICE`
+(`ERRCODE_NAME_TOO_LONG`) — never an error. A create would silently succeed against the
+truncated name, and the next plan's `WHERE datname = $1` (the name exactly as declared) would
+find nothing and try to create it again, forever. Refusing at plan is the only way this stays a
+one-time failure instead of an infinite loop.
+
+## Mapping (`database-provenance.test.ts` proves this against the committed fixtures)
+
+| prop               | `CREATE DATABASE` option | `pg_database` column                                |
+| ------------------ | ------------------------ | --------------------------------------------------- |
+| `owner`            | `OWNER`                  | `datdba` (via `pg_get_userbyid`)                    |
+| `encoding`         | `ENCODING`               | `encoding`                                          |
+| `localeProvider`   | `LOCALE_PROVIDER`        | `datlocprovider`                                    |
+| `lcCollate`        | `LC_COLLATE`             | `datcollate`                                        |
+| `lcCtype`          | `LC_CTYPE`               | `datctype`                                          |
+| `allowConnections` | `ALLOW_CONNECTIONS`      | `datallowconn`                                      |
+| `connectionLimit`  | `CONNECTION LIMIT`       | `datconnlimit`                                      |
+| `isTemplate`       | `IS_TEMPLATE`            | `datistemplate`                                     |
+| `tablespace`       | `TABLESPACE`             | `dattablespace` (joined to `pg_tablespace.spcname`) |
+
+`datlocprovider` is Postgres's internal 1-byte `"char"` type. Measured live: `@effect/sql-pg`
+decodes it as raw bytes, not text, so the read query maps it with a `CASE` in SQL to the same
+three words `pg_collation.h`'s `collprovider_name` returns for the same codes (`b`→`builtin`,
+`i`→`icu`, `c`→`libc`) before it ever crosses the wire as JSON.
+
+### Excluded, and why
+
+| option              | reason                                                                       |
+| ------------------- | ---------------------------------------------------------------------------- |
+| `TEMPLATE`          | consumed only at create time to copy from; no column records it              |
+| `STRATEGY`          | consumed only at create time (WAL_LOG/FILE_COPY); not stored                 |
+| `LOCALE`            | a shorthand for `LC_COLLATE`/`LC_CTYPE`; this family declares those directly |
+| `BUILTIN_LOCALE`    | folds into `datcollate`/`datctype` like `LOCALE`, no column of its own       |
+| `ICU_LOCALE`        | `datlocale` exists, but deferred — all 24 live databases are libc            |
+| `ICU_RULES`         | stored in `daticurules`, no ICU-provider consumer yet                        |
+| `COLLATION_VERSION` | for `pg_upgrade`; normally omitted so Postgres computes it                   |
+| `OID`               | for `pg_upgrade`'s internal use only; not something a stack should assert    |
+
+## Identifier quoting: why this file does not reuse `alchemy`'s `sql(value)`
+
+`CREATE DATABASE` takes no bind parameters for any value, not even `OWNER` — measured at
+`gram.y`: every `createdb_opt_item` value is `NumericOnly`, `opt_boolean_or_string` or the
+keyword `DEFAULT`, none of which reaches `PARAM` (`$n`). Every value in this statement is
+escaped by hand and run through `.unsafe()`.
+
+The database `name` is a `ColId` (`gram.y` line 17327) — one token. Effect's own
+`Statement.defaultEscape('"')`, what `sql(value)` compiles to, ALSO rewrites every `.` in a
+value to `"."`, because it is built for a schema-qualified name like `schema.table`. A database
+named `"my.app"` would come out `"my"."app"` — two tokens where the grammar parses one, a
+syntax error this provider would cause. `quoteIdent` (`database-sql.ts`) is the single-token
+form instead: quote, and double an embedded `"`. Nothing else.
+
+Every other `WITH` value (`OWNER`, `TABLESPACE`, `ENCODING`, `LOCALE_PROVIDER`, `LC_COLLATE`,
+`LC_CTYPE`) is a string literal in the grammar, not an identifier: `createdb_opt_item`'s
+string branch is `opt_boolean_or_string → NonReservedWord_or_Sconst → NonReservedWord |
+Sconst`. `quoteStringLiteral` wraps in `'` and doubles an embedded `'`; it never emits a
+backslash, so it does not depend on which way `standard_conforming_strings` points (measured
+`on` above, the PG18 default since 9.1).
+
+## House differences from S11/S14
+
+`delete` refuses unconditionally (`PostgresDatabaseDropRefused`) and `defaultRemovalPolicy` is
+`retain` — two independent reasons `DROP DATABASE` never runs through this provider. Most
+databases this family will manage are adopted, not created from nothing; a destroy on data is
+Tim's manual act over the socket, never an engine call.
+
+## Ownership
+
+A database carries no ownership mark in `pg_database`. Per H1 (the house's Snippet-precedent
+rule for marker-less APIs), `read` always answers `Unowned` for a match — every one of the
+mini's 19 already-live databases needs `adopt(true)` in the consuming stack.
+
+## Unmeasured
+
+Whether `ALTER DATABASE … REFRESH COLLATION VERSION` should ever be offered as an explicit,
+separate operation (not part of `reconcile`) is open — nothing in this family calls it.

package/docs/release-binary-catalogs.md

@@ -112,10 +112,46 @@ alertmanager, blackbox_exporter, node_exporter and postgres_exporter
 `darwin_arm64` to `darwin_all`), pyroscope and vector. `bao` (OpenBao) is
 walked — see `OPENBAO_RELEASES` above.
 
-⚠️ REASONED NOT MEASURED: the Prometheus-family archives wrap their files in a
-directory, and `tar.ts` refuses a directory entry (and any PAX header) for the
-whole archive. Walking those down includes a reader change, not only a data
-set ([release-binary-upstream.md](./release-binary-upstream.md), gap 11).
+### The Prometheus family's shape, MEASURED 2026-09-23
+
+★ **Now measured, not reasoned.** All four Prometheus-family darwin-arm64
+archives wrap every entry in one directory, so `tar.ts` refused each one
+whole — before this unit, on `entry "<root>/" is a directory`. Walking them
+down needed a reader change, not only a data set: `tarReader(wanted, root)`
+now strips exactly one DECLARED leading directory, pinned as `archive.root`
+(gap 11 below, and tar.ts's own header comment, carry the full detail).
+
+Read at `2026-09-23T14:33Z` with `gh api repos/<owner>/<repo>/releases/tags/<tag>`,
+then downloaded to a scratch directory (not executed) and re-hashed:
+
+| package (darwin-arm64)                           | asset                                          | size (B)   | `digest` matches  | wrapper directory (root)                |
+| ------------------------------------------------ | ---------------------------------------------- | ---------- | ----------------- | --------------------------------------- |
+| `prometheus/alertmanager` v0.33.1                | `alertmanager-0.33.1.darwin-arm64.tar.gz`      | 37,247,168 | yes (`a94fbe54…`) | `alertmanager-0.33.1.darwin-arm64`      |
+| `prometheus/blackbox_exporter` v0.28.0           | `blackbox_exporter-0.28.0.darwin-arm64.tar.gz` | 15,705,022 | yes (`ec6c70cc…`) | `blackbox_exporter-0.28.0.darwin-arm64` |
+| `prometheus/node_exporter` v1.12.1               | `node_exporter-1.12.1.darwin-arm64.tar.gz`     | 5,368,643  | yes (`35b246a3…`) | `node_exporter-1.12.1.darwin-arm64`     |
+| `prometheus-community/postgres_exporter` v0.20.1 | `postgres_exporter-0.20.1.darwin-arm64.tar.gz` | 10,072,235 | yes (`4dd2b9e7…`) | `postgres_exporter-0.20.1.darwin-arm64` |
+
+`tar -tvzf` on each downloaded archive (nothing extracted) showed: entry 1 is
+the wrapper (typeflag `5`, size 0, `runner`/`circleci` owned), then only
+root-level regular files under it — the exporter binary, `LICENSE`, `NOTICE`,
+and for alertmanager also `amtool` and `alertmanager.yml`. No PAX (`x`/`g`) or
+GNU long-name (`L`/`K`) entries in any of the four. Re-run afterward with the
+worktree's OWN `tarReader(wanted, root)` over the same downloaded bytes: every
+archive now parses to completion and returns the named member at its full
+pinned size (e.g. `alertmanager` → 47,058,626 bytes) — see
+`tar-root.test.ts` and `binary-root.test.ts` for the same proof as committed
+fixtures.
+
+⛔ **This unit adds the reader capability and its tests, not a new catalog
+entry.** No `PinnedArchive` for alertmanager, blackbox_exporter,
+node_exporter or postgres_exporter exists here yet — that is a follow-up data
+module (its own walk-down of the checksum format: `sha256sums.txt`, archives
+only, so member digests would be `computed` like OpenBao's) and its own PR.
+
+⚠️ **`vector` is NOT covered by this measurement or this reader change.**
+Vector's queue entry (above) has its own archive shape, unmeasured here; do
+not assume it also wraps in a single directory without walking it down
+separately.
 
 ## What this resource is not for
 

package/docs/release-binary-refusals.md

@@ -1,7 +1,7 @@
 # Release binaries — every refusal
 
 Status: active
-Verified: 2026-09-22
+Verified: 2026-09-23
 
 Everything `Release.Binary` refuses, by where it is refused. The guide is
 [release-binary.md](./release-binary.md). ★ One page per subject: the guide says
@@ -16,13 +16,15 @@ At plan (the probe and `diff`), before anything is touched: a pin that is
 missing or not a plain value (an Output pin would be a fetch; a first deploy
 is never diffed, so reconcile refuses it there, before any host call, from the
 props as declared); a repo that is not `owner/name`, or whose name is `.` or
-`..`; a tag, asset or name that is not one safe path segment; an asset that is
-not a `.tar.gz` or `.tgz` (a glob is not a name); a size that is not an
-integer from 1 byte to 1 GiB (it is allocated up front); a digest that is not
-64 lower-case hex; a member that is absolute or climbs. Also a relative or
-unnormalised directory; a mode that is setuid, setgid, sticky, group- or
-world-writable, or not owner-readable and owner-executable; an owner or group
-that is not a valid name or id; a new pin at the same path.
+`..`; a tag, asset, name or **root** that is not one safe path segment (`root`
+added 2026-09-23: refuses `''`, `'.'`, `'..'` and anything with a `/`, same as
+a tag or asset); an asset that is not a `.tar.gz` or `.tgz` (a glob is not a
+name); a size that is not an integer from 1 byte to 1 GiB (it is allocated up
+front); a digest that is not 64 lower-case hex; a member that is absolute or
+climbs. Also a relative or unnormalised directory; a mode that is setuid,
+setgid, sticky, group- or world-writable, or not owner-readable and
+owner-executable; an owner or group that is not a valid name or id; a new pin
+at the same path.
 
 ⚠️ **Not on a first deploy with `directory: dir.path`.** Alchemy neither
 probes nor diffs a create whose props hold an Output, so there every check
@@ -51,6 +53,18 @@ header checksum, uses base-256, is neither ustar nor GNU, a lone zero block,
 data after the end, a truncated archive; the declared member missing; the
 member's SHA-256 not its pin. Every one of these ends `Nothing was written.`
 
+**With `archive.root` declared** (tar.ts, 2026-09-23 — the Prometheus family's
+own shape, walked down for this): a second entry named `<root>/`; any entry
+whose first path segment is not exactly `root` — `<root>-evil/x` is a
+different segment, not a prefix match, and is refused the same as a plain
+top-level file beside the wrapper; the `<root>/` entry itself being anything
+but an empty (size-0) directory, including a hard link or symlink at that
+exact name; and the declared root never appearing in the archive at all.
+Every other refusal above — PAX, GNU long-name, `..`, links, devices, a
+duplicate name — still applies to entries _inside_ the root, unchanged.
+**Without `root`,** a directory entry (the wrapper included) is refused
+exactly as it always was: byte-identical to a reader with no root support.
+
 After the write: a file that does not read back as declared (a create is
 removed). Errors are tagged (`BinaryRefused`, `DownloadFailed`,
 `ChecksumMismatch`, `ArchiveRefused`) and carry the house refusal sentence.

package/docs/release-binary-upstream.md

@@ -116,21 +116,39 @@ that upstream wants it.
     fails with `BinaryRefused`, and the provider would fail with the tag union
     instead of `lift()`'s `Error`. `error-channel.test.ts` fails the moment
     either changes, so this page moves with it.
-11. **The tar reader accepts one measured layout.** Measured 2026-09-22 against
-    `extractMembers`: macOS's default `tar czf` (bsdtar 3.5.3) writes a PAX `x`
-    header before every entry (a sub-second `mtime` and the
-    `com.apple.provenance` xattr), so even a one-file archive is refused whole.
-    `--no-mac-metadata` still writes them; `--format ustar` passes. A wrapping
-    directory entry is refused whole. Go's `archive/tar` writing root-level
-    files passes. The house accepts this on purpose: the Victoria archives are
-    flat, and homeflare-builds writes plain ustar. ⚠️ REASONED NOT MEASURED:
-    the Prometheus family's archives (`alertmanager-0.34.1.darwin-arm64.tar.gz`)
-    wrap their files in a directory, so the queue in
-    release-binary-catalogs.md needs a reader change, not only a data set.
-    Generic replacement: skip directory entries, and links that are not the
-    declared member, because nothing is ever written from an entry name; read
-    PAX records and refuse only a `path`, `linkpath` or `size` record. The
-    member digest still guards the bytes.
+11. **The tar reader accepts two measured layouts: flat, and one declared
+    root.** Measured 2026-09-22 against `extractMembers`: macOS's default
+    `tar czf` (bsdtar 3.5.3) writes a PAX `x` header before every entry (a
+    sub-second `mtime` and the `com.apple.provenance` xattr), so even a
+    one-file archive is refused whole. `--no-mac-metadata` still writes them;
+    `--format ustar` passes. Go's `archive/tar` writing root-level files
+    passes. The house accepts this on purpose: the Victoria archives are flat,
+    and homeflare-builds writes plain ustar.
+    ★ **MEASURED 2026-09-23, no longer reasoned**: all four Prometheus-family
+    darwin-arm64 archives (`alertmanager-0.33.1.darwin-arm64.tar.gz` — the
+    estate pins **0.33.1**, not the 0.34.1 this page previously cited —
+    `blackbox_exporter-0.28.0`, `node_exporter-1.12.1`,
+    `postgres_exporter-0.20.1`) wrap every entry in exactly one directory
+    (typeflag `5`, size 0, first) and carry no PAX or GNU long-name entries
+    (release-binary-catalogs.md has the full table and commands). The house
+    chose the **narrow fix**, not the generic one below: `tarReader(wanted,
+root)` accepts exactly one entry named `<root>/`, requires every other
+    name to begin with that exact segment, and strips the prefix before a name
+    is matched, listed or checked for a duplicate — refusing a second
+    directory entry, a `<root>-evil/x` sibling (a segment match, not a string
+    prefix), anything outside the root, and a `<root>/` that is not an empty
+    directory. Without `root` the refusal is unchanged: a directory entry, the
+    wrapper included, is still refused whole.
+    ⚠️ **The generic replacement below is still the more upstreamable shape**
+    and was NOT what the house built here: skip directory entries, and links
+    that are not the declared member, because nothing is ever written from an
+    entry name; read PAX records and refuse only a `path`, `linkpath` or
+    `size` record. The member digest still guards the bytes either way. The
+    house's narrower `root` prop is easier to review (a vendor's wrapper name
+    is pinned, not inferred) but does not reach an archive with no declared
+    wrapper, or more than one PAX record kind, the way the generic reader
+    would; a PR to upstream would need to pick one, and a house-only
+    consumption doesn't have to.
 12. **One source, one tag alphabet, other prop names.** `releaseUrl` fixes
     `https://github.com`. Upstream's GitHub family also reaches GitHub
     Enterprise (`normalizeGitHubBaseUrl`, `GitHub/BaseUrl.ts`). A tag must be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.23.0",
+  "version": "0.25.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",
@@ -60,10 +60,18 @@
       "types": "./dist/netbox/index.d.ts",
       "default": "./dist/netbox/index.js"
     },
+    "./postgres": {
+      "types": "./dist/postgres/index.d.ts",
+      "default": "./dist/postgres/index.js"
+    },
     "./linux": {
       "types": "./dist/linux/index.d.ts",
       "default": "./dist/linux/index.js"
     },
+    "./paperless": {
+      "types": "./dist/paperless/index.d.ts",
+      "default": "./dist/paperless/index.js"
+    },
     "./release": {
       "types": "./dist/release/index.d.ts",
       "default": "./dist/release/index.js"
@@ -72,6 +80,10 @@
       "types": "./dist/caddy/index.d.ts",
       "default": "./dist/caddy/index.js"
     },
+    "./litellm": {
+      "types": "./dist/litellm/index.d.ts",
+      "default": "./dist/litellm/index.js"
+    },
     "./verify": {
       "types": "./dist/verify/index.d.ts",
       "default": "./dist/verify/index.js"
@@ -84,6 +96,7 @@
   "peerDependencies": {
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",
     "@effect/platform-node": "4.0.0-rc.115",
+    "@effect/sql-pg": "4.0.0-rc.115",
     "alchemy": "2.0.0-beta.79",
     "cloudflare": ">=4.5.0",
     "effect": "4.0.0-rc.115",