@warlock.js/cascade 5.30.0 → 5.31.0

package/skills/cascade-basics/SKILL.md

@@ -56,12 +56,12 @@ export class User extends Model<UserSchema> {
 
 // Write
 const user = await User.create({ name: "Ada Lovelace", email: "ada@example.com" });
-user.id;                  // generated ID — direct property
-user.get("status");        // "active" — default fired
+user.id; // generated ID — direct property
+user.get("status"); // "active" — default fired
 
 // Read
 const found = await User.find(user.id);
-found?.get("email");       // "ada@example.com"
+found?.get("email"); // "ada@example.com"
 
 // Filter
 const active = await User.where("status", "active").get();
@@ -70,22 +70,22 @@ const page = await User.paginate({ page: 1, limit: 20 });
 
 ## Pick a skill
 
-| If the task is about… | Load |
-| --- | --- |
-| Defining a model class — schema, decorators, `Model<TSchema>`, accessors | The `define-model` topic |
-| Querying — `.where`, `.find`, `.first`, `.all`, `.count`, `.exists`, ordering | The `query-data` topic |
-| Pagination — `.paginate`, `cursorPaginate`, `chunk` | The `paginate-results` topic |
-| Relations — `belongsTo` / `hasMany` / `belongsToMany`, eager loading | The `define-relations` topic |
-| Migrations — `migration` definition, `up`/`down`, CLI | The `write-migration` topic |
-| Transactions — `transaction(fn)`, rollback, isolation | The `manage-transactions` topic |
-| Dirty tracking — `hasChanges`, `isDirty`, `getDirtyColumns`, `getDirtyColumnsWithValues` | The `track-changes` topic |
-| Lifecycle hooks — `saving`, `saved`, `deleting`, `deleted` | The `subscribe-to-model-events` topic |
-| Soft / hard / trash deletes + restore | The `configure-delete-strategy` topic |
-| Atomic ops — `Model.increase`, `decrease`, `atomic`, `Model.delete(filter)` | The `perform-atomic-ops` topic |
-| Aggregates — `.sum`, `.avg`, `.count`, `.groupBy`, `.having` | The `aggregate-data` topic |
-| Vector search — `similarTo`, pgvector / Atlas vector index | The `search-by-vector` topic |
-| Multiple databases — `connectToDatabase`, per-model `static dataSource` | The `manage-data-sources` topic |
-| CLI + Operations API — `cascade migrate`, `migrate:rollback`, programmatic | The `run-cascade-cli` topic |
+| If the task is about…                                                                    | Load                                  |
+| ---------------------------------------------------------------------------------------- | ------------------------------------- |
+| Defining a model class — schema, decorators, `Model<TSchema>`, accessors                 | The `define-model` topic              |
+| Querying — `.where`, `.find`, `.first`, `.all`, `.count`, `.exists`, ordering            | The `query-data` topic                |
+| Pagination — `.paginate`, `cursorPaginate`, `chunk`                                      | The `paginate-results` topic          |
+| Relations — `belongsTo` / `hasMany` / `belongsToMany`, eager loading                     | The `define-relations` topic          |
+| Migrations — `migration` definition, `up`/`down`, CLI                                    | The `write-migration` topic           |
+| Transactions — `transaction(fn)`, rollback, isolation                                    | The `manage-transactions` topic       |
+| Dirty tracking — `hasChanges`, `isDirty`, `getDirtyColumns`, `getDirtyColumnsWithValues` | The `track-changes` topic             |
+| Lifecycle hooks — `saving`, `saved`, `deleting`, `deleted`                               | The `subscribe-to-model-events` topic |
+| Soft / hard / trash deletes + restore                                                    | The `configure-delete-strategy` topic |
+| Atomic ops — `Model.increase`, `decrease`, `atomic`, `Model.delete(filter)`              | The `perform-atomic-ops` topic        |
+| Aggregates — `.sum`, `.avg`, `.count`, `.groupBy`, `.having`                             | The `aggregate-data` topic            |
+| Vector search — `similarTo`, pgvector / Atlas vector index                               | The `search-by-vector` topic          |
+| Multiple databases — `connectToDatabase`, per-model `static dataSource`                  | The `manage-data-sources` topic       |
+| CLI + Operations API — `cascade migrate`, `migrate:rollback`, programmatic               | The `run-cascade-cli` topic           |
 
 ## Things NOT to do
 

package/skills/configure-delete-strategy/SKILL.md

@@ -11,11 +11,11 @@ description: 'Pick the delete behavior — `permanent` (hard delete), `soft` (se
 
 `DeleteStrategy` is `"permanent" | "soft" | "trash"`.
 
-| Strategy | Behavior | Reversible? |
-| --- | --- | --- |
-| `permanent` | DELETE the row / document (the default fallback) | No |
-| `soft` | Set the `deletedAt` column; the row stays in the table | Yes — via `Model.restore(id)` |
-| `trash` | Move the record to a separate table / collection, then delete the original | Yes — via `Model.restore(id)` |
+| Strategy    | Behavior                                                                   | Reversible?                   |
+| ----------- | -------------------------------------------------------------------------- | ----------------------------- |
+| `permanent` | DELETE the row / document (the default fallback)                           | No                            |
+| `soft`      | Set the `deletedAt` column; the row stays in the table                     | Yes — via `Model.restore(id)` |
+| `trash`     | Move the record to a separate table / collection, then delete the original | Yes — via `Model.restore(id)` |
 
 ## Set the default per-model
 
@@ -36,9 +36,9 @@ When the strategy resolves to `"soft"`, `Migration.create(Model, { … })` adds
 ## Override per-call
 
 ```ts
-await user.destroy();                            // uses the model's strategy
-await user.destroy({ strategy: "permanent" });   // GDPR-compliant hard delete
-await user.destroy({ strategy: "trash" });       // move to the trash table
+await user.destroy(); // uses the model's strategy
+await user.destroy({ strategy: "permanent" }); // GDPR-compliant hard delete
+await user.destroy({ strategy: "trash" }); // move to the trash table
 ```
 
 Resolution order: `destroy({ strategy })` → `static deleteStrategy` → data source `defaultDeleteStrategy` → `"permanent"`.
@@ -50,10 +50,10 @@ After a `"soft"` destroy the in-memory instance reflects the change — `model.g
 Restore is a **static** operation keyed by the record's id. It auto-detects whether the record was soft-deleted or trashed:
 
 ```ts
-const user = await User.restore(123);            // clears deletedAt or pulls from trash; fires "restored"
+const user = await User.restore(123); // clears deletedAt or pulls from trash; fires "restored"
 const user2 = await User.restore(123, { onIdConflict: "fail" });
 
-await User.restoreAll();                          // restore every deleted record for this model
+await User.restoreAll(); // restore every deleted record for this model
 ```
 
 There is no instance `user.restore()` — call `User.restore(id)`. `restoreAll(options?)` restores all soft-deleted (or all trashed) records for the model's table.
@@ -91,7 +91,7 @@ export class User extends Model<UserSchema> {
 With that scope in place:
 
 ```ts
-await User.all();                                          // active only (scope applied)
+await User.all(); // active only (scope applied)
 await User.query().withoutGlobalScope("notDeleted").get(); // active + soft-deleted
 await User.query().withoutGlobalScope("notDeleted").whereNotNull("deletedAt").get(); // only deleted
 ```

package/skills/define-model/SKILL.md

@@ -48,10 +48,10 @@ export class User extends Model<UserSchema> {
 ## Read state — `.id`, `.uuid`, and `.get(field)`
 
 ```ts
-user.id;                   // direct property — ID is so common cascade exposes it directly
-user.uuid;                 // the same id, narrowed to `string` (see below)
-user.get("status");        // canonical reader for every other column
-user.get<number>("age");   // TypeScript generic for typed reads
+user.id; // direct property — ID is so common cascade exposes it directly
+user.uuid; // the same id, narrowed to `string` (see below)
+user.get("status"); // canonical reader for every other column
+user.get<number>("age"); // TypeScript generic for typed reads
 ```
 
 Use the direct `.id` property; use `.get("field")` for everything else. Add a typed getter on the model class when the same field is read in many places — turns N typed-cast call sites into one named accessor.
@@ -60,18 +60,20 @@ Use the direct `.id` property; use `.get("field")` for everything else. Add a ty
 
 Both getters return the model's primary id (`this.get("id")`); the only difference is the **static type**:
 
-| Accessor | Return type | Use when |
-|---|---|---|
-| `model.id` | `string \| number` | You want the real id type — SQL auto-increment is `number`, MongoDB's ObjectId is `string`. |
-| `model.uuid` | `string` | You want to pass the id to code typed for a single `string` id, without leaking the engine's `string \| number` union everywhere. |
+| Accessor     | Return type        | Use when                                                                                                                          |
+| ------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `model.id`   | `string \| number` | You want the real id type — SQL auto-increment is `number`, MongoDB's ObjectId is `string`.                                       |
+| `model.uuid` | `string`           | You want to pass the id to code typed for a single `string` id, without leaking the engine's `string \| number` union everywhere. |
 
 `uuid` does **not** validate or coerce the value to a UUID — the name is historical. It simply returns the same id, typed as `string`, so a helper typed for a string id accepts it on either engine:
 
 ```ts
-function shareLink(modelId: string) { /* ... */ }
+function shareLink(modelId: string) {
+  /* ... */
+}
 
-shareLink(user.uuid);  // ✓ typechecks on both Postgres and MongoDB
-shareLink(user.id);    // ✗ TS error on SQL: `number` is not assignable to `string`
+shareLink(user.uuid); // ✓ typechecks on both Postgres and MongoDB
+shareLink(user.id); // ✗ TS error on SQL: `number` is not assignable to `string`
 ```
 
 ## Write — three update idioms
@@ -94,7 +96,7 @@ await user.merge({ name: "Augusta Ada King", status: "active" }).save();
 
 The everyday case. Service takes `Partial<UserSchema>` from a request body, merges it into the instance, saves. Existing fields not in the object are untouched.
 
-**Safe against id-retargeting by design.** `model.merge(req.body); await model.save();` is the canonical update-my-profile shape — and `req.body` is attacker-controlled. On an already-persisted model, `merge()` drops identity columns (`id`, `_id`, the configured primary key) instead of applying them, so a body carrying `{ id: "<victim-id>", role: "admin" }` cannot redirect the write onto someone else's row: `update()`/`replace()`/`destroy()` build their filter from `model.trustedPrimaryKey` — the id captured when the instance became persisted (hydration, or right after an insert), never the current in-memory value. Identity columns are also excluded from the `$set`/`$unset` payload, so an explicit `.set("id", …)` on a loaded record doesn't rewrite the key of the row it's pinned to either. This only applies to an *existing* record — `User.create({ id, ... })` with an explicit id is unchanged, since there's no row to retarget yet. If you deliberately need to change a primary key, do it through the atomic/raw APIs (see the `perform-atomic-ops` topic), not `merge()`.
+**Safe against id-retargeting by design.** `model.merge(req.body); await model.save();` is the canonical update-my-profile shape — and `req.body` is attacker-controlled. On an already-persisted model, `merge()` drops identity columns (`id`, `_id`, the configured primary key) instead of applying them, so a body carrying `{ id: "<victim-id>", role: "admin" }` cannot redirect the write onto someone else's row: `update()`/`replace()`/`destroy()` build their filter from `model.trustedPrimaryKey` — the id captured when the instance became persisted (hydration, or right after an insert), never the current in-memory value. Identity columns are also excluded from the `$set`/`$unset` payload, so an explicit `.set("id", …)` on a loaded record doesn't rewrite the key of the row it's pinned to either. This only applies to an _existing_ record — `User.create({ id, ... })` with an explicit id is unchanged, since there's no row to retarget yet. If you deliberately need to change a primary key, do it through the atomic/raw APIs (see the `perform-atomic-ops` topic), not `merge()`.
 
 ### `.save()` after manual mutation — when changes are spread
 
@@ -110,11 +112,11 @@ await user.save();
 
 Quick reference:
 
-| Situation | Pattern |
-| --- | --- |
-| 1–2 specific fields | `user.set(k, v).save()` |
-| Bulk from an object | `user.merge(data).save()` |
-| After spread mutations | `user.save()` |
+| Situation              | Pattern                   |
+| ---------------------- | ------------------------- |
+| 1–2 specific fields    | `user.set(k, v).save()`   |
+| Bulk from an object    | `user.merge(data).save()` |
+| After spread mutations | `user.save()`             |
 
 ## Remove a field — `.unset(field)`
 

package/skills/define-relations/SKILL.md

@@ -50,7 +50,7 @@ export class User extends Model<UserSchema> {
 
   @BelongsToMany("Role", {
     pivot: "user_roles",
-    localKey: "user_id",   // pivot column → this model (User)
+    localKey: "user_id", // pivot column → this model (User)
     foreignKey: "role_id", // pivot column → the related model (Role)
   })
   public roles!: Role[];
@@ -64,12 +64,12 @@ export class User extends Model<UserSchema> {
 Manage pivot rows through `model.pivot(relation)`, which returns the relation's `PivotOperations` handle:
 
 ```ts
-await user.pivot("roles").attach([adminId, editorId]);             // add (skips existing)
+await user.pivot("roles").attach([adminId, editorId]); // add (skips existing)
 await user.pivot("roles").attach([adminId], { addedBy: actorId }); // + extra pivot columns
-await user.pivot("roles").detach([editorId]);                      // remove a subset
-await user.pivot("roles").detach();                                // remove all
-await user.pivot("roles").sync([adminId]);                         // replace the whole set
-await user.pivot("roles").toggle([adminId]);                       // flip each id
+await user.pivot("roles").detach([editorId]); // remove a subset
+await user.pivot("roles").detach(); // remove all
+await user.pivot("roles").sync([adminId]); // replace the whole set
+await user.pivot("roles").toggle([adminId]); // flip each id
 ```
 
 `model.attach(relation, ids, pivotData?)` and `model.detach(relation, ids?)` are thin shortcuts for the two most common ops; `.sync()` / `.toggle()` live only on the `pivot(relation)` handle (or the standalone `createPivotOperations(model, relation)`). Passing a non-`belongsToMany` relation throws. Routing through `model.pivot(relation)` keeps the join-table `.sync()` distinct from `Model.sync(Target, field)` (the denormalization-embed feature). Pivot ops run direct driver writes — no model lifecycle events fire on the related model.
@@ -82,7 +82,7 @@ Load related models in the same query, avoiding N+1:
 const posts = await Post.with("author").get();
 
 for (const post of posts) {
-  post.getRelation("author");   // already loaded — no second query
+  post.getRelation("author"); // already loaded — no second query
 }
 ```
 
@@ -104,11 +104,9 @@ await User.with("posts.comments").get();
 Filter parents based on conditions on children:
 
 ```ts
-const usersWithPublishedPosts = await User
-  .whereHas("posts", (query) => {
-    query.where("status", "published");
-  })
-  .get();
+const usersWithPublishedPosts = await User.whereHas("posts", (query) => {
+  query.where("status", "published");
+}).get();
 ```
 
 `.whereHas(relation, callback)` runs the callback on a query builder scoped to the related model. Use when "find Xs that have at least one Y matching Z."
@@ -131,8 +129,8 @@ Why not `post.set("author", currentUser)`? `set` treats the value as a column wr
 ```ts
 const post = await Post.with("author").first();
 
-post.getRelation("author");     // typed access to the loaded User
-post.author;                    // direct field — only if you declared it as a typed field
+post.getRelation("author"); // typed access to the loaded User
+post.author; // direct field — only if you declared it as a typed field
 
 // Without eager loading — load on demand, then read:
 await post.load("author");
@@ -146,10 +144,7 @@ const author = post.getRelation("author");
 `.with()` runs separate queries and hydrates relations. `.joinWith()` joins at the SQL/aggregation level:
 
 ```ts
-const result = await User
-  .joinWith("posts")
-  .where("posts.status", "published")
-  .get();
+const result = await User.joinWith("posts").where("posts.status", "published").get();
 ```
 
 Use `.joinWith` when you need conditions across both tables in a single query. Use `.with` when you want hydrated relation models without joining.

package/skills/index.md

@@ -1,11 +1,13 @@
 ---
 description: "Model-first ORM for MongoDB and Postgres. Exports `Model`, `RegisterModel`, `Migration`, `defineModel`, `BelongsTo`, `HasMany`, `transaction`, `DataSource`, `dataSourceRegistry`, `connectToDatabase`, `runMigrations`. Use for: define a model, add a column or collection, write or alter a migration, query or filter records, paginate, aggregate or group, add a relation, run a transaction, soft delete, track changes, react to save or delete events, vector search. Not this package: request validation and schemas → @warlock.js/seal; routes, controllers, repositories → @warlock.js/core."
 ---
+
 # @warlock.js/cascade
 
 Cascade is the data layer. The model is the query entry point (`User.find(id)`, `User.paginate(...)`); one seal schema gives the TypeScript type, the save-time validation, and the shape migrations write against. MongoDB and Postgres drivers ship with the same query API. Server-only.
 
 ## The 80% path
+
 1. Read `cascade-basics.md` first: it is the map and the ten foundations.
 2. Define the model and register it (`define-model.md`), then relations (`define-relations.md`).
 3. Write the migration; models never create tables or collections on their own (`write-migration.md`, `alter-migration.md`, run with `run-cascade-cli.md`).
@@ -14,6 +16,7 @@ Cascade is the data layer. The model is the query entry point (`User.find(id)`,
 6. Connect and manage drivers (`manage-data-sources.md`); hook lifecycle and diffs (`subscribe-to-model-events.md`, `track-changes.md`); embeddings via `search-by-vector.md`.
 
 ## Conventions and pitfalls
+
 - `pg` and `mongodb` are optional peers; install only the driver you use.
 - `.create()` validates against the schema, applies defaults, and throws on failure.
 - Pick an update idiom by shape: `.set(k, v).save()` for one or two fields, `.merge(data).save()` for payloads.

package/skills/manage-transactions/SKILL.md

@@ -92,9 +92,12 @@ Throwing works too (and re-throws to the caller); `ctx.rollback()` is the non-th
 Default is the driver's default (typically `READ COMMITTED`). Request a different level via `isolationLevel`:
 
 ```ts
-await transaction(async () => {
-  /* ... */
-}, { isolationLevel: "SERIALIZABLE" });
+await transaction(
+  async () => {
+    /* ... */
+  },
+  { isolationLevel: "SERIALIZABLE" },
+);
 ```
 
 On `SERIALIZABLE`, Postgres may abort with a serialization failure when concurrent transactions conflict — wrap in retry logic at the caller.
@@ -104,21 +107,24 @@ On `SERIALIZABLE`, Postgres may abort with a serialization failure when concurre
 Pass `settings` to configure PostgreSQL values only for the current transaction. This is useful for row-level security context, timeouts, and schema selection; Cascade applies each value with parameterized `set_config(..., true)`, so it cannot leak back into the pool:
 
 ```ts
-await transaction(async () => {
-  await Invoice.query().get();
-}, {
-  settings: {
-    "app.tenant_id": tenantId,
-    statement_timeout: 5_000,
+await transaction(
+  async () => {
+    await Invoice.query().get();
   },
-});
+  {
+    settings: {
+      "app.tenant_id": tenantId,
+      statement_timeout: 5_000,
+    },
+  },
+);
 ```
 
 ## Row locking — `lockForUpdate({ skipLocked })` (Postgres)
 
 Chain `lockForUpdate()` on any query to emit `SELECT ... FOR UPDATE`: the matched rows are locked until the transaction ends, so no other transaction can modify or lock them. Only meaningful **inside** a transaction — outside one the lock releases immediately.
 
-`{ skipLocked: true }` adds `SKIP LOCKED` — rows another transaction already holds are silently skipped instead of waited on. That is the standard concurrent queue-claim shape: N workers each grab *different* pending rows with no double-processing and no blocking.
+`{ skipLocked: true }` adds `SKIP LOCKED` — rows another transaction already holds are silently skipped instead of waited on. That is the standard concurrent queue-claim shape: N workers each grab _different_ pending rows with no double-processing and no blocking.
 
 ```ts
 import { transaction } from "@warlock.js/cascade";
@@ -184,7 +190,7 @@ const { rows: counts } = await dataSource.raw<{ count: number }>(
 
 ### Native-array columns (`JSONB[]` / `TEXT[]` / `INTEGER[]`)
 
-From a value alone the serializer can't tell a `json` / `jsonb` column (which needs JSON text) from a genuine **native-array** column (`arrayJson()` → `JSONB[]`, `arrayText()` → `TEXT[]`, …, which needs the raw JS array so node-pg emits a `{...}` literal). Guess wrong and Postgres rejects the insert with *"malformed array literal"*.
+From a value alone the serializer can't tell a `json` / `jsonb` column (which needs JSON text) from a genuine **native-array** column (`arrayJson()` → `JSONB[]`, `arrayText()` → `TEXT[]`, …, which needs the raw JS array so node-pg emits a `{...}` literal). Guess wrong and Postgres rejects the insert with _"malformed array literal"_.
 
 **This is handled automatically.** On connect the driver introspects `information_schema` once and remembers which columns are native arrays **per table**, so `arrayText()` / `arrayJson()` columns just work with **no configuration**. Because it's per-table, the same column name being `TEXT[]` in one table and `jsonb` in another is encoded correctly for each; the pgvector all-number array form is still preserved.
 

package/skills/paginate-results/SKILL.md

@@ -14,8 +14,8 @@ The everyday case for listings with page numbers:
 ```ts
 const page = await User.paginate({ page: 1, limit: 20 });
 
-page.data;        // User[]
-page.pagination;  // { total, page, limit, pages }
+page.data; // User[]
+page.pagination; // { total, page, limit, pages }
 ```
 
 `PaginationOptions` is `{ page?, limit? }` — there is no `filter` field; filter by chaining `.where()` before `.paginate()` (below).
@@ -23,9 +23,7 @@ page.pagination;  // { total, page, limit, pages }
 Chain off `.where()` for filtered pagination:
 
 ```ts
-const activePage = await User
-  .where("status", "active")
-  .paginate({ page: 2, limit: 20 });
+const activePage = await User.where("status", "active").paginate({ page: 2, limit: 20 });
 ```
 
 **Cost characteristic.** Offset pagination scans `offset + limit` rows on every page — page 100 with limit 20 scans 2020 rows just to skip 2000. Fine for the first few pages; not great deep in the result set.
@@ -37,9 +35,9 @@ For very large datasets where deep pagination matters:
 ```ts
 const first = await User.query().orderBy("created_at", "desc").cursorPaginate({ limit: 20 });
 
-first.data;                   // User[]
-first.pagination.nextCursor;  // opaque value — pass to the next call
-first.pagination.hasMore;     // boolean
+first.data; // User[]
+first.pagination.nextCursor; // opaque value — pass to the next call
+first.pagination.hasMore; // boolean
 
 const next = await User.query()
   .orderBy("created_at", "desc")

package/skills/perform-atomic-ops/SKILL.md

@@ -19,10 +19,13 @@ Signature: `Model.increase(filter, field, amount)` / `Model.decrease(filter, fie
 ## Arbitrary atomic mutations — `Model.atomic`
 
 ```ts
-await User.atomic({ id: userId }, {
-  $set: { last_seen: new Date() },
-  $inc: { login_count: 1 },
-});
+await User.atomic(
+  { id: userId },
+  {
+    $set: { last_seen: new Date() },
+    $inc: { login_count: 1 },
+  },
+);
 ```
 
 `Model.atomic(filter, operations)` → `Promise<number>`. Driver-flavored atomic mutation — MongoDB has `$set` / `$inc` / `$push` / `$pull` natively; the Postgres driver supports `$set` / `$unset` / `$inc` / `$dec` (and `$setOnInsert` on upsert) and throws `UnsupportedUpdateOperationError` for the rest. Use when you need to combine multiple field changes atomically without loading the model first.
@@ -48,7 +51,11 @@ const granted = await Quota.atomic(
 
 // MongoDB only: pipeline update, $addToSet, arrayFilters
 await Post.findOneAndUpdate({ slug }, [{ $set: { score: { $add: ["$likes", "$shares"] } } }]);
-await Post.atomic({ slug }, { $set: { "grades.$[low].score": 50 } }, { arrayFilters: [{ "low.score": { $lt: 50 } }] });
+await Post.atomic(
+  { slug },
+  { $set: { "grades.$[low].score": 50 } },
+  { arrayFilters: [{ "low.score": { $lt: 50 } }] },
+);
 ```
 
 - `atomic(filter, update, { upsert?, arrayFilters?, trustedFilter? })` → modified + upserted count.
@@ -56,6 +63,7 @@ await Post.atomic({ slug }, { $set: { "grades.$[low].score": 50 } }, { arrayFilt
 - `findAndUpdate(filter, update, { upsert?, arrayFilters? })`. No `trustedFilter`, because it reads the rows back with `where(filter)`.
 
 **Postgres.** An upsert runs as `INSERT … ON CONFLICT (target) DO UPDATE … RETURNING *`. The target is the primary key, or a unique index, whose columns are ALL equality keys of the filter. Other filter conditions become `DO UPDATE … WHERE`. If the row exists and fails them, nothing is written and `findOneAndUpdate` returns `null`. The driver throws `UnsupportedUpdateOperationError` (`.operation`, `.driver`) for:
+
 - pipeline updates
 - `arrayFilters`
 - `$push`, `$pull`, `$addToSet` and unknown operators
@@ -98,10 +106,7 @@ const rows = await OrderItem.createMany(millionRows, { bulk: true, batchSize: 10
 ## Bulk update — `Model.findAndUpdate(filter, operations)`
 
 ```ts
-const updated = await User.findAndUpdate(
-  { status: "pending" },
-  { $set: { status: "active" } },
-);
+const updated = await User.findAndUpdate({ status: "pending" }, { $set: { status: "active" } });
 // updated: User[] — the matched-and-updated models
 ```
 
@@ -112,8 +117,8 @@ const updated = await User.findAndUpdate(
 ## Bulk delete — `Model.delete(filter)`
 
 ```ts
-await User.delete({ status: "spam" });      // delete all matching → count
-await User.deleteOne({ status: "spam" });   // delete the first match → count
+await User.delete({ status: "spam" }); // delete all matching → count
+await User.deleteOne({ status: "spam" }); // delete the first match → count
 ```
 
 `Model.delete(filter?)` and `Model.deleteOne(filter?)` both return `Promise<number>`. These bypass the per-instance delete strategy and `deleted` events — they are raw driver deletes.
@@ -129,16 +134,16 @@ for (const user of targets) {
 
 ## When to reach for what
 
-| Task | Reach for |
-| --- | --- |
-| Increment a counter | `Model.increase(filter, field, n)` |
-| Atomically change multiple fields on one record | `Model.atomic(filter, ops)` |
-| Insert N records | `Model.createMany(rows)` |
-| Insert a large batch fast (no per-row events) | `Model.createMany(rows, { bulk: true, batchSize })` |
-| Update many rows with operators | `Model.findAndUpdate(filter, { $set: {...} })` |
-| Update one record by id | `Model.update(id, data)` |
-| Delete many rows (raw) | `Model.delete(filter)` |
-| Multi-row read-modify-write | Wrap in a transaction (see the `manage-transactions` topic) |
+| Task                                            | Reach for                                                     |
+| ----------------------------------------------- | ------------------------------------------------------------- |
+| Increment a counter                             | `Model.increase(filter, field, n)`                            |
+| Atomically change multiple fields on one record | `Model.atomic(filter, ops)`                                   |
+| Insert N records                                | `Model.createMany(rows)`                                      |
+| Insert a large batch fast (no per-row events)   | `Model.createMany(rows, { bulk: true, batchSize })`           |
+| Update many rows with operators                 | `Model.findAndUpdate(filter, { $set: {...} })`                |
+| Update one record by id                         | `Model.update(id, data)`                                      |
+| Delete many rows (raw)                          | `Model.delete(filter)`                                        |
+| Multi-row read-modify-write                     | Wrap in a transaction (see the `manage-transactions` topic)   |
 | Need lifecycle events / delete strategy per row | `Model.where(...).get()` + iterate + `.save()` / `.destroy()` |
 
 ## Things NOT to do

package/skills/query-data/SKILL.md

@@ -20,9 +20,9 @@ const activeUsers = await User.where("status", "active").get();
 ### Operators
 
 ```ts
-const adults     = await User.where("age", ">", 18).get();
-const recent     = await User.where("created_at", ">=", lastWeek).get();
-const nonAdmins  = await User.where("role", "!=", "admin").get();
+const adults = await User.where("age", ">", 18).get();
+const recent = await User.where("created_at", ">=", lastWeek).get();
+const nonAdmins = await User.where("role", "!=", "admin").get();
 ```
 
 3-argument form. Common operators: `=`, `!=`, `<`, `<=`, `>`, `>=`, `in`, `notIn`, `like`, `between`. Same syntax across MongoDB and Postgres.
@@ -30,10 +30,7 @@ const nonAdmins  = await User.where("role", "!=", "admin").get();
 ### Compound conditions
 
 ```ts
-const activeAdmins = await User
-  .where("status", "active")
-  .where("role", "admin")
-  .get();
+const activeAdmins = await User.where("status", "active").where("role", "admin").get();
 ```
 
 Chained `.where()` calls combine with `AND`.
@@ -58,7 +55,7 @@ await User.first({ email, password }); // throws UnsafeFilterError if password i
 
 ```ts
 query.whereRaw({ $expr: { $gt: ["$stock", "$reserved"] } }); // object form — MongoDB
-query.whereRaw("age > ?", [30]);                             // string form — SQL, real bindings
+query.whereRaw("age > ?", [30]); // string form — SQL, real bindings
 ```
 
 The **object form** is checked like any other filter value, plus it rejects the server-side-JavaScript operators `$where`, `$function` and `$accumulator` anywhere in the expression (throws `UnsafeRawExpressionError`); `$expr` and the other aggregation operators keep working. The **string form on the MongoDB driver throws `UnsafeRawExpressionError`** — a string used to compile to `{ $where: "<js>" }`, executing arbitrary JavaScript inside `mongod` per scanned document; there is no safe way to parameterize that, so it's rejected outright. Use the object form instead. SQL drivers keep string mode with real `?` bindings (unchanged).
@@ -68,15 +65,15 @@ The **object form** is checked like any other filter value, plus it rejects the
 ### By ID
 
 ```ts
-const user = await User.find(id);  // User | null
+const user = await User.find(id); // User | null
 ```
 
 ### First match
 
 ```ts
-const anyUser    = await User.first();                              // first user, any
-const firstAdmin = await User.first({ role: "admin" });             // first admin
-const filtered   = await User.where("status", "active").first();    // chain into .first()
+const anyUser = await User.first(); // first user, any
+const firstAdmin = await User.first({ role: "admin" }); // first admin
+const filtered = await User.where("status", "active").first(); // chain into .first()
 ```
 
 `.first()` with no args returns the very first record (driver-dependent default order). With a filter object, the first match by equality. Chain off `.where()` when you need operators.
@@ -94,10 +91,7 @@ Throws when nothing matches — useful when you KNOW it should exist and want th
 ## Order and paginate
 
 ```ts
-const newest = await User
-  .where("status", "active")
-  .orderBy("created_at", "desc")
-  .get();
+const newest = await User.where("status", "active").orderBy("created_at", "desc").get();
 ```
 
 `.orderBy(field, "asc" | "desc")` sorts. Default direction is `"asc"`. Chain multiple `.orderBy()` for tiebreakers.
@@ -116,11 +110,11 @@ rows[0].name; // typed as UserSchema, not a User instance
 ## Count and existence
 
 ```ts
-const total       = await User.count();
+const total = await User.count();
 const activeCount = await User.count({ status: "active" });
-const adminCount  = await User.where("role", "admin").count();
+const adminCount = await User.where("role", "admin").count();
 
-const hasAdmin    = await User.where("role", "admin").exists();      // boolean, short-circuits
+const hasAdmin = await User.where("role", "admin").exists(); // boolean, short-circuits
 const noneBlocked = await User.where("status", "blocked").notExists();
 ```
 
@@ -129,7 +123,7 @@ const noneBlocked = await User.where("status", "blocked").notExists();
 ## Get many — `.all(filter?)`
 
 ```ts
-const allUsers    = await User.all();
+const allUsers = await User.all();
 const activeUsers = await User.all({ status: "active" });
 ```
 
@@ -141,19 +135,19 @@ const activeUsers = await User.all({ status: "active" });
 
 Cascade's query builder has around 60 methods. Reach for these as the need arises:
 
-| Reach for | When |
-| --- | --- |
-| `.whereIn(field, values)` / `.whereNotIn(field, values)` | Match against / exclude a list |
-| `.whereNull(field)` / `.whereNotNull(field)` | Nullability checks |
-| `.whereBetween(field, [a, b])` | Inclusive range |
-| `.whereDate(field, value)`, `.whereDateBetween`, `.whereDateBefore`, `.whereDateAfter` | Date helpers |
-| `.whereLike(field, pattern)` / `.whereStartsWith` / `.whereEndsWith` / `.whereSearch` | Pattern matching — see below for literal-vs-regex semantics |
-| `.whereHas(relation, callback)` | Filter by conditions on a related model |
-| `.sum(field)` / `.avg(field)` / `.min(field)` / `.max(field)` | Aggregates — the `aggregate-data` topic |
-| `.distinct(field)` / `.pluck(field)` | Single-field reads (distinct values, flat list) |
-| `.chunk(size, callback)` | Stream a large table in batches |
-| `.cursorPaginate({ limit, cursor })` | Cursor pagination — the `paginate-results` topic |
-| `.similarTo(column, embedding)` | Vector similarity — the `search-by-vector` topic |
+| Reach for                                                                              | When                                                        |
+| -------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `.whereIn(field, values)` / `.whereNotIn(field, values)`                               | Match against / exclude a list                              |
+| `.whereNull(field)` / `.whereNotNull(field)`                                           | Nullability checks                                          |
+| `.whereBetween(field, [a, b])`                                                         | Inclusive range                                             |
+| `.whereDate(field, value)`, `.whereDateBetween`, `.whereDateBefore`, `.whereDateAfter` | Date helpers                                                |
+| `.whereLike(field, pattern)` / `.whereStartsWith` / `.whereEndsWith` / `.whereSearch`  | Pattern matching — see below for literal-vs-regex semantics |
+| `.whereHas(relation, callback)`                                                        | Filter by conditions on a related model                     |
+| `.sum(field)` / `.avg(field)` / `.min(field)` / `.max(field)`                          | Aggregates — the `aggregate-data` topic                     |
+| `.distinct(field)` / `.pluck(field)`                                                   | Single-field reads (distinct values, flat list)             |
+| `.chunk(size, callback)`                                                               | Stream a large table in batches                             |
+| `.cursorPaginate({ limit, cursor })`                                                   | Cursor pagination — the `paginate-results` topic            |
+| `.similarTo(column, embedding)`                                                        | Vector similarity — the `search-by-vector` topic            |
 
 Each chains off `User.where(...)` or `User.query()` and ends with the appropriate terminator. (`where`, `with`, `joinWith`, `first`, `count`, `find`, `all`, `paginate` are static shortcuts on the model; the rest live on the query builder, so reach them via `User.query()` or by chaining off a static `where`.)
 

package/skills/run-cascade-cli/SKILL.md

@@ -19,6 +19,7 @@ cascade migrate:export-sql      # write .up.sql / .down.sql instead of executing
 ```
 
 Flags:
+
 - `migrate` — `-f/--fresh` (drop everything and re-run), `-s/--sql` (export SQL instead of executing), `--pending-only`, `-c/--compact`, `-p/--path <glob>`
 - `migrate:rollback` — `-a/--all` (roll back everything), `--batches N`, `-p/--path <glob>`
 - `migrate:export-sql` — `--pending-only`, `-c/--compact`, `-p/--path <glob>`
@@ -102,16 +103,16 @@ Reach for these when you need migrations inside test setup (`beforeAll(async ()
 
 ## Common task → command
 
-| You want to… | Command |
-|---|---|
-| Run all pending migrations | `cascade migrate` |
-| Drop everything and re-run | `cascade migrate -f` |
-| Roll back the last batch | `cascade migrate:rollback` |
-| Roll back everything | `cascade migrate:rollback --all` |
-| Generate SQL without executing | `cascade migrate --sql` |
-| Generate SQL for pending only | `cascade migrate --sql --pending-only` |
-| See what's been executed | `cascade migrate:list` |
-| Run from a non-default folder | `cascade migrate -p "<glob>"` |
+| You want to…                   | Command                                |
+| ------------------------------ | -------------------------------------- |
+| Run all pending migrations     | `cascade migrate`                      |
+| Drop everything and re-run     | `cascade migrate -f`                   |
+| Roll back the last batch       | `cascade migrate:rollback`             |
+| Roll back everything           | `cascade migrate:rollback --all`       |
+| Generate SQL without executing | `cascade migrate --sql`                |
+| Generate SQL for pending only  | `cascade migrate --sql --pending-only` |
+| See what's been executed       | `cascade migrate:list`                 |
+| Run from a non-default folder  | `cascade migrate -p "<glob>"`          |
 
 ## Things NOT to do