@owlmeans/postgres-resource 0.1.18-rc.3 → 0.1.18-rc.31

package/README.md

@@ -1,32 +1,48 @@
 # @owlmeans/postgres-resource
 
-PostgreSQL-backed `Resource<T>` implementation — schema-driven tables, structure reconciliation,
-code-registered migrations, and custom SQL with resource-alias placeholders.
-
-## Overview
-
-- `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, tableName?)` — factory for Postgres resources
-- `PostgresResource<T>` — extends `Resource<T>` with a Drizzle table, custom SQL, transactions, and field encryption
-- The resource's **AJV schema is the single source of truth for the table structure** — columns, types,
-  nullability, defaults, primary key and indexes are all derived from it
-- A `pg:` keyword vocabulary inside that schema covers what JSON Schema can't express: column types and
-  lengths, foreign keys, composite indexes, checks, partial indexes
-- Tables are created and reconciled automatically at `init()`; migrations run around that in `pre`/`post` stages
+PostgreSQL-backed `Resource<T>`, and the default store for the records a product owns and queries:
+users, orders, projects, invoices, settings, audit rows. The resource's AJV schema is the single
+source of truth for the table, and the package creates and reconciles that table at boot. It also
+runs code migrations around the reconciliation and resolves resource-alias placeholders in custom
+SQL. Other stores fit other shapes:
+- [`@owlmeans/mongo-resource`](../mongo-resource): documents whose shape varies per record and are read whole.
+- [`@owlmeans/redis-resource`](../redis-resource): data defined by expiry, a lock, a counter or fan-out.
+- [`@owlmeans/storage-resource`](../storage-resource): file bytes. The record describing the file stays here.
+- [`@owlmeans/state`](../state): client-side records.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/postgres-resource @owlmeans/postgres pg
+bun add @owlmeans/postgres-resource@^0.1.18-rc.30 @owlmeans/postgres@^0.1.18-rc.31 pg
 ```
 
 `pg` and `ajv` are peer dependencies of this package. `@owlmeans/postgres` provides the connection
 service this package resolves through.
 
+## Concepts
+
+- **The schema is the table**: columns, types, nullability, defaults, primary key, indexes and
+  foreign keys all derive from `resource.schema`. Nothing else writes DDL: no `pgTable`, no
+  `drizzle-kit`, no hand-written `CREATE TABLE`.
+- **`pg:` overrides**: a keyword inside the schema for what JSON Schema cannot say. That covers
+  column type and length, `unique`, `references`, composite indexes, checks, `unmanaged` columns
+  and per-table `autoSync`.
+- **Reconciliation** (`PgAutoSync`): at `init()` the resource introspects the live table, diffs it
+  against the compiled `TableSpec` and applies the DDL plan in one transaction under an advisory
+  lock. `Full` adds, retypes and drops. `Additive` only adds. `Off` emits no DDL.
+- **Migrations**: code bodies registered with `migration(name, apply, stage?)`. `Pre` runs before
+  reconciliation and can rescue data it would drop. `Post` runs after it and can use new columns.
+  Each runs once, in its own transaction, recorded in `_owlmeans_migrations`.
+- **Placeholders**: `{{}}`, `{{alias}}`, `{{alias.property}}`, `{{#alias}}` and `{{$}}` resolve
+  *identifiers only* in custom SQL. Values always travel as `$1..$n` parameters.
+- **Paged by default**: `list(where)` returns at most `DEFAULT_PAGE_SIZE` (100) rows, with the
+  primary key appended to every sort as a tiebreak.
+
 ## Usage
 
-Define a resource:
+### Define and register a resource
 
-```typescript
+```ts
 import { makePostgresResource } from '@owlmeans/postgres-resource'
 import type { PostgresResource } from '@owlmeans/postgres-resource'
 import type { ResourceMaker } from '@owlmeans/resource'
@@ -35,45 +51,60 @@ export interface ProjectResource extends PostgresResource<ProjectRecord> {}
 
 export const makeProjectResource: ResourceMaker<ProjectRecord, ProjectResource> = (dbAlias, serviceAlias) => {
   const resource = makePostgresResource<ProjectRecord, ProjectResource>(
-    RES_PROJECT, dbAlias, serviceAlias, makeProjectResource
+    RES_PROJECT, dbAlias, serviceAlias
   )
   resource.schema = ProjectSchema
   resource.index('idx_project_entity', { columns: ['entityId'] })
 
   return resource
 }
-```
 
-Register in context:
-
-```typescript
+// in the server context factory, next to appendPostgres(context)
 context.registerResource(makeProjectResource())
 ```
 
-Use in a handler:
+### Read and write from a handler
 
-```typescript
+```ts
 const projects = context.resource<ProjectResource>(RES_PROJECT)
-const record = await projects.create({ entityId, alias, title })
-const list = await projects.list({ criteria: { entityId } })
+const record = await projects.create({ entityId, alias, title })     // the database assigns the id
+
+const one = await projects.load({ entityId, alias })                  // null when absent
+const { items, total } = await projects.list(
+  { entityId, status: ['draft', 'active'] },                          // an array means "any of these"
+  { page: 0, size: 20, sort: [{ field: 'createdAt', order: 'desc' }] }
+)
+
+await projects.patch({ id: record.id, status: 'active' })             // merge
+await projects.update({ ...record, title: 'Renamed' })                // replace the whole row
 ```
 
-### Schema → table
+`size` defaults to `DEFAULT_PAGE_SIZE` (100); `list(where, { size: 0 })` lifts the limit. `total`
+always describes the whole match, independently of the page. `entityId` is the organization's
+stable record id from `requireEntityKey(req)`, never a value read off the token.
+
+### Schema to table
+
+```ts
+import { DateSchema } from '@owlmeans/auth'
+import type { JSONSchemaType } from 'ajv'
 
-```typescript
-const ProjectSchema: JSONSchemaType<ProjectRecord> = {
+const InvoiceSchema: JSONSchemaType<InvoiceRecord> = {
   type: 'object',
   properties: {
-    id: { type: 'string', format: 'uuid' },
-    email: { type: 'string', pg: { type: 'varchar', length: 320, unique: true } },
-    ownerId: { type: 'string', pg: { references: { resource: 'users', onDelete: 'cascade' } } },
-    payload: { type: 'object', nullable: true },          // → jsonb
-    createdAt: DateSchema                                  // → timestamptz
+    id: { type: 'string', format: 'uuid' },                          // primary key; never in required
+    entityId: { type: 'string' },
+    number: { type: 'string', pg: { type: 'varchar', length: 32, unique: true } },
+    customerId: { type: 'string', pg: { references: { resource: 'customers', onDelete: 'cascade' } } },
+    status: { type: 'string', enum: ['draft', 'sent', 'paid'] },     // text + CHECK
+    tags: { type: 'array', items: { type: 'string' } },              // text[]
+    lines: { type: 'array', items: { type: 'object' } },             // jsonb
+    note: { type: 'string', nullable: true },
+    createdAt: DateSchema                                            // timestamptz
   },
-  required: ['id', 'email'],
+  required: ['entityId', 'number', 'customerId', 'status'],
   pg: {
-    table: 'app_projects',
-    indexes: [{ name: 'idx_owner_created', columns: ['ownerId', 'createdAt'] }]
+    indexes: [{ name: 'idx_invoice_entity_created', columns: ['entityId', 'createdAt'] }]
   }
 }
 ```
@@ -84,51 +115,40 @@ const ProjectSchema: JSONSchemaType<ProjectRecord> = {
 | `string` + `format: 'uuid'` | `uuid` |
 | `DateSchema` (`{type:'object', format:'date-time'}`) | `timestamptz` |
 | `integer` / `number` / `boolean` | `integer` / `double precision` / `boolean` |
-| `array`, nested `object` | `jsonb` |
+| `array` of plain `string`/`integer`/`number`/`boolean` items | native `<scalar>[]`, e.g. `text[]` |
+| any other `array`, nested `object` | `jsonb` |
 | string `enum` | `text` + `CHECK` |
 | `nullable: true` | nullable column |
 | in `required[]` | `NOT NULL` |
 | `secure: true` | ciphertext column, `lock`/`unlock` aware |
 | `id` property | primary key, `gen_random_uuid()::text` default |
 
-AJV in strict mode rejects unknown keywords — register `pgKeyword` to allow `pg:`:
+AJV in strict mode rejects unknown keywords, so register `pgKeyword` to allow `pg:`:
+
+```ts
+import { pgKeyword } from '@owlmeans/postgres-resource'
 
-```typescript
 ajv.addKeyword(pgKeyword)
 ```
 
-### Structure reconciliation
-
-At `init()` the resource introspects `information_schema` / `pg_catalog`, diffs against the compiled
-spec, and applies the DDL plan in one transaction under a `pg_advisory_xact_lock`, so concurrent
-replicas never race. Policy comes from `DbConfig.meta.autoSync`:
-
-| `PgAutoSync` | Behaviour |
-|---|---|
-| `Full` (default) | add / retype / backfill / drop columns, reconcile indexes and constraints |
-| `Additive` | add only — never retypes, never drops. The adoption path for a pre-existing table |
-| `Off` | create the table if absent, otherwise leave it alone |
+### Migrations
 
-A cast Postgres cannot perform raises `PostgresCastRequired` rather than truncating data. Columns
-listed in `pg.unmanaged` are outside reconciliation's authority entirely.
+```ts
+import { MigrationStage } from '@owlmeans/resource'
 
-### Migrations
+resource.migration('0001-rescue-legacy-slug', async tx => {
+  await tx.execute(`UPDATE {{}} SET slug = legacy_slug WHERE slug IS NULL`)
+}, MigrationStage.Pre)
 
-```typescript
-resource.migration('0001-backfill-slug', async tx => {
-  await tx.execute(`UPDATE {{}} SET slug = lower(title) WHERE slug IS NULL`)
+resource.migration('0002-backfill-status', async tx => {
+  await tx.execute(`UPDATE {{}} SET status = $1 WHERE status IS NULL`, ['draft'])
 }, MigrationStage.Post)
 ```
 
-Stages bracket the structure sync: `Pre` runs **before** the table is reshaped (so a migration can
-rescue data reconciliation would drop), `Post` **after** (so it can use the new columns). Applied
-once, in registration order, each in its own transaction, recorded in `_owlmeans_migrations`.
 Migrations declared on a table this package just created are **baselined**, not executed. An edited
-body raises `MigrationConflict`; a failing one raises `MigrationError` and aborts `init()`.
+applied body raises `MigrationConflict`; a failing one raises `MigrationError` and aborts `init()`.
 
-### Custom SQL
-
-Placeholders resolve **identifiers only** — values stay in `params` and are bound as `$1..$n`:
+### Custom SQL and transactions
 
 | Placeholder | Resolves to |
 |---|---|
@@ -138,11 +158,22 @@ Placeholders resolve **identifiers only** — values stay in `params` and are bo
 | `{{#alias}}` | the bare quoted table name (for `ON CONFLICT ON CONSTRAINT`) |
 | `{{$}}` | the owning resource's quoted schema |
 
-```typescript
-const rows = await projects.select(
-  `SELECT p.* FROM {{}} p JOIN {{users}} u ON u.id = {{self.ownerId}} WHERE u.active = $1`,
-  [true]
+```ts
+const overdue = await invoices.select(
+  `SELECT {{}}.* FROM {{}} JOIN {{customers}} ON {{customers.id}} = {{self.customerId}}
+   WHERE {{self.entityId}} = $1 AND {{self.status}} = $2 AND {{customers.active}} = $3`,
+  [entityId, 'sent', true]
 )
+
+const settled = await invoices.transaction(async tx => {
+  const count = await tx.execute(
+    `UPDATE {{}} SET status = $1 WHERE {{self.customerId}} = $2 AND {{self.status}} = $3`,
+    ['paid', customerId, 'sent']
+  )
+  await tx.execute(`UPDATE {{payments}} SET settled = true WHERE {{payments.customerId}} = $1`, [customerId])
+
+  return count
+})
 ```
 
 An unknown alias or property raises `PostgresPlaceholderError` at parse time rather than being
@@ -150,56 +181,109 @@ substituted blindly.
 
 ## API
 
-### `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, tableName?): T`
+### `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, tableName?): T`
 
 Creates a Postgres resource. `dbAlias` and `serviceAlias` default to `DEFAULT_DB_ALIAS`
 (`'postgres'`). `tableName` overrides the physical table name, which otherwise derives from the alias.
+`schema`, `index()` and `migration()` land in a module-scope declaration keyed by alias.
 
 ### `PostgresResource<T>`
 
-Extends `Resource<T>` with:
+Extends `Resource<T>`, `LockableResource<T>` and `MigratableResource<PostgresTx, PostgresResource<T>>` with:
 
-- `schema?: AnySchema` — the source of truth for the table structure
-- `table: TableSpec` / `entity: PgRuntimeTable` — the compiled spec and the runtime Drizzle table
+- `schema?: AnySchema`, the source of truth for the table structure
+- `table: TableSpec` / `entity: PgRuntimeTable`, the compiled spec and the runtime Drizzle table (after `init()`)
 - `db(): Promise<PostgresDb>` / `client(): Promise<Pool>`
-- `index(name, spec): this` / `migration(name, apply, stage?): this` — chainable declarations
-- `query` / `queryOne` / `execute` — raw rows and affected counts
-- `select` / `selectOne` — rows marshalled back into `T`
-- `ref(alias?): string` — fully qualified identifier of this or another resource
-- `transaction(fn)` — a `PostgresTx` with the same placeholder-aware helpers
-- `insert` / `upsert` / `patch` / `purge` / `count` — beyond the base contract
-- `lock(record, fields?)` / `unlock(record, fields?)` — encrypt/decrypt `secure` fields
+- `index(name, spec: PgIndexSpec)` / `migration(name, apply, stage?)`, chainable declarations
+- `query(text, params?)` / `queryOne(text, params?)` / `execute(text, params?)`, which return raw rows or the affected count
+- `select(text, params?)` / `selectOne(text, params?)`, which return rows marshalled back into `T`
+- `ref(alias?): string`, the fully qualified identifier of this or another resource
+- `transaction(fn)`, which runs `fn` with a `PostgresTx` (`client`, `query`/`queryOne`/`execute`, `ref`)
+- `insert(record)` (a caller-supplied id), `upsert(record, conflict?)`, `patch(record, opts?)` (merge)
+- `lock(record, fields?)` / `unlock(record, fields?)`, which encrypt/decrypt `secure` fields
 - `getDefaults(): Partial<T>`
 
 ### `Resource<T>` methods (all implemented)
 
-`get`, `load`, `create`, `update`, `save`, `delete`, `pick`, `list`
-
-`create` refuses a caller-supplied id (use `insert`); `update` replaces the whole record (use `patch`
-to merge); `pick` deletes the record it returns, atomically.
-
-### Errors
-
-`PostgresError` and its subclasses — `PostgresSyncError`, `PostgresCastRequired`,
-`PostgresConstraintError`, `PostgresForeignKeyError`, `PostgresCheckError`, `PostgresDeadlockError`,
-`PostgresPlaceholderError`, `PostgresConnectionError`, `PostgresBootstrapError`. Driver errors are
-translated by `pgErrorToResourceError`, which unwraps Drizzle's `DrizzleQueryError` to reach the
-`pg` error underneath and preserves the raw `code`/`detail`/`hint`/`severity`. Unique violations
-surface as `RecordExists` and not-null violations as `MisshapedRecord`.
+`get`, `load`, `list`, `count`, `create`, `update`, `save`, `delete`, `take`, `purge`
 
-### Constants
+`get` and `load` take either an id or a `Criteria<T>` (with an optional `sort`), so reading one
+record by several fields is a single statement. `create` refuses a caller-supplied id (use
+`insert`); `update` replaces the whole record (use `patch` to merge); `take` deletes the record it
+returns, atomically, and raises when there is nothing to take where `delete` answers `null`; `purge`
+refuses an empty criteria rather than emptying the table. `ttl` raises `UnsupportedArgumentError`,
+since Postgres has no row expiry.
 
-- `DEFAULT_DB_ALIAS` — `'postgres'`
-- `DEFAULT_PAGE_SIZE` — `10`
-- `DEF_MIGRATIONS_TABLE` — `'_owlmeans_migrations'`
-- `PG_KEYWORD` — `'pg'`; `PG_MAX_IDENTIFIER` — `63`
-- `PgAutoSync`, `PgIndexMethod`, `PgReferentialAction`, `PgErrorCode`
+Criteria follow the shared vocabulary from [`@owlmeans/resource`](../resource). A key naming no
+column raises `UnsupportedArgumentError`. A dotted key reaches into a `jsonb` column, a criteria
+object against a `jsonb` column becomes containment (`@>`), and `$contains`/`$contained`/`$overlaps`
+are `@>`/`<@`/`&&` on array columns.
 
-## Related Packages
+### Errors
 
-- [`@owlmeans/resource`](../resource) — `Resource<T>`, `ResourceRecord`, migrations, error family
-- [`@owlmeans/postgres`](../postgres) — the connection service required by this package
-- [`@owlmeans/mongo-resource`](../mongo-resource) — the MongoDB counterpart
+`PostgresError` and its subclasses are `PostgresSyncError`, `PostgresCastRequired`,
+`PostgresConstraintError`, `PostgresForeignKeyError`, `PostgresCheckError`, `PostgresDeadlockError`
+(`retryable`), `PostgresPlaceholderError`, `PostgresConnectionError` and `PostgresBootstrapError`.
+Driver errors are translated by `pgErrorToResourceError`, which unwraps Drizzle's
+`DrizzleQueryError` to reach the `pg` error underneath and preserves the raw
+`code`/`detail`/`hint`/`severity` in the message. Unique violations surface as `RecordExists` and
+not-null violations as `MisshapedRecord`.
+
+### Exports
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makePostgresResource` | function | The resource factory |
+| `PostgresResource<T>` | type | The resource interface described above |
+| `PostgresDbService`, `PostgresDb`, `PostgresTx`, `PostgresMeta` | type | Connection service contract (implemented by `@owlmeans/postgres`), db handle, transaction façade, `DbConfig.meta` shape |
+| `TableSpec`, `ColumnSpec`, `ColumnJsonType`, `PgRuntimeTable` | type | The compiled table description |
+| `PgPropertyOverride`, `PgRootOverride`, `PgIndexSpec`, `PgUniqueSpec`, `PgCheckSpec`, `PgReferenceSpec` | type | The `pg:` vocabulary and `index()` spec |
+| `LiveTable`, `LiveColumn`, `LiveIndex`, `LiveConstraint`, `DdlPlan`, `DdlStatement`, `DdlKind` | type | Introspection results and the reconciliation plan |
+| `pgKeyword` | const | `{ keyword: 'pg', valid: true }` for AJV strict mode |
+| `schemaToTableSpec`, `toFormatType` | function | The schema compiler |
+| `criteriaToSql`, `sortToSql` | function | `Criteria<T>` to a WHERE clause and `Sort<T>` to ORDER BY over the same table |
+| `refOf`, `resolvePlaceholders`, `resetPlaceholderCache`, `PlaceholderContext` | function / type | `{{alias}}` resolution, identifiers only |
+| `pgTableName`, `pgIdentifier`, `assertSqlIdentifier`, `quoteIdent`, `quoteLiteral`, `qualify`, `advisoryKey` | function | Identifier helpers |
+| `rowToRecord`, `resultToRecord`, `recordToValues`, `recordToFullValues`, `specToTable` | function | Row and record marshalling, Drizzle table construction |
+| `initializeTable`, `applyForeignKeys`, `TableInit` | function / type | The `init()` lifecycle |
+| `introspectTable`, `countNonNull`, `planSync`, `planForeignKeys`, `applyPlan`, `ensureSchema`, `acquireLock`, `releaseLock` | function | Reconciliation machinery |
+| `makeTx`, `makeMigrationStore` | function | The migration façade and ledger |
+| `getDeclaration`, `resetDeclarations`, `PostgresDeclaration` | function / type | Module-scope declarations per alias; `resetDeclarations` is the testing seam |
+| `getSchemaSecureFeilds` | function | `secure: true` properties used by `lock`/`unlock` |
+| `pgErrorToResourceError`, `describePgError`, `PostgresError` family | function / class | Driver error translation |
+| `DEFAULT_DB_ALIAS`, `DEFAULT_PAGE_SIZE`, `DEF_MIGRATIONS_TABLE` | const | `'postgres'`, `100`, `'_owlmeans_migrations'` |
+| `PG_KEYWORD`, `PG_MAX_IDENTIFIER`, `ID_FIELD`, `DEF_SQL_TYPE`, `DEF_JSON_TYPE`, `DEF_ID_DEFAULT`, `STRING_RETURNING_TYPES` | const | Compiler constants |
+| `PgAutoSync`, `PgIndexMethod`, `PgReferentialAction`, `PgErrorCode`, `PgTypeOid` | enum | Reconciliation policy, index methods, FK actions, driver codes, type OIDs |
+
+## Common pitfalls
+
+- **A second owner of the DDL.** Drizzle table definitions, `drizzle-kit` or hand-written
+  `CREATE TABLE` compete with reconciliation, which drops what the other owner added.
+- **`Full` sync on an adopted table drops undeclared columns.** Boot once with `Additive`, confirm
+  the plan comes out empty, then switch to `Full`. Or list the columns in `pg.unmanaged`.
+- **`autoSync: 'off'` never creates the table.** The first query then dies with `42P01`.
+- **Listing `id` in `required`**, or generating ids in application code. The database assigns them,
+  and `create` refuses a supplied id; use `insert` when you really have one.
+- **Interpolating values into SQL.** Placeholders are for identifiers. Values go in `params`.
+- **Aliasing a table that a placeholder still names.** `{{self.x}}` expands to the qualified
+  `"schema"."table"."x"`, which Postgres rejects next to `FROM {{}} p`.
+- **Relying on registration order for `{{alias}}`.** It reads the other resource's *initialized*
+  table spec. Foreign keys to a later resource are deferred by the `appendPostgres` middleware, so
+  do not reorder registrations.
+- **The same index declared twice under different names** (schema root, property override and
+  `index()`). Duplicates are collapsed only by name.
+- **Expecting `update` to merge.** Use `patch`.
+- **Reading "everything" with `list(where)`.** It stops at 100. Use `{ size: 0 }`, or page with a
+  unique tiebreak.
+- **A migration body closed over a loop variable.** Its checksum fingerprints the wrapper and drifts.
+
+## Related packages
+
+- [`@owlmeans/postgres`](../postgres): the connection service required by this package
+- [`@owlmeans/resource`](../resource): `Resource<T>`, `ResourceRecord`, criteria, migrations, error family
+- [`@owlmeans/mongo-resource`](../mongo-resource): the MongoDB counterpart
+- [`@owlmeans/redis-resource`](../redis-resource): caches, locks and expiring records beside the table
+- [`@owlmeans/queue`](../queue): long imports and batch writes that should not run inside a request
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -209,7 +293,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.33
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/postgres-resource",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.509Z",
+  "version": "0.1.18-rc.31",
+  "generatedAt": "2026-09-22T17:37:10.918Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/postgres-resource/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/postgres-resource
 
 **Layer:** Infra
-**Install:** `"@owlmeans/postgres-resource": "^0.1.18-rc.0"` in `dependencies` (peers `pg`, `ajv`)
+**Install:** `"@owlmeans/postgres-resource": "^0.1.18-rc.31"` in `dependencies` (peers `pg`, `ajv`)
 
 The Postgres counterpart of [[mongo-resource]]. The difference that governs everything else: a
 Mongo collection has no structure, a Postgres table does — so **the resource layer owns the DDL**
@@ -18,15 +18,18 @@ and derives it from the resource's AJV schema.
 
 | Export | Description |
 |--------|-------------|
-| `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, maker?, tableName?)` | The resource factory. Aliases default to `DEFAULT_DB_ALIAS` (`'postgres'`). |
-| `PostgresResource<T>` | `Resource<T>` + `table`/`entity`, custom SQL, transactions, `insert`/`upsert`/`patch`/`purge`/`count`, `lock`/`unlock`. |
-| `PostgresDbService`, `PostgresDb`, `PostgresTx` | Service contract implemented by `@owlmeans/postgres`; the db handle `{ drizzle, pool, schema, database }`; the transaction façade. |
+| `makePostgresResource<R, T>(alias, dbAlias?, serviceAlias?, tableName?)` | The resource factory. Aliases default to `DEFAULT_DB_ALIAS` (`'postgres'`); `tableName` overrides the physical table (else the sanitized alias). |
+| `PostgresResource<T>` | `Resource<T>` + `table`/`entity`, `db()`/`client()`, `index`, `ref`, `getDefaults`, custom SQL (`query`/`queryOne`/`execute`/`select`/`selectOne`), `transaction`, `insert`/`upsert`/`patch`, `lock`/`unlock`, `migration`/`migrations`. |
+| `PostgresDbService`, `PostgresDb`, `PostgresTx` | Service contract implemented by `@owlmeans/postgres`; the db handle `{ drizzle, pool, schema, database }`; the transaction façade (`client`, `query`/`queryOne`/`execute`, `ref`). |
+| `PostgresMeta` | The `DbConfig.meta` shape this package reads — `database`, `autoSync`, `url`, and the pool/probe knobs. |
 | `TableSpec`, `ColumnSpec`, `PgPropertyOverride`, `PgRootOverride`, `DdlPlan` | The compiled table description and the `pg:` vocabulary types. |
+| `PgIndexSpec`, `PgUniqueSpec`, `PgCheckSpec`, `PgReferenceSpec` | What `resource.index()` and the `pg:` overrides are written with. |
+| `criteriaToSql`, `sortToSql` | `Criteria<T>` → a WHERE clause and `Sort<T>` → the ORDER BY, for code that builds its own statement over the same table. |
 | `pgKeyword` | `{ keyword: 'pg', valid: true }` — register it when running AJV in strict mode. |
 | `schemaToTableSpec`, `pgTableName`, `pgIdentifier`, `quoteIdent`, `qualify`, `advisoryKey` | The compiler and identifier helpers. |
 | `refOf`, `resolvePlaceholders` | `{{alias}}` resolution — identifiers only. |
 | `PostgresError` family, `pgErrorToResourceError`, `describePgError` | Driver-error translation. |
-| `getDeclaration`, `resetDeclarations` | Module-scope index/migration declarations, keyed by alias. |
+| `getDeclaration`, `resetDeclarations` | Module-scope schema/index/migration declarations, keyed by alias. |
 | `DEFAULT_DB_ALIAS`, `DEFAULT_PAGE_SIZE`, `DEF_MIGRATIONS_TABLE`, `PgAutoSync`, `PgIndexMethod`, `PgReferentialAction`, `PgErrorCode` | Constants. |
 
 ## The schema is the table — never write DDL
@@ -34,7 +37,7 @@ and derives it from the resource's AJV schema.
 ```typescript
 export const makeProjectResource: ResourceMaker<ProjectRecord, ProjectResource> = (dbAlias, serviceAlias) => {
   const resource = makePostgresResource<ProjectRecord, ProjectResource>(
-    RES_PROJECT, dbAlias, serviceAlias, makeProjectResource
+    RES_PROJECT, dbAlias, serviceAlias
   )
   resource.schema = ProjectSchema
   resource.index('idx_project_entity', { columns: ['entityId'] })
@@ -48,12 +51,18 @@ Never call `pgTable`/`pgSchema`, never call `drizzle()`, never run `drizzle-kit`
 `CREATE TABLE`. Two owners of the same DDL is the failure mode this package exists to remove:
 reconciliation would drop what the other owner added.
 
+`schema`, `index()` and `migration()` all land in the module-scope declaration for the alias rather
+than on the resource object, so a maker that runs more than once for the same alias — a custom
+maker wrapping the built-in one, a spec calling it again — reads and extends the same declaration
+instead of starting a fresh, emptier one.
+
 | JSON Schema | Postgres |
 |---|---|
 | `string` · `string`+`format:'uuid'` | `text` · `uuid` |
 | `DateSchema` (`{type:'object', format:'date-time'}`) | `timestamptz` |
 | `integer` · `number` · `boolean` | `integer` · `double precision` · `boolean` |
-| `array`, nested `object` | `jsonb` |
+| `array` of plain `string`/`integer`/`number`/`boolean` items (no `format`, no `enum`) | native `<scalar>[]`, e.g. `text[]` |
+| any other `array` (objects, enums, formatted items, no `items`), nested `object` | `jsonb` |
 | string `enum` | `text` + `CHECK` |
 | `nullable: true` · in `required[]` | nullable · `NOT NULL` |
 | `secure: true` | ciphertext column, `lock`/`unlock` aware |
@@ -90,24 +99,41 @@ declaration sites merge into one `TableSpec` — the schema root, a per-property
 not an error. Two entries under one name would emit the same `CREATE INDEX` twice in a single DDL
 transaction, and Postgres answers the second with `42P07`, rolling back the plan that created the
 table: the resource then fails every boot with an error naming an index that does not exist.
-`byName` in `utils/schema.ts` collapses them and warns.
+The compiler collapses the duplicates itself, keeps the first declaration and warns on the console.
 
 ## Reconciliation is authoritative — `PgAutoSync`
 
-At `init()`: introspect → diff → apply the whole `DdlPlan` in one transaction under
-`pg_advisory_xact_lock`, so concurrent replicas don't race. `DbConfig.meta.autoSync`:
+At `init()`: take a **session** advisory lock on the qualified table name → introspect → diff →
+apply the whole `DdlPlan` in one transaction → release the lock. The lock is session level, not
+`xact`, because it has to span the migrations as well as the DDL, and those run in transactions of
+their own inside it — only the plan itself is one `BEGIN`/`COMMIT`. Concurrent replicas therefore
+serialize on the whole initialization, not just on the DDL. `DbConfig.meta.autoSync`:
 
 | Value | Behaviour |
 |---|---|
 | `Full` (default) | add / retype+backfill / drop columns, reconcile indexes and constraints |
 | `Additive` | add only — never retypes, never drops |
-| `Off` | create if absent, otherwise leave alone |
+| `Off` | **no table DDL** — the structure is never diffed and no statement is emitted, so a missing table is never created and the first query dies with `42P01`. Only for a table something else already provisions |
+
+The schema root override `pg: { autoSync }` is a boolean and wins per table: it turns reconciliation
+back on for one table under `meta.autoSync: 'off'`, and off for one table under the other two modes.
+`Full` versus `Additive` still comes from the config.
 
 **`Full` DROPs columns the schema doesn't declare.** Adopting a table this package didn't create:
 boot once with `Additive`, confirm the plan comes out empty, then flip to `Full`. Columns listed in
 `pg.unmanaged` stay outside reconciliation's authority permanently. A cast Postgres cannot perform
 raises `PostgresCastRequired` instead of truncating.
 
+**A retype drops the column's default first and restores it after.** Postgres refuses
+`ALTER COLUMN … TYPE` outright when the column carries a DEFAULT it cannot cast to the new type
+(`42804 default for column "x" cannot be cast automatically`), and it refuses before reading a
+single row, so `USING` never gets a chance to help. Since the plan is one transaction, that refusal
+aborts the whole reconciliation and the resource then fails *every* boot with an error naming the
+column it is trying to fix. The plan therefore emits `DROP DEFAULT` → `ALTER … TYPE … USING` →
+`SET DEFAULT`, restoring the default from the spec rather than from what the column was carrying.
+The `id` column is where this shows up in practice: it is created with a `gen_random_uuid()::text`
+default, so any change to its declared type takes this path.
+
 ## Migrations bracket the sync
 
 `migration`/`migrations()` implement the shared `MigratableResource` capability from
@@ -141,10 +167,16 @@ resource.migration('0001-rescue-legacy', async tx => {
 
 ```typescript
 await projects.select(
-  `SELECT p.* FROM {{}} p JOIN {{users}} u ON u.id = {{self.ownerId}} WHERE u.active = $1`, [true]
+  `SELECT {{}}.* FROM {{}} JOIN {{users}} u ON u.id = {{self.ownerId}} WHERE u.active = $1`, [true]
 )
 ```
 
+**Do not alias a table a placeholder still names.** Every `{{…}}` expands to the *qualified*
+`"schema"."table"` — `{{self.ownerId}}` to `"schema"."table"."ownerId"` — so aliasing the same table
+as `p` in the `FROM` makes Postgres reject the expansion with `invalid reference to FROM-clause
+entry`. Either write the qualified form throughout, as above, or alias the table and stop using
+`{{self.…}}` for its columns.
+
 Postgres cannot bind an identifier as a parameter — that is the entire reason this mechanism exists.
 Values have no such excuse: they stay in `params` as `$1..$n`. An unknown alias or property raises
 `PostgresPlaceholderError` at parse time.
@@ -158,13 +190,45 @@ middleware `appendPostgres` installs — use that rather than reordering registr
 
 | Method | Semantics |
 |---|---|
-| `create` | refuses a caller-supplied id (`RecordExists`) — use `insert` |
+| `create` | refuses a caller-supplied id (`RecordExists`) — use `insert`; rejects `opts.ttl` with `UnsupportedArgumentError` (mongo parity) |
 | `update` | **replaces** the whole record — use `patch` to merge |
-| `pick` | `DELETE … RETURNING`: it deletes the record it returns, atomically |
-| `load` | rejects `opts.ttl` with `UnsupportedArgumentError` (mongo parity) |
+| `load(where, { sort })` / `get(where, { sort })` | one `SELECT … ORDER BY … LIMIT 1`, so "the newest matching row" is one statement rather than a list whose head is taken |
+| `delete` / `take` | one `DELETE … RETURNING`: the row is handed back by the statement that removed it. `take` **deletes** and throws `UnknownRecordError` on a miss |
+| `purge` | `DELETE … RETURNING` over the criteria; refuses an empty criteria object (`UnsupportedArgumentError('purge:no-criteria')`) rather than truncating the table |
+| `count` | `count(*)` over the criteria, no rows carried back |
 | `upsert` | `INSERT … ON CONFLICT DO UPDATE`, conflicting on the primary key by default |
 | `select`/`selectOne` | custom SQL marshalled back into `T`; `query`/`queryOne` return raw rows |
 
+## Paging
+
+Postgres is **PAGED**: `DEFAULT_PAGE_SIZE` is `100`, so `list(where)` with no `size` returns the
+first 100 rows — a table is unbounded, and an unpaged read is a production incident waiting for the
+row count to grow. `total` is counted separately, so it describes the whole match rather than the
+window, and `list(where, { size: 0 })` lifts the limit: the explicit, greppable way to read a whole
+table.
+
+`sort` becomes the `ORDER BY`, a bare field name ascending, and **the primary key is always
+appended as a tiebreak**. Postgres has no implicit row order, so paginating on a non-unique sort
+key silently duplicates and skips rows between pages — a difference from mongo that would surface
+as a data bug rather than an error.
+
+## Criteria against a table
+
+`criteriaToSql` answers the shared vocabulary ([[resource]]) in SQL, so one criteria object selects
+the same rows here as it does against a collection or in memory. What is specific to a table:
+
+- **A key naming no column raises `UnsupportedArgumentError`.** A typo that silently widened a
+  query to the whole table is worth being loud about — the schemaless stores cannot detect one.
+- **A dotted key reaches into a jsonb column** (`#>>`), and a criteria object against a jsonb
+  column becomes containment (`@>`). A dotted key over a non-jsonb column is refused, and `sort`
+  refuses dotted paths outright: ORDER BY names a column the caller actually declared.
+- `$contains`/`$contained`/`$overlaps` are the array operators `@>`, `<@` and `&&`;
+  `$like`/`$ilike` are `LIKE`/`ILIKE`; `$exists: true` and `$null: false` are `IS NOT NULL`, their
+  negations `IS NULL`.
+- **`{ $in: [null, …] }` is widened explicitly.** SQL `IN` never matches NULL, so a null in the
+  list would silently disappear; the condition becomes `IN (…) OR IS NULL` (and the `$nin` form
+  `NOT IN (…) AND IS NOT NULL`), which is what the other stores answer.
+
 ## Errors
 
 Drizzle raises `DrizzleQueryError` and hangs the `pg` error off `cause`, so the driver `code` is not
@@ -175,9 +239,9 @@ translation — consumers classify retryable DDL races on `42P01`/`42703`.
 
 ## Config
 
-`DbConfig.schema` is the Postgres **SCHEMA** (layer-suffixed by `dbName()`); the **DATABASE** comes
-from `meta.database` and is never suffixed. Values starting with `/` are read as files by the
-existing `fileConfigReader` middleware.
+`DbConfig.schema` is the Postgres **SCHEMA** (the service's `name(alias?)` returns it as given); the
+**DATABASE** comes from `meta.database`. Values starting with `/` are read as files by the existing
+`fileConfigReader` middleware.
 
 ## Tests
 

package/build/consts.d.ts

@@ -1,5 +1,12 @@
 export declare const DEFAULT_DB_ALIAS = "postgres";
-export declare const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Rows `list()` returns when the caller names no `size`.
+ *
+ * A relational table is unbounded, so an unpaged read is a production incident waiting for
+ * the row count to grow. Asking for everything stays possible — and greppable — as
+ * `list(where, { size: 0 })`.
+ */
+export declare const DEFAULT_PAGE_SIZE = 100;
 /**
  * Table that records which code-registered migrations have already been applied.
  * Lives in the same Postgres schema as the resources it tracks, so dropping the

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,gBAAgB,aAAa,CAAA;AAE1C,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAA;AAE1D,oEAAoE;AACpE,eAAO,MAAM,UAAU,OAAO,CAAA;AAE9B,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC,qFAAqF;AACrF,eAAO,MAAM,QAAQ,OAAO,CAAA;AAE5B,iFAAiF;AACjF,eAAO,MAAM,YAAY,SAAS,CAAA;AAElC,eAAO,MAAM,aAAa,UAAU,CAAA;AAEpC,sEAAsE;AACtE,eAAO,MAAM,cAAc,4BAA4B,CAAA;AAEvD;;;;;;GAMG;AACH,oBAAY,UAAU;IACpB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,GAAG,QAAQ;CACZ;AAED,oBAAY,aAAa;IACvB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,oBAAY,mBAAmB;IAC7B,QAAQ,cAAc;IACtB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,OAAO,aAAa;IACpB,UAAU,gBAAgB;CAC3B;AAED;;;GAGG;AACH,oBAAY,WAAW;IACrB,eAAe,UAAU;IACzB,mBAAmB,UAAU;IAC7B,gBAAgB,UAAU;IAC1B,cAAc,UAAU;IACxB,cAAc,UAAU;IACxB,eAAe,UAAU;IACzB,cAAc,UAAU;IACxB,eAAe,UAAU;IACzB,eAAe,UAAU;IACzB,YAAY,UAAU;IACtB,gBAAgB,UAAU;IAC1B,yBAAyB,UAAU;IACnC,yBAAyB,UAAU;IACnC,sBAAsB,UAAU;IAChC,oBAAoB,UAAU;IAC9B,gBAAgB,UAAU;IAC1B,mBAAmB,UAAU;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,YAAI,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAU,CAAA;AAEhG,uFAAuF;AACvF,oBAAY,SAAS;IACnB,IAAI,OAAO;IACX,SAAS,OAAO;IAChB,WAAW,OAAO;CACnB"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,gBAAgB,aAAa,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAA;AAE1D,oEAAoE;AACpE,eAAO,MAAM,UAAU,OAAO,CAAA;AAE9B,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC,qFAAqF;AACrF,eAAO,MAAM,QAAQ,OAAO,CAAA;AAE5B,iFAAiF;AACjF,eAAO,MAAM,YAAY,SAAS,CAAA;AAElC,eAAO,MAAM,aAAa,UAAU,CAAA;AAEpC,sEAAsE;AACtE,eAAO,MAAM,cAAc,4BAA4B,CAAA;AAEvD;;;;;;GAMG;AACH,oBAAY,UAAU;IACpB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,GAAG,QAAQ;CACZ;AAED,oBAAY,aAAa;IACvB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,oBAAY,mBAAmB;IAC7B,QAAQ,cAAc;IACtB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,OAAO,aAAa;IACpB,UAAU,gBAAgB;CAC3B;AAED;;;GAGG;AACH,oBAAY,WAAW;IACrB,eAAe,UAAU;IACzB,mBAAmB,UAAU;IAC7B,gBAAgB,UAAU;IAC1B,cAAc,UAAU;IACxB,cAAc,UAAU;IACxB,eAAe,UAAU;IACzB,cAAc,UAAU;IACxB,eAAe,UAAU;IACzB,eAAe,UAAU;IACzB,YAAY,UAAU;IACtB,gBAAgB,UAAU;IAC1B,yBAAyB,UAAU;IACnC,yBAAyB,UAAU;IACnC,sBAAsB,UAAU;IAChC,oBAAoB,UAAU;IAC9B,gBAAgB,UAAU;IAC1B,mBAAmB,UAAU;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,YAAI,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAU,CAAA;AAEhG,uFAAuF;AACvF,oBAAY,SAAS;IACnB,IAAI,OAAO;IACX,SAAS,OAAO;IAChB,WAAW,OAAO;CACnB"}

package/build/consts.js

@@ -1,5 +1,12 @@
 export const DEFAULT_DB_ALIAS = 'postgres';
-export const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Rows `list()` returns when the caller names no `size`.
+ *
+ * A relational table is unbounded, so an unpaged read is a production incident waiting for
+ * the row count to grow. Asking for everything stays possible — and greppable — as
+ * `list(where, { size: 0 })`.
+ */
+export const DEFAULT_PAGE_SIZE = 100;
 /**
  * Table that records which code-registered migrations have already been applied.
  * Lives in the same Postgres schema as the resources it tracks, so dropping the