@happyvertical/smrt-core 0.42.6 → 0.43.0

package/AGENTS.md

@@ -18,7 +18,8 @@ subsystem you are editing. This file keeps what holds across all of them.
 | `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: allowlisted fields, deterministic fingerprints, output validation, and transport-neutral envelope (#2444) | — |
+| `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
 
@@ -37,7 +38,8 @@ subsystem you are editing. This file keeps what holds across all of them.
 `_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`. Keep semantic search behind the
+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
@@ -49,13 +51,8 @@ await collection.list({
 });
 ```
 
-Projection primitive (#1902): pass `select: ['id', 'title', 'tenantId']` to
-`list()` when an admin/list workflow needs compact rows. `select` uses SMRT
-field names, maps them to DB columns internally, and returns plain objects keyed
-by the same SMRT field names without hydrating `SmrtObject` instances. It
-composes with `where`, `orderBy`, `limit`, and `offset`; `beforeList`
-interceptors still run. It is for column-backed fields only and cannot combine
-with `include`/relationship eager loading.
+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
@@ -79,43 +76,18 @@ 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).
 
-## Bounded Collection Read Plans
-
-Use `executeCollectionReadPlan()` when one operation needs several independent
-collections. It bounds top-level `collection.list()` concurrency while keeping
-all reads on the normal registry/collection path. Callers must choose an
-explicit positive `maxConcurrency` and pass their normal shared
-`collectionOptions` when database or tenant context matters.
-
-The executor deliberately does not compose SQL, cache the plan, or change pool
-defaults. On failure it stops starting queued entries, drains operations already
-in flight, and rethrows the first error.
-
 ## Canonical Bounded Data Queries (#2444)
 
-`normalizeDataQueryRequest()` and `normalizeDataQueryResult()` are the trust
-boundary for the transport-neutral table/report/content query envelope. An
-authenticated adapter supplies a trusted `DataQuerySchema`; the caller only
-gets its declared projectable/sortable/filterable/facetable fields. The helpers
-never execute a query or decide tenant/principal access.
-
-Use `createDataQueryFingerprint()` for cache and result correlation. It omits
-the request id and page position, canonicalizes equivalent filter/projection/
-facet forms, and adds the identity sort tie-break. Keep data-query values
-scalar, requests/pages/facets positive and bounded, results within the schema
-byte cap with declared field types preserved. Datetimes must be valid RFC 3339
-instants, identity fields must be string/number/datetime-compatible, and JSON
-result fields are depth/container/string/byte bounded before cloning. Return
-only normalized `DataQueryResult` envelopes to REST, MCP,
-WebMCP, and browser consumers. Adapter-specific report/content context wraps
-the base envelope; it does not add unsafe fields or SQL-like controls to it.
+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
 
-Two persistence primitives every `SmrtObject`/`SmrtCollection` inherits — load-bearing for learning agents, usable by any object. Full guide: `docs/content/core.md` → "Context Memory System".
-
-- **Context memory** (`remember`/`recall`/`recallAll`/`forget`/`forgetScope`, table `_smrt_contexts`): stores any JSON value keyed by `(owner_class, owner_id, scope, key, version)` with a `confidence` score (0–1) and a stored `expiresAt` (metadata — `recall()` does **not** filter expired rows; expiry is caller-managed). `recall()` returns the highest-confidence match with an optional `minConfidence` floor and **opt-in** hierarchical scope fallback (`includeAncestors: true` → `'a/b/c' → 'a/b' → 'a' → 'global'`; default off); `recallAll()` returns a `Map`. Typical use: cache a learned strategy (e.g. a working selector per host) and reuse it across sessions. `success_count`/`failure_count` columns exist for outcome-weighting: `SmrtObject.remember()` leaves them untouched, `SmrtCollection.remember()` resets them to zero, and neither recall path updates them. `LearningMemory` is the layer that maintains them (and that does filter expired rows).
-- **Semantic search** (on `SmrtCollection`, table `_smrt_embeddings`): `semanticSearch(query)`, `findSimilar(object)`, `findSimilarToEmbedding(vector)` — cosine ranking over embeddings of the fields declared in `@smrt({ embeddings })`. Native pgvector/HNSW when configured, in-memory `CosineSimilarity` fallback otherwise; default local model `Xenova/bge-base-en-v1.5` (768-dim) or AI `text-embedding-3-small`. Hits hydrate via `list({ 'id in': … })`, so `@TenantScoped` isolation applies to results.
+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
 
@@ -235,12 +207,35 @@ 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()` and emit foreign-key indexes
-production never gets: the suite runs on a richer schema than it ships.
+**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.
 
 - 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 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;
