@homeflare/alchemy 0.23.0 → 0.25.0

package/src/paperless/matching.ts

@@ -0,0 +1,239 @@
+/**
+ * One shape for every Paperless taxonomy object (Tag, DocumentType, StoragePath, CustomField):
+ * locate by `name__iexact` only while there is no prior state, identify the exact (name, owner),
+ * create-or-update, never delete by default. Modelled on `../netbox/resource.ts`'s
+ * `netboxOperations`, with the differences this unit's spec calls for.
+ *
+ * ⛔ THE CREATE BODY ALWAYS CARRIES `owner`, NULL WHEN UNDECLARED. `OwnedObjectSerializer.create`
+ *   sets the owner to the TOKEN USER when the field is absent from the body (Paperless-ngx
+ *   `documents/serialisers.py:495-502` at v3.1.1) — omitting it the way NetBox's `prefix-form.ts`
+ *   omits 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. Sending `owner: null` explicitly is what keeps a create
+ *   idempotent under this vendor's default.
+ *
+ * ★ READ ANSWERS `Unowned(attrs)` ON EVERY MATCH (H1, alchemy-provider-standard). Paperless has no
+ *   ownership marker this package could check — `owner` here is the estate's OWN prop, not proof
+ *   of who created the row — so, per the house's 2026-09-21 decision, identical is not ours: a
+ *   live match never adopts silently. `--adopt` (or `adopt(true)`) resolves it, same as any other
+ *   marker-less API (upstream's `Snippet.ts#read`).
+ *
+ * ⛔ IDENTITY IS THE STORED `id`, NOT `name`/`owner`, ONCE A RESOURCE HAS STATE (PR 163, red-team
+ *   HIGH finding). `diff` and `reconcile` used to re-derive identity from `news` alone on EVERY
+ *   call — `fetchLive` located a live row by `(name, owner)` even when `output` (the engine's
+ *   record of what this declaration last wrote, `Provider.ts#reconcile`'s `output` parameter) was
+ *   right there holding the object's real id. Editing `name` (or `owner`, for the three owned
+ *   families) on an already-deployed resource is the single most ordinary edit anyone would make
+ *   — and it made `fetchLive(news)` miss the row it previously wrote, fall into the create branch,
+ *   POST a SECOND object under the new name/owner, and leave the original permanently orphaned
+ *   (`list()` always answers `[]` by design, so `nuke` can never find it either). `diff` reported
+ *   a plain `{action:'update'}` — nothing told the operator this was about to duplicate and
+ *   abandon an object.
+ *
+ *   The fix: once `output` is defined, `fetchLive` locates by `output.id` (a direct
+ *   `GET {collection}/{id}/`), never by name — a changed `name`/`owner` becomes an ordinary PATCH
+ *   of that same id (Paperless allows PATCHing both on all four types; documents keep their
+ *   tag/type/path because the id never changes). `patchBody`/`matches` now compare `name` and
+ *   (when `spec.owned !== false`) `owner` against the live row too, so the rename/re-own actually
+ *   reaches the PATCH body — locating the right row was necessary but not sufficient. The
+ *   name/owner-based `fetchByName` locate survives ONLY for the no-state path: a genuine first
+ *   create, or the engine's own adoption probe (`provider.read`, called with `output: undefined`
+ *   per `Plan.ts`'s adopt block) — `read` is unchanged and still locates by name for exactly that
+ *   reason. If `output.id` no longer exists live (deleted out of band — by hand, or by another
+ *   tool), `fetchLive` refuses loudly (`Effect.die`) rather than silently falling through to a
+ *   create: a plan that would otherwise read as "ordinary update" instead names the id and tells
+ *   the operator to adopt or clean up state, the same posture `immutable` already uses below for
+ *   `CustomField.dataType`.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { PaperlessRow } from './client.ts';
+import { paperless } from './client.ts';
+import { guardBody } from './constraint-guard.ts';
+import type { PaperlessBody } from './constraints.ts';
+import { absentOn404, matchingLocate, ownerOf } from './matching-locate.ts';
+import type { MatchingProps, MatchingSpec } from './matching-types.ts';
+
+/** Re-exported so `tag.ts`/`document-type.ts`/`storage-path.ts`/`custom-field.ts` keep importing the contract from `./matching.ts` — only the shape itself lives in `matching-types.ts`, split out to hold the file-size cap. */
+export type {
+  FieldSpec,
+  MatchingError,
+  MatchingProps,
+  MatchingRequirements,
+  MatchingSpec,
+} from './matching-types.ts';
+
+/** Object equality good enough for this family's scalars, nullable ints and `extra_data` JSON. */
+const sameValue = (a: unknown, b: unknown): boolean =>
+  typeof a === 'object' && a !== null ? JSON.stringify(a) === JSON.stringify(b) : Object.is(a, b);
+
+export const matchingOperations = <
+  Props extends MatchingProps,
+  Attributes extends { readonly id: number },
+>(
+  spec: MatchingSpec<Props, Attributes>,
+) => {
+  // ★ IDENTITY RESOLUTION LIVES IN `matching-locate.ts` (file-size cap) — `fetchByName` for the
+  //   no-state path, `fetchLive` for the `output.id`-first switch this file's header describes.
+  const { fetchByName, fetchById, fetchLive, objectPath } = matchingLocate<Props>(spec);
+
+  /** ⚠️ ALWAYS NAME-BASED — this is `read`'s own contract (S7): find the object from props alone, with no `output` to consult. Unaffected by the identity switch above. */
+  const read = (props: Props) =>
+    fetchByName(props).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+    );
+
+  const readById = (props: Props, id: number) =>
+    fetchById(id).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+    );
+
+  const createBody = (props: Props): PaperlessBody => {
+    const out: PaperlessBody =
+      spec.owned === false
+        ? { name: props.name }
+        : { name: props.name, owner: props.owner ?? null };
+    for (const field of [...spec.fields, ...(spec.createOnly ?? [])]) {
+      const value = field.prop(props);
+      if (value !== undefined) out[field.key] = value;
+    }
+    return out;
+  };
+
+  /**
+   * ⚠️ Only fields that DIFFER from the live row — a PATCH that repeats an unchanged value is
+   *   still a write the audit log carries for nothing.
+   * ⛔ `name` AND (WHEN OWNED) `owner` ARE COMPARED TOO, NOT JUST `spec.fields`. Locating the
+   *   right row by `id` fixed WHERE the write lands; without this, a rename/re-own would still
+   *   locate correctly and then send an empty-for-those-keys PATCH, so the live object's name or
+   *   owner would silently never change (PR 163).
+   */
+  const patchBody = (props: Props, live: PaperlessRow): PaperlessBody => {
+    const out: PaperlessBody = {};
+    if (props.name !== live['name']) out['name'] = props.name;
+    if (spec.owned !== false && ownerOf(live) !== (props.owner ?? undefined)) {
+      out['owner'] = props.owner ?? null;
+    }
+    for (const field of spec.fields) {
+      const value = field.prop(props);
+      if (value !== undefined && !sameValue(value, field.live(live))) out[field.key] = value;
+    }
+    return out;
+  };
+
+  const matches = (props: Props, live: PaperlessRow): boolean => {
+    if (props.name !== live['name']) return false;
+    if (spec.owned !== false && ownerOf(live) !== (props.owner ?? undefined)) return false;
+    return spec.fields.every((field) => {
+      const value = field.prop(props);
+      return value === undefined || sameValue(value, field.live(live));
+    });
+  };
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* fetchLive(news, output);
+        if (live === undefined) return { action: 'update' } as const;
+        const refusal = spec.immutable?.(live, news);
+        if (refusal !== undefined) return yield* Effect.die(new Error(refusal));
+        if (matches(news, live)) return { action: 'noop' } as const;
+        return spec.endpoint.update === undefined
+          ? ({ action: 'replace' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        const before = yield* fetchLive(news, output);
+        let id: number | undefined;
+        if (before === undefined) {
+          const body = createBody(news);
+          yield* guardBody(spec.endpoint.create, body, true);
+          yield* paperless('POST', `${spec.collection}/`, body);
+        } else {
+          id = typeof before['id'] === 'number' ? before['id'] : undefined;
+          // ⚠️ RE-CHECKED HERE, NOT ONLY IN `diff` — an adoption's first reconcile can run with
+          //   no prior `diff` at all, and `immutable` guards a write that would destroy data.
+          const refusal = spec.immutable?.(before, news);
+          if (refusal !== undefined) return yield* Effect.die(new Error(refusal));
+          if (spec.endpoint.update !== undefined) {
+            const body = patchBody(news, before);
+            if (Object.keys(body).length > 0) {
+              yield* guardBody(spec.endpoint.update, body, false);
+              yield* paperless('PATCH', `${objectPath(before)}/`, body);
+            }
+          }
+        }
+        // ★ READ BACK BY id WHEN WE HAVE ONE — a just-PATCHed row is read back by the id we
+        //   wrote to, not by (possibly just-changed) name, so a rename's own read-back cannot
+        //   fail the way the write it follows no longer can either. A fresh create has no id yet
+        //   to read back by, so that branch still reads back by the name it just created.
+        const after = yield* id === undefined ? read(news) : readById(news, id);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              `${spec.describe(news)}: the write returned no error but the object is still absent.`,
+            ),
+          );
+        }
+        return after;
+      }),
+
+    /**
+     * ⛔ `output.id` FIRST, SAME SWITCH AS `fetchLive` (PR 163 re-review). The engine always
+     *   passes `output` here too (`Apply.ts`'s delete call sites all carry `output: attr`) —
+     *   `olds` is only the PROPS as last persisted, which drifts from the live object exactly
+     *   the way `news` did pre-fix: rename it out of band (by hand, or by another tool) after
+     *   the last successful reconcile, and a name-only locate silently finds nothing, `destroy`
+     *   returns as if there were nothing to delete, and the engine drops the state row anyway —
+     *   reporting "deleted" while the live object survives, permanently orphaned (the same
+     *   consequence `matching.ts`'s header describes for the original bug, on the delete path
+     *   the original fix didn't touch). A 404 on the `output.id` itself is NOT an error here,
+     *   unlike `fetchLive`'s die — it means the object is already gone, which is exactly the
+     *   idempotent success `delete` is supposed to report (S11, alchemy-provider-standard).
+     */
+    destroy: (olds: Props, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        const live = output === undefined ? yield* fetchByName(olds) : yield* fetchById(output.id);
+        if (live === undefined) return;
+        yield* absentOn404(paperless('DELETE', `${objectPath(live)}/`));
+      }),
+  };
+};
+
+/** The five provider handlers for a spec'd Paperless taxonomy object, wired once. */
+export const matchingHandlers = <
+  Props extends MatchingProps,
+  Attributes extends { readonly id: number },
+>(
+  spec: MatchingSpec<Props, Attributes>,
+) => {
+  const ops = matchingOperations(spec);
+  return {
+    /** ⚠️ `[]` — Paperless index endpoints return the whole estate; adoption stays explicit. */
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) =>
+      ops
+        .read(olds)
+        .pipe(Effect.map((attrs) => (attrs === undefined ? undefined : Unowned(attrs)))),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      ops.diff(news, output),
+    // ⛔ `output` IS WHAT MAKES THE IDENTITY FIX WORK (PR 163) — the engine always passes it
+    //   (`Provider.ts#reconcile`), so it is optional here only so a test can still call
+    //   `reconcile({ news })` for a from-nothing create without spelling out `output: undefined`.
+    //   ⚠️ `| undefined` on the optional type itself, not just `?` — `exactOptionalPropertyTypes`
+    //   otherwise refuses the engine's own `output: Attributes | undefined` at the call site.
+    reconcile: ({ news, output }: { news: Props; output?: Attributes | undefined }) =>
+      ops.reconcile(news, output),
+    // ⚠️ `output` PASSED THROUGH, NOT DROPPED — see `destroy`'s own header above (PR 163
+    //   re-review). Same `| undefined` reasoning as `reconcile` just above.
+    delete: ({ olds, output }: { olds: Props; output?: Attributes | undefined }) =>
+      ops.destroy(olds, output),
+  };
+};

