@warlock.js/cascade 4.0.171 → 4.1.1

package/skills/define-model/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: define-model
+description: 'Define a Cascade model — `@RegisterModel()`, class extends `Model<TSchema>`, `static table`, `static schema`, three update idioms (`.set` / `.merge` / `.save`), `.unset`, `.destroy`, `static toJsonColumns` / `resource` for output shaping. Triggers: `Model`, `RegisterModel`, `static schema`, `.set`, `.merge`, `.save`, `.unset`, `.destroy`, `toJsonColumns`, `resource`; "how do I define a model", "shape the JSON output", "remove a field"; typical import `import { Model, RegisterModel } from "@warlock.js/cascade"`. Skip: querying — `@warlock.js/cascade/query-data/SKILL.md`; relations — `@warlock.js/cascade/define-relations/SKILL.md`; competing libs `mongoose`, `prisma`, `typeorm` `@Entity`.'
+---
+
+# Define a model
+
+Four moves: schema → class → write → read. Every Cascade model uses the same shape.
+
+## Step 1 — Define the schema
+
+The schema is your single declaration of what a record looks like. Same `v.object` does triple duty later: validates incoming data, infers the TypeScript type, and is the shape your table writes against.
+
+```ts title="src/app/users/models/user/user.model.ts"
+import { v, type Infer } from "@warlock.js/seal";
+
+export const userSchema = v.object({
+  name: v.string(),
+  email: v.string().email(),
+  status: v.literal("active", "inactive").default("active"),
+});
+
+export type UserSchema = Infer<typeof userSchema>;
+```
+
+- Fields are **required by default** — chain `.optional()` on any field that may be missing.
+- `Infer<typeof userSchema>` derives the TS type. No second declaration, no drift.
+- The schema is standalone — reuse it for HTTP body validation, service-input validation, anywhere else.
+- See [`@warlock.js/seal/seal-basics/SKILL.md`](@warlock.js/seal/seal-basics/SKILL.md) for the validator vocabulary.
+
+## Step 2 — Define the model class
+
+```ts
+import { Model, RegisterModel } from "@warlock.js/cascade";
+
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  public static table = "users";
+  public static schema = userSchema;
+}
+```
+
+- `@RegisterModel()` puts `User` in the global registry. That registry is what lets relations look each other up by name.
+- `extends Model<UserSchema>` gives the class the entire CRUD/query API typed against your schema.
+- `static table` matches the migration. Plural, lowercase, snake_case is the convention on both drivers.
+- `static schema` attaches the validator. On every `save()`, the data goes through `userSchema` before it hits the database.
+
+## Read state — `.id` and `.get(field)`
+
+```ts
+user.id;                   // direct property — ID is so common cascade exposes it directly
+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.
+
+## Write — three update idioms
+
+Cascade gives you three ways to update an instance. Knowing when each fits saves you from reaching for the wrong one.
+
+### `.set(field, value).save()` — one field change
+
+```ts
+await user.set("status", "inactive").save();
+```
+
+Direct, reads top to bottom. `.set()` stages; `.save()` persists and fires events.
+
+### `.merge(data).save()` — bulk update from an object
+
+```ts
+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.
+
+### `.save()` after manual mutation — when changes are spread
+
+```ts
+user.set("status", "inactive");
+
+if (someCondition) {
+  user.set("online_state", "offline");
+}
+
+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()` |
+
+## Remove a field — `.unset(field)`
+
+```ts
+await user.unset("image").save();
+```
+
+`.unset()` marks the field for removal — Postgres sets it to `NULL`, MongoDB drops the field entirely. Different from `.set("image", null)` which stores an explicit null (and may fail validation if the field isn't `.optional()`).
+
+## Delete — `.destroy()`
+
+```ts
+await user.destroy();
+```
+
+Runs the model's lifecycle (events, configured delete strategy), then removes the record. See [`@warlock.js/cascade/configure-delete-strategy/SKILL.md`](@warlock.js/cascade/configure-delete-strategy/SKILL.md) for soft / hard / trash semantics.
+
+## Public output shaping
+
+`JSON.stringify(user)` calls `model.toJSON()` under the hood. With no configuration, it returns the entire row. **Always configure shaping when the model is returned from an HTTP handler.**
+
+### Fast escape — `static toJsonColumns`
+
+```ts
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  public static table = "users";
+  public static schema = userSchema;
+  public static toJsonColumns = ["id", "name", "email"];
+}
+```
+
+Anything outside the allow-list is dropped from serialization. Use when the public shape is a strict subset of the columns.
+
+### Richer path — `static resource`
+
+```ts
+class UserResource {
+  public constructor(private data: Record<string, unknown>) {}
+
+  public toJSON() {
+    return {
+      id: this.data.id,
+      displayName: this.data.name,
+      contactEmail: this.data.email,
+      avatar: this.data.image ?? null,
+    };
+  }
+}
+
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  public static table = "users";
+  public static schema = userSchema;
+  public static resource = UserResource;
+}
+```
+
+Plain TypeScript class. No framework dependencies. `static resourceColumns` narrows which columns reach the resource; pair the two for strongly-typed public output.
+
+## Things NOT to do
+
+- Don't `new User()` to create a record — `User.create({...})` validates, persists, fires events.
+- Don't `.set("relation_name", instance)` for a relation slot. Use `setRelation("name", instance)`.
+- Don't return the raw model from an HTTP route without shaping output. Add `toJsonColumns` or `resource`.
+- Don't `await user.save()` and forget the `await` — your changes live only on the instance and never reach the DB.
+- Don't expect schema defaults to apply on `.merge()` — defaults fire on `.create()` only.
+
+## See also
+
+- [`@warlock.js/cascade/query-data/SKILL.md`](@warlock.js/cascade/query-data/SKILL.md) — finding and filtering records
+- [`@warlock.js/cascade/define-relations/SKILL.md`](@warlock.js/cascade/define-relations/SKILL.md) — relations and eager loading
+- [`@warlock.js/cascade/track-changes/SKILL.md`](@warlock.js/cascade/track-changes/SKILL.md) — dirty tracking
+- [`@warlock.js/cascade/subscribe-to-model-events/SKILL.md`](@warlock.js/cascade/subscribe-to-model-events/SKILL.md) — lifecycle hooks

package/skills/define-relations/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: define-relations
+description: 'Define and query relations — `@BelongsTo` / `@HasMany` / `@BelongsToMany`, `.with("relation")` eager loading, `.whereHas(relation, cb)` filter-by-related, `setRelation` on save, `.joinWith` for SQL joins, `loadRelation`, `lazy(() => Model)`. Triggers: `@BelongsTo`, `@HasMany`, `@BelongsToMany`, `.with`, `.whereHas`, `setRelation`, `.joinWith`, `lazy`; "define a relation", "avoid N+1", "eager load posts", "filter parents by child"; typical import `import { BelongsTo, HasMany, BelongsToMany } from "@warlock.js/cascade"`. Skip: model basics — `@warlock.js/cascade/define-model/SKILL.md`; competing libs `mongoose populate`, `prisma include`, `typeorm relations`.'
+---
+
+# Define and query relations
+
+Relations are decorators on model fields. Cascade's global registry (populated by `@RegisterModel()`) lets each relation look up its peer by name — so `@BelongsTo("User")` finds the `User` class without an import (which avoids circular-dep hell when two models reference each other).
+
+## Three core relation types
+
+### `@BelongsTo(target)` — the foreign-key side
+
+```ts
+import { BelongsTo, Model, RegisterModel } from "@warlock.js/cascade";
+
+@RegisterModel()
+export class Post extends Model<PostSchema> {
+  public static table = "posts";
+  public static schema = postSchema;
+
+  @BelongsTo("User", { foreignKey: "author_id" })
+  public author!: User;
+}
+```
+
+`Post.belongs_to(User)`. The `author_id` column lives on `posts`. Pass the model name (string) for late-bound lookup, or a `lazy(() => User)` thunk if you need explicit type checking. `lazy` comes from `@mongez/reinforcements` (`import { lazy } from "@mongez/reinforcements"`), not from cascade.
+
+### `@HasMany(target)` — the inverse, one-to-many
+
+```ts
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  public static table = "users";
+  public static schema = userSchema;
+
+  @HasMany("Post", { foreignKey: "author_id" })
+  public posts!: Post[];
+}
+```
+
+`User.has_many(Post)`. Same `author_id` column on `posts` — the relation is described from both ends so eager loading and filtering work in both directions.
+
+### `@BelongsToMany(target, options)` — many-to-many via a pivot
+
+```ts
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  // ...
+
+  @BelongsToMany("Role", {
+    pivot: "user_roles",
+    localKey: "user_id",   // pivot column → this model (User)
+    foreignKey: "role_id", // pivot column → the related model (Role)
+  })
+  public roles!: Role[];
+}
+```
+
+`User.belongs_to_many(Role)` via the `user_roles` pivot table with `user_id` + `role_id`. The pivot's two columns are `localKey` (this model's FK) and `foreignKey` (the related model's FK) — there is no `relatedKey` option. Both sides of the many-to-many declare the relation (symmetric).
+
+#### Pivot operations
+
+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], { 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
+```
+
+`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.
+
+## Eager loading — `.with(relation)`
+
+Load related models in the same query, avoiding N+1:
+
+```ts
+const posts = await Post.with("author").get();
+
+for (const post of posts) {
+  post.getRelation("author");   // already loaded — no second query
+}
+```
+
+Multiple relations:
+
+```ts
+await User.with("posts", "roles").get();
+```
+
+Nested relations via dot:
+
+```ts
+await User.with("posts.comments").get();
+// Loads users → their posts → comments for each post — all in 3 queries, not N²
+```
+
+## Filtering by related conditions — `.whereHas`
+
+Filter parents based on conditions on children:
+
+```ts
+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."
+
+## Setting a relation on save — `setRelation`
+
+When you persist a model that ALSO needs to wire a relation slot at the same time, use `setRelation` — NOT `.set()`:
+
+```ts
+const post = new Post();
+post.merge({ title: "Hello", body: "..." });
+post.setRelation("author", currentUser);
+await post.save();
+```
+
+Why not `post.set("author", currentUser)`? `set` treats the value as a column write — for a relation slot, you'd be writing the User instance into a column. `setRelation` knows it's a relation, picks the right foreign-key column, and stores the ID.
+
+## Reading loaded relations
+
+```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
+
+// Without eager loading — load on demand, then read:
+await post.load("author");
+const author = post.getRelation("author");
+```
+
+`getRelation("name")` returns the loaded relation (or null if not loaded). `post.load("relation", ...)` lazy-loads one or more relations onto the instance and returns the model (`this`) — read the value back with `getRelation` afterward. Useful when you didn't `.with()` upfront and need a relation conditionally.
+
+## Joins — when eager loading isn't enough
+
+`.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();
+```
+
+Use `.joinWith` when you need conditions across both tables in a single query. Use `.with` when you want hydrated relation models without joining.
+
+## Sync — embedded relations stay fresh
+
+For embedded/denormalized relations (cached `author_name` on posts, etc.), Cascade's sync system keeps the embedded copy in step with the source-of-truth via `Model.sync(Target, field)` and the `@warlock.js/cascade` sync helpers.
+
+## Things NOT to do
+
+- Don't `post.set("author", user)`. Use `setRelation("author", user)`. `set` treats the value as a column write; `setRelation` picks the right foreign key.
+- Don't load all parents and iterate to fetch each child — that's the N+1 problem. Eager-load with `.with(...)` (or load specific children with `.load(...)` after the parent fetch).
+- Don't define a relation on only one side. Both ends of `BelongsTo`/`HasMany` and both sides of `BelongsToMany` need the decorator for queries to work bidirectionally.
+- Don't import the related class for `@BelongsTo` if it would create a circular dependency. Use the string form (`@BelongsTo("User")`) or `lazy(() => User)`.
+
+## See also
+
+- [`@warlock.js/cascade/query-data/SKILL.md`](@warlock.js/cascade/query-data/SKILL.md) — `.whereHas` and other filters
+- [`@warlock.js/cascade/define-model/SKILL.md`](@warlock.js/cascade/define-model/SKILL.md) — `@RegisterModel`, the registry that makes name-based lookup work

package/skills/manage-data-sources/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: manage-data-sources
+description: 'Configure multiple databases — register each via `connectToDatabase({ name, driver, database, isDefault })`, assign a model with `static dataSource = "name"`, route a migration with `dataSource` on the migration class, inspect via `dataSourceRegistry.get(name)` / `getAllDataSources()`. The first (or `isDefault: true`) source is the default. Triggers: `connectToDatabase`, `dataSourceRegistry`, `dataSourceRegistry.get`, `getAllDataSources`, `static dataSource`; "multi-database app", "per-tenant DB", "analytics on separate DB"; typical import `import { connectToDatabase, dataSourceRegistry } from "@warlock.js/cascade"`. Skip: per-source migrations — `@warlock.js/cascade/write-migration/SKILL.md`; transaction scope — `@warlock.js/cascade/manage-transactions/SKILL.md`; competing patterns `mongoose.createConnection`, `typeorm` `DataSource`, `prisma` multi-schema.'
+---
+
+# Manage data sources
+
+Most apps run against a single database, and Cascade's defaults assume that. When you need multiple — analytics on a separate DB, per-tenant DBs — register each one and bind models to the right source.
+
+## Register sources at boot
+
+`connectToDatabase()` builds the driver, registers the data source, and connects. Call it once per database:
+
+```ts
+import { connectToDatabase } from "@warlock.js/cascade";
+
+await connectToDatabase({
+  name: "primary",
+  driver: "postgres",
+  database: "app",
+  host: "localhost",
+  port: 5432,
+  username: "app",
+  password: "secret",
+  isDefault: true, // the default source for models that don't pin one
+});
+
+await connectToDatabase({
+  name: "analytics",
+  driver: "postgres",
+  database: "analytics",
+  host: "analytics-host",
+});
+
+await connectToDatabase({
+  name: "logs",
+  driver: "mongodb",
+  database: "logs",
+  uri: "mongodb://localhost:27017",
+});
+```
+
+The first source registered becomes the default unless another passes `isDefault: true`. (Lower-level: `dataSourceRegistry.register({ name, driver, isDefault })` if you build the driver yourself — `register` takes a `DataSourceOptions` object whose `driver` is a `DriverContract` instance, and constructs the `DataSource` for you.)
+
+## Assign a model to a source
+
+```ts
+@RegisterModel()
+export class AnalyticsEvent extends Model<AnalyticsEventSchema> {
+  public static table = "analytics_events";
+  public static schema = analyticsEventSchema;
+  public static dataSource = "analytics"; // ← goes to the analytics DB
+}
+
+@RegisterModel()
+export class LogEntry extends Model<LogEntrySchema> {
+  public static table = "logs";
+  public static schema = logEntrySchema;
+  public static dataSource = "logs"; // ← goes to MongoDB
+}
+```
+
+`static dataSource` takes the registered name (or a `DataSource` instance). Models without it use the default. Same query API; different storage. There is no per-query `Model.using(name)` override — the binding lives on the class.
+
+## Migrations per data source
+
+A migration class can pin its target source:
+
+```ts
+import { Migration } from "@warlock.js/cascade";
+
+export default class CreateEventsTable extends Migration {
+  public readonly table = "analytics_events";
+  public readonly dataSource = "analytics";
+
+  public up(): void {
+    this.createTable();
+    this.id();
+    this.string("type");
+    this.timestamps();
+  }
+
+  public down(): void {
+    this.dropTable();
+  }
+}
+```
+
+See [`@warlock.js/cascade/write-migration/SKILL.md`](@warlock.js/cascade/write-migration/SKILL.md) for the migration shape.
+
+## Transactions and data sources
+
+The top-level `transaction(fn)` helper runs on the **default** source's driver — it does not take a source name. To transact against a non-default source, reach for that source's driver directly (`dataSourceRegistry.get("analytics").driver.transaction(...)`). Transactions can't span two sources; coordinate at the application level (saga / outbox) if you need that.
+
+```ts
+await transaction(async () => {
+  // runs on the default source
+  await Order.create({ ... });
+  await OrderItem.createMany(items);
+});
+```
+
+## Multi-tenant per-tenant database
+
+For strict tenant isolation, register a source per tenant once, then bind at the model layer (or resolve the model class per tenant):
+
+```ts
+async function ensureTenantSource(tenantId: string) {
+  try {
+    dataSourceRegistry.get(tenantId); // throws if not registered
+  } catch {
+    const config = await loadTenantConfig(tenantId);
+    await connectToDatabase({ name: tenantId, ...config, isDefault: false });
+  }
+}
+```
+
+Register each tenant source once and reuse it — re-registering the same name re-creates the source.
+
+## Inspection
+
+```ts
+dataSourceRegistry.get("analytics"); // the DataSource instance (throws if missing)
+dataSourceRegistry.get(); // the default DataSource
+dataSourceRegistry.getAllDataSources(); // DataSource[] — every registered source
+```
+
+There is no `has(name)` / `list()` / `setDefault()` — guard with a `try/catch` around `get(name)`, iterate `getAllDataSources()`, and set the default via `isDefault` at registration.
+
+## Things NOT to do
+
+- Don't call `dataSourceRegistry.register("name", config)` — `register` takes a single `DataSourceOptions` object (`{ name, driver, isDefault }`, `driver` being a built `DriverContract`); for the common case use `connectToDatabase({ name, ... })`.
+- Don't reach for `Model.using(name)` / `setDefault` / `has` / `list` — they don't exist. Bind via `static dataSource`, inspect via `get` / `getAllDataSources`.
+- Don't span a transaction across two data sources. Use a saga / outbox pattern.
+- Don't write to a read replica. Most replicas reject writes; the data is overwritten on the next replication.
+
+## See also
+
+- [`@warlock.js/cascade/write-migration/SKILL.md`](@warlock.js/cascade/write-migration/SKILL.md) — per-source migrations
+- [`@warlock.js/cascade/manage-transactions/SKILL.md`](@warlock.js/cascade/manage-transactions/SKILL.md) — transactions run on the default source

package/skills/manage-transactions/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: manage-transactions
+description: 'Wrap multi-statement work in `transaction(async () => {...})` — rollback on throw, commit on resolve, optional `isolation` level (Postgres), per-`dataSource` scope. Postgres native; MongoDB requires replica set. Triggers: `transaction`, `isolation`, `SERIALIZABLE`, `READ COMMITTED`, nested savepoints; "wrap two writes atomically", "transfer balance between accounts", "rollback on error", "MongoDB replica set transactions"; typical import `import { transaction } from "@warlock.js/cascade"`. Skip: single-row atomic ops without a transaction — `@warlock.js/cascade/perform-atomic-ops/SKILL.md`; per-source scope — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing patterns `mongoose.startSession`, `pg` `BEGIN` manually, `prisma.$transaction`, `typeorm` `QueryRunner`.'
+---
+
+# Use transactions
+
+A transaction is a sequence of database operations that succeed or fail as one unit. Cascade wraps the driver-level transaction with a function-shaped API — pass a callback, throw to roll back, return to commit.
+
+## Shape
+
+```ts
+import { transaction } from "@warlock.js/cascade";
+
+await transaction(async () => {
+  const account = await Account.where("id", fromId).firstOrFail();
+  const target = await Account.where("id", toId).firstOrFail();
+
+  await account.merge({ balance: account.get<number>("balance") - amount }).save();
+  await target.merge({ balance: target.get<number>("balance") + amount }).save();
+});
+```
+
+If either `.save()` throws, both are rolled back. If the callback returns, both are committed atomically.
+
+## Return values
+
+The callback's resolved value becomes the transaction's resolved value:
+
+```ts
+const order = await transaction(async () => {
+  const created = await Order.create({...});
+  await OrderItem.createMany(items.map(item => ({ ...item, order_id: created.id })));
+  return created;
+});
+// order is the created Order
+```
+
+## Rollback on throw
+
+Any thrown error inside the callback rolls back the entire transaction and re-throws to the caller:
+
+```ts
+try {
+  await transaction(async () => {
+    await user.save();
+    if (someInvariantFails) {
+      throw new Error("invariant violated");
+    }
+    await audit.save();
+  });
+} catch (error) {
+  // both user and audit writes are rolled back; error propagates here
+}
+```
+
+## MongoDB requires a replica set
+
+MongoDB transactions only work on replica sets — a single-node `mongod` without `--replSet` will throw. For local dev, run a single-node replica set:
+
+```bash
+mongod --replSet rs0 --port 27017
+# then in mongo shell:
+rs.initiate()
+```
+
+Postgres has no such requirement — transactions work out of the box.
+
+## Nesting
+
+The function-shaped `transaction(fn)` is **not** nestable — calling it inside an already-open transaction is not supported. For nested scope on Postgres, drop to the manual API (`driver.beginTransaction()`) and use savepoints explicitly. For most app code, keep a single top-level `transaction(fn)` and let any inner failure abort the whole flow.
+
+## Explicit rollback
+
+The callback receives a transaction context; call `ctx.rollback()` to roll back without throwing:
+
+```ts
+await transaction(async (ctx) => {
+  await user.save();
+  if (!isValid) {
+    ctx.rollback("validation failed");
+  }
+});
+```
+
+Throwing works too (and re-throws to the caller); `ctx.rollback()` is the non-throwing path.
+
+## Isolation level (Postgres)
+
+Default is the driver's default (typically `READ COMMITTED`). Request a different level via `isolationLevel`:
+
+```ts
+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.
+
+## Outside the transaction
+
+Once the callback returns, the transaction is committed. Subsequent calls — including reads — see the committed state. Don't try to "share" a model instance between inside-transaction and outside contexts; reload outside if you need fresh state.
+
+## Side effects after commit — the outbox pattern
+
+For "side effects must only happen if the transaction succeeded" (publish to a queue, send an email, write to a search index), don't run them inside the transaction. Use the outbox pattern: write a row to an outbox table inside the transaction, dispatch from the outbox in a separate worker after commit.
+
+## Things NOT to do
+
+- Don't call external APIs (HTTP, queues, file writes) inside a transaction. Long-running side effects extend the lock; failures don't roll back the external call.
+- Don't use a single-node mongod for transactions. Run a replica set even in dev.
+- Don't `try/catch` and swallow inside a transaction — the catch defeats the rollback. If you must, re-throw after handling.
+- Don't pass models loaded outside the transaction into it expecting fresh reads. Reload inside.
+
+## See also
+
+- [`@warlock.js/cascade/perform-atomic-ops/SKILL.md`](@warlock.js/cascade/perform-atomic-ops/SKILL.md) — atomic single-document ops without a full transaction
+- [`@warlock.js/cascade/manage-data-sources/SKILL.md`](@warlock.js/cascade/manage-data-sources/SKILL.md) — transactions run on the default source