@@ -255,6 +250,7 @@ production never gets: the suite runs on a richer schema than it ships.
 ## 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 supplied transaction database and restores the original binding on success or failure. Use it when domain validation and persistence must share one transaction; never reach into `_db`, and do not use the same instance concurrently during the 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

package/agents/collection-reads.md

@@ -0,0 +1,40 @@
+<!-- Module doc for packages/core/AGENTS.md. Linked from the Modules table there. -->
+
+# Collection reads
+
+This module covers bounded collection reads beyond the basic query contract in
+`packages/core/AGENTS.md`.
+
+## Projections and related rows
+
+`list({ select })` uses SMRT field names, maps them to database columns, and
+returns plain rows without hydrating objects. It composes with `where`,
+`orderBy`, `limit`, and `offset`, runs normal `beforeList`/tenant interceptors,
+and is limited to column-backed fields; it cannot combine with `include`.
+
+For one child per parent, use
+[`latest-related.md`](latest-related.md). It uses a portable ranked CTE,
+declared primary keys, adapter-specific offset-only syntax, explicit aliases,
+and hydrates only the visible parent page.
+
+## Facets, counts, and read plans
+
+`collection.facets({ fields, where })` runs one bounded `GROUP BY` per requested
+field and returns `{ field, values: [{ value, count }] }`. It accepts at most 20
+fields, clamps value limits to 1,000 and the collection ceiling, never hydrates
+objects, and applies the same read/tenant/sensitive-field rails as `select`.
+Stored array/string-list values are grouped as stored; they are not unnested.
+`collection.counts({ where })` returns `{ total, filtered }` through two scoped
+`COUNT(*)` queries. Local coverage is SQLite/DuckDB; optional scalar PostgreSQL
+coverage requires `SMRT_TEST_POSTGRES_URL`.
+
+`executeCollectionReadPlan()` bounds concurrent reads across independent
+collections while preserving the normal registry and collection options. The
+caller supplies a positive `maxConcurrency`; the executor does not compose SQL,
+cache, or alter pool defaults, and drains already-started work before returning
+the first error.
+
+`where` operators must remain aligned with `@happyvertical/sql`'s `buildWhere`:
+`=`, `>`, `<`, `>=`, `<=`, `!=`, `in`, `not in`, and `like`. Arrays imply `IN`,
+and null values render `IS NULL`/`IS NOT NULL`. `contains` and dot-notation JSON
+paths are intentionally rejected until the SQL layer supports them.

package/agents/data-query.md

@@ -0,0 +1,21 @@
+<!-- Module doc for packages/core/AGENTS.md. Linked from the Modules table there. -->
+
+# Bounded data queries (#2444)
+
+`normalizeDataQueryRequest()` and `normalizeDataQueryResult()` define the trust
+boundary for the transport-neutral table/report/content query envelope. A
+trusted adapter supplies `DataQuerySchema`; callers receive only its declared
+projectable, sortable, filterable, and facetable fields. The helpers validate
+and normalize but never execute SQL or decide tenant/principal access.
+
+Use `createDataQueryFingerprint()` for cache and result correlation. It omits
+request id and page position, canonicalizes equivalent filter/projection/facet
+forms, and adds the identity sort tie-break. Keep values scalar and request,
+page, and facet sizes positive and bounded. Results must stay within the schema
+byte cap with declared field types preserved; datetimes are RFC 3339 instants,
+identity fields are string/number/datetime-compatible, and JSON values are
+bounded by depth, container count, string size, and bytes before cloning.
+
+Only normalized `DataQueryResult` envelopes cross REST, MCP, WebMCP, and browser
+boundaries. Adapter-specific report/content context wraps the base envelope; it
+does not add unsafe fields or SQL-like controls.

package/agents/latest-related.md