package/src/paperless/providers.ts

@@ -0,0 +1,27 @@
+/**
+ * All four Paperless taxonomy providers, one credentials layer shared between them.
+ *
+ *     Layer.mergeAll(paperlessProviders(), …the stack's other providers)
+ *
+ * ⚠️ `HttpClient.HttpClient` IS NOT BUNDLED HERE, and that follows `../netbox/index.ts` and
+ *   `../forgejo/client.ts`'s own precedent (its header: "the idiom Alchemy's own providers
+ *   follow — `Hetzner/Providers.ts` builds on `FetchHttpClient.layer`") rather than diverging
+ *   from it: the transport is the consuming STACK's choice (`FetchHttpClient.layer` in
+ *   production, a fake `HttpClient` in a test), not a house default a provider file should pin.
+ */
+import * as Layer from 'effect/Layer';
+import { CustomFieldProvider } from './custom-field.ts';
+import { DocumentTypeProvider } from './document-type.ts';
+import { type PaperlessCredentials, environmentLayer } from './credentials.ts';
+import { StoragePathProvider } from './storage-path.ts';
+import { TagProvider } from './tag.ts';
+
+export const paperlessProviders = (
+  credentials: Layer.Layer<PaperlessCredentials> = environmentLayer,
+) =>
+  Layer.mergeAll(
+    TagProvider(),
+    DocumentTypeProvider(),
+    StoragePathProvider(),
+    CustomFieldProvider(),
+  ).pipe(Layer.provide(credentials));

