@warlock.js/cascade 5.19.1 → 5.20.0

package/skills/define-relations/SKILL.md

@@ -1,171 +1,171 @@
----
-name: define-relations
-description: "Define and query relations in @warlock.js/cascade; use when you need to define 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
+---
+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/index.md

@@ -0,0 +1,23 @@
+---
+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`).
+4. Query, paginate, aggregate (`query-data.md`, `paginate-results.md`, `aggregate-data.md`, `perform-atomic-ops.md`).
+5. Wrap multi-step writes in a transaction (`manage-transactions.md`); pick a delete strategy (`configure-delete-strategy.md`).
+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.
+- `.destroy()` follows the configured strategy (permanent, soft, or trash), not always a hard delete.
+- Relations refer to models by registered name, so `@RegisterModel()` must run first.
+- Run code needing a live connection through `onceConnected`, not at import time.
+- Undefined `where` values and unsafe filters throw on purpose; sanitize user-supplied filters.

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

@@ -1,140 +1,140 @@
----
-name: manage-data-sources
-description: "Manage data sources in @warlock.js/cascade; use when you need to manage data sources."
----
-
-# 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
+---
+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