@@ -0,0 +1,35 @@
+<!-- Module doc for packages/core/AGENTS.md. Linked from the Modules table there. -->
+
+# Latest-related reads (#1903)
+
+Use `SmrtCollection.listWithLatestRelated()` when a page needs one row from a
+declared `@oneToMany` relationship without N+1 queries or hydrating unrelated
+children. `latestRelated.orderBy` ranks rows within each parent, `select`
+chooses the returned child fields (defaulting to the related model's declared
+primary key), and an optional `sortBy` orders parents by the winning child
+before the parent `limit`/`offset` are applied. The result is
+`{ parent, latestRelated }`: `parent` is hydrated and `latestRelated` is a
+plain projection or `null` when the parent has no child.
+
+The read plan uses a portable `ROW_NUMBER()` CTE with explicit null-last
+ordering and the declared primary keys for every tie-break, join, and result
+map. The parent primary key is never assumed to be `id`; the related primary
+key is the default projection when `select` is omitted. Only the visible
+parent page is hydrated.
+
+Pagination is adapter-aware: SQLite uses `LIMIT -1` for offset-only reads,
+while DuckDB and PostgreSQL use `LIMIT ALL`. In-memory DuckDB and JSON adapters
+retain their engine hint even when no URL or database type is present, so the
+generated syntax remains legal for the actual driver.
+
+Internal result aliases are bounded `__smrt_lr_N` identifiers. The allocator
+reserves declared and live parent table columns, and parent columns are
+projected explicitly (using the public table-schema API where available) rather
+than `parent.*`, so externally added columns cannot collide or corrupt the
+latest-related projection. JSON adapters without live schema introspection use
+the declared schema as their fallback.
+
+The primitive preserves normal read interceptors, tenant and STI scope, and
+does not expose a cache option until cache invalidation is implemented. Tests
+cover custom primary keys, SQLite/DuckDB offset-only pagination, long field
+names, external alias collisions, and cleanup of temporary database files.

package/agents/memory.md

@@ -0,0 +1,16 @@
+<!-- Module doc for packages/core/AGENTS.md. Linked from the Modules table there. -->
+
+# Object memory and semantic search
+
+Context memory (`remember`, `recall`, `recallAll`, `forget`, `forgetScope`) is
+stored in `_smrt_contexts`, keyed by owner, scope, key, and version. Values have
+a 0–1 confidence and optional expiry metadata; `recall()` does not filter
+expired rows. Ancestor fallback is opt-in (`includeAncestors: true`) and walks
+`a/b/c → a/b → a → global`. `LearningMemory` owns outcome counters and expiry
+filtering; object/collection recall does not update them.
+
+Semantic search uses `_smrt_embeddings` and cosine ranking over fields declared
+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.

package/agents/schema-paths.md

@@ -648,30 +648,26 @@ upsert conflict target. When reading a PostgreSQL catalog array, cast it
 the array OID returns the raw `{a,b}` literal, and reading that as "no columns"
 silently inverts an index-existence decision.
 
-## Referential integrity lives in `delete()`, not in the DDL
+## Same-package referential integrity uses two matching rails
 