package/src/paperless/storage-path.ts

@@ -0,0 +1,78 @@
+/**
+ * `Paperless.StoragePath` — a Paperless-ngx storage path template, create-or-update and never
+ * deleted. Same shape as `document-type.ts` plus the vendor-required `path` template string.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { PaperlessStoragePathRequest } from './generated/types/storage-paths.ts';
+import { type MatchingProps, type MatchingRequirements, matchingHandlers } from './matching.ts';
+
+export interface StoragePathProps extends MatchingProps {
+  /** ⚠️ maxLength 128 (generated constraint table). The locate key. */
+  name: string;
+  /** ⚠️ minLength 1 (generated table). Paperless's storage-path template syntax, e.g. `{correspondent}/{title}`. */
+  path: string;
+  /** ⚠️ maxLength 256. */
+  match?: string;
+  matchingAlgorithm?: PaperlessStoragePathRequest['matching_algorithm'];
+  isInsensitive?: boolean;
+}
+
+export interface StoragePathAttributes {
+  id: number;
+  name: string;
+  path: string;
+  match: string;
+  matchingAlgorithm: number;
+  isInsensitive: boolean;
+  owner: number | undefined;
+}
+
+export interface StoragePath extends Resource<
+  'Paperless.StoragePath',
+  StoragePathProps,
+  StoragePathAttributes,
+  never,
+  MatchingRequirements
+> {}
+
+export const StoragePath = Resource<StoragePath>('Paperless.StoragePath', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const handlers = matchingHandlers<StoragePathProps, StoragePathAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      id,
+      isInsensitive: live['is_insensitive'] === true,
+      match: typeof live['match'] === 'string' ? live['match'] : '',
+      matchingAlgorithm:
+        typeof live['matching_algorithm'] === 'number' ? live['matching_algorithm'] : 0,
+      name: typeof live['name'] === 'string' ? live['name'] : props.name,
+      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
+      path: typeof live['path'] === 'string' ? live['path'] : props.path,
+    };
+  },
+  collection: 'storage_paths',
+  describe: (props) => `storage_paths ${props.name}`,
+  endpoint: {
+    create: 'paperless:POST /api/storage_paths/',
+    update: 'paperless:PATCH /api/storage_paths/{id}/',
+  },
+  fields: [
+    { key: 'path', live: (r) => r['path'], prop: (p) => p.path },
+    { key: 'match', live: (r) => r['match'], prop: (p) => p.match },
+    {
+      key: 'matching_algorithm',
+      live: (r) => r['matching_algorithm'],
+      prop: (p) => p.matchingAlgorithm,
+    },
+    { key: 'is_insensitive', live: (r) => r['is_insensitive'], prop: (p) => p.isInsensitive },
+  ],
+});
+
+export const StoragePathProvider = () =>
+  Provider.effect(StoragePath, Effect.succeed(StoragePath.Provider.of(handlers)));

