@happyvertical/smrt-core 0.45.1 → 0.45.2

package/AGENTS.md

@@ -1,299 +1,91 @@
 # @happyvertical/smrt-core
 
-ORM, code generation, AI integration, and the DispatchBus. Everything else builds on this.
-
-Key surfaces are `SmrtObject`, `SmrtCollection`, `ObjectRegistry`,
-`DispatchBus`, `GlobalInterceptors`, and `LearningMemory`; this file documents
-their invariants and source locations, and the module docs below cover the
-per-subsystem semantics.
+Foundation ORM, registry, schema/code generation, AI integration, and DispatchBus.
+Read the module for the subsystem being edited; root AGENTS covers shared model
+and repository rules.
 
 ## Modules
 
-Subsystem semantics live in sibling module docs — read the one for the
-subsystem you are editing. This file keeps what holds across all of them.
-
-| Module | Scope | Module doc |
+| Source | Scope | Module doc |
 |---|---|---|
-| `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 four `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) |
-| `src/data-query.ts` | canonical bounded data-query normalizer and transport-neutral envelope (#2444) | [agents/data-query.md](agents/data-query.md) |
-| `src/collection.ts` | bounded collection reads, projections, latest-related hydration, facets, counts, and read plans | [agents/collection-reads.md](agents/collection-reads.md) |
-
-## SmrtObject Lifecycle
-
-`constructor(options)` → `initialize()` → ready for `save()`/`delete()`/`loadFromId()`
-
-- `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)
-- Persisted `save()` uses loaded `updated_at` in its `UPDATE`; zero rows throws
-  `RUNTIME_REVISION_CONFLICT`. Explicit `expectedUpdatedAt` binds a save or
-  delete to an earlier snapshot. Remote guarded deletes bind the same predicate
-  into the final `DELETE`; embedded adapters compare inside the shared write queue
-  before cascading. That queue serializes same-process saves, deletes, and full
-  `SmrtObject.withTransaction()` callbacks. Custom writes must preserve this
-  public CAS ordering contract. PostgreSQL predicate:
-  [agents/revision-guard.md](agents/revision-guard.md).
-- Native DuckDB UUID columns are hydrated as canonical strings before model
-  initialization, natural-key lookup, and embedded revision claims. Exact
-  natural-key probes retain the interceptor-authorized filter when
-  canonicalizing a wrapped identity. Custom embedded-CAS paths that consume
-  persisted rows must use `getCanonicalPersistedRow()` so UUID identities are
-  cast in the same coherent read before reuse.
-- `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)
-
-## LearningMemory (#1886)
-
-`LearningMemory` provides tenant-isolated, confidence-scored recall over
-`_smrt_contexts` plus optional injected semantic search. `capture()` reinforces
-successes and decays failures while updating outcome counters; `recall()`
-applies confidence, expiry, time-decay, and hierarchical-scope filters and
-refreshes `last_used_at`. Detailed persistence and search semantics are in
-[agents/memory.md](agents/memory.md). Keep semantic search behind the
-`SmrtCollection.semanticSearch`-compatible injection boundary.
-
-## SmrtCollection Query
-
-```typescript
-await collection.list({
-  where: { status: 'active', 'price >': 10 },
-  limit: 50, offset: 0, orderBy: 'created_at DESC'
-});
-```
-
-Projection, latest-related, facets, counts, and bounded read plans are
-documented in [agents/collection-reads.md](agents/collection-reads.md).
-
-`list()` and `query()` hydrate model instances serially in result order because
-an `initialize()` hook may query through the same transaction-bound PostgreSQL
-client. Keep this serialization invariant; use `select` when callers need plain
-rows without model hydration.
-
-Native DuckDB model hydration casts declared UUID columns to `VARCHAR` in the
-read query because its JavaScript binding otherwise returns lossy HUGEINT
-wrapper objects. Explicit projections apply the same cast for selected UUID
-fields so bounded query envelopes preserve canonical row and relationship ids.
-For STI child columns, raw `query()` SELECTs, and latest-related projections,
-the read path describes the output types without evaluating the query, then
-performs one data-bearing SELECT with UUID result columns cast to `VARCHAR`;
-mutation statements are never reinterpreted or replayed.
-
-**WHERE operators**: `=`, `>`, `<`, `>=`, `<=`, `!=`, `in`, `not in`, `like`.
-Arrays auto-detect `IN`. NULL is a value, not an operator: `{ deletedAt: null }`
-renders `IS NULL` and `{ 'deletedAt !=': null }` renders `IS NOT NULL`.
-
-This list is the set `@happyvertical/sql`'s `buildWhere` can execute, and
-`convertWhereKeys` accepts nothing outside it — an operator accepted here but
-unknown there fails inside the query builder, after the API said the query was
-valid (#2276). Two entries were removed for that reason and now reject at the
-API boundary: `contains` (never existed in the SQL layer; use `like` with
-explicit wildcards) and dot-notation JSON paths such as `metadata.userId` (never
-rewritten into an extraction expression, so they reached SQL as qualified column
-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`. 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).
-
-## Canonical Bounded Data Queries (#2444)
-
-The normalizers and fingerprint are the trust boundary for the
-transport-neutral query envelope; full bounds, schema, and output rules live in
-[agents/data-query.md](agents/data-query.md). Adapters own tenant/principal
-access and query execution.
-
-## Object Memory & Semantic Search
-
-Context memory and semantic search are persistence primitives inherited by
-`SmrtObject`/`SmrtCollection`; their storage, scope, expiry, and tenant
-invariants are in [agents/memory.md](agents/memory.md).
-
-## @smrt() Decorator Options
-
-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).
-
-## @field() UI hints (#2046)
-
-`@field({ ui: { basic, group, order, locked } })` — a static, presentation-only
-seed for the field-policy rail (epic #2045). Carried in the manifest under the
-field's `_meta.ui` (never a top-level `FieldDefinition` key), readable at
-runtime via `getAllFields()` at `field._meta.ui`, and emitted (sanitized) with
-`description` into generated web-collection definitions and browser MCP tool
-schemas. No schema/persistence/security effect — `sensitive`/`readPermission`
-stay the security rail, and `sensitive`/`transient` fields never emit to the
-client at all.
-
-## Domain Knowledge Artifacts
+| `src/object.ts`, `src/collection.ts`, `src/child-accessors.ts` | Lifecycle, hydration, operators, STI, child accessors, dispatch | [agents/object-runtime.md](agents/object-runtime.md) |
+| `src/revision-guard.ts` | Guarded writes and PostgreSQL revision precision | [agents/revision-guard.md](agents/revision-guard.md) |
+| `src/collection.ts` | Projections, latest-related, facets, counts, read plans | [agents/collection-reads.md](agents/collection-reads.md) |
+| `src/collection.ts` | Limits, sort whitelist, generated list order | [agents/query-bounds.md](agents/query-bounds.md) |
+| `src/data-query.ts` | Transport-neutral bounded query normalization | [agents/data-query.md](agents/data-query.md) |
+| `src/schema/`, `src/migrations/`, `src/cascade.ts`, `src/system/` | DDL parity, indexes, migrations, delete integrity, retention | [agents/schema-paths.md](agents/schema-paths.md) |
+| `src/change-feed.ts` | Durable changes, cursors, table versions, retention | [agents/change-feed.md](agents/change-feed.md) |
+| `src/change-signals.ts` | Signal bus, replica fan-out, SSE | [agents/change-signals.md](agents/change-signals.md) |
+| `src/generators/`, `src/vite-plugin/web-collections.ts` | REST/CLI/MCP generation, manifest hashes, ETags | [agents/generators.md](agents/generators.md) |
+| `src/vite-plugin/`, `src/consumer-plugin/`, `src/knowledge.ts` | Decorator UI hints, knowledge projection, generation snapshots | [agents/build-knowledge.md](agents/build-knowledge.md) |
+| `src/object.ts`, `src/collection.ts`, `src/learning/memory.ts` | Context memory and semantic search | [agents/memory.md](agents/memory.md) |
+
+## Cross-module invariants
+
+- `ObjectRegistry` is a `globalThis` singleton so registration survives HMR.
+
+- Production DDL uses manifest generators; `getTestDatabase()` uses registry
+  generators. Keep columns, indexes, FK actions, and runtime conflict targets in
+  parity (`src/schema/schema-path-parity.test.ts`). Every new query predicate
+  needs its index or an explicit reason none is needed.
+- Tenant scoping covers every read and every unique/conflict key. Explicit
+  conflict columns are not rewritten; their author must include tenant scope.
+- Persisted saves use `id` and loaded `updated_at`; new saves use natural keys.
+  Preserve revision compare-and-swap ordering through public `save()`,
+  `claimRevision()`, and transaction APIs. Embedded saves, deletes, and complete
+  `withTransaction()` callbacks share a process-local write queue.
+- Collection model hydration is serial in result order: initialization may query
+  the same transaction-bound PostgreSQL client. Use projections for plain rows.
+- Native DuckDB UUIDs must be cast coherently on read before identity reuse;
+  custom embedded revision paths use `getCanonicalPersistedRow()`. Never replay
+  a mutation to discover result types.
+- `withDatabase(db, callback)` restores only database bindings (including public
+  `options.db`); `withTransaction(callback)` also restores identity/revision
+  metadata after rollback. Do not use a bound instance concurrently.
+- `ensureSystemTables(db, typeHint?)` provisions framework tables idempotently;
+  call it on a base PostgreSQL connection before caller-owned transactions.
+  Bootstrap uses an advisory lock. Application tables still require migrations;
+  runtime table verification checks existence only.
+- Manifest generation fails closed on scanner errors, including unresolved
+  decorator spreads. Never emit partial, default-open registration.
+- Generated registration repairs bundled class identity using the exact imported
+  constructor, explicit package, and isolated one-object manifest. Never infer
+  ownership from paths, simple names, or table names; packages can share names.
+  Consumer regression gate: `packages/bundle-gate/src/__tests__/registry-identity.spec.ts`.
 
-`smrtPlugin()` writes runtime manifests and agent/developer knowledge artifacts:
-
-- local dev/build: `.smrt/manifest.json` and `.smrt/smrt-knowledge.json`
-- package build: `dist/manifest.json` and `dist/smrt-knowledge.json`
-
-Keep `manifest.json` runtime-focused. `smrt-knowledge.json` is the deterministic
-agent contract for downstream review and architecture tools.
-
-The schema-version-1 object projection is additive and high-signal: it retains
-normalized tenant mode/field, explicit `cti`/`sti` strategy, conflict columns,
-method signatures, and field defaults/constraints/readonly/transient flags.
-Sensitive fields are removed before both `fields` and `relationships` are
-derived, including legacy flags stored under `_meta`; matching field and
-snake-case column names are also removed from projected conflict columns, and a
-sensitive custom tenant field is omitted while retaining scope and mode.
-Generated artifacts assert this boundary with `sensitiveFieldsExcluded: true`;
-the optional marker keeps schema version 1 additive while letting readers
-identify older artifacts that require raw-manifest corroboration.
-
-Config precedence for knowledge is defaults → top-level `knowledge` in
-`smrt.config.ts` → `packages[packageName].knowledge` → plugin option →
-object-level `@smrt({ knowledge })`.
-
-Object-level `knowledge: false` excludes an object from authored context only;
-it must not change runtime manifest registration. Use
-`knowledge: { tags, summary, risks }` for review-sensitive domain objects.
-
-HTTP knowledge routes are disabled by default. If `knowledge.api.enabled` is
-true, generated SvelteKit routes must stay GET-only and guarded by dev mode or
-admin auth.
-
-## DispatchBus
-
-- `emit(signalType, payload, metadata)` → creates persistent Dispatch record
-- `on(pattern, handler)` → in-memory handler (immediate)
-- `subscribe({ signalType, subscriber })` → persistent subscription (survives restarts)
-- `process(subscriberName, handler)` → process pending dispatches
-- Wildcards: `campaign.*` matches `campaign.completed` (single segment only)
-- Tables: `_smrt_dispatch`, `_smrt_dispatch_subscriptions`
-- Status: `pending → processing → completed` (or `failed`)
-
-## Single Table Inheritance (STI)
-
-- Base: `@smrt({ tableStrategy: 'sti' })` — children inherit, share one table
-- Discriminator: `_meta_type` column with qualified names (`@happyvertical/smrt-content:Article`)
-- Child fields: `@meta()` decorator → stored in `_meta_data` JSONB (not as columns)
-- Polymorphic queries: collection loads `_meta_type`, creates correct subclass dynamically
-- Validation: fail-fast on save if `_meta_type` missing or mismatched
-
-## Child Accessors (R10)
-
-`src/child-accessors.ts` installs a consistent `get<FieldName>()` instance method for every `@oneToMany` field at `@smrt()` registration time (e.g. `@oneToMany('OrderItem') items` → `order.getItems()`), delegating to `loadRelatedMany`. Two invariants:
-
-- **Additive** — never overwrites a hand-rolled method of the same name (checks the whole prototype chain). `Profile.getMetadata()` (key-value) and `ProfileRelationship.getTerms()` are preserved.
-- **Runtime-only** — attached to the prototype, invisible to the build-time manifest, so it never leaks into the REST/CLI/MCP surface.
-
-When the target declares multiple FKs back to the parent, annotate `@oneToMany(Target, { foreignKey: '<inverseField>' })`; `loadRelatedMany` and the eager `include:` loader both honor it (else first-match).
-
-## Vite Plugin
+## Gotchas
 
-```typescript
-// vite.config.ts — required for @smrt() decorators (Vite 8+, oxc transform)
-export default defineConfig({
-  oxc: {
-    decorator: {
-      legacy: true,
-      emitDecoratorMetadata: true,
-    },
-  },
-});
+- Optional filesystem support stays lazy: use `createFilesystemAdapter()` in
+  `src/filesystem-loader.ts`, not a static files-SDK import. Fully bundled apps
+  import `@happyvertical/smrt-core/filesystem` at startup. Use
+  `importOptionalDependency()` for similarly heavy optional dependencies.
+- Database retries are transient-only, four attempts total for `get`/`upsert`.
+  Use `src/db-errors.ts` classifiers through the cause chain, never message
+  matching (SDK driver text can live in `context.originalError`). Constraints,
+  bad input, missing tables, and aborted PostgreSQL transactions fail immediately.
+  Unique/PK violations become `VALIDATION_UNIQUE_CONSTRAINT`, NOT NULL becomes
+  `VALIDATION_REQUIRED_FIELD`; other failures keep the driver error as `cause`.
+- Property initializers precede option values; options win. Arrays/objects are
+  shallow-cloned. Collection creation caches fields; table verification caches
+  by DB URL and table. Preserve these scopes when changing initialization.
+- The Vite plugin loads scanner/schema code from `dist/` when present. Rebuild
+  core after editing those sources before testing consumer manifest generation.
+  Vite 8 requires `oxc.decorator: { legacy: true, emitDecoratorMetadata: true }`.
+
+## Validation
+
+Run focused tests first, then applicable package checks:
+
+```bash
+pnpm --filter @happyvertical/smrt-core test
+pnpm --filter @happyvertical/smrt-core typecheck
+pnpm --filter @happyvertical/smrt-core build
+pnpm --filter @happyvertical/smrt-core test:postgres
+pnpm check:agents-chain
+pnpm smrt dev:knowledge-check
 ```
 
-Under Vite 8 the oxc transform does not honor the pre-Vite-8 `esbuild.tsconfigRaw`
-recipe (or tsconfig `experimentalDecorators` reached through SvelteKit's
-`extends "./.svelte-kit/tsconfig.json"` chain), so that recipe throws
-`SyntaxError: Invalid or unexpected token` on the first SSR request. Configure
-decorators through `oxc.decorator` instead. Consumers still pinned on vite<8 need
-the legacy `esbuild.tsconfigRaw` form with `experimentalDecorators: true,
-emitDecoratorMetadata: true`.
-
-For independent CI invocations, both `smrtPlugin()` and `smrtConsumer()` accept
-the same `generationSnapshot: { path, sha256, provenance, sourceRoot }`. The
-schema-v1 snapshot produced by `serializeSmrtGenerationSnapshot()` contains the
-merged project/dependency manifest, portable source paths, and source-file
-digests; each plugin selects its own view. Reuse mode fails closed on
-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)
-
-`ensureSystemTables(db, typeHint?)` is the public, idempotent provisioning
-boundary for framework-owned `_smrt_*` tables. Call it on a base PostgreSQL
-connection before opening a caller-owned transaction; its advisory-locked
-bootstrap prevents missing-table probes from poisoning that transaction.
-
-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()`. Manifest and registry schemas must
-agree on same-package foreign keys as well as columns and indexes:
-`@foreignKey` emits a named physical constraint, while `@crossPackageRef` and
-`@tenantId` remain indexed runtime relationships without physical constraints.
-Natural-key references default to `CASCADE`; ordinary references default to
-immediate `NO ACTION`, matching `SmrtObject.delete()`.
-
-Same-package archival/audit identifiers that intentionally outlive their
-parent may use `@foreignKey(Target, { constraint: false })`. This explicit
-exception retains relationship loading, indexing, and application-side delete
-metadata while omitting the physical constraint, schema dependency, and
-app-side cascade/preflight action so the stored identifier survives deletion;
-document the retention reason at the field, and keep ordinary same-package
-relationships constrained.
-
-When a relationship is valid on every engine but a particular database cannot
-faithfully enforce its physical shape, use the public, explicit allowlist
-`@foreignKey(Target, { constraint: { engines: ['postgres', 'sqlite'] } })`.
-Only physical DDL and schema dependency planning are engine-scoped; native UUID
-storage, relationship loading, indexes, and application-side delete enforcement
-remain active on every engine. Empty or unknown allowlists fail closed. Do not
-use this option to hide an otherwise invalid schema.
-
-- Change column/index emission on every shipping path, proven by the path-parity
-  test `src/schema/schema-path-parity.test.ts` (#2359; index rules in the module doc). A "same as migrations" comment is a claim to check.
-- Every new query predicate ships with its index, or a reason it doesn't.
-- Creation is dependency-planned on every entry point. PostgreSQL defers mutual
-  cycle constraints until both tables exist; SQLite keeps cycles inline;
-  DuckDB refuses unsupported cycles/actions unless the field has an explicit
-  physical-constraint engine allowlist rather than silently omitting them.
-  In particular, generated same-package constraints retain the compatibility
-  default `ON UPDATE CASCADE`; DuckDB/JSON cannot enforce that action and must
-  return an actionable refusal instead of stripping the clause.
-  PostgreSQL deferred adds are idempotent and probe the exact child/parent
-  columns for orphans before `NOT VALID` + validation. Rollback drops children
-  before parents, removes deferred PostgreSQL cycle constraints first, and
-  defers SQLite checks while dropping populated cycles. Schema aggregation that
-  deliberately filters a parent also removes the retained child's physical FK.
-- 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.
-- **Transaction-bound instances**: `SmrtClass.withDatabase(db, callback)` temporarily binds an initialized instance (including its public `options.db`) to a caller-owned transaction database and restores only the database binding. Transaction owners persisting one object should use `SmrtObject.withTransaction(callback)`, which restores identity/revision metadata after rollback and serializes its embedded callback with ordinary writes. Bound saves re-enter that hold. Never reach into `_db`, and do not use the same instance concurrently during either callback.
-- **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 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
-- **Manifest required**: build-time AST scanning creates manifest. Without vitest plugin → "No field metadata"
-- **ManifestBuilder fails on scanner errors**: every production manifest path
-  must abort before adapting partial scan results. A syntax error or unresolved
-  `@smrt()` config spread cannot be allowed to emit a default-open manifest.
-- **Vite plugin loads scanner from `dist/` first**: `src/vite-plugin/import-build-aware.ts` prefers `dist/` when it exists on disk; it only falls back to `src/` on fresh clones. So if you edit `src/scanner/*.ts` or `src/schema/generator.ts` and want those edits reflected in consumer manifest generation, you must rebuild (`pnpm build` or have `pnpm dev` / `pnpm build:watch` running in core). This is intentional — sniffing `.ts` vs `.js` via `import.meta.url` was non-deterministic under tsx and broke 12–13 publishes (#1139).
-- **Bundled registry ownership**: flattened production bundles can rewrite constructor names and make decorator-time stack inference attribute provider code to the consumer. Generated registration repairs identity only from the exact imported constructor plus an explicit package and isolated one-object manifest; never infer ownership from output paths, simple names, or table names. Distinct packages may export the same simple name under qualified keys. The production-consumer gate lives in `packages/bundle-gate/src/__tests__/registry-identity.spec.ts` (#2308).
+The PostgreSQL lane is required for numeric types, UUID casts, conflict targets,
+timestamps, and migrations. Tests generate their manifest before Vitest; restart
+watch mode after adding decorated classes. Documentation-only changes need
+instruction-chain and knowledge freshness checks, not the runtime test suite.

package/agents/build-knowledge.md

@@ -0,0 +1,92 @@
+# Decorators, build integration, and knowledge
+
+Key options: `tableName`, `tableStrategy` ('cti'|'sti'), `conflictColumns`, `indexes` (declared multi-column indexes; see [schema-paths.md](schema-paths.md)), `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).
+
+## @field() UI hints (#2046)
+
+`@field({ ui: { basic, group, order, locked } })` — a static, presentation-only
+seed for the field-policy rail (epic #2045). Carried in the manifest under the
+field's `_meta.ui` (never a top-level `FieldDefinition` key), readable at
+runtime via `getAllFields()` at `field._meta.ui`, and emitted (sanitized) with
+`description` into generated web-collection definitions and browser MCP tool
+schemas. No schema/persistence/security effect — `sensitive`/`readPermission`
+stay the security rail, and `sensitive`/`transient` fields never emit to the
+client at all.
+
+## Lightweight discovery
+
+`src/knowledge-discovery.ts`, exported through `smrt-core/knowledge`, enumerates
+installed scope directories and reads canonical AGENTS/legacy CLAUDE docs without
+loading package code, artifacts, or scanning objects. CLI snapshots and MCP share
+these primitives. Callers retain selection policy: snapshots resolve links and
+fall back to `packages/*` only when no installed SMRT package loads; MCP preserves
+node_modules paths, deduplicates realpaths, excludes authored workspace links,
+and then enriches the selected packages. Workspace-root/glob discovery remains
+owned by each consumer.
+
+## Domain Knowledge Artifacts
+
+`smrtPlugin()` writes runtime manifests and agent/developer knowledge artifacts:
+
+- local dev/build: `.smrt/manifest.json` and `.smrt/smrt-knowledge.json`
+- package build: `dist/manifest.json` and `dist/smrt-knowledge.json`
+
+Keep `manifest.json` runtime-focused. `smrt-knowledge.json` is the deterministic
+agent contract for downstream review and architecture tools.
+
+The schema-version-1 object projection is additive and high-signal: it retains
+normalized tenant mode/field, explicit `cti`/`sti` strategy, conflict columns,
+method signatures, and field defaults/constraints/readonly/transient flags.
+Sensitive fields are removed before both `fields` and `relationships` are
+derived, including legacy flags stored under `_meta`; matching field and
+snake-case column names are also removed from projected conflict columns, and a
+sensitive custom tenant field is omitted while retaining scope and mode.
+Generated artifacts assert this boundary with `sensitiveFieldsExcluded: true`;
+the optional marker keeps schema version 1 additive while letting readers
+identify older artifacts that require raw-manifest corroboration.
+
+Config precedence for knowledge is defaults → top-level `knowledge` in
+`smrt.config.ts` → `packages[packageName].knowledge` → plugin option →
+object-level `@smrt({ knowledge })`.
+
+Object-level `knowledge: false` excludes an object from authored context only;
+it must not change runtime manifest registration. Use
+`knowledge: { tags, summary, risks }` for review-sensitive domain objects.
+
+HTTP knowledge routes are disabled by default. If `knowledge.api.enabled` is
+true, generated SvelteKit routes must stay GET-only and guarded by dev mode or
+admin auth.
+
+
+## Vite Plugin
+
+```typescript
+// vite.config.ts — required for @smrt() decorators (Vite 8+, oxc transform)
+export default defineConfig({
+  oxc: {
+    decorator: {
+      legacy: true,
+      emitDecoratorMetadata: true,
+    },
+  },
+});
+```
+
+Under Vite 8 the oxc transform does not honor the pre-Vite-8 `esbuild.tsconfigRaw`
+recipe (or tsconfig `experimentalDecorators` reached through SvelteKit's
+`extends "./.svelte-kit/tsconfig.json"` chain), so that recipe throws
+`SyntaxError: Invalid or unexpected token` on the first SSR request. Configure
+decorators through `oxc.decorator` instead. Consumers still pinned on vite<8 need
+the legacy `esbuild.tsconfigRaw` form with `experimentalDecorators: true,
+emitDecoratorMetadata: true`.
+
+For independent CI invocations, both `smrtPlugin()` and `smrtConsumer()` accept
+the same `generationSnapshot: { path, sha256, provenance, sourceRoot }`. The
+schema-v1 snapshot produced by `serializeSmrtGenerationSnapshot()` contains the
+merged project/dependency manifest, portable source paths, and source-file
+digests; each plugin selects its own view. Reuse mode fails closed on
+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.

package/agents/memory.md

@@ -14,3 +14,7 @@ by `@smrt({ embeddings })`, with native pgvector/HNSW or an in-memory fallback.
 Results hydrate through `list({ 'id in': … })`, so normal tenant isolation still
 applies. Keep injected search behind the `SmrtCollection.semanticSearch`
 boundary.
+
+`LearningMemory.capture()` reinforces successes and decays failures while
+updating outcome counters. Its tenant-isolated `recall()` applies confidence,
+expiry, time-decay, and hierarchical-scope filters and refreshes `last_used_at`.

package/agents/object-runtime.md

@@ -0,0 +1,83 @@
+# Object and collection runtime
+
+`constructor(options)` → `initialize()` → ready for `save()`/`delete()`/`loadFromId()`
+
+- `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)
+- Persisted `save()` uses loaded `updated_at` in its `UPDATE`; zero rows throws
+  `RUNTIME_REVISION_CONFLICT`. Explicit `expectedUpdatedAt` binds a save or
+  delete to an earlier snapshot. Remote guarded deletes bind the same predicate
+  into the final `DELETE`; embedded adapters compare inside the shared write queue
+  before cascading. That queue serializes same-process saves, deletes, and full
+  `SmrtObject.withTransaction()` callbacks. Custom writes must preserve this
+  public CAS ordering contract. PostgreSQL predicate:
+  [revision-guard.md](revision-guard.md).
+- Native DuckDB UUID columns are hydrated as canonical strings before model
+  initialization, natural-key lookup, and embedded revision claims. Exact
+  natural-key probes retain the interceptor-authorized filter when
+  canonicalizing a wrapped identity. Custom embedded-CAS paths that consume
+  persisted rows must use `getCanonicalPersistedRow()` so UUID identities are
+  cast in the same coherent read before reuse.
+- `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)
+
+
+## SmrtCollection Query
+
+Projection, latest-related, facets, counts, and bounded read plans are
+documented in [collection-reads.md](collection-reads.md).
+
+`list()` and `query()` hydrate model instances serially in result order because
+an `initialize()` hook may query through the same transaction-bound PostgreSQL
+client. Keep this serialization invariant; use `select` when callers need plain
+rows without model hydration.
+
+Native DuckDB model hydration casts declared UUID columns to `VARCHAR` in the
+read query because its JavaScript binding otherwise returns lossy HUGEINT
+wrapper objects. Explicit projections apply the same cast for selected UUID
+fields so bounded query envelopes preserve canonical row and relationship ids.
+For STI child columns, raw `query()` SELECTs, and latest-related projections,
+the read path describes the output types without evaluating the query, then
+performs one data-bearing SELECT with UUID result columns cast to `VARCHAR`;
+mutation statements are never reinterpreted or replayed.
+
+**WHERE operators**: `=`, `>`, `<`, `>=`, `<=`, `!=`, `in`, `not in`, `like`.
+Arrays auto-detect `IN`. NULL is a value, not an operator: `{ deletedAt: null }`
+renders `IS NULL` and `{ 'deletedAt !=': null }` renders `IS NOT NULL`.
+
+`convertWhereKeys` must accept only operators executable by the SQL builder.
+`contains` and dot-notation JSON paths reject at the boundary; use `like` with
+explicit wildcards. Adding operators requires SQL support first.
+`src/__tests__/issue-2276-where-contract.test.ts` executes the accepted set.
+
+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 [query-bounds.md](query-bounds.md).
+
+
+## DispatchBus
+
+- `emit(signalType, payload, metadata)` → creates persistent Dispatch record
+- `on(pattern, handler)` → in-memory handler (immediate)
+- `subscribe({ signalType, subscriber })` → persistent subscription (survives restarts)
+- `process(subscriberName, handler)` → process pending dispatches
+- Wildcards: `campaign.*` matches `campaign.completed` (single segment only)
+- Tables: `_smrt_dispatch`, `_smrt_dispatch_subscriptions`
+- Status: `pending → processing → completed` (or `failed`)
+
+## Single Table Inheritance (STI)
+
+- Base: `@smrt({ tableStrategy: 'sti' })` — children inherit, share one table
+- Discriminator: `_meta_type` column with qualified names (`@happyvertical/smrt-content:Article`)
+- Child fields: `@meta()` decorator → stored in `_meta_data` JSONB (not as columns)
+- Polymorphic queries: collection loads `_meta_type`, creates correct subclass dynamically
+- Validation: fail-fast on save if `_meta_type` missing or mismatched
+
+## Child Accessors (R10)
+
+`src/child-accessors.ts` installs a consistent `get<FieldName>()` instance method for every `@oneToMany` field at `@smrt()` registration time (e.g. `@oneToMany('OrderItem') items` → `order.getItems()`), delegating to `loadRelatedMany`. Two invariants:
+
+- **Additive** — never overwrites a hand-rolled method of the same name (checks the whole prototype chain). `Profile.getMetadata()` (key-value) and `ProfileRelationship.getTerms()` are preserved.
+- **Runtime-only** — attached to the prototype, invisible to the build-time manifest, so it never leaks into the REST/CLI/MCP surface.
+
+When the target declares multiple FKs back to the parent, annotate `@oneToMany(Target, { foreignKey: '<inverseField>' })`; `loadRelatedMany` and the eager `include:` loader both honor it (else first-match).