@happyvertical/smrt-core 0.43.10 → 0.44.1

package/AGENTS.md

@@ -27,14 +27,14 @@ subsystem you are editing. This file keeps what holds across all of them.
 
 - `initialize()`: loads field initializers, applies option values (options override initializers), loads from DB if id/slug provided
 - `save()`: upsert with STI validation, interceptor execution, auto-embeddings. Persisted objects (`isPersisted` — set by DB hydration and successful saves) upsert on `['id']` so natural-key edits (e.g. slug renames) update in place; new objects upsert on the natural-key conflict columns for ingestion-style dedup (#1472)
-- Persisted `save()` calls use the object's loaded `updated_at` revision in the
-  database `UPDATE`; zero affected rows throws `RUNTIME_REVISION_CONFLICT`
-  without overwriting the newer row. `save({ expectedUpdatedAt })` supplies an
-  explicit revision when a caller binds the mutation to an earlier preview or
-  selection snapshot. Embedded adapters serialize every same-process model
-  save, delete, and complete `SmrtObject.withTransaction()` callback through
-  one queue; bound saves re-enter that hold. Custom write paths must use those
-  public APIs rather than bypassing the CAS ordering contract.
+- 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

package/agents/generators.md

@@ -63,6 +63,110 @@ requested path rather than a hardcoded `index.js`.
 Generated code also has to be valid in an ES module: `arguments` is not a legal
 binding name there, however convenient it reads.
 
+## Browser-plane playbook preflight route (#2590)
+
+`GET {basePath}/_preflight?key=<playbook key>` (`src/generators/preflight-route.ts`)
+is an advisory, read-effect, idempotent report of what a caller's playbook would
+be allowed to do — capability *selection*, never authorization. Resolution and
+verdict shaping live in `@happyvertical/smrt-playbooks`, which depends on this
+package, so core takes the evaluator as the `APIConfig.playbookPreflight` seam and
+the dependency stays one-way. Without a provider the route 404s.
+
+**`authMiddleware` is never invoked by preflight**, and that is enforced
+structurally rather than by discipline: `PlaybookPreflightRouteOptions` has no
+auth member of any kind, and `rest.ts` passes the boolean `appAuthConfigured`
+instead — so there is no handle in the module to invoke by mistake. A synthetic-
+`Request` dry run is explicitly not an option: the middleware is request-bound,
+returns a `Response` rather than a boolean, and may consult session stores,
+rate-limit, or audit. The app-auth layer therefore reports `unknown`, which is the
+honest answer, and a future `authPredicate` seam can fill it in without changing
+the contract.
+
+The static layers preflight predicts against are exported from the same module —
+`isApiActionEnabledForObject`, `isRestActionRoutable`, `isRestRoutePublic`,
+`restFieldReadPermissions`, `restMethodForApiAction`,
+`resolveRegisteredObjectName` — and `APIGenerator`'s own
+`isApiActionEnabled` / `isRoutePublic` now delegate to them, so the route and the
+prediction of the route cannot drift. Exposure and existence are separate
+questions: `include`/`exclude` gate a route, they do not conjure one, so
+`isRestActionRoutable` additionally requires a custom action to be declared in
+`api.routes` — the only map `dispatchCustomCollectionAction` iterates. A custom
+action is predicted against the verb its own route config declares, so a
+`public: 'read'` opt-out neither silently covers a `POST` action nor falsely
+denies a declared `GET` one. Every unresolvable key returns the provider's single uniform
+"unavailable" body with an unconditional 200: unknown and unauthorized keys are
+indistinguishable at the HTTP layer too.
+
+## Emitted agent surface (#2591)
+
+Generated model tools have always been build-time artifacts — virtual module,
+manifest, knowledge graph. View intents (#2588) and playbooks (#2589) existed
+only once something mounted, so "what can an agent do in this app" had no answer
+short of enumerating every route. This closes that.
+
+The same OXC scan that builds the manifest also runs the scanner's
+agent-surface matcher (`ScanResults.agentSurface`). `smrtPlugin()` captures it
+in `scanWithOxc`, projects it with `toKnowledgeAgentSurface`, and passes it to
+`buildDomainKnowledgeManifest` as `agentSurface`. Note that declaration
+discovery is NOT bound to the plugin's `include` glob — an app that scans
+`src/lib/objects/**` for models still has its `src/lib/agent/*.intents.ts`
+sidecars found (see `packages/scanner/AGENTS.md`). Two more consequences worth
+holding onto:
+
+- **It never touches `manifest.json`.** The runtime manifest stays
+  runtime-focused; the agent-addressable surface is an agent/developer contract,
+  so it lands in `.smrt/smrt-knowledge.json` and `dist/smrt-knowledge.json`
+  only, under `agentSurface: { intents, playbooks, diagnostics }`.
+- **It is passed in, not scanned in `knowledge.ts`.** The scanner carries a
+  native parser binary and `smrt-core`'s main entry is browser-reachable, so
+  core's sync knowledge builder must not import it. The Vite plugin already
+  imports the scanner lazily on the Node side and is the only caller that writes
+  this artifact.
+
+The field is **omitted entirely** when a package declares nothing, which is what
+makes it additive in practice rather than only on paper: every existing
+package's checked-in artifact stays byte-identical.
+
+Each declaring module gets a `sourceHashes` entry under the
+`agentSurface:<package-relative path>` prefix (`AGENT_SURFACE_HASH_PREFIX`), so
+EDITING an intent sidecar marks the artifact stale exactly like editing
+`AGENTS.md` does (`stale-domain-knowledge`).
+
+Hashes alone cannot see an **added** declaration, though: a brand-new sidecar
+has no recorded hash to mismatch, the runtime manifest never carries intents,
+and `AGENTS.md` is untouched — so every other signal stays green while the
+artifact omits a real operation. `dev:knowledge-check` therefore also re-derives
+the declaration SET from source and compares it to the artifact by identity,
+reporting either direction as `stale-agent-surface`. The scan is bounded like
+the numeric-precision lint: `src` only, behind the scanner's token pre-filter.
+
+That re-derivation must model what the EMITTER sees, not merely what is on
+disk, or it reports drift no rebuild can clear. Which files count is decided by
+the scanner's exported `isAgentSurfaceSourcePath` — the same predicate the
+emitter itself uses, never a list copied into the checker — and the per-file
+results run through `mergeAgentSurfaces` before comparing, because the merge is
+where a duplicate identity and a derived tool-name collision are resolved and
+the artifact is the merged result.
+Diagnostics are compared alongside identities: a sidecar containing only a
+computed declaration adds no identity and has no prior hash, so without that,
+"a diagnostic, never silence" would quietly become "a diagnostic, until the
+artifact goes stale". The walk covers `<pkg>/src` while the emitter globs the
+whole project root, so an emitted entry from outside `src` is not reported as
+missing — this check did not look there, and claiming otherwise would be an
+error nothing could clear.
+
+Both `stale-*` codes are warnings by default and errors under `--strict`, which
+is what CI runs. Alongside them: `agent-surface-missing-identity`,
+`agent-surface-duplicate-identity`, and `agent-surface-empty-playbook` are
+errors, and `agent-surface-not-static` is a warning. A cross-file duplicate
+arrives as a *diagnostic* rather than two entries — the scanner's merge already
+dropped the loser — so that diagnostic maps to the duplicate error rather than
+the not-static warning; otherwise the error would be unreachable for the case it
+exists to catch.
+
+`smrt doctor` prints the whole surface — model tools, intents, playbooks — from
+these artifacts alone, with no application running.
+
 ## Custom-action contract
 
 `resolveCustomActionMetadata()` is the common discovery and invocation contract

package/agents/revision-guard.md

@@ -0,0 +1,66 @@
+# Revision compare-and-swap guard (`src/revision-guard.ts`)
+
+Every persisted `save()` pins its `UPDATE` to the revision the writer loaded;
+`claimRevision()` does the same without running domain hooks, and
+`delete({ expectedUpdatedAt })` binds the same predicate into its final
+`DELETE`. Zero affected rows raises `RUNTIME_REVISION_CONFLICT` rather than
+overwriting or removing a newer row.
+
+## Why the predicate is not an equality (#2620)
+
+The guard used to compare `updated_at` to `loadedRevision.toISOString()`. On
+PostgreSQL a JavaScript `Date` is two lossy conversions away from the stored
+value, so that predicate matched no row at all in two common situations — and
+the object then conflicted on *every* later save, permanently, rather than
+losing a race:
+
+- **Precision.** `updated_at` is a microsecond column. Any row last written by
+  raw SQL — `updated_at = CURRENT_TIMESTAMP` / `now()`, including SMRT's own
+  migration backfills — carries a sub-millisecond tail a `Date` cannot hold.
+- **Process timezone.** Schemas created before the `TIMESTAMPTZ` mapping still
+  hold `updated_at` as `timestamp WITHOUT time zone`, and `pg` hydrates that
+  type in the process zone, so on a non-UTC host `toISOString()` renders a wall
+  clock the row never held. The same columns are written under three different
+  conventions — `pg` serializes a bound `Date` in the process zone,
+  `claimRevision()` writes a UTC ISO string, and raw `CURRENT_TIMESTAMP` writes
+  in the *server* zone — so no single rendering can match every row.
+
+## What the predicate does instead
+
+`postgresRevisionCondition()` builds
+`date_trunc('milliseconds', updated_at) IN (…)` over both wall-clock renderings
+of the revision, the process-zone one and the UTC one, each tagged `+00` so a
+`timestamptz` comparison honours it and a `timestamp` comparison discards it —
+the predicate therefore does not depend on the *session* TimeZone either. On a
+UTC process the two renderings coincide and the condition is single-valued.
+
+Lost-race semantics are preserved: a concurrent writer advances `updated_at` to
+roughly "now", so it must land on the loaded revision — or, on a non-UTC
+process only, on that revision shifted by the whole UTC offset — to the
+millisecond before it could slip past. Collapsing that second rendering so the
+predicate is single-valued on every process is tracked as #2623.
+
+## Rules
+
+- Never rebuild this predicate by hand; call `postgresRevisionCondition()`.
+  Every guarded write — `save()`, `claimRevision()`, and the guarded `DELETE` —
+  goes through `SmrtObject.revisionPredicate()` so no path is left on the exact
+  equality.
+- The condition is PostgreSQL-only. Embedded engines take the process-local
+  compare/upsert fallback (`usesEmbeddedRevisionFallback`), and remote LibSQL
+  stores ISO text whose exact equality round-trips losslessly.
+- Custom write paths must go through `save()`, `save({ expectedUpdatedAt })`,
+  or `claimRevision()` rather than bypassing the CAS ordering contract.
+- The driver-layer half — `pg` hydrating and serializing `timestamp` columns in
+  the process zone — is tracked as happyvertical/sdk#1223. The guard
+  deliberately assumes neither hydration convention, so a UTC-hydration fix
+  there cannot break it.
+
+## Coverage
+
+`src/__tests__/issue-2620-revision-guard-precision-postgres.optional.test.ts`
+runs the whole battery — guarded save, `save({ expectedUpdatedAt })`,
+`claimRevision()`, guarded delete, and their still-conflicts counterparts —
+against both `updated_at` column shapes in the registered PostgreSQL suite (`pnpm --filter @happyvertical/smrt-core
+test:postgres`). `src/__tests__/revision-guard.test.ts` covers the rendering
+itself in the default suite.

package/agents/schema-paths.md

@@ -715,6 +715,105 @@ SQLite requires a deliberate table rebuild; DuckDB reports the unsupported ALTER
 path. Neither engine treats an unsupported constraint addition as a successful
 no-op.
 
+### Pre-R11 `text` ids converge to `uuid` before any FK statement (#2608)
+
+R11 made SMRT identifiers and references native `uuid` on PostgreSQL. A
+database created before that change still stores its `id` columns as `text`
+while every reference column added afterwards materializes as `uuid`.
+PostgreSQL cannot implement a foreign key across two different physical types —
+FK DDL admits no cast — so `ADD CONSTRAINT … NOT VALID` fails with SQLSTATE
+42804 and aborts every later statement in the same migration batch.
+
+Two rails handle it, and both are PostgreSQL-only. SQLite stores UUIDs as text
+by design and DuckDB cannot rewrite a column type in place, so neither engine
+emits anything for this drift.
+
+**The runtime guard fails closed.** `SchemaManager.ensurePostgresForeignKey()`
+reads both live column types and refuses to emit `ADD CONSTRAINT` when they
+disagree, naming both columns, both live types, and the repair. It deliberately
+skips the orphan probe in that case: across mismatched types the probe answers
+a question about casted values, not about the constraint being refused, and it
+has to run again after the columns converge anyway.
+
+**The differ converges the columns.** `planUuidConvergence()`
+(`src/schema/uuid-convergence.ts`) groups every manifest relationship that
+declares UUID on both sides into connected components and converges a component
+only when the live database already proves the target shape — at least one
+member is native `uuid`. A component that is `text` on *every* side is the
+tolerated pre-R11 deployment and is left alone; its foreign keys are
+type-compatible today, and the R11 uuid/text equivalence in
+`migrations/differ.ts` keeps it out of the column diff.
+
+Components, not individual pairs, are the unit of decision: one legacy `text`
+primary key can be referenced by several children, and converting it for one
+of them would break every sibling that is still `text`. A self-referential
+table falls out of the same grouping because both endpoints land in one
+component. Convergence is relationship-driven, so a legacy `text` id that
+nothing references keeps its R11 tolerance.
+
+The planner never coerces data. Before emitting anything it probes each column
+it would rewrite for values that are not uuid-shaped (the same `~*` canonical
+pattern the orphan probe uses) and refuses the whole component — with the count
+and a sample value — if any exist, if the probe cannot run, if a member carries
+some third physical type, or if a live foreign key still constrains a column
+that must change. `@happyvertical/sql` introspection does not expose live
+PostgreSQL constraint names, so SMRT cannot drop and re-add those constraints
+for you: drop them deliberately, rerun the migration to converge, and let SMRT
+re-add the manifest constraints.
+
+Refusals are reported, not silent. Each one becomes a warning advisory with no
+executable SQL, so it reaches `unactionableChanges` / `hasManualDrift` and
+`db:status` shows **blocked: incompatible column types** instead of *pending*.
+The same check runs per relationship in `compareForeignKeys`, so a foreign key
+whose live types will still disagree after this run's conversions is reported
+blocked rather than emitted as pending DDL that cannot succeed.
+
+The planner also inspects tables the manifest no longer declares. A live
+foreign key from an orphan table onto a column that must convert still blocks
+`ALTER COLUMN … TYPE`, so the differ introspects every existing table — not
+only the manifest ones — whenever there is at least one conversion candidate,
+and reports the dependency instead of emitting DDL PostgreSQL would reject. An
+already-converged database has no candidates and pays nothing.
+
+Ordering is a contract. Conversions carry `SchemaChange.phase =
+'pre_foreign_key'`, and the orchestrator emits them **before every CREATE TABLE
+and every foreign-key statement in the batch**. Both halves matter:
+`planForeignKeyCreation()` only defers the constraints inside a mutual cycle,
+so an acyclic new child table keeps its foreign key *inline in `CREATE TABLE`*
+— a brand-new `uuid` child pointing at a legacy `text` parent fails exactly
+like an existing one, before the parent could be converted. Conversions only
+ever rewrite columns that already exist, so leading the batch is always safe. A
+live `DEFAULT` on a converting column is dropped first (PostgreSQL refuses
+`ALTER COLUMN … TYPE` when the default cannot be cast); the ordinary default
+comparison re-establishes the manifest default on the next run.
+
+There are **two** batch builders and both order on that marker:
+`collectStatementsFromDiff()` in `migrations/orchestrate.ts` (used by
+`getPendingSchemaStatements` / `migrateSmrtSchemas`) and the tracker batch
+`db:migrate` assembles by hand in `@happyvertical/smrt-cli`
+(`commands/utilities.ts`). `partitionSchemaChanges()` carries
+`SchemaChange.phase` onto `MigrationAction.phase` so the CLI can partition the
+same way, in both the applied batch and the `--dry-run` preview. If you add a
+third consumer, order it the same way.
+
+Convergence entries carry the manifest column definition. Every `type_upgrade`
+consumer reads `SchemaChange.column` — `partitionSchemaChanges()` in
+`@happyvertical/smrt-cli` skips an entry without one — so a conversion missing
+it would drop out of the `db:migrate` batch while `compareForeignKeys()` still
+assumed the converged type. Refused convergences carry the same column plus an
+advisory and no SQL, and the CLI routes them to the report-only advisories
+rather than to manual interventions or the tracker.
+
+The uuid wording is gated on the manifest. Both the runtime guard and the
+status planner reach their incompatible-type branch for *any* mismatched pair,
+not only uuid/text. A `USING …::uuid` repair is suggested only when the
+manifest declares UUID on both sides **and** a live side is actually `text`;
+otherwise the diagnostic names the two live types and asks the operator to
+align them deliberately.
+
+The conversion is one-time and idempotent: once the column is native `uuid`,
+the component is uniformly UUID and the planner emits nothing.
+
 Properties to keep if you touch that module:
 
 - **The plan is registry-derived and rebuilt per delete.** Registration is

package/dist/cascade.d.ts

@@ -96,15 +96,11 @@ export declare function cascadeReferencesTo(db: DatabaseInterface, registry: Cas
 /**
  * Run the cascade and the target row's own deletion atomically.
  *
- * When anything references the class and the adapter exposes `transaction()`,
- * the whole sequence runs inside one — including the caller's `deleteSelf`
- * statement, so a failure part-way through cannot leave the object deleted with
- * its junction rows intact (or vice versa). Adapters without transaction
- * support run the same statements sequentially; this is the documented
- * degradation, not a silent one.
- *
- * When nothing references the class there is nothing to keep consistent, and
- * the transaction is skipped — see the comment on that branch.
+ * When the adapter exposes `transaction()`, the whole sequence runs inside one
+ * — including framework-owned row cleanup and the caller's `deleteSelf`
+ * statement, so a failure part-way through cannot leave either side orphaned.
+ * Adapters without transaction support run the same statements sequentially;
+ * this is the documented degradation, not a silent one.
  *
  * @param db - Database the object is bound to
  * @param registry - Registry view used to build cascade plans

package/dist/cascade.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../src/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;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;AAkZD,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;;;;;;;;;;;;;;GAcG;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,CAuDxB"}

package/dist/cascade.js

@@ -24,14 +24,11 @@ import { createLogger } from "@happyvertical/logger";
 *   `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.
-* - When anything needs cascading, everything runs inside a single
-*   transaction when the adapter exposes one, so a partial cascade cannot
-*   survive a failure. A class with no typed references AND no registered
-*   polymorphic association class anywhere in the process skips the
-*   transaction — see {@link runCascadeDelete}. A `metaType` column can point
+* - 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; in an app with even one registered, this fast path is
-*   rare, not the common case.
+*   plausibly relevant.
 *
 * ## Which references are followed
 *
@@ -240,6 +237,43 @@ async function tolerateMissingTable(operation, fallback, context) {
 		throw error;
 	}
 }
+/**
+* System-table cleanup may ignore an absent table for databases created before
+* that subsystem existed, but never a missing column in a table that does
+* exist. The shared `undefined_object` classification intentionally combines
+* both cases, so this security boundary must retain the narrower driver signal.
+*/
+function normalizeMissingTableName(value) {
+	const unquoted = value.replace(/["'`[\]]/g, "");
+	return (unquoted.split(".").at(-1) ?? unquoted).replace(/[^A-Za-z0-9_$-]/g, "").toLowerCase();
+}
+function missingTableNames(messages) {
+	const names = [];
+	const patterns = [
+		/no such table:\s*([^\s,;]+)/giu,
+		/(?:relation|table)\s+((?:"[^"]+"(?:\."[^"]+")*)|(?:[A-Za-z0-9_.$-]+))\s+does not exist/giu,
+		/table with name\s+((?:"[^"]+")|(?:[A-Za-z0-9_.$-]+))\s+does not exist/giu
+	];
+	for (const message of messages) for (const pattern of patterns) for (const match of message.matchAll(pattern)) if (match[1]) names.push(normalizeMissingTableName(match[1]));
+	return names;
+}
+function isMissingTableError(error, expectedTable) {
+	const classification = classifyDatabaseError(error);
+	if (classification.kind !== "undefined_object") return false;
+	if (classification.sqlstate === "42703" || classification.driverCode === "42703" || classification.driverCodes.includes("42703")) return false;
+	const names = missingTableNames(classification.driverMessages);
+	const expected = normalizeMissingTableName(expectedTable);
+	return names.length > 0 && names.every((missingTableName) => missingTableName === expected);
+}
+async function tolerateMissingSystemTable(operation, fallback, context) {
+	try {
+		return await operation();
+	} catch (error) {
+		if (!isMissingTableError(error, context.table)) throw error;
+		logger.warn(`Cascade delete skipped ${context.action} on '${context.table}': table not found in this database.`, { error: error instanceof Error ? error.message : String(error) });
+		return fallback;
+	}
+}
 async function selectIds(db, tableName, column, ids) {
 	const found = [];
 	for (const batch of chunkArray(ids, 900)) {
@@ -275,7 +309,8 @@ async function deleteByIds(db, tableName, ids) {
 * enough.
 *
 * A missing system table is not an error — an application database may predate
-* the table, and losing derived rows must never fail an otherwise valid delete.
+* the table. Every other cleanup failure propagates so the surrounding delete
+* transaction rolls back rather than orphaning tenant-sensitive recall data.
 */
 async function deleteSystemRows(db, ids, classNames) {
 	const ownerIds = ids.filter((id) => typeof id === "string" && id.length > 0 && id !== COLLECTION_OWNER_SENTINEL);
@@ -288,14 +323,13 @@ async function deleteSystemRows(db, ids, classNames) {
 		EMBEDDINGS_TABLE,
 		"object_id",
 		"object_class"
-	]]) for (const batch of chunkArray(ownerIds, 900)) try {
-		await db.delete(table, {
-			...idPredicate(idColumn, batch),
-			...idPredicate(classColumn, classNames)
-		});
-	} catch (error) {
-		logger.warn(`Failed to clean ${table} rows during cascade delete: ${error instanceof Error ? error.message : String(error)}`);
-	}
+	]]) for (const batch of chunkArray(ownerIds, 900)) await tolerateMissingSystemTable(() => db.delete(table, {
+		...idPredicate(idColumn, batch),
+		...idPredicate(classColumn, classNames)
+	}), void 0, {
+		table,
+		action: "framework-owned row cleanup"
+	});
 }
 /**
 * Resolve every reference pointing at `ids` of `className`, recursively.
@@ -383,15 +417,11 @@ async function cascadeReferencesTo(db, registry, target) {
 /**
 * Run the cascade and the target row's own deletion atomically.
 *
-* When anything references the class and the adapter exposes `transaction()`,
-* the whole sequence runs inside one — including the caller's `deleteSelf`
-* statement, so a failure part-way through cannot leave the object deleted with
-* its junction rows intact (or vice versa). Adapters without transaction
-* support run the same statements sequentially; this is the documented
-* degradation, not a silent one.
-*
-* When nothing references the class there is nothing to keep consistent, and
-* the transaction is skipped — see the comment on that branch.
+* When the adapter exposes `transaction()`, the whole sequence runs inside one
+* — including framework-owned row cleanup and the caller's `deleteSelf`
+* statement, so a failure part-way through cannot leave either side orphaned.
+* Adapters without transaction support run the same statements sequentially;
+* this is the documented degradation, not a silent one.
 *
 * @param db - Database the object is bound to
 * @param registry - Registry view used to build cascade plans
@@ -402,12 +432,17 @@ async function cascadeReferencesTo(db, registry, target) {
 async function runCascadeDelete(db, registry, target, deleteSelf) {
 	const ids = target.id ? [target.id] : [];
 	if (buildCascadePlan(registry, target.className).isEmpty) {
-		await deleteSelf(db);
-		await deleteSystemRows(db, ids, ownerClassCandidates(registry, target.className));
-		return {
-			affectedTables: /* @__PURE__ */ new Set(),
-			affectedTableClasses: /* @__PURE__ */ new Map()
+		const runWithoutReferences = async (bound) => {
+			await deleteSystemRows(bound, ids, ownerClassCandidates(registry, target.className));
+			await deleteSelf(bound);
+			return {
+				affectedTables: /* @__PURE__ */ new Set(),
+				affectedTableClasses: /* @__PURE__ */ new Map()
+			};
 		};
+		const transaction = db.transaction;
+		if (typeof transaction !== "function") return runWithoutReferences(db);
+		return transaction.call(db, runWithoutReferences);
 	}
 	const run = async (bound) => {
 		const result = await cascadeReferencesTo(bound, registry, {