package/src/paperless/tag.ts

@@ -0,0 +1,91 @@
+/**
+ * `Paperless.Tag` — a Paperless-ngx tag, create-or-update and never deleted by default.
+ *
+ * ★ `matchingAlgorithm` AND THE OTHER ENUM-SHAPED FIELDS ARE INDEXED OFF THE GENERATED REQUEST
+ *   TYPE (`PaperlessTagRequest['matching_algorithm']`), NEVER RETYPED. The literal union `0 | 1 |
+ *   … | 6` comes from `codegen/paperless.ts`'s reading of the vendor's own `MatchingAlgorithm`
+ *   enum — copying it by hand here would be exactly the guess `schema-provenance` doctrine
+ *   forbids, and a vendor that adds a seventh algorithm would leave this type silently stale.
+ *
+ * ⛔ NO CREDENTIAL IS A PROP. `PAPERLESS_URL`/`PAPERLESS_TOKEN` come from `credentials.ts`.
+ * ⛔ `defaultRemovalPolicy: 'retain'` — the reconciler this replaces never deletes taxonomy, and
+ *   a tag's id is referenced by every document it is attached to.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { PaperlessTagRequest } from './generated/types/tags.ts';
+import { type MatchingProps, type MatchingRequirements, matchingHandlers } from './matching.ts';
+
+export interface TagProps extends MatchingProps {
+  /** ⚠️ maxLength 128 (generated constraint table). The locate key — see matching.ts's header. */
+  name: string;
+  /** ⚠️ minLength 1, maxLength 7 (a CSS hex color, generated table doesn't enforce the `#`). */
+  color?: string;
+  /** ⚠️ maxLength 256. The text or pattern documents are matched against. */
+  match?: string;
+  matchingAlgorithm?: PaperlessTagRequest['matching_algorithm'];
+  isInsensitive?: boolean;
+  /** Marks this tag as an inbox tag: newly consumed documents are tagged with it. */
+  isInboxTag?: boolean;
+  /** Another `Paperless.Tag`'s id — Paperless allows one level of tag nesting. */
+  parent?: number;
+}
+
+export interface TagAttributes {
+  id: number;
+  name: string;
+  color: string;
+  match: string;
+  matchingAlgorithm: number;
+  isInsensitive: boolean;
+  isInboxTag: boolean;
+  owner: number | undefined;
+  parent: number | undefined;
+}
+
+export interface Tag extends Resource<
+  'Paperless.Tag',
+  TagProps,
+  TagAttributes,
+  never,
+  MatchingRequirements
+> {}
+
+export const Tag = Resource<Tag>('Paperless.Tag', { defaultRemovalPolicy: 'retain' });
+
+const handlers = matchingHandlers<TagProps, TagAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      color: typeof live['color'] === 'string' ? live['color'] : '',
+      id,
+      isInboxTag: live['is_inbox_tag'] === true,
+      isInsensitive: live['is_insensitive'] === true,
+      match: typeof live['match'] === 'string' ? live['match'] : '',
+      matchingAlgorithm:
+        typeof live['matching_algorithm'] === 'number' ? live['matching_algorithm'] : 0,
+      name: typeof live['name'] === 'string' ? live['name'] : props.name,
+      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
+      parent: typeof live['parent'] === 'number' ? live['parent'] : undefined,
+    };
+  },
+  collection: 'tags',
+  describe: (props) => `tags ${props.name}`,
+  endpoint: { create: 'paperless:POST /api/tags/', update: 'paperless:PATCH /api/tags/{id}/' },
+  fields: [
+    { key: 'color', live: (r) => r['color'], prop: (p) => p.color },
+    { key: 'match', live: (r) => r['match'], prop: (p) => p.match },
+    {
+      key: 'matching_algorithm',
+      live: (r) => r['matching_algorithm'],
+      prop: (p) => p.matchingAlgorithm,
+    },
+    { key: 'is_insensitive', live: (r) => r['is_insensitive'], prop: (p) => p.isInsensitive },
+    { key: 'is_inbox_tag', live: (r) => r['is_inbox_tag'], prop: (p) => p.isInboxTag },
+    { key: 'parent', live: (r) => r['parent'], prop: (p) => p.parent },
+  ],
+});
+
+export const TagProvider = () => Provider.effect(Tag, Effect.succeed(Tag.Provider.of(handlers)));