-No schema path emits a `FOREIGN KEY` clause on any engine — grep `schema/ddl/*`,
-`schema-manager.ts` and `differ.ts` for `REFERENCES` and you get nothing. That is
-a deliberate position, not an oversight: emitting constraints changes delete
-semantics for every consumer, requires topological table ordering in both
-migrate paths (neither orders today), and needs a plan for the orphans already in
-production databases. Emitting them is tracked separately.
-
-What `@foreignKey(..., { onDelete })` therefore means is *application* behaviour,
-applied by `SmrtObject.delete()` through `src/cascade.ts` (#2371):
+`@foreignKey(Target)` emits a physical database constraint when the target is
+in the same package and applies the same action through `SmrtObject.delete()`
+in `src/cascade.ts`. A shared delete-action resolver keeps both paths aligned;
+the established generated `ON UPDATE CASCADE` default remains unchanged:
 
 | 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` |
-| Anything else, including every `@tenantId()` field | `NO ACTION` — the row is left alone |
+| Ordinary same-package reference | `NO ACTION` — deletion is refused while references remain |
+| Every `@tenantId()` field | Excluded from physical constraints and delete cascades |
 
 The natural-key rule is what cleans junction rows up without any per-package
 annotation: a junction declares
 `@smrt({ conflictColumns: ['content_id', 'asset_id', 'relationship'] })`, so the
 row is *identified* by the content and cannot outlive it. An ordinary child
-(`Order.customerId`) is keyed by `(slug, context)` and keeps its pre-#2371
-behaviour unless it opts in explicitly.
+(`Order.customerId`) is keyed by `(slug, context)` and therefore defaults to
+immediate `NO ACTION` unless it opts in explicitly.
 
 **`@tenantId()` is excluded even though it lands in `conflictColumns`.**
 #2360 leads every tenant-scoped class's *default* natural key with the
@@ -682,8 +678,26 @@ tenant column scopes ownership; it does not identify the row the way a
 junction's foreign key does. Detected via the `__tenancy.isTenantIdField`
 marker on `FieldMeta` (`smrt-core` reads it structurally so it never depends
 on `smrt-tenancy`). `@tenantId()` exposes no `onDelete` option today, so
-this cannot currently be overridden per field — found in review before this
-landed (originally reachable, untested, and undocumented).
+this cannot currently be overridden per field.
+
+`@crossPackageRef()` remains runtime-only: it registers relationship loading
+and indexes but deliberately emits no physical constraint, avoiding circular
+package DDL. Tenant markers follow the same non-constraint rule because a
+tenant is a scope, not an ownership edge.
+
+Every schema creation entry point uses the same deterministic dependency
+planner. Parents are created before children. SQLite keeps cycle constraints
+inline because it can create them safely. PostgreSQL creates mutually dependent
+tables first and adds their named constraints afterward. DuckDB refuses cycles,
+self-references, `CASCADE`, and `SET NULL` with an actionable error because its
+current ALTER/constraint support cannot enforce those shapes safely.
+
+For existing tables, PostgreSQL checks the exact child table/column against the
+exact referenced table/column before adding a constraint as `NOT VALID` and
+then validating it. If orphans exist (or the probe cannot run), migration stops
+with detector and repair SQL. SQLite requires a deliberate table rebuild;
+DuckDB reports the unsupported ALTER path. Neither engine treats an unsupported
+constraint addition as a successful no-op.
 
 Properties to keep if you touch that module:
 

package/dist/browser.js

@@ -16,7 +16,7 @@ import { executeToolCall, executeToolCalls, formatToolResults, validateToolCall
 import { SmrtObject } from "./object.js";
 import { SMRT_COLLECTION_BASE_NAMES, isSmrtCollectionExtendsName } from "./registry/collection-resolution.js";
 import { ObjectRegistry, smrt } from "./registry.js";
-import { SmrtCollection } from "./collection.js";
+import { DEFAULT_FACET_LIMIT, MAX_FACET_FIELDS, MAX_FACET_LIMIT, SmrtCollection } from "./collection.js";
 import { SmrtHierarchical } from "./hierarchical.js";
 import { SmrtJunction } from "./junction.js";
 import { SmrtPolymorphicAssociation } from "./polymorphic-association.js";
@@ -24,4 +24,4 @@ import "./signals/index.js";
 import { DEFAULT_RETENTION_POLICY, clearRetentionTasks, getRetentionTasks, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, unregisterRetentionTask } from "./system/retention.js";
 import "./system/index.js";
 import "./tools/index.js";
-export { AIError, AiUsageCollector, AiUsagePersistenceHandler, ConfigurationError, DEFAULT_AI_COST_RATES, DEFAULT_RETENTION_POLICY, 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, clearRetentionTasks, config, convertTypeToJsonSchema, ensureBootstrapSystemTableCompatibility, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, ensureSystemTables, estimateAiUsageCost, executeToolCall, executeToolCalls, formatToolResults, generateToolFromMethod, generateToolManifest, getDatabaseEngine, getRetentionTasks, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isSmrtCollectionExtendsName, isTransientDatabaseError, isUniqueViolationError, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, shouldIncludeMethod, smrt, smrt as smrtRegistry, tableExists, unregisterRetentionTask, validateToolCall };
+export { AIError, AiUsageCollector, AiUsagePersistenceHandler, ConfigurationError, DEFAULT_AI_COST_RATES, DEFAULT_FACET_LIMIT, DEFAULT_RETENTION_POLICY, DatabaseError, ErrorUtils, FilesystemError, MAX_FACET_FIELDS, MAX_FACET_LIMIT, 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, clearRetentionTasks, config, convertTypeToJsonSchema, ensureBootstrapSystemTableCompatibility, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, ensureSystemTables, estimateAiUsageCost, executeToolCall, executeToolCalls, formatToolResults, generateToolFromMethod, generateToolManifest, getDatabaseEngine, getRetentionTasks, isAbortedTransactionError, isDeterministicDatabaseError, isNotNullViolationError, isSmrtCollectionExtendsName, isTransientDatabaseError, isUniqueViolationError, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, shouldIncludeMethod, smrt, smrt as smrtRegistry, tableExists, unregisterRetentionTask, validateToolCall };

package/dist/cascade.d.ts

@@ -1,13 +1,14 @@
 import { DatabaseInterface } from '@happyvertical/sql';
 import { ObjectRegistry } from './registry.js';
+import { ForeignKeyAction } from './schema/types.js';
 /**
  * Referential action applied to rows pointing at a deleted object.
  *
- * Same vocabulary as SQL's `ON DELETE`, enforced by the framework instead of
- * the engine. `NO ACTION` means "leave the rows alone" — SMRT emits no
- * constraint, so nothing raises.
+ * Same vocabulary as SQL's `ON DELETE`, enforced by the framework before the
+ * engine. `NO ACTION` is preflighted like an immediate restrictive action so
+ * application-side and database-side enforcement agree.
  */
-export type OnDeleteAction = 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+export type OnDeleteAction = ForeignKeyAction;
 /** One reference that must be resolved before the target row can be removed. */
 export interface CascadeReference {
     /** Registered name of the class holding the referencing column. */
@@ -18,8 +19,8 @@ export interface CascadeReference {
     fieldName: string;
     /** Column (snake_case) holding the reference. */
     column: string;
-    /** Resolved action, never `NO ACTION` (those are dropped from the plan). */
-    action: Exclude<OnDeleteAction, 'NO ACTION'>;
+    /** Resolved action. `NO ACTION` is preflighted like an immediate RESTRICT. */
+    action: OnDeleteAction;
     /** `true` when the action was declared rather than derived from the key. */
     declared: boolean;
 }

package/dist/cascade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAMpD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;AAsB/E,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,mEAAmE;IACnE,WAAW,EAAE,2BAA2B,EAAE,CAAC;IAC3C,yEAAyE;IACzE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,OAAO,cAAc,EACnB,oBAAoB,GACpB,WAAW,GACX,oBAAoB,GACpB,cAAc,GACd,uBAAuB,GACvB,UAAU,GACV,YAAY,GACZ,gBAAgB,CACnB,CAAC;AASF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAM5E;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,MAAM,GAChB,WAAW,CAwHb;AA8UD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9D,OAAO,CAAC,aAAa,CAAC,CAwBxB;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE;IACN,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC/B,EACD,UAAU,EAAE,CAAC,EAAE,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GACnD,OAAO,CAAC,aAAa,CAAC,CAgDxB"}
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAKpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAM1D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAsB9C,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,EAAE,cAAc,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,mEAAmE;IACnE,WAAW,EAAE,2BAA2B,EAAE,CAAC;IAC3C,yEAAyE;IACzE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,OAAO,cAAc,EACnB,oBAAoB,GACpB,WAAW,GACX,oBAAoB,GACpB,cAAc,GACd,uBAAuB,GACvB,UAAU,GACV,YAAY,GACZ,gBAAgB,CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAE5E;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,MAAM,GAChB,WAAW,CAgIb;AAkVD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9D,OAAO,CAAC,aAAa,CAAC,CAwBxB;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE;IACN,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC/B,EACD,UAAU,EAAE,CAAC,EAAE,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GACnD,OAAO,CAAC,aAAa,CAAC,CAgDxB"}

package/dist/cascade.js

@@ -1,5 +1,6 @@
 import { classifyDatabaseError } from "./db-errors.js";
 import { ConfigurationError, DatabaseError } from "./errors.js";
+import { normalizeForeignKeyAction, resolveForeignKeyDeleteAction } from "./schema/foreign-key-policy.js";
 import { chunkArray } from "./utils/chunk.js";
 import { toSnakeCase } from "./utils/naming.js";
 import { createLogger } from "@happyvertical/logger";
@@ -7,8 +8,9 @@ import { createLogger } from "@happyvertical/logger";
 /**
 * App-side referential integrity for `SmrtObject.delete()` (#2371).
 *
-* SMRT emits **no** DB-level `FOREIGN KEY` constraints on any engine, so the
-* database will never clean up after a deleted row. Before this module,
+* 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
@@ -45,14 +47,15 @@ import { createLogger } from "@happyvertical/logger";
 * |---|---|
 * | Column is part of the referencing class's `conflictColumns`, and is not a `@tenantId()` field | `CASCADE` |
 * | Polymorphic `(metaType, metaId)` association row | `CASCADE` |
-* | Anything else, including every `@tenantId()` field | `NO ACTION` (legacy behaviour — the row is left alone) |
+* | 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 keeps today's behaviour unless it opts in with
+* 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
@@ -88,12 +91,6 @@ var COLLECTION_OWNER_SENTINEL = "__collection__";
 * is broken by the visited set; this bound catches unbounded *chains*.
 */
 var MAX_CASCADE_DEPTH = 10;
-var CASCADE_ACTIONS = /* @__PURE__ */ new Set([
-	"CASCADE",
-	"SET NULL",
-	"RESTRICT",
-	"NO ACTION"
-]);
 /**
 * Normalize a declared `onDelete` value.
 *
@@ -102,9 +99,7 @@ var CASCADE_ACTIONS = /* @__PURE__ */ new Set([
 * an unset or unrecognized value so the caller can fall back to the default.
 */
 function normalizeOnDelete(value) {
-	if (typeof value !== "string") return void 0;
-	const normalized = value.trim().toUpperCase().replace(/_/g, " ");
-	return CASCADE_ACTIONS.has(normalized) ? normalized : void 0;
+	return normalizeForeignKeyAction(value);
 }
 function isPolymorphicAssociationClass(fields) {
 	return fields.has("metaType") && fields.has("metaId") && fields.has("role");
@@ -142,14 +137,17 @@ function buildCascadePlan(registry, className) {
 		for (const relationship of relationships) {
 			if (relationship.type !== "foreignKey" && relationship.type !== "crossPackageRef") continue;
 			if (!targetNames.has(relationship.targetClass)) continue;
+			if (relationship.type === "foreignKey" && relationship.options?.constraint === false) continue;
 			const tableName = registry.getTableName(sourceClass);
 			if (!tableName) continue;
 			const column = toSnakeCase(relationship.fieldName);
-			const declaredAction = normalizeOnDelete(relationship.options?.onDelete);
 			if (!conflictColumns) conflictColumns = new Set(registry.getConflictColumns(sourceClass));
-			const isTenantIdField = relationship.options?.__tenancy?.isTenantIdField === true;
-			const action = declaredAction ?? (!isTenantIdField && conflictColumns.has(column) ? "CASCADE" : "NO ACTION");
-			if (action === "NO ACTION") continue;
+			if (relationship.options?.__tenancy?.isTenantIdField === true) continue;
+			const { action, declared } = resolveForeignKeyDeleteAction({
+				declared: relationship.options?.onDelete,
+				isConflictColumn: conflictColumns.has(column),
+				isTenantIdField: false
+			});
 			if (action === "SET NULL" && fields.get(relationship.fieldName)?.required) throw ConfigurationError.invalidConfiguration(`${sourceClass}.${relationship.fieldName} onDelete: 'SET NULL'`, relationship.fieldName, "a nullable field (mark it `nullable: true`, or use 'CASCADE' / 'RESTRICT')");
 			references.push({
 				className: sourceClass,
@@ -157,7 +155,7 @@ function buildCascadePlan(registry, className) {
 				fieldName: relationship.fieldName,
 				column,
 				action,
-				declared: declaredAction !== void 0
+				declared
 			});
 		}
 	}
@@ -317,16 +315,16 @@ async function resolveReferences(ctx, className, tableName, ids, depth) {
 	if (depth > MAX_CASCADE_DEPTH) throw DatabaseError.constraintViolation(`cascade delete from ${className} exceeded the maximum depth of ${MAX_CASCADE_DEPTH}; check for a chain of onDelete: 'CASCADE' references that never terminates`, className);
 	const plan = buildCascadePlan(ctx.registry, className);
 	for (const reference of plan.references) {
-		if (reference.action !== "RESTRICT") continue;
+		if (reference.action !== "RESTRICT" && reference.action !== "NO ACTION") continue;
 		let remaining = 0;
 		for (const batch of chunkArray(pending, 900)) {
 			remaining += await tolerateMissingTable(() => ctx.db.count(reference.tableName, idPredicate(reference.column, batch)), 0, {
 				table: reference.tableName,
-				action: "RESTRICT check"
+				action: `${reference.action} check`
 			});
 			if (remaining > 0) break;
 		}
-		if (remaining > 0) throw DatabaseError.constraintViolation(`${reference.className}.${reference.fieldName} declares onDelete: 'RESTRICT' and ${remaining} row(s) still reference this ${className}`, reference.column);
+		if (remaining > 0) throw DatabaseError.constraintViolation(`${reference.className}.${reference.fieldName} ${reference.declared ? "declares" : "resolves to"} onDelete: '${reference.action}' and ${remaining} row(s) still reference this ${className}`, reference.column);
 	}
 	for (const reference of plan.references) {
 		if (reference.action === "SET NULL") {