@happyvertical/smrt-core 0.51.32 → 0.51.33

package/agents/build-knowledge.md

@@ -33,6 +33,10 @@ importing one fails at worker startup. A failure fails the build.
 
 ## Lightweight discovery
 
+Filesystem-only discovery, module-doc parsing, and graph freshness are owned by
+`@happyvertical/smrt-scanner/knowledge`. Core's knowledge exports remain compatible
+reexports. Runtime manifest projection and custom-action semantics stay in core.
+
 `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
@@ -119,3 +123,12 @@ 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.
+
+## Clean consumer type checks (TypeScript 6)
+
+The consumer config hook writes `.smrt/register.js` alongside generated types
+after route preflight succeeds. Generated SvelteKit registration imports that
+module, so it must exist during `svelte-kit sync`, before Vite's `buildStart`.
+Both hosted routes and the legacy `svelteKit: true` mode follow this order.
+The clean-consumer regression fixture ships real provider declarations and
+checks the generated imports with `svelte-check`.

package/dist/__tests__/fixtures/collection-coverage-fixtures.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Fixtures for collection.ts coverage tests (convenience finders, count,
+ * getDiff, getOrUpsert, and collection-scoped memory).
+ *
+ * Separate file so the @smrt() classes land in the test manifest.
+ *
+ * @see src/collection.ts (issue #1500 coverage, ORM group)
+ */
 import { SmrtCollection } from '../../collection.js';
 import { SmrtObject } from '../../object.js';
 export declare class CovWidget extends SmrtObject {

package/dist/__tests__/fixtures/inheritance-resolver-fixtures.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Fixture classes for inheritance-resolver coverage tests.
+ *
+ * Kept in a separate file (not the test file) so they are picked up by
+ * test-manifest generation. Mirrors the convention used by
+ * inheritance-test-classes.ts.
+ *
+ * @see src/registry/inheritance-resolver.ts (issue #1500 coverage, ORM group)
+ */
 import { SmrtHierarchical } from '../../hierarchical.js';
 import { SmrtObject } from '../../object.js';
 export declare class IRBase extends SmrtObject {

package/dist/__tests__/fixtures/inheritance-test-classes.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Test fixture classes for inheritance tests
+ * These classes must be in a separate file (not in the test file itself)
+ * so they can be included in the test manifest generation
+ */
 import { SmrtObject } from '../../object.js';
 export declare class InheritanceTestContent extends SmrtObject {
     title: string;

package/dist/__tests__/fixtures/object-ai-memory-fixtures.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Fixtures for object.ts AI + memory coverage tests.
+ *
+ * Separate file so the @smrt() classes are picked up by test-manifest
+ * generation. The AI client is injectable so is()/do()/describe() can run
+ * against a stub without a real provider (mocking AI is the only mocking
+ * allowed by the testing rules).
+ *
+ * @see src/object.ts (issue #1500 coverage, ORM group)
+ */
 import { SmrtObject } from '../../object.js';
 /** Minimal stub matching the slice of AIClient that is()/do()/describe() use. */
 export interface StubAi {

package/dist/__typechecks__/collection-read-plan.d.ts

@@ -1,5 +1,5 @@
-import { SmrtCollectionReadPlan, SmrtCollectionReadPlanEntry, SmrtCollectionReadPlanResult } from '../collection-read-plan';
-import { SmrtObject } from '../object';
+import { type SmrtCollectionReadPlan, type SmrtCollectionReadPlanEntry, type SmrtCollectionReadPlanResult } from '../collection-read-plan';
+import type { SmrtObject } from '../object';
 type Equal<Left, Right> = (<Value>() => Value extends Left ? 1 : 2) extends <Value>() => Value extends Right ? 1 : 2 ? true : false;
 type Expect<Value extends true> = Value;
 type ReadPlanTypeProbe = SmrtObject & {

package/dist/adapters/ai-usage.d.ts

@@ -1,5 +1,8 @@
-import { AiUsageHandler, AiUsageSnapshot, SmrtAiUsageEvent } from '@happyvertical/smrt-types';
-import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * In-memory AI usage tracking adapters.
+ */
+import type { AiUsageHandler, AiUsageSnapshot, SmrtAiUsageEvent } from '@happyvertical/smrt-types';
+import type { DatabaseInterface } from '@happyvertical/sql';
 /**
  * Collects normalized AI usage events in memory for quick inspection.
  */

package/dist/adapters/cost-rates.d.ts

@@ -1,4 +1,4 @@
-import { AiTokenUsage } from '@happyvertical/smrt-types';
+import type { AiTokenUsage } from '@happyvertical/smrt-types';
 /**
  * Cost rates are expressed in USD per 1K tokens.
  *

package/dist/adapters/metrics.d.ts

@@ -1,4 +1,10 @@
-import { Signal, SignalAdapter } from '@happyvertical/smrt-types';
+/**
+ * Metrics Adapter for Signal System
+ *
+ * Tracks execution metrics for SMRT objects in Prometheus-compatible format.
+ * Collects counts, durations, error rates, and success rates.
+ */
+import type { Signal, SignalAdapter } from '@happyvertical/smrt-types';
 /**
  * Execution metrics for a specific method
  */

package/dist/adapters/pubsub.d.ts

@@ -1,4 +1,10 @@
-import { Signal, SignalAdapter } from '@happyvertical/smrt-types';
+/**
+ * Pub/Sub Adapter for Signal System
+ *
+ * Broadcasts signals to subscribers for real-time updates.
+ * Supports multiple subscriber types (callbacks, WebSocket, SSE).
+ */
+import type { Signal, SignalAdapter } from '@happyvertical/smrt-types';
 /**
  * Signal filter function
  *

package/dist/cascade.d.ts

@@ -1,6 +1,72 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { ObjectRegistry } from './registry.js';
-import { ForeignKeyAction } from './schema/types.js';
+/**
+ * App-side referential integrity for `SmrtObject.delete()` (#2371).
+ *
+ * Same-package `@foreignKey` fields now emit database constraints where the
+ * engine can enforce the declared policy. Cross-package references and older
+ * schemas still rely on this application-side path. Before this module,
+ * `delete()` removed the object's own row and nothing else: junction rows,
+ * polymorphic association rows, `_smrt_embeddings` and `_smrt_contexts` entries
+ * were all left pointing at an id that no longer resolved, and
+ * `@foreignKey(..., { onDelete })` was metadata nobody read.
+ *
+ * This module implements those semantics in the application layer. It mirrors
+ * what a DB-level constraint would do, deliberately including the parts that
+ * make it *unlike* a model-layer delete:
+ *
+ * - Cascaded rows are removed with set-based statements. Their `beforeDelete` /
+ *   `afterDelete` hooks and interceptors do **not** run, and no change-feed
+ *   tombstone is written for them — exactly as `ON DELETE CASCADE` behaves.
+ *   Only the object `delete()` was called on runs the full lifecycle.
+ * - Every delete runs inside a single transaction when the adapter exposes
+ *   one, including cleanup of framework-owned context and embedding rows, so
+ *   a partial cascade cannot survive a failure. A `metaType` column can point
+ *   at any class at runtime, so a polymorphic association class is always
+ *   plausibly relevant.
+ *
+ * ## Which references are followed
+ *
+ * A reference is any `@foreignKey` / `@crossPackageRef` field on a registered
+ * class whose target resolves to the deleted object's class (or one of its
+ * registered STI ancestors), plus the polymorphic `(metaType, metaId)` pair on
+ * {@link SmrtPolymorphicAssociation} subclasses.
+ *
+ * The action comes from the field's declared `onDelete`. When it is not
+ * declared, the default is derived from the referencing class's natural key:
+ *
+ * | Reference | Default when `onDelete` is absent |
+ * |---|---|
+ * | Column is part of the referencing class's `conflictColumns`, and is not a `@tenantId()` field | `CASCADE` |
+ * | Polymorphic `(metaType, metaId)` association row | `CASCADE` |
+ * | Ordinary same-package reference | `NO ACTION` (deletion is refused while references remain) |
+ * | Every `@tenantId()` field | Excluded: tenant scope is not an ownership edge |
+ *
+ * The natural-key rule is what makes junction rows work without any
+ * per-package annotation: a junction declares
+ * `@smrt({ conflictColumns: ['content_id', 'asset_id', 'relationship'] })`, so
+ * `content_id` identifies the row and the row cannot outlive the content it
+ * links. An ordinary child (`Order.customerId`) is keyed by `(slug, context)`,
+ * so it defaults to immediate `NO ACTION` unless it opts in with
+ * `@foreignKey(Customer, { onDelete: 'CASCADE' })`.
+ *
+ * `@tenantId()` fields are excluded from the natural-key rule even though
+ * `@happyvertical/smrt-tenancy` leads a tenant-scoped class's *default*
+ * `conflictColumns` with the tenant column (#2360): the tenant column scopes
+ * ownership, it does not identify the row the way a junction's foreign key
+ * does, and it targets a class (`Tenant`) that is virtually always
+ * referenced. Without this exclusion, deleting one `Tenant` row would
+ * recursively CASCADE through every tenant-scoped table that has not
+ * declared its own `conflictColumns` — the overwhelming majority. The field
+ * is detected via the `__tenancy.isTenantIdField` marker `@tenantId()`
+ * attaches to its own registration (`FieldMeta.__tenancy`, read structurally
+ * so `smrt-core` never depends on `smrt-tenancy`). `@tenantId()` exposes no
+ * `onDelete` option today, so this cannot currently be overridden per field.
+ *
+ * @see https://github.com/happyvertical/smrt/issues/2371
+ * @module
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { ObjectRegistry } from './registry.js';
+import type { ForeignKeyAction } from './schema/types.js';
 /**
  * Referential action applied to rows pointing at a deleted object.
  *

package/dist/change-feed-authz.d.ts

@@ -1,5 +1,88 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { ChangeFeedPage, GetChangesOptions } from './change-feed.js';
+/**
+ * Change-feed table/row authorization seam (issue #3020).
+ *
+ * The generated `_changes`/`_events` routes authorize on "an authenticated
+ * principal" plus tenant scope (`getTenantScopedChangesSince`,
+ * `resolveDispatchTenantScope`) — see `change-feed-sensitivity.ts`'s scope
+ * note. That is enough to keep one tenant from seeing another's rows, but it
+ * cannot express "table X is readable by some principals of the tenant but
+ * not others" or "principal P only sees their own rows of table X" (a
+ * bay-tablet station versus the back office). `?tables=` was a client-chosen
+ * filter, never enforcement: a table the client did not ask for was withheld
+ * only because it did not ask, not because it could not have.
+ *
+ * This module is the consumer-supplied seam that closes that gap, evaluated
+ * identically by **every** transport — the generated SvelteKit `_changes`/
+ * `_events` routes AND the runtime REST generator's `_changes`/`_events`
+ * (`generators/changes-route.ts`, `generators/events-route.ts`) — so no
+ * transport can leak what another denies. Two independent hooks,
+ * dependency-inverted onto `globalThis` exactly like
+ * {@link resolveDispatchTenantScope} (`dispatch/tenant-resolver.ts`) so a
+ * consumer app registers them once — wherever it already calls
+ * `enableTenancy()`, or its `hooks.server.ts` — with **no change to the
+ * generated "DO NOT EDIT" route files' imports**:
+ *
+ * - `authorizeChangeFeed({ locals, request, tables }) => allowedTables` —
+ *   table-level. Its result is INTERSECTED with the client's `?tables=`
+ *   filter (never unioned): a table the hook does not name is never queried,
+ *   let alone returned, regardless of what the client asked for.
+ * - `isChangeFeedEntryVisible({ locals, request, entry }) => boolean` —
+ *   row-level, for scope narrower than a whole table (a station sees only its
+ *   own rows). Applied per entry, after the table-level filter, before
+ *   anything is serialized to the client — including a live `_events` signal,
+ *   which never carries a payload but still carries the row id and write
+ *   timing the row hook exists to withhold.
+ *
+ * ## `locals` vs. `request`
+ *
+ * SvelteKit routes pass both `event.locals` and `event.request`. The REST
+ * generator has no `locals` concept, so it passes `locals: undefined` and the
+ * `authMiddleware`-processed `Request` (whatever properties/headers the
+ * middleware attached) as `request` — a REST-hosting consumer identifies the
+ * principal from `request`, not `locals`. Every real caller supplies
+ * `request`; it is typed optional only so a low-level unit test can omit it.
+ *
+ * Both hooks are optional and independent. When neither is registered, every
+ * transport behaves exactly as before (#1540 posture — authenticated +
+ * tenant scoped only, no per-table or per-row check): every call in this
+ * module is a synchronous no-op pass-through until a consumer opts in.
+ *
+ * ## Fail-closed
+ *
+ * A hook that throws, or returns something other than the documented shape,
+ * is treated as authorizing nothing for that call — the same posture
+ * {@link resolveDispatchTenantScope} takes for a throwing tenant resolver
+ * (fail closed rather than fail the request), and the same *shape* of answer
+ * (200, empty `changes`, cursor still advances) the change-feed sensitivity
+ * filter (#2937) already gives a request naming only tables it may not see.
+ * A 5xx here would tell a caller its own hook is broken, which is
+ * indistinguishable from "your hook denied me" from the caller's side and
+ * would leak that distinction; the contract that matters — never an
+ * unfiltered feed — holds identically either way.
+ *
+ * ## Cursor correctness
+ *
+ * Every filter here narrows the *returned* `changes` array; nothing here ever
+ * touches `cursor`/`resyncRequired`/`resyncCursor`. This mirrors #2937's
+ * sensitivity filter (`change-feed.ts`, "Filters ... affect which rows are
+ * returned, never how the cursor advances") and for the same reason: a
+ * client must advance past a denied entry without re-polling it forever, and
+ * the entry's row id/timing must never be inferable from a cursor that stalls
+ * on it. Table denial is implemented via `getChangesSince`'s explicit
+ * `denyAllTables` option rather than an empty `tables` array —
+ * `getChangesSince` treats an omitted/empty `tables` as "no filter", so an
+ * empty array would (perversely) widen the read to everything, and an
+ * earlier version of this module instead passed a guaranteed-no-match
+ * sentinel table name through the ordinary `table_name IN (...)` path; that
+ * broke on PostgreSQL, which rejects a NUL byte in a text parameter, turning
+ * a denied request into a 500 instead of the required 200 empty page. A
+ * `denyAllTables` request skips the `IN (...)` clause entirely — no
+ * synthesized value ever reaches the driver — while still running the same
+ * horizon/pruned-cursor computation any other filter does, so the cursor
+ * still advances correctly; it just matches zero rows.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type ChangeFeedPage, type GetChangesOptions } from './change-feed.js';
 /**
  * Minimal shape shared by a durable {@link ChangeFeedEntry} (`change-feed.ts`)
  * and a live `ChangeSignal` (`change-signals.ts`) — both carry exactly

package/dist/change-feed.d.ts

@@ -1,5 +1,136 @@
-import { DatabaseInterface } from '@happyvertical/sql';
-import { SmrtObject } from './object.js';
+/**
+ * Adapter-agnostic change feed — the framework's change-observation spine
+ * (issue #1758, parent PRD #1755).
+ *
+ * Every framework `save()`/`delete()` appends exactly one row to the
+ * `_smrt_changes` system table (monotonic per-database sequence, table name,
+ * row id, operation, tenant id, timestamp). Deletes are recorded as
+ * tombstones (`operation: 'delete'`), distinguishable from updates. One read
+ * interface — {@link getChangesSince} — returns changes after a cursor,
+ * filterable by table and tenant, and serves three eventual consumers:
+ * client delta pull, the SSE push channel, and the per-table version source
+ * backing ETags.
+ *
+ * ## Cursor semantics (the precise guarantee)
+ *
+ * Sequences are allocated *inside* the append statement as
+ * `COALESCE(MAX(seq), 0) + 1` over the feed table itself, with a retry on
+ * primary-key conflict. `MAX(seq)` only observes committed rows, so a row
+ * with sequence `N` can only be inserted while every row with sequence
+ * `< N` is already committed (a conflicting in-flight allocation of the same
+ * value blocks, then retries). Committed rows therefore always form a
+ * contiguous run ending at `MAX(seq)` — the **committed horizon**. Sequence
+ * order equals commit order; out-of-order commit visibility (the classic
+ * MVCC race that makes native identity/serial columns unsafe as cursors
+ * under concurrent writers) cannot occur.
+ *
+ * {@link getChangesSince} reads the committed horizon `H = MAX(seq)`, then
+ * returns matching rows with `since < seq <= H` (bounded by `limit`), and a
+ * `cursor` that is either `H` (page exhaustive) or the last returned `seq`
+ * (page limited). Because no change can ever commit at or below an observed
+ * horizon after it was observed, polling with returned cursors misses no
+ * committed change and never returns the same change twice — under any
+ * number of concurrent writers, identically on SQLite, Postgres and DuckDB.
+ * This is the design reason the allocator is `MAX+1` rather than a native
+ * AUTOINCREMENT/identity column: identity values are allocated before
+ * commit, so a reader on Postgres could observe seq 101 while seq 100 is
+ * still uncommitted and advance its cursor past it. (No shared
+ * auto-increment mechanism exists in the system-table schema path either;
+ * see `system/schema.ts`.)
+ *
+ * ## Staged appends inside caller transactions (PostgreSQL, #2649)
+ *
+ * `MAX+1` allocation costs a *wait*: two appends that pick the same value
+ * conflict on the primary key, and the loser waits for the winner's
+ * transaction to end. Under autocommit that is one statement. Inside a
+ * caller-managed transaction it is the whole transaction — and a long write
+ * transaction that appends and then keeps taking row locks forms a genuine
+ * lock cycle with any writer that took those row locks first and then
+ * appended. PostgreSQL detects it (`40P01`) and aborts one side, so an
+ * ordinary concurrent request could abort a legitimate long write.
+ *
+ * PostgreSQL appends issued inside a caller transaction are therefore
+ * **staged**: `_smrt_append_change` inserts into `_smrt_changes_pending`,
+ * whose identity key conflicts with nothing, so the append never waits on
+ * another transaction and the cycle cannot form. The staged row is still
+ * fate-shared with the caller (a rollback removes it). {@link drainChangeFeed}
+ * — run by {@link getChangesSince} before it reads, and (throttled) by the
+ * append path itself — moves *committed* staged rows into `_smrt_changes`
+ * under a try-only advisory lock, numbering them `MAX(seq) + row_number()` in
+ * staged order. Draining is driven from JavaScript rather than inside the
+ * append helper so that every sequenced entry also gets its live `_events`
+ * signal: an entry sequenced invisibly server-side would be skipped for good
+ * by a subscriber whose `Last-Event-ID` came from a later, higher sequence.
+ * Signals for drained entries are published only once the drain is proven
+ * committed, so a rollback can never advertise a sequence another appender
+ * then reuses.
+ *
+ * The cursor guarantee is unchanged, because sequences are still allocated by
+ * exactly one `MAX+1` writer at a time and only ever for already-committed
+ * work: committed sequences stay contiguous, and no entry can appear at or
+ * below a horizon a reader already observed. What a staged append gives up is
+ * *promptness*, not durability or order: its entry becomes visible one drain
+ * after its transaction commits, and its position in the log is its drain
+ * order rather than its statement order. An autocommit append drains before
+ * allocating whenever its throttle allows, so staged work usually keeps its
+ * place ahead of later writes.
+ *
+ * SQLite and DuckDB keep the direct `MAX+1` insert unchanged — SQLite
+ * serializes writers outright, so the defect is unreachable there.
+ *
+ * Contention note: appends serialize on the head of the log. Each append is
+ * one small INSERT (issued from the write path *after* the user's row was
+ * written), so the serialization window is one statement; conflicts resolve
+ * with a bounded retry loop and are impossible on single-writer engines
+ * (SQLite). PostgreSQL invokes that INSERT through the framework-owned
+ * `_smrt_append_change` function so failure isolation remains one statement.
+ *
+ * ## Failure semantics
+ *
+ * A feed-write failure must never fail the user's write. The interceptor
+ * wraps the append in a try/catch: on failure it logs a warning (deduped per
+ * database) and continues. The trade-off is availability of the user's
+ * write over completeness of the feed — consumers already need a
+ * full-resync path for cursors older than the retention window, and the
+ * same path covers a (rare) dropped feed row. PostgreSQL runs the INSERT in a
+ * PL/pgSQL exception subtransaction and returns a caught SQLSTATE as data;
+ * JavaScript only throws/logs after PostgreSQL has restored the caller's
+ * transaction, so a swallowed append failure cannot surface later as 25P02.
+ * The append still joins a caller-managed transaction on the same handle and
+ * shares its fate (a rollback removes the staged row with the data row).
+ *
+ * ## Known gaps (documented in the PRD)
+ *
+ * - Writes that bypass framework mutation paths (raw SQL) are invisible to
+ *   the feed — the same accepted gap as the #1499 collection cache.
+ *   {@link bumpChangeFeed} is the manual escape hatch: out-of-band writers
+ *   append a synthetic change row for the affected table.
+ * - **Spurious `update` entries**: `SmrtObject.save()` has no dirty-check,
+ *   so a field-unchanged `.save()` still appends an `update` row. This is
+ *   by design — the writer observes writes, not diffs (it has no old-row
+ *   access), so the feed faithfully mirrors the write path. Diff-aware
+ *   paths (`getOrUpsert()`'s diff guard, the sync-apply endpoint's no-op
+ *   detection) short-circuit before `save()` and append nothing.
+ *   Subscribers must tolerate spurious entries; they are convergent — a
+ *   re-fetch returns identical data.
+ *
+ * ## Retention
+ *
+ * The log is append-only and grows with write volume. {@link pruneChangeFeed}
+ * bounds it by age (`maxAgeMs`) and/or row count (`maxRows`); call it from a
+ * scheduled job sized so the retention window comfortably exceeds the
+ * slowest consumer's polling interval. Pruning deletes oldest-first and
+ * always retains the newest entry, so retained sequences stay a contiguous
+ * `[floor..horizon]` run — which is how {@link getChangesSince} *detects* a
+ * consumer whose cursor predates the retained window and answers it with
+ * `resyncRequired: true` plus a fresh resume cursor instead of silently
+ * skipping the pruned changes.
+ *
+ * @see https://github.com/happyvertical/smrt/issues/1758
+ * @packageDocumentation
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { SmrtObject } from './object.js';
 /** Name of the append-only change-feed system table. */
 export declare const CHANGE_FEED_TABLE = "_smrt_changes";
 /**

package/dist/change-signals.d.ts

@@ -1,4 +1,69 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * Change-signal bus — the live push spine for the generated `_events` SSE
+ * route (issue #1763, parent PRD #1755).
+ *
+ * The change feed (#1758) is a durable, cursor-addressable log; this bus is
+ * its ephemeral companion. Every framework `save()`/`delete()` that appends a
+ * feed row also publishes a coarse {@link ChangeSignal} here, which fans out
+ * synchronously to in-process subscribers (the SSE controllers of connected
+ * `_events` clients) and, when the database adapter exposes a notification
+ * capability, to peer replicas over the same channel. Absence of that
+ * capability degrades gracefully — no cross-replica push, never an error, and
+ * it never blocks the write.
+ *
+ * ## What a signal carries (and deliberately does not)
+ *
+ * A signal is `{ table, operation, rowId, tenantId, seq }` — never any row
+ * payload. Authorization stays entirely on the read path: a subscriber learns
+ * *that* something changed and its cursor (`seq`), then re-reads through the
+ * authorized collection routes to catch up. This is why the bus can broadcast
+ * a tenant's writes to peer replicas without leaking data across a trust
+ * boundary. The `seq` is the same monotonic cursor dimension the change feed
+ * allocates, so a reconnecting client can resume via `getChangesSince`.
+ *
+ * ## Delivery model
+ *
+ * - Local delivery is a synchronous fan-out ({@link deliverLocally}) into each
+ *   listener callback, wrapped in a try/catch **per listener** so one throwing
+ *   listener (e.g. a closed SSE controller's `enqueue`) never blocks the
+ *   others. There is no per-subscriber queue — backpressure is delegated to
+ *   each platform `ReadableStream`.
+ * - Cross-replica delivery reuses the same {@link deliverLocally} helper on
+ *   receipt, so locally-published and peer-received signals travel one code
+ *   path. Notifications this process published are skipped by `source` id
+ *   (echo-avoidance), exactly as the collection cache does.
+ *
+ * This mirrors `collection-cache.ts`'s notify/listen structure; study that
+ * module for the shared cross-process conventions (`resolveDbCacheKey`,
+ * `getNotifications`, the lazy listener and finally-retract).
+ *
+ * ## Known gaps
+ *
+ * - **Subscriber cap lives at the route boundary**: the bus tracks subscribers,
+ *   but generated `_events` routes decide whether to reject a new connection
+ *   before opening a stream (#1860).
+ * - **Raw-SQL writes are invisible**: signals originate from the framework
+ *   write path (same accepted gap as the #1758 feed and #1498 cache). A
+ *   `bumpChangeFeed` escape-hatch write appends a feed row but does not
+ *   publish a signal.
+ * - **Caller-managed transactions signal late, not early** (#2649): a
+ *   PostgreSQL append made inside a caller transaction that has already
+ *   written is *staged*, so it has no sequence to signal with at
+ *   `afterSave`/`afterDelete` time. Its signal is published instead by the
+ *   drain that sequences it, which is the first post-commit moment — closing
+ *   the older hazard where a pre-commit signal could describe a write a later
+ *   rollback undid, and where the rolled-back seq was reused by the next
+ *   append. The cost is latency: live subscribers see a transaction-wrapped
+ *   write one drain after it commits, and on engines without staging
+ *   (SQLite, DuckDB) the pre-commit caveat still applies. The autocommit
+ *   default path — save()/delete() as independent statements — is exact and
+ *   unchanged. Clients reconcile via cursor catch-up either way, so
+ *   convergence holds.
+ *
+ * @see https://github.com/happyvertical/smrt/issues/1763
+ * @packageDocumentation
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
 /**
  * Operation carried by a change signal. Kept as a local string union — this
  * module deliberately does NOT import `./change-feed.js` (which imports this

package/dist/child-accessors.d.ts

@@ -1,4 +1,42 @@
-import { RelationshipMetadata } from './registry/types';
+/**
+ * R10 — consolidated child-accessor API for `@oneToMany` relationships.
+ *
+ * Before R10 every model hand-rolled its own child accessor (`getTerms`,
+ * `getChildren`, `getForProfile`, …) with inconsistent names and shapes. This
+ * module installs ONE canonical accessor per `@oneToMany` field at class
+ * registration time: a `@oneToMany('Child') items` field gains a `getItems()`
+ * instance method that delegates to the existing `loadRelatedMany('items')`
+ * resolver — the same code path used for lazy loading and `include:` eager
+ * loading, which itself queries through the child collection (the queryable
+ * primitive).
+ *
+ * Two invariants make this safe to apply to every registered class:
+ *
+ * - **Additive.** If a method of the computed name already exists anywhere on
+ *   the prototype chain — a hand-rolled accessor like
+ *   `ProfileRelationship.getTerms()`, a differently-shaped `Profile.getMetadata()`,
+ *   or a `SmrtObject` base method — it is left untouched. The generated
+ *   accessor never renames or shadows an existing public signature.
+ * - **Runtime-only.** Accessors are attached to the prototype at registration;
+ *   they are invisible to the build-time manifest, so they never leak into the
+ *   generated REST/CLI/MCP surface (those read `classInfo.tools`/scanned
+ *   methods, not the runtime prototype). They are a developer-ergonomics
+ *   convenience layered on top of `loadRelatedMany`.
+ *
+ * Multiplicity note: when the child class declares more than one foreign key
+ * back to the parent (e.g. `ProfileRelationship.fromProfileId` /
+ * `toProfileId`), annotate the `@oneToMany` with `{ foreignKey: 'fromProfileId' }`
+ * so `loadRelatedMany` resolves the correct inverse side. Without it the
+ * resolver falls back to the first matching foreign key (legacy behavior). An
+ * explicit `foreignKey` that matches no inverse FK is treated as an error.
+ *
+ * STI note: a child class inherits the base's generated accessor through the
+ * prototype chain. `loadRelatedMany` resolves the inverse FK against the
+ * instance's class AND its registered ancestors (see
+ * `ObjectRegistry.getInverseRelationshipsForSelf`), so calling the accessor on
+ * an STI subclass instance resolves a `@oneToMany` declared on its base.
+ */
+import type { RelationshipMetadata } from './registry/types';
 /**
  * Compute the canonical child-accessor method name for a `@oneToMany` field.
  *

package/dist/class.d.ts

@@ -1,11 +1,11 @@
-import { AIClient, AIClientOptions } from '@happyvertical/ai';
-import { FilesystemAdapter, FilesystemAdapterOptions } from '@happyvertical/files';
-import { LoggerConfig } from '@happyvertical/logger';
-import { AiUsageListOptions, AiUsageSnapshot, AiUsageStats, AiUsageSummaryOptions, SignalAdapter, SmrtAiUsageRecord } from '@happyvertical/smrt-types';
-import { DatabaseInterface } from '@happyvertical/sql';
-import { AiUsageConfig, MetricsConfig, PubSubConfig } from './config.js';
-import { DatabaseConfig } from './database.js';
-import { DecisionClient, DecisionConfig, DecisionOptions, DecisionRequest, DecisionResult } from './decisions.js';
+import type { AIClient, AIClientOptions } from '@happyvertical/ai';
+import type { FilesystemAdapter, FilesystemAdapterOptions } from '@happyvertical/files';
+import { type LoggerConfig } from '@happyvertical/logger';
+import type { AiUsageListOptions, AiUsageSnapshot, AiUsageStats, AiUsageSummaryOptions, SignalAdapter, SmrtAiUsageRecord } from '@happyvertical/smrt-types';
+import { type DatabaseInterface } from '@happyvertical/sql';
+import type { AiUsageConfig, MetricsConfig, PubSubConfig } from './config.js';
+import type { DatabaseConfig } from './database.js';
+import { type DecisionClient, type DecisionConfig, type DecisionOptions, type DecisionRequest, type DecisionResult } from './decisions.js';
 import { SignalBus } from './signals/bus.js';
 /**
  * Configuration options for the SmrtClass

package/dist/collection-cache.d.ts

@@ -1,4 +1,50 @@
-import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * Opt-in read-through cache for collection reads (issue #1498).
+ *
+ * SSR-rendered SMRT apps re-query read-heavy / write-rare collections on
+ * every request, and the per-query round-trip dominates wall time when a
+ * page needs many collections. This module memoizes `list()`/`get()` row
+ * sets keyed by the final SQL + parameters, for an opt-in TTL.
+ *
+ * Correctness model:
+ * - Caching is OFF by default. It is enabled per call
+ *   (`list({ cache: { ttl } })`) or per model (`@smrt({ cache: { ttl } })`).
+ * - SMRT owns every mutation path (`save()`/`delete()` back
+ *   `collection.create()`, `getOrUpsert()`, junction attach/detach), so all
+ *   writes invalidate the affected table's entries in-process automatically.
+ * - Entries and flights are partitioned by the concrete DatabaseInterface
+ *   object, final SQL and parameters. Distinct transaction/connection handles
+ *   never share rows or failures, even when their database URL is identical.
+ * - Invalidation remains URL/table scoped, so a write clears every handle's
+ *   entries and STI siblings (which share a table) stay coherent.
+ * - Caches are per-process. With multiple replicas, a local invalidation
+ *   leaves peers stale until TTL unless cross-process invalidation is opted
+ *   into (`crossProcess: true`), which broadcasts over the database
+ *   adapter's notification capability (e.g. Postgres LISTEN/NOTIFY) when
+ *   the adapter provides one.
+ *
+ * Cached values are raw result rows, not hydrated instances — hydration and
+ * read interceptors (tenancy, audit) run on every call, cached or not, and
+ * each caller receives isolated row copies.
+ *
+ * Known limitations:
+ * - Invalidation fires when a mutation's SQL executes, not when its
+ *   surrounding transaction commits. A write inside an uncommitted
+ *   transaction invalidates (and may broadcast) immediately; a concurrent
+ *   reader could repopulate the cache from the pre-commit snapshot, and a
+ *   rollback leaves the cache invalidated for a write that never landed.
+ *   Caching targets read-heavy / write-rare data where this is rare; for
+ *   models mutated inside multi-statement transactions, coherence is still
+ *   bounded by TTL. Per-call `cache: false` forces a fresh read where it
+ *   matters.
+ * - Writes that bypass the framework's mutation paths (raw `db.query`
+ *   issued outside `collection.query()`, external processes without
+ *   `crossProcess`) are only bounded by TTL.
+ *
+ * @see https://github.com/happyvertical/smrt/issues/1498
+ * @packageDocumentation
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
 /**
  * Read-through cache configuration for collection reads.
  *

package/dist/collection-read-plan.d.ts

@@ -1,6 +1,6 @@
-import { SmrtClassOptions } from './class';
-import { SmrtListOptions, SmrtSelectedRow, SmrtSelectField } from './collection';
-import { SmrtObject } from './object';
+import type { SmrtClassOptions } from './class';
+import type { SmrtListOptions, SmrtSelectedRow, SmrtSelectField } from './collection';
+import type { SmrtObject } from './object';
 type DynamicSmrtObject = SmrtObject & Record<string, unknown>;
 type SmrtHydratedCollectionReadOptions<ModelType extends SmrtObject> = Omit<SmrtListOptions<ModelType>, 'select'> & {
     select?: undefined;