package/src/postgres/connection.ts

@@ -0,0 +1,62 @@
+/**
+ * Where a database's cluster comes from, and how each lifecycle operation gets a client.
+ *
+ * ⛔ NO ESTATE VALUE LIVES HERE. The kit is PUBLIC; the mini's socket path, its user and its
+ *   database names are the CONSUMER's props, passed to `postgresConnection(...)` in a house
+ *   stack — never a default, never a fallback (`docs/postgres.md#path`).
+ * ★ A LAZY `Context.Service` WHOSE VALUE IS AN `Effect` (S24), THE SAME SHAPE THE HOUSE USES FOR
+ *   CREDENTIALS: `yield* yield* PostgresConnection` resolves the config INSIDE each operation,
+ *   never at layer build. Nothing here holds a secret today (`PostgresConnectionConfig` has no
+ *   `password` — S25, and CREATE DATABASE has none to assert either), but the shape is the one a
+ *   later TLS path (`Config.redacted` from the environment) drops into without a rewrite.
+ * ★ THE POOL IS BUILT IN A SCOPE AND CLOSED PER OPERATION. `Effect.provide(op, PgClient.layer(config))`
+ *   already opens a scope for the layer's build and closes it when `op` finishes — one pool per
+ *   `withPg` call, never held across a whole `reconcile`.
+ */
+import * as PgClient from '@effect/sql-pg/PgClient';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+
+/** What a stack passes to reach one cluster. `host` may be a socket directory (one beginning
+ * with `/` expands to `${host}/.s.PGSQL.${port}` — measured in
+ * `node_modules/@effect/sql-pg/src/PgConnection.ts`, the "Details" doc on `Config`) or a TCP
+ * host name; `port` defaults to `@effect/sql-pg`'s own default (5432) when omitted. */
+export interface PostgresConnectionConfig {
+  readonly host: string;
+  readonly port?: number;
+  readonly database: string;
+  readonly username: string;
+  readonly ssl?: boolean;
+}
+
+/** The lazy connection service. Its value is an `Effect` of the config, per S24 — see the file
+ * header for why. */
+export class PostgresConnection extends Context.Service<
+  PostgresConnection,
+  Effect.Effect<PostgresConnectionConfig>
+>()('Postgres.Connection') {}
+
+/** A stack's one-line way to provide a cluster: `Layer.provide(postgresConnection({ … }))` on
+ * `PostgresDatabaseProvider()`, or merged into the stack's own layer tree. */
+export const postgresConnection = (
+  config: PostgresConnectionConfig,
+): Layer.Layer<PostgresConnection> => Layer.succeed(PostgresConnection, Effect.succeed(config));
+
+/**
+ * Run one operation against a freshly built, freshly closed connection pool.
+ *
+ * Every `read`, `reconcile` step and `delete` in this family calls this once for the whole
+ * operation — never once per statement — so a reconcile that runs a `SELECT`, then a `CREATE`,
+ * then a re-read shares one pool and closes it once, while a plan-only `read` still opens and
+ * closes its own.
+ */
+export const withPg = <A, E>(
+  build: (pg: PgClient.PgClient) => Effect.Effect<A, E>,
+): Effect.Effect<A, E | SqlError, PostgresConnection> =>
+  Effect.gen(function* () {
+    const resolveConfig = yield* PostgresConnection;
+    const config = yield* resolveConfig;
+    return yield* Effect.provide(Effect.flatMap(PgClient.PgClient, build), PgClient.layer(config));
+  });

