@happyvertical/smrt-core 0.40.69 → 0.40.70

package/AGENTS.md

@@ -17,6 +17,7 @@ subsystem you are editing. This file keeps what holds across all of them.
 | `src/change-feed.ts` | the adapter-agnostic change-observation spine — `_smrt_changes`, cursors, table versions, generated `_changes` routes, retention | [agents/change-feed.md](agents/change-feed.md) |
 | `src/change-signals.ts` + the generated `_events` SSE route | the push companion to the change feed — the signal bus, cross-replica fan-out, the SSE route, and its documented gaps | [agents/change-signals.md](agents/change-signals.md) |
 | `src/generators/` + `src/vite-plugin/web-collections.ts` | REST/CLI/MCP/web-collection generation, the `manifestHash` emission sites, and generated conditional-GET / ETag v2 semantics | [agents/generators.md](agents/generators.md) |
+| `src/schema/` | the five `SchemaGenerator` entry points, which two reach production, why schema drift stayed invisible, and the #2382 index/tenancy rules | [agents/schema-paths.md](agents/schema-paths.md) |
 
 ## SmrtObject Lifecycle
 
@@ -25,6 +26,7 @@ subsystem you are editing. This file keeps what holds across all of them.
 - `initialize()`: loads field initializers, applies option values (options override initializers), loads from DB if id/slug provided
 - `save()`: upsert with STI validation, interceptor execution, auto-embeddings. Persisted objects (`isPersisted` — set by DB hydration and successful saves) upsert on `['id']` so natural-key edits (e.g. slug renames) update in place; new objects upsert on the natural-key conflict columns for ingestion-style dedup (#1472)
 - `is(criteria)` / `do(instructions)` / `describe()`: AI operations via function calling. They inject the object's own `toPublicJSON()` (sensitive fields stripped) as a "content body" so the model reasons over the instance. Options: `includeData: false` skips injection (for callers that already curate the relevant fields into the instruction); `maxDataLength` overrides the truncation budget. Neither key is forwarded to `ai.message()`. (#1567)
+- `save()` error contract (#2366): unique/PK violation → `ValidationError` `VALIDATION_UNIQUE_CONSTRAINT`, NOT NULL → `VALIDATION_REQUIRED_FIELD`, both on the first attempt on every adapter; any other database failure → `DatabaseError` with the driver error on `cause`
 - `getSlug()`: auto-generates from name → title → label → id
 - `loadRelated(fieldName)`: lazy-loads relationships (cached in `_loadedRelationships` Map)
 
@@ -74,7 +76,7 @@ references). Re-adding either requires the query builder to support it first;
 `src/__tests__/issue-2276-where-contract.test.ts` executes every accepted
 operator against a database to keep the two in step.
 
-STI child collections auto-filter by `_meta_type`.
+STI child collections auto-filter by `_meta_type`. Query bounds — `LIMIT 1` on `get()`, the `limit`/`offset` parser, the `orderBy` whitelist and sensitive/permission refusals, and the deterministic generated-list ordering (#2367) — are in [agents/query-bounds.md](agents/query-bounds.md).
 
 ## Bounded Collection Read Plans
 
@@ -97,7 +99,7 @@ Two persistence primitives every `SmrtObject`/`SmrtCollection` inherits — load
 
 ## @smrt() Decorator Options
 
-Key options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`, `ui` (`{ icon, label, description }` — nav/help hints round-tripped through the manifest as plain data; `description` is the object-level seed for form-level help, #2046).
+Key options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `indexes` (declared multi-column indexes, #2357 — see "Schema paths"), `api`/`mcp`/`cli` (generation config), `ai` (callable methods), `hooks` (beforeSave/afterSave/beforeDelete/afterDelete), `embeddings` (auto-generate), `tenantScoped`, `agent`, `ui` (`{ icon, label, description }` — nav/help hints round-tripped through the manifest as plain data; `description` is the object-level seed for form-level help, #2046).
 
 Registration sets `SMRT_TABLE_NAME` static property (survives minification).
 
@@ -203,13 +205,36 @@ byte/provenance/path/content drift, skips scans and manifest writes, and still
 generates routes, types, registration, and virtual modules. Omit it for normal
 local development and watch mode.
 
+## Schema paths (#2382)
+
+Production DDL comes from the **manifest** paths
+(`generateSTISchemaFromManifest`/`generateCTISchemaFromManifest`, selected in
+`src/scanner/manifest-generator.ts` → registered `schema` → `db:migrate`). The
+**registry** paths feed `getTestDatabase()` and emit foreign-key indexes
+production never gets: the suite runs on a richer schema than it ships.
+
+- Change column/index emission on every shipping path, proven by a path-parity
+  test (#2359 adds one). A "same as migrations" comment is a claim to check.
+- Every new query predicate ships with its index, or a reason it doesn't.
+- Numeric types, uuid casts, conflict targets, timestamps, migrations: run the
+  `test:postgres` lane — SQLite affinity accepts what PostgreSQL rejects.
+- Read `dist/manifest.json`/regenerated schemas for what a decorator produced;
+  count across all packages instead of sampling.
+- Tenant scoping is whole-path: every unique constraint and conflict target on a
+  tenant-scoped table carries the tenant column, and every read path — not only
+  `list()` — is interceptor-aware.
+- Rolling indexes out is part of the change: a bulk `CREATE INDEX` batch needs
+  the bounded, concurrent migrate path (#2362, Gotchas), or it takes production
+  down on deploy.
+
 ## Gotchas
 
 - **Filesystem support is a lazy boundary (#1979)**: `SmrtClass` acquires `options.fs` adapters via `createFilesystemAdapter()` (`src/filesystem-loader.ts`), never a static `@happyvertical/files` import — the files SDK statically pulls @aws-sdk/client-s3 and reaches googleapis, and a static edge here would land it in every downstream SSR bundle. Node/tsx/vite-dev runtimes resolve it on first use; fully-bundled deployments import `@happyvertical/smrt-core/filesystem` at startup. Use `importOptionalDependency()` (`src/lazy-external.ts`) for any similar optional heavyweight dependency.
 - **Never override toJSON()** — handles STI discriminator + meta field extraction. Use `transformJSON()`
 - **Property init order**: TypeScript initializers run first, then `initialize()` applies option values (options win)
-- **No runtime schema creation**: application tables must be prepared explicitly via migrations/tooling; runtime only verifies and fails clearly
-- **Retry logic**: `db.get()` (3 retries, 250ms) and `db.upsert()` (3 retries, 500ms) have built-in retry
+- **No runtime schema creation**: application tables must be prepared explicitly via migrations/tooling; runtime verification is `tableExists()` only (`src/schema/table-verifier.ts`) — no column, type, or index check
+- **PostgreSQL migrate batches are always time-bounded (#2362)**: `MigrationTracker.applyAll({ atomic: true })` emits `SET LOCAL lock_timeout`/`statement_timeout` before any DDL, so a batch blocked on one table cannot hold its earlier locks indefinitely. `postgresSafe: true` adds concurrent-index mode — non-index DDL commits atomically, then index DDL runs `CONCURRENTLY` on a session pinned via `db.acquireSession()` (a pooled `db.query` would not keep the `SET` and the DDL on one connection). That mode is deliberately **not atomic**: unfinished index migrations are recorded `failed`, not `running`, and their `error_message` carries a `[smrt: concurrent-index phase 1 committed]` marker so a reconciling re-run resumes at the index build instead of replaying committed DDL. INVALID indexes are found via `pg_index.indisvalid` (`pg_indexes` reports them as present) and dropped before rebuild. Operational detail: `packages/cli/AGENTS.md`.
+- **Retry logic is transient-only (#2366)**: `db.get()`/`db.upsert()` retry 4× total (initial + 3), but `ErrorUtils.withRetry` classifies via the cause chain (`src/db-errors.ts`) and rethrows deterministic failures immediately — constraint violations, bad input syntax, missing tables, aborted PG tx (`25P02`). `@happyvertical/sql` stringifies the driver text into `context.originalError`, so **never match `error.message`**; use `classifyDatabaseError()` / `isUniqueViolationError()` / `isAbortedTransactionError()`.
 - **Field caching**: `_cachedFields` populated during `Collection.create()` — eliminates async `getFields()` per query
 - **Smart cloning**: arrays/objects shallow-cloned in property init to prevent aliasing (Issue #22)
 - **Table verification cache**: `isTableVerified(dbUrl, tableName)` avoids redundant `tableExists()` calls

package/README.md

@@ -425,7 +425,26 @@ Every `SmrtObject`/`SmrtCollection` can persist learned knowledge via `remember(
 | `AIError` | AI provider failures |
 | `ValidationError` | Field/object validation failures |
 | `RuntimeError` | General runtime failures |
-| `ErrorUtils` | Sanitization and formatting helpers |
+| `ErrorUtils` | Retry policy (`withRetry`, `isRetryable`) plus sanitization helpers |
+
+### Database error classification
+
+Driver errors reach the model layer wrapped by `@happyvertical/sql`, which
+stringifies the driver text into `context.originalError` — so the constraint
+wording never appears on `error.message`. Classify through the cause chain
+instead of matching messages.
+
+| Export | Description |
+|--------|------------|
+| `classifyDatabaseError` | Walks the cause chain and returns the kind plus `deterministic` / `retryable` |
+| `classifyDialectMessage` | Matches a single raw dialect message (the DuckDB fallback) |
+| `isUniqueViolationError` | Unique or primary-key violation anywhere in the chain |
+| `isNotNullViolationError` | NOT NULL violation anywhere in the chain |
+| `isAbortedTransactionError` | Statement issued inside an aborted PostgreSQL transaction (`25P02`) |
+| `isDeterministicDatabaseError` | A retry cannot change the outcome |
+| `isTransientDatabaseError` | Contention or availability; a retry may succeed |
+| `DatabaseErrorKind` | Union of classification kinds |
+| `DatabaseErrorClassification` | Structured result of `classifyDatabaseError` |
 
 ### Tools (AI Function Calling)
 

package/agents/query-bounds.md

@@ -0,0 +1,45 @@
+<!-- Module doc for packages/core/AGENTS.md. Linked from the Modules table there. -->
+
+# Query bounds (#2367)
+
+`src/query-bounds.ts` is the single parser every generated read surface uses for
+`limit`/`offset`. A bound is a non-negative integer or it is a client error:
+malformed input raises a 400-typed `QueryBoundsError` (a `ValidationError`, so
+`withRetry` never retries it and `normalizeTypedHttpError` renders it as a
+structured 400) instead of reaching the driver as `LIMIT NaN`. Oversized pages
+are **clamped** to `MAX_LIST_LIMIT` (1000) rather than rejected, and an explicit
+`0` means zero rows — it is not folded into `DEFAULT_LIST_LIMIT` (50).
+
+- `collection.get()` / `findOne()` / `findById()` emit `LIMIT 1`.
+- `collection.list()` validates `limit`/`offset` but applies **no implicit
+  default**: it is the framework's bulk-read primitive and relationship,
+  junction, hierarchy and `listByIds()` callers all expect every matching row, so
+  a framework-wide default would truncate correct queries. Applications opt in
+  per collection with `defaultListLimit` / `maxListLimit` (validated at
+  construction). The generated surfaces enforce the ceiling on their own
+  untrusted input regardless.
+- `orderBy` runs the same rail as `where` (#1540) and `select` (#1902): terms are
+  checked against the field whitelist and refused for `@field({ sensitive: true })`
+  and `@field({ readPermission })` columns — ordering is a comparison, and
+  `?orderBy=api_secret&limit=1` is an oracle over a column the request may neither
+  filter on nor project — and for fields that are registered but **not
+  column-backed** — `oneToMany`/`manyToMany`/`meta`/`transient`, plus the
+  `id`/`slug`/`context` system columns on a custom-primary-key class, which the
+  schema generator omits — all of which otherwise reach the driver as
+  `no such column` and surface as a 500. The whitelist is skipped only for
+  manifest-less inline test classes (#869), exactly as `where` skips it. `where`
+  still whitelists those omitted system columns; that is a pre-existing gap of
+  the same family, not closed here because `where: { id }` is on internal
+  hydration paths.
+- Every generated list surface (REST, SvelteKit, MCP, and the emitted stdio MCP
+  runtime) pages with `ORDER BY created_at DESC, <pk> ASC` unless the caller
+  supplies `orderBy` — `LIMIT`/`OFFSET` with no ordering is not pagination, and
+  `created_at` alone still ties. `<pk>` follows a declared
+  `@field({ primaryKey: true })` (read from `_meta.primaryKey` in manifests)
+  because custom-primary-key classes have no synthetic `id` column. The stdio
+  runtime gets the per-object ordering baked in via `RuntimeOptions.listOrderBy`;
+  it cannot resolve a primary key on its own. Index: #2363.
+- `listByIds()` chunks its `IN` list at `IN_LIST_CHUNK_SIZE` (900), like the
+  relationship/junction/hierarchy loaders.
+
+Keyset pagination is deliberately out of scope.

package/agents/schema-paths.md

@@ -0,0 +1,328 @@
+# smrt-core/schema paths
+
+Module semantics for `src/schema/` — which `SchemaGenerator` entry point reaches
+a real database, what each one emits, and the rules that keep them in step.
+Package orientation, the cross-module invariants, and the traps that apply
+before editing anything live in [../AGENTS.md](../AGENTS.md) — read that first;
+its "Schema paths" section is the short form of everything below.
+
+Written from the 2026-08-17 database-layer gap assessment (epic #2382). Symbol
+names here are stable; the line numbers the assessment quotes are not, so trust
+this call graph and re-grep before citing a location.
+
+## Five entry points, two of which ship
+
+`src/schema/generator.ts` exposes five index-emitting entry points. They do not
+produce the same schema for the same class.
+
+| Entry point | Selected by | Status |
+|---|---|---|
+| `generateSTISchemaFromManifest` | `src/scanner/manifest-generator.ts` | **production** |
+| `generateCTISchemaFromManifest` | `src/scanner/manifest-generator.ts` | **production** |
+| `generateSTISchemaFromRegistry` | `src/testing/database.ts` (`getTestDatabase()`), `src/schema/utils.ts` (`generateSchema`; `ensureSchema` only as a fallback) | tests + runtime helpers |
+| `generateSchemaFromRegistry` | the same two callers | tests + runtime helpers |
+| `generateSchema` (AST) | the `smrt:schema` virtual module, which has no consumer | dead (#2380) |
+
+Production DDL takes the manifest route:
+
+```
+@smrt() class ─▶ scanner ─▶ manifest.json ─▶ generate{STI,CTI}SchemaFromManifest
+              ─▶ registered `schema` ─▶ ObjectRegistry.getAllSchemasAsDefinitions()
+                 ├─▶ smrt db:migrate | db:diff | db:status
+                 │     (the CLI drives SchemaComparer + MigrationTracker directly)
+                 └─▶ migrateSmrtSchemas() / getPendingSchemaStatements()
+                       (src/migrations/orchestrate.ts — exported for programmatic
+                        use; no in-repo caller outside its own tests)
+```
+
+The suite takes the registry route, and the registry route emits indexes the
+manifest route does not — per-column foreign-key indexes, and STI partial FK
+indexes filtered by `_meta_type`. Tests therefore run against a richer schema
+than any deployment receives. `src/testing/database.ts`'s "Generate schema using
+SchemaGenerator (same as migrations)" comment describes an intent, not the code.
+
+The manifest STI path even populates a `fkColumnsByClass` map and never reads it
+— only its registry counterpart iterates one — and the manifest CTI path has no
+FK loop at all. Both manifest paths then skip the explicit
+`@foreignKey(X, { indexed: true })` opt-in — the CTI one under a comment claiming
+"FK columns and unique columns get their own indexes", which holds on the
+registry paths and not on this one.
+
+`src/schema/utils.ts` sits in between, and the two exports differ:
+
+- `generateSchema()` (reached from `SmrtCollection.generateSchema()`) always
+  rebuilds from the registry and writes the result back into the registry,
+  replacing whatever the manifest registered for that class.
+- `ensureSchema()` (reached from the deprecated `smrt db:setup`) is
+  manifest-first: it takes `ObjectRegistry.getSchema()` plus the merged
+  `getAllSchemasAsDefinitions()` table definition, and only falls back to
+  `generateSchema()` when no schema is registered at all.
+
+So a normal build keeps the manifest schema through `db:setup`, and a
+registry-derived schema is a dev/test artifact. `smrt-content` shows what one
+looks like: `packages/content/src/hooks.server.ts` `bootstrapSchema()` calls
+`generateSchema()` for every registered class and then `ensureSchema()` from the
+SvelteKit `handle` hook on any `/api/*` request, so that process holds
+registry-derived schemas rather than the manifest ones. It reaches only that
+package's own `vite dev` app — the library build excludes the file and the
+package never exports it — but it is the shape to recognize. Check which route a
+process actually took before trusting a reproduction.
+
+## Why the drift stayed invisible
+
+Every drift oracle compares a database with the same artifact that dropped the
+index:
+
+- `verifyPersistenceTable()` (`src/schema/table-verifier.ts`) calls
+  `db.tableExists()` and nothing else. "Runtime verifies schema" has always meant
+  existence-only — no column, type, constraint, or index comparison.
+- `smrt doctor` never opens a database connection.
+- `db:status` and `db:diff` diff the live database against
+  `getAllSchemasAsDefinitions()`, i.e. the manifest projection.
+
+An index the manifest never emitted is "in sync" by construction. That is how a
+production database reached 164 unindexed `tenant_id` columns while `db:status`
+reported no drift (#2356 → #2359). The assessment's other counts — 196/231
+`@foreignKey` and 91/92 `@crossPackageRef` columns with no production index,
+238/238 tables carrying a redundant index on the primary key, zero DB-level
+foreign-key constraints on any engine — come from regenerating every package's
+schema against a live database, so re-measure rather than quote them once the
+epic's fixes land.
+
+## Rules
+
+### 1. Verify against the production path, not the test path
+
+Any change to column or index emission goes on **all** paths that ship and is
+proven by a path-parity test. #2359 adds that test under `src/schema/`; until it
+lands, assert the parity yourself in the nearest generator test — a green suite
+otherwise proves the registry paths only. Read the call graph before believing a
+comment: "same as migrations" was wrong for years.
+
+### 2. Every new query predicate ships with its index
+
+Collection methods, poll loops, auth lookups, junction right-side filters, and
+polymorphic owner lookups all count — or write down why the predicate does not
+need one. For list workloads, EXPLAIN on a PostgreSQL snapshot; the measured
+spread on the assessed workload was 21 ms → 0.1 ms.
+
+### 3. Run the PostgreSQL lane
+
+Anything touching numeric types, uuid casts, upsert conflict targets, timestamps,
+or migrations runs the package's `test:postgres` script:
+
+```bash
+pnpm --filter @happyvertical/smrt-<pkg> test:postgres
+```
+
+core, cli, users, sales, marketing, analytics, and vitest carry the lane.
+SQLite's type affinity accepts values PostgreSQL rejects — a money field declared
+`number = 0` compiles to INTEGER and only fails on PG (#2361).
+
+### 4. Read the built artifact, not the source
+
+What a decorator produced is in `dist/manifest.json` and in regenerated schemas:
+`integer` vs `decimal`, the actual index list, the actual conflict columns. When
+the question is "how many tables/columns/indexes", regenerate and count across
+every package; do not sample a few and extrapolate.
+
+### 5. Index intent belongs on both the constraint and the read path
+
+A conflict target is not automatically a unique index, and a unique index is not
+automatically the index a read path uses. Custom `conflictColumns` replace the
+`(slug, context)` index while `loadFromSlug`/`getId` still query slug+context;
+STI drops `@field({ unique: true })`. Check the pair, not the declaration.
+
+### 6. Multi-tenancy is a whole-path property
+
+Every unique constraint and every conflict target on a tenant-scoped table
+includes the tenant column — otherwise a second tenant's `save()` of the same
+natural key updates the first tenant's row through `DO UPDATE SET` (#2360). And
+every read path is interceptor-aware: hydration (`loadFromId`/`loadFromSlug`),
+get-by-slug, vector search, and collection memory, not only `list()` (#2365).
+
+### 7. Retry only transient errors
+
+Classify through the cause chain (SQLSTATE), never on a message substring, and
+never retry inside an aborted PostgreSQL transaction (`25P02`). Test the
+contract end to end against a real database, not only the classifier (#2366).
+
+### 8. Thread new decorator options through every config-rebuild site
+
+A new `@smrt()` or `@field()` option that affects schema must reach the
+`SchemaGeneratorConfig` type in `src/schema/generator.ts` and every site that
+rebuilds that config — `src/schema/utils.ts` and `src/testing/database.ts` — or
+it is silently dropped on the paths that rebuild it (#2357).
+
+### 9. Delete or wire dead paths, and write docs to what the code does
+
+Dead code that looks canonical misleads the next agent: the AST `generateSchema`
+path, `SchemaOverrideSystem`, and the never-emitted `triggers: []` all read as
+supported surfaces (#2380). Documentation follows the implementation, not the
+intent — say "verifies the table exists" when that is what runs.
+
+### 10. Untracked "known limitation" comments are bugs nobody will read
+
+File the issue and link it from the comment. A `products` comment explaining why
+a conflict-column change was refrained from sat there for months — and
+misdescribed the failure mode the whole time.
+
+### 11. Consumer repair scripts are signals
+
+Downstream repair tooling (anytown's `db-repair-plan.ts` carried column-type
+repairs, missing STI columns and indexes, and `tenant_id` backfills since April)
+is the consumer-side record of framework gaps. Mine it during triage.
+
+### 12. Try to falsify before filing, and treat operations as correctness
+
+Re-verify a finding at source before it becomes an issue — one assessment
+candidate claimed conflict indexes past two columns were narrowed to two
+columns, when only the index *name* is shortened. And an index fix that ships
+without a bounded-timeout, `CONCURRENTLY`-capable migrate path can take
+production down on rollout (#2362).
+
+### 13. Composite indexes are declared, not inferred (#2357)
+
+The generated set only covers foreign keys, unique/conflict columns,
+`updated_at`, the STI discriminator, `tenant_id`, and single columns opted in
+with `@field({ indexed: true })`. A list workload's access path is composite,
+so declare it:
+
+```ts
+@smrt({
+  indexes: [
+    { name: 'contents_tenant_id_publish_date_idx',
+      columns: ['tenantId', 'publish_date'] },
+  ],
+})
+```
+
+`columns` takes field names or column names in access-path order — filter
+columns first, sort column last. Declare columns, not a direction: PostgreSQL
+scans a btree either way, so an ascending index also serves the matching
+`ORDER BY ... DESC` as an ordered scan with no Sort node. `unique` and `where`
+(partial index) are honoured.
+
+`appendDeclaredIndexes()` runs on all five entry points, before
+`ensureTenantIdIndex()`, so a declared composite leading with the tenant column
+replaces the automatic standalone `tenant_id` index rather than duplicating it.
+Unknown columns, malformed entries, and a name collision with a different index
+all fail generation — a silently dropped index only surfaces later as a
+production slowdown. Rule 8 above is why this works at runtime at all.
+
+### 14. Relationship targets resolve to a class name on both paths
+
+`@foreignKey`/`@oneToMany`/`@manyToMany` accept a class, a name string, or a
+`() => Target` thunk. The decorator invokes the thunk and throws when the target
+cannot be resolved (never `related: ''`); the scanner unwraps the same thunk
+from raw source (never `related: '() => Target'`). An unresolved target silently
+costs the relationship edge, `loadRelated()`, and the FK-derived index (#2379).
+A thunk resolves at decoration time, so a target declared later in the same
+module is still in its temporal dead zone — use the string form there.
+
+### 15. A SQLite type change is a table rebuild (#2370)
+
+SQLite has no `ALTER TABLE ... ALTER COLUMN ... TYPE`, so
+`src/migrations/sqlite-rebuild.ts` answers a `type_upgrade` on SQLite with the
+statement list SQLite's own docs prescribe: stage a new table under
+`_smrt_rebuild_<table>`, copy, drop, rename, replay the indexes and triggers.
+`SchemaComparer.compareTable` swaps that plan in for the differ's
+"requires table recreation" placeholder, so `db:migrate` applies it inside the
+normal atomic batch instead of exiting 1 forever.
+
+Four properties of that module are load-bearing; keep them if you touch it:
+
+- **The target shape comes from the live `sqlite_master` DDL**, retyping only
+  the drifted columns. It is not regenerated from the manifest, so the rebuild
+  never becomes an implicit `DROP COLUMN`, and it preserves table constraints,
+  `CHECK`s, and `WITHOUT ROWID`/`STRICT`.
+- **The rebuild is hoisted ahead of the table's other column changes.** Its
+  staging DDL and copy list are captured at diff time, and the differ emits
+  changes in manifest field order, so a new field declared above the retyped
+  one would otherwise run `ALTER TABLE ... ADD COLUMN` first and have the
+  rebuild silently drop it — both statements succeed and the batch commits.
+  Rebuild first, then add columns to the rebuilt table.
+- **The copy carries no `CAST`.** SQLite applies the destination column's
+  affinity on insert — the same conversion a fresh table performs. An explicit
+  cast is worse: non-numeric TEXT cast to REAL/INTEGER silently becomes `0`,
+  and an ISO timestamp cast to NUMERIC-affinity `DATETIME` becomes its year.
+- **It refuses when any table has a foreign key onto the target and
+  `PRAGMA foreign_keys` is ON** (the SMRT adapter's default). `DROP TABLE`
+  performs an implicit `DELETE FROM` that fires `ON DELETE CASCADE` on
+  children, and `defer_foreign_keys` defers constraint *checks*, not FK
+  *actions* — verified: the child rows go. The target's own self-reference
+  counts, because the staging table copies that clause and becomes a child of
+  the table being dropped (verified: a two-row self-referencing table finishes
+  the rebuild holding one row). Such a column stays manual drift.
+- **`PRAGMA legacy_alter_table` brackets the rename**, because SQLite ≥ 3.25
+  re-parses the schema on `ALTER TABLE ... RENAME` and a view still pointing at
+  the just-dropped table makes it fail outright. It is restored immediately
+  after; a rolled-back batch leaves it set on that connection, which is inert
+  here only because nothing else in SMRT renames a table.
+
+All the drifted columns of one table share a single rebuild: the first change
+carries the plan and the rest become `no change needed` comments that the CLI
+classifies as no-ops.
+
+## What the differ compares (#2369)
+
+`SchemaComparer` (`src/migrations/differ.ts`) compares each manifest column's
+type, then — unless the type itself is drifting — its nullability and default,
+and always reports what it will not touch:
+
+- **Strengthening** (`SET NOT NULL`, `SET DEFAULT`) is executable on
+  PostgreSQL/DuckDB. `SET NOT NULL` is preceded by an `UPDATE … WHERE c IS NULL`
+  backfill of the manifest default; without a default the live data is probed
+  and, if NULLs exist, the change is reported (comment SQL + `advisory`) instead
+  of emitting an ALTER that would abort the atomic batch.
+- **Relaxing** (`DROP NOT NULL`, `DROP DEFAULT`) is a report-only advisory until
+  the caller passes `relaxColumns` (`db:migrate --relax-columns`). The manifest
+  can be under-specified (#2372 registration-order weakness), so a live column
+  that is stricter than the manifest is never weakened silently.
+- **Orphans** — DB columns absent from the manifest, DB tables no manifest
+  declares (`SchemaDiff.orphan_tables`), and unclaimed `*_key` unique constraint
+  indexes — are always reported. A NOT NULL orphan without a default is a
+  `warning` advisory (every ORM insert fails on it); `includeDroppedColumns`
+  (`--drop-columns`) drops it, `relaxColumns` relaxes it. Advisory-only changes
+  carry no SQL, never reach the tracker, and do not fail `db:migrate`.
+- **ADD COLUMN** is planned per engine: DuckDB rejects every inline constraint
+  (add with `DEFAULT`, then `SET NOT NULL`, `CREATE UNIQUE INDEX`); SQLite
+  rejects inline `UNIQUE` (separate `CREATE UNIQUE INDEX <table>_<col>_key`, the
+  PostgreSQL constraint-index name, so the orphan sweep leaves it alone) and
+  `NOT NULL` without a default on a populated table; PostgreSQL keeps constraints
+  inline. DuckDB has no `ADD CONSTRAINT`, so the separate index is the only
+  way to add uniqueness there; the bundled DuckDB 1.4.x resolves
+  `ON CONFLICT (col)` through that index (the old #12684 limitation the DuckDB
+  strategy's `requiresInlineUnique()` note describes no longer reproduces —
+  the #2369 DuckDB test pins the upsert), older DuckDB builds may not. A required column with no default is enforced only on an empty table;
+  on a populated one it is added nullable and the `NOT NULL` is reported as a
+  manual follow-up on every engine.
+- **SQLite** has no `ALTER COLUMN`: nullability/default alterations are manual
+  (comment SQL → `db:migrate` exit 1). The #2370 rebuild (rule 15) consumes
+  only `type_upgrade` placeholders today; extending it to rewrite constraints
+  would lift this.
+- Defaults compare through `canonicalizeDefault()`, which folds engine
+  renderings (`'x'::text`, `CAST('t' AS BOOLEAN)`, `CURRENT_TIMESTAMP` vs
+  `now()`) by manifest type; an unclassifiable rendering skips the comparison
+  rather than risking a false positive that would churn every run. The
+  round-trip test (create from each DDL strategy → compare → zero changes) in
+  `src/migrations/__tests__/issue-2369-*.test.ts` guards this.
+
+### 16. `schema.ddl` is a preview, not the table
+
+`SchemaDefinition.ddl` / `manifest.json` `schema.ddl` is the engine-neutral
+CREATE TABLE string from `SchemaGenerator.generateSQL()` with no engine: no
+indexes, no triggers, abstract `REAL`/`JSON`/`UUID`/`TIMESTAMP`. It is kept for
+backward compatibility only. Everything that needs an executable table renders
+`columns` + `indexes` through `getDDLStrategy(engine)` — `db:migrate`
+(`migrations/orchestrate.ts`), `MigrationGenerator` (default
+`materializeStructuredSchema: true`; `false` is a deprecated opt-out),
+`SchemaAggregator`, and `createIsolatedTestDbFromManifest` in smrt-vitest, the
+last two via `src/schema/manifest-schema.ts` (`collectManifestTables` /
+`renderCollectedManifestTable`). The cached string is merged in only for a
+table whose contributors expose no structured columns (hand-authored
+manifests); table constraints that exist only in the string are dropped with a
+warning, as `db:migrate` drops them. Do not add a new consumer of the
+string, and do not write a private CREATE INDEX renderer — the retired ones
+dropped `where` and `jsonPath` (#2358). Every DDL strategy also spells out
+`PRIMARY KEY NOT NULL`: SQLite lets a bare non-INTEGER PRIMARY KEY hold NULL.

package/dist/browser.d.ts

@@ -18,6 +18,7 @@ export * from './class';
 export * from './collection';
 export type { AiUsageConfig, GlobalSignalConfig, MetricsConfig, PubSubConfig, } from './config';
 export { config } from './config';
+export { classifyDatabaseError, classifyDialectMessage, type DatabaseErrorClassification, type DatabaseErrorKind, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isTransientDatabaseError, isUniqueViolationError, } from './db-errors';
 export * from './errors';
 export { type HierarchyView, SmrtHierarchical } from './hierarchical';
 export { type JunctionAttachOptions, type JunctionFilterOptions, SmrtJunction, } from './junction';

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,cAAc,kBAAkB,CAAC;AAEjC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,0BAA0B,EAC1B,KAAK,iCAAiC,GACvC,MAAM,2BAA2B,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD,cAAc,iBAAiB,CAAC;AAEhC,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,cAAc,eAAe,CAAC"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,cAAc,kBAAkB,CAAC;AAEjC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAOlC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,yBAAyB,EACzB,4BAA4B,EAC5B,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,0BAA0B,EAC1B,KAAK,iCAAiC,GACvC,MAAM,2BAA2B,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD,cAAc,iBAAiB,CAAC;AAEhC,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,cAAc,eAAe,CAAC"}

package/dist/browser.js

@@ -8,6 +8,7 @@ import { SignalSanitizer } from "./signals/sanitizer.js";
 import { SignalBus } from "./signals/bus.js";
 import { assertPostgresSystemTimestampsCurrent, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, getDatabaseEngine, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, tableExists } from "./system/compatibility.js";
 import { SmrtClass } from "./class.js";
+import { classifyDatabaseError, classifyDialectMessage, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isTransientDatabaseError, isUniqueViolationError } from "./db-errors.js";
 import { AIError, ConfigurationError, DatabaseError, ErrorUtils, FilesystemError, NetworkError, RuntimeError, SmrtError, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils } from "./errors.js";
 import { convertTypeToJsonSchema, generateToolFromMethod, generateToolManifest, shouldIncludeMethod } from "./tools/tool-generator.js";
 import { executeToolCall, executeToolCalls, formatToolResults, validateToolCall } from "./tools/tool-executor.js";
@@ -21,4 +22,4 @@ import { SmrtPolymorphicAssociation } from "./polymorphic-association.js";
 import "./signals/index.js";
 import "./system/index.js";
 import "./tools/index.js";
-export { AIError, AiUsageCollector, AiUsagePersistenceHandler, ConfigurationError, DEFAULT_AI_COST_RATES, DatabaseError, ErrorUtils, FilesystemError, MetricsAdapter, NetworkError, ObjectRegistry, PubSubAdapter, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, assertPostgresSystemTimestampsCurrent, config, convertTypeToJsonSchema, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, estimateAiUsageCost, executeToolCall, executeToolCalls, formatToolResults, generateToolFromMethod, generateToolManifest, getDatabaseEngine, isSmrtCollectionExtendsName, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, shouldIncludeMethod, smrt, smrt as smrtRegistry, tableExists, validateToolCall };
+export { AIError, AiUsageCollector, AiUsagePersistenceHandler, ConfigurationError, DEFAULT_AI_COST_RATES, DatabaseError, ErrorUtils, FilesystemError, MetricsAdapter, NetworkError, ObjectRegistry, PubSubAdapter, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, assertPostgresSystemTimestampsCurrent, classifyDatabaseError, classifyDialectMessage, config, convertTypeToJsonSchema, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, estimateAiUsageCost, executeToolCall, executeToolCalls, formatToolResults, generateToolFromMethod, generateToolManifest, getDatabaseEngine, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isSmrtCollectionExtendsName, isTransientDatabaseError, isUniqueViolationError, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, shouldIncludeMethod, smrt, smrt as smrtRegistry, tableExists, validateToolCall };

package/dist/class.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"class.d.ts","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"class.d.ts","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":"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"}

package/dist/class.js

@@ -5,6 +5,7 @@ import { SMRT_SCHEMA_VERSION, getSystemTableDDL } from "./system/schema.js";
 import { ensurePostgresChangeFeedAppendFunction, registerChangeFeedWriter } from "./change-feed.js";
 import { config } from "./config.js";
 import { createFilesystemAdapter } from "./filesystem-loader.js";
+import { applyPostgresRuntimeTimeouts } from "./postgres-timeouts.js";
 import { SignalBus } from "./signals/bus.js";
 import { assertPostgresSystemTimestampsCurrent, ensureLegacySystemTableCompatibility, tableExists } from "./system/compatibility.js";
 import { createLogger } from "@happyvertical/logger";
@@ -12,6 +13,25 @@ import { getAI } from "@happyvertical/ai";
 import { getDatabase } from "@happyvertical/sql";
 //#region src/class.ts
 var SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL = "SELECT pg_advisory_xact_lock(hashtext('smrt'), hashtext('system-tables'))";
+/**
+* Timeout budget for the PostgreSQL system-table bootstrap transaction.
+*
+* The runtime pool's session `lock_timeout`/`statement_timeout` (#2377) are
+* sized for request work. This transaction is not request work: it holds the
+* advisory lock across up to 29 sequential DDL round-trips — ~18.85 s on the
+* high-latency link `bootstrapSystemTables` documents — and a second replica
+* cold-starting against the same fresh database *waits* on that lock. Both GUCs
+* bound that wait, because `pg_advisory_xact_lock` is an ordinary statement in
+* the lock manager, so at the runtime defaults the second replica would abort
+* with "canceling statement due to lock timeout" where it previously waited and
+* succeeded.
+*
+* Five minutes is an order of magnitude above the documented worst case and
+* still bounded — this is a raise, not a disable. `SET LOCAL` scopes it to this
+* transaction, the same lever migrations use for the same reason (#2362).
+*/
+var SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_MS = 3e5;
+var SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL = [`SET LOCAL lock_timeout = '${SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_MS}ms'`, `SET LOCAL statement_timeout = '${SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_MS}ms'`];
 var logger = createLogger({ level: "info" });
 function firstString(...candidates) {
 	return candidates.find((candidate) => {
@@ -247,9 +267,10 @@ var SmrtClass = class SmrtClass {
 			} else {
 				if (typeof this.options.db === "string") {
 					const isMemoryDb = this.options.db === ":memory:";
+					const bounded = applyPostgresRuntimeTimeouts({ url: this.options.db });
 					this._db = await getDatabase({
-						url: this.options.db,
-						...isMemoryDb ? {} : { dbid: `smrt:${this.options.db}` }
+						...bounded,
+						...isMemoryDb ? {} : { dbid: `smrt:${bounded.url}` }
 					});
 				} else if ("query" in this.options.db) this._db = this.options.db;
 				else if ("client" in this.options.db && this.options.db.client) {
@@ -262,9 +283,10 @@ var SmrtClass = class SmrtClass {
 				} else {
 					const dbUrl = this.options.db.url || "memory";
 					const isMemoryDb = dbUrl === ":memory:" || dbUrl === "memory";
+					const bounded = applyPostgresRuntimeTimeouts({ ...this.options.db });
 					this._db = await getDatabase({
-						...this.options.db,
-						...isMemoryDb ? {} : { dbid: `smrt:${dbUrl}` }
+						...bounded,
+						...isMemoryDb ? {} : { dbid: `smrt:${bounded.url ?? dbUrl}` }
 					});
 				}
 				/**
@@ -406,6 +428,7 @@ var SmrtClass = class SmrtClass {
 			const tx = await beginTransaction.call(this._db);
 			if (!tx) throw new Error("Database transaction could not be started");
 			try {
+				for (const sql of SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL) await tx.query(sql);
 				await tx.query(SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL);
 				const result = await callback(tx);
 				await tx.commit();
@@ -416,6 +439,7 @@ var SmrtClass = class SmrtClass {
 			}
 		}
 		if (typeof transaction === "function") return transaction.bind(this._db)(async (tx) => {
+			for (const sql of SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL) await tx.query(sql);
 			await tx.query(SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL);
 			return callback(tx);
 		});