package/src/postgres/database-attrs.ts

@@ -0,0 +1,87 @@
+/**
+ * `Postgres.Database` props and attributes, and the one prop-level check that runs before any
+ * statement: the name's byte length against `NAMEDATALEN`.
+ *
+ * ⛔ EVERY ASSERTED PROP HERE HAS A CITED COLUMN. `docs/postgres.md#mapping` and
+ *   `database-provenance.test.ts` are what make that true rather than asserted: the test parses
+ *   the two committed fixtures (`create_database.sgml`'s synopsis, `pg_database.h`'s struct) and
+ *   fails if a prop here has no synopsis option or no catalog column behind it.
+ * ⛔ NO PASSWORD, EVER. A database has none in `pg_database` (S25) — `CREATE DATABASE` has no
+ *   password option at all (`gram.y@REL_18_6#createdb_opt_name`, measured: `IDENT | CONNECTION
+ *   LIMIT | ENCODING | LOCATION | OWNER | TABLESPACE | TEMPLATE`).
+ */
+
+/** NAMEDATALEN (`pg_config_manual.h@REL_18_6` line 29) minus the C string terminator: the
+ * longest name the server stores without truncating. */
+export const POSTGRES_NAME_MAX_BYTES = 63;
+
+/** UTF-8 byte length, the same unit `NAMEDATALEN` counts in (`scansup.c@REL_18_6#truncate_identifier`
+ * clips by `pg_mbcliplen`, a byte-oriented, multibyte-aware clip — never a JS `.length`, which
+ * counts UTF-16 code units and would pass a 63-byte multibyte name that is really 70+ bytes, or
+ * refuse a 63-byte name whose `.length` looks smaller). */
+export const utf8ByteLength = (value: string): number => new TextEncoder().encode(value).byteLength;
+
+/**
+ * Declared, at-most-once-asserted properties of one database.
+ *
+ * Every prop here maps to a `CREATE DATABASE` `WITH` option `create_database.sgml` documents
+ * AND a `pg_database` column that stores it (`database-provenance.test.ts`). `TEMPLATE`,
+ * `STRATEGY` and `OID` are excluded because nothing in `pg_database` reads them back once the
+ * database exists; `ICU_RULES` and `COLLATION_VERSION` are excluded for having no consumer in
+ * this family today. See `docs/postgres.md#excluded`.
+ */
+export interface PostgresDatabaseProps {
+  /** At most 63 UTF-8 bytes — refused at plan past that (`PostgresDatabaseNameRefused`). The
+   * identity: a name change is a plan-time refusal, never a replace. */
+  readonly name: string;
+  /** A role name in `pg_roles`, asserted before create (`PostgresDatabaseOwnerMissing`) and
+   * compared against `pg_get_userbyid(datdba)` on every plan thereafter. */
+  readonly owner: string;
+  /** `pg_encoding_to_char(datdatabase.encoding)`, e.g. `"UTF8"`. @default the template's. */
+  readonly encoding?: string;
+  /** `'builtin' | 'icu' | 'libc'` — `pg_database.datlocprovider` decoded
+   * (`pg_collation.h@REL_18_6#collprovider_name`). @default the template's. */
+  readonly localeProvider?: 'builtin' | 'icu' | 'libc';
+  /** `pg_database.datcollate`. @default the template's. */
+  readonly lcCollate?: string;
+  /** `pg_database.datctype`. @default the template's. */
+  readonly lcCtype?: string;
+  /** `pg_database.datallowconn`. @default `true`. */
+  readonly allowConnections?: boolean;
+  /** `pg_database.datconnlimit`; `-1` means unlimited. @default `-1`. */
+  readonly connectionLimit?: number;
+  /** `pg_database.datistemplate`. @default `false`. */
+  readonly isTemplate?: boolean;
+  /** A tablespace name in `pg_tablespace`. @default the template's (usually `pg_default`). */
+  readonly tablespace?: string;
+}
+
+/** Live attributes, read back after every reconcile. No `password` — see the file header. */
+export interface PostgresDatabaseAttributes {
+  readonly name: string;
+  readonly oid: number;
+  readonly owner: string;
+  readonly encoding: string;
+  readonly localeProvider: 'builtin' | 'icu' | 'libc';
+  readonly collate: string;
+  readonly ctype: string;
+  readonly allowConnections: boolean;
+  readonly connectionLimit: number;
+  readonly isTemplate: boolean;
+  readonly tablespace: string;
+}
+
+/**
+ * Refuse a name the server would truncate, before any statement is built.
+ *
+ * ★ CALLED FROM `diff` (so a plan fails, never a deploy) AND FROM `reconcile` (so a fake or a
+ *   direct call gets the same refusal, never just a broken statement).
+ */
+export const nameByteRefusal = (
+  name: string,
+): { readonly byteLength: number; readonly limit: number } | undefined => {
+  const byteLength = utf8ByteLength(name);
+  return byteLength > POSTGRES_NAME_MAX_BYTES
+    ? { byteLength, limit: POSTGRES_NAME_MAX_BYTES }
+    : undefined;
+};