joist-codegen 2.3.0-next.12 → 2.3.0-next.121

package/skills/joist-reactive-hints/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: joist-reactive-hint
+description: Explains how Joist reactive hints work and what they cost to run — a hint is both a reverse-reactivity trigger (which roots re-run when a hinted field changes) and a forward load hint (what gets populated before the lambda runs), so a rule can pull an entire child collection into memory even when its lambda only reads a parent field. Covers followReverseHint, the two rule shapes (child-rooted reacting up to a parent vs parent-rooted reacting down into a child collection), and how to avoid surprise O(children) loads. Use when reasoning about the performance of a reactive rule/field/property (addRule, hasReactiveField, hasReactiveProperty, hasReactiveReference), when a validation rule seems to load far more rows than expected, when deciding whether to put a field in a reactive hint vs load it on-demand, or when a hot-path mutation (e.g. a bulk job) triggers surprise N×M loads. Keywords: reactive hint, load hint, reverse reactivity, followReverseHint, reverseSubHint, m2o vs o2m reactivity, over-invalidation, populate, "a parent rule that hints a child collection loads the whole collection".
+---
+
+# Joist reactive hints
+
+Reactive hints declare the fields a rule, `ReactiveField`, `ReactiveProperty`, or `ReactiveReference`
+depends on. A hint does **double duty**: Joist walks it in **reverse** to find *which* roots to re-run
+when a hinted field changes, then uses it **forward as a load hint** to populate that data on each root
+before the lambda runs. Most hints are cheap — but either direction can pull an entire child collection
+into memory, and the *forward* load is the surprising one, so both are the focus below.
+
+## TL;DR
+
+A reactive rule/field is declared on a **root entity** with a hint. There are two shapes, and they
+cost very differently.
+
+**Shape #1 — rule on the child, hint reaches *up* to the parent** (e.g. a rule on `Book` with
+`{ author: ["currentDraftBook"] }`). When `Author.currentDraftBook` changes, Joist walks the hint in
+reverse (`followReverseHint`), reversing the `Book.author` m2o into the `Author.books` o2m and
+**loading the whole collection** to enumerate the child roots, then re-runs each book's rule.
+`O(children)` per parent-field change. This is **intuitive**: "change the author, and all of its books
+re-check."
+
+**Shape #2 — rule on the parent, hint reaches *down* into a child collection** (e.g. a rule on `Author`
+with `{ books: ["title"] }`). When a single `Book.title` changes, the reverse walk is **cheap** — one
+`book.author` m2o hop to the one author. But the reactive hint is **also a load hint**: before running
+the author's lambda, Joist populates `author.books`, pulling the **entire** collection into memory —
+*even if the lambda only reads `author.status` and never touches the books*.
+
+> The surprising one is **Shape #2**. `{ books: ["title"] }` reads like "react to book titles," but it
+> *also* means "load all of this author's books every time this rule fires." A lambda whose body is just
+> `return a.status === "active" ? undefined : "…"` still pays to load `author.books`, because the
+> **hint, not the lambda body, decides what gets loaded**.
+
+Neither shows up in tests (behavior is correct; only throughput/memory suffer). Both bite bulk/hot-path
+jobs at scale — Shape #2 especially, because it looks cheap from the reverse-reactivity side.
+
+## Why: reverse reactivity *and* load hints
+
+A hinted-field change triggers two steps, both in `joist-core/build/reactivity/reactiveHints.js`:
+
+**Step 1 — find the roots (reverse walk).** `followReverseHint` starts at the changed entity and walks
+the hint in reverse, reversing each *traversed relation* (via `reverseSubHint`):
+
+- Reverse of an **m2o** (`Book.author`) is the **o2m** (`Author.books`) — so a **child-rooted** rule
+  reacting to a parent field loads the whole sibling collection just to list the roots (Shape #1).
+- Reverse of an **o2m** (`Author.books`) is the **m2o** (`Book.author`) — so a **parent-rooted** rule
+  reacting to a child field finds exactly one root per changed child (Shape #2's reverse is cheap).
+- A **leaf field** (primitive / enum / m2o read as a value, e.g. `["title"]`, `["currentDraftBook"]`) is
+  only a "react to this field changing" trigger; it is **not** traversed into.
+
+**Step 2 — load the hint (forward populate).** Before running each root's lambda, Joist populates the
+reactive hint *as a load hint* on that root so the lambda can read it synchronously. For a parent-rooted
+rule with `{ books: [...] }`, that is effectively `author.populate("books")` — the **full collection** —
+**regardless of what the lambda actually reads**. This is why Shape #2 is expensive even though its
+reverse walk touched only one author: the cost is in the forward load, not the reverse walk.
+
+So `{ author: ["currentDraftBook"] }` on `Book` compiles to a reactive target
+`{ entity: Author, fields: ["currentDraftBook"], path: ["books"] }` — "when `Author.currentDraftBook`
+changes, load `Author.books` and re-validate each" — while `{ books: ["title"] }` on `Author` loads
+`author.books` on every fire so the rule can run at all. Either way Joist over-invalidates for
+correctness: every sibling is re-checked/loaded even when only one could change the outcome.
+
+## The old/new-value shortcut — and when it does NOT apply
+
+`followReverseHint` has a reference-history optimization (`getInstanceData(c).getReferenceHistory`)
+that pulls in **old + new** values — but only when the **step being walked is itself an m2o/poly**
+(the "`Book.author` moved to a new `Author`" reparent case). It exists so a reparent re-validates
+both the old and new parent.
+
+It does **not** turn a child→`parent.field` reaction into a cheap old/new lookup: there, the walked
+step is the `books` **o2m**, so Joist takes the `relation.load()` (full-collection) branch. The
+`currentDraftBook` field's own m2o-ness is irrelevant — it's reacted to *as a field*, not *traversed*.
+
+Rule of thumb for the cost of one changed field:
+- reverse step is an **o2m/o2o** (you're on the child, parent-field changed) → **loads the full
+  sibling collection**.
+- reverse step is an **m2o/poly** being reparented → loads a couple entities (current + history).
+
+## How to spot / avoid it
+
+- **The hint decides the load, not the lambda body.** A parent rule with `{ books: [...] }` loads
+  *every* book on *every* fire, even if the lambda only reads the parent's own fields. If the rule does
+  not actually need the collection, do not hint it; if it does, know you are paying `O(children)` memory
+  per fire.
+- **For SQL-derived fields, split the hint with `hasAsyncReactiveField`.** It takes two hints — a
+  `loadHint`, whose data is populated into memory and passed to the lambda, and a `reactiveHint`, whose
+  data only *triggers* recalculation but is **not** loaded into memory (the lambda recomputes from SQL
+  instead). Put the large child collections you merely need to react to in the `reactiveHint` so a
+  child-field change still recomputes the value without pulling every sibling into memory.
+- **Root the rule where the frequently-changing field lives.** A rule on `Book` reacting to
+  `author.currentDraftBook` reloads all siblings; the same check rooted on `Author` reacting to its
+  own `["currentDraftBook"]` needs no reverse collection-load (but then detecting anything about the
+  *children* forces you to scan them anyway — so this only helps if the check is about the parent).
+- **Only react to fields that change rarely.** Put a field in the reactive hint only if you truly
+  need to re-run when it changes. If you just need to *read* a value, `await rel.load()` it on
+  demand inside the rule and leave it out of the hint. Reserve the hint for the rare-change trigger
+  that actually needs to fire the rule.
+- **Watch bulk/hot-path mutations.** If a job sets some `parent.fk` once per child (e.g. a bulk
+  copy job setting `author.currentDraftBook` per book), any child-rooted rule reacting to that fk
+  reloads every child's siblings — the same `O(children × siblings)` you'd get from an explicit
+  `parent.children.load()` in the loop.
+
+## Worked examples
+
+### Shape #2 — the surprising one: a parent rule hinting into a child collection
+
+```ts
+// ❌ Rooted on Author. The hint `{ books: ["title"] }` reads like "react to book titles" — but it is
+// ALSO a load hint, so every time ANY book's title changes, Joist loads the author's ENTIRE `books`
+// collection into memory to run this rule, even though the lambda only looks at the author's status.
+authorConfig.addRule(["status", { books: ["title"] }], (a) => {
+  return a.status === "active" ? undefined : "inactive authors need review";
+});
+
+// ✅ The rule only depends on the author's own status, so hint only that — no books are loaded.
+authorConfig.addRule("status", (a) => {
+  return a.status === "active" ? undefined : "inactive authors need review";
+});
+```
+
+If the rule genuinely must react to a child field, keep the hint — but know each fire loads the whole
+collection, so reserve it for collections the lambda actually reads and for child fields that change
+rarely.
+
+### Shape #1 — intuitive but still O(children): a child rule reacting to a parent field
+
+Invariant wanted: "an unpublished book must be one of its author's tracked books — its `favoriteBook` or
+`currentDraftBook`."
+
+```ts
+// ❌ Simple but O(books × siblings) on the bulk copy-job hot path:
+// the job sets author.currentDraftBook per book -> reverse-loads author.books each time.
+bookConfig.addRule(
+  ["publishedAt", { author: ["favoriteBook", "currentDraftBook"] }],
+  (b) => { ... },
+);
+
+// ✅ React only to favoriteBook (which changes rarely — on publish, not per draft edit);
+// read currentDraftBook on-demand so it's not a reactive dependency.
+bookConfig.addRule(["publishedAt", { author: ["favoriteBook"] }], async (b) => {
+  if (b.publishedAt) return;
+  const author = b.author.get;
+  const favorite = author.favoriteBook.get;
+  const draft = await author.currentDraftBook.load(); // read, don't react
+  if (b !== favorite && b !== draft) return `${b} is unpublished but neither the favorite nor current draft`;
+});
+```

package/skills/joist-test-factories/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: joist-test-factories
+description: Use when writing or refactoring Joist ORM tests with newTestInstance factories, DeepNew, run or makeRun, toMatchEntity, and nested Given graphs.
+---
+
+# Joist Test Factories
+
+Write isolated, succinct tests that use Joist's factories for setup, retain
+typed entity references through the action, and assert those same entities
+with `toMatchEntity`.
+
+Authoritative references:
+
+- <https://joist-orm.io/testing/test-factories/>
+- <https://joist-orm.io/testing/entity-matcher/>
+- <https://joist-orm.io/testing/test-utils/>
+- <https://joist-orm.io/goals/great-tests/>
+
+## Non-Negotiable Rules
+
+1. Create initial Given state with test factories. Never use the same function
+   or API operation under test to arrange its own preconditions.
+2. Set only fields and relationships that define the boundary case. Let the
+   factories supply unrelated required values and dependencies.
+3. Keep direct `const` references to entities that participate in the action or
+   assertions.
+4. Keep using the factory-created `DeepNew` graph after same-`EntityManager`
+   actions or actions run through Joist's test `run` helper. Do not reload the
+   same rows merely to assert against them.
+5. Use `run` or the project's `makeRun` wrapper when production code needs an
+   isolated `EntityManager`; it flushes Given state and mirrors the callback's
+   flushed Joist writes into the original test graph.
+6. Assert entity state and relationships with `toMatchEntity`.
+7. Prefer focused tests for one behavior over a single scenario that exercises
+   unrelated updates at several graph levels.
+
+## Given, When, Then
+
+Structure every test as "Given the state of the world is X, When action Y
+happens, Then the state of the world is Z": the factory-created graph is the
+Given, the code under test is the When, and `toMatchEntity` proves the Then.
+Mark the three phases with `// Given`, `// When`, `// Then` comments:
+
+```ts
+it.withCtx("updates a book", async (ctx) => {
+  // Given an author with one book
+  const author = newAuthor(ctx.em, {
+    books: [{ title: "Before" }],
+  });
+  const [book] = author.books.get;
+
+  // When we update the book's title (updateBook owns and flushes its production unit of work)
+  await run(ctx, (ctx) => updateBook(ctx, { id: book.id, title: "After" }));
+
+  // Then the book's title is changed
+  expect(author).toMatchEntity({ books: [{ title: "After" }] });
+});
+```
+
+The factory owns the Given defaults. `run` provides production isolation and
+mirrors flushed writes. The callback still owns its production unit of work.
+`toMatchEntity` owns the Then's entity-aware assertions.
+
+## Factories Own Given State
+
+Do not call the same code under test to arrange its own preconditions:
+
+```ts
+// Wrong: saveAuthor is both setup and the behavior under test.
+const created = await saveAuthor(ctx, {
+  firstName: "a1",
+  books: [{ title: "Before" }],
+});
+const author = await created.author;
+```
+
+This couples setup to the behavior under test, can reproduce the same bug in
+both phases, and loses the ergonomic `DeepNew` type.
+
+Use a factory instead:
+
+```ts
+const author = newAuthor(ctx.em, {
+  books: [{ title: "Before" }],
+});
+const [book] = author.books.get;
+```
+
+Factories are test-only tools. Never call them from production code.
+Using another production API for Given state can be valid in an integration
+test when that API's authorization, hooks, defaults, or events are part of the
+scenario. This should be intentional, not the default way to create rows.
+
+## Keep Given State Minimal
+
+Every explicit factory option should answer: "Why does this test need this
+value?"
+
+```ts
+// Wrong: most values are unrelated to changing one title.
+const author = newAuthor(ctx.em, {
+  firstName: "Ann",
+  lastName: "Smith",
+  age: 40,
+  books: [
+    {
+      title: "Before",
+      order: 1,
+      published: false,
+      reviews: [],
+    },
+  ],
+});
+```
+
+```ts
+// Right: only the value being changed is specified.
+const author = newAuthor(ctx.em, {
+  books: [{ title: "Before" }],
+});
+```
+
+Specify additional values only when they establish the scenario. Examples:
+
+- Two `{}` children establish collection cardinality.
+- Distinct sort orders may be necessary for a parent/sort-order unique key.
+- An initial value is necessary when the assertion proves that it changed.
+- A relation override is necessary when the identity of that relation matters.
+
+Do not copy production payloads into factory opts. Factory opts describe the
+minimum database state before the action, not every field the action accepts.
+
+## Build Graphs in One Factory Call
+
+Prefer a top-level factory with nested opts when it clearly describes the
+scenario:
+
+```ts
+const author = newAuthor(ctx.em, {
+  books: [{ title: "First", reviews: [{ rating: 5 }] }, { title: "Second" }],
+});
+const [firstBook, secondBook] = author.books.get;
+const [review] = firstBook.reviews.get;
+```
+
+This is usually clearer than creating each row separately and wiring every
+required relation by hand. Separate factory calls are appropriate when the
+test's behavior is specifically about how independently created entities
+relate.
+
+Factories recursively fill required primitives and relations. They also reuse
+an obvious existing entity when exactly one candidate exists. Use factory
+controls intentionally:
+
+- Pass an entity directly to force a specific relation.
+- Pass `{ use: entity }` to nominate an existing entity throughout a factory
+  scope.
+- Pass `{}` for a relation when a new related entity is required.
+- Use `useFactoryDefaults: false` sparingly; frequent use means the factory
+  defaults may be too opinionated.
+- Use `useFactoryDefaults: "none"` only for tests explicitly exercising invalid
+  or incomplete state.
+
+## Retain Entity References
+
+Immediately name entities used by the action or assertions:
+
+```ts
+const author = newAuthor(ctx.em, {
+  books: [{}, {}],
+});
+const [updatedBook, deletedBook] = author.books.get;
+```
+
+Do not unnecessarily rediscover Given entities later by index, query, ID, or
+mutation result. Newly created entities can come from the action result, and a
+query result is appropriate when querying is the behavior under test.
+
+For complicated cross-references in one factory graph, use factory IDs:
+
+```ts
+const author = newAuthor(ctx.em, {
+  books: [
+    { is: "b#1", title: "First" },
+    { is: "b#2", prequel: "b#1", title: "Second" },
+  ],
+});
+const [firstBook, secondBook] = author.books.get;
+
+expect(secondBook).toMatchEntity({ prequel: firstBook });
+```
+
+The `factories` proxy is also available when direct relation destructuring is
+awkward:
+
+```ts
+newAuthor(ctx.em, { books: [{}, {}] });
+const { a1, b1, b2 } = factories;
+```
+
+The proxy resolves against the most recently used `EntityManager`, so avoid it
+in tests with multiple active test entity managers.
+
+Prefer ordinary named constants when the graph is small; they make the test's
+roles clearer than numeric factory IDs.
+
+## DeepNew Means Async-Free Graph Access
+
+Follow the signature generated by the project's Joist version. Factories that
+return `DeepNew<Entity>` provide the loaded graph ergonomics used here:
+
+```ts
+export function newAuthor(em: EntityManager, opts: FactoryOpts<Author> = {}): DeepNew<Author> {
+  return newTestInstance(em, Author, opts, {});
+}
+```
+
+`DeepNew` is a loadedness type for the factory-created graph, so setup and
+assertions can use `.get` without `await`:
+
+```ts
+const author = newAuthor(ctx.em, { books: [{}] });
+const [book] = author.books.get;
+
+expect(author).toMatchEntity({ books: [book] });
+```
+
+Avoid this boilerplate:
+
+```ts
+const books = await author.books.load();
+const reloadedAuthor = await ctx.em.load(Author, author.id);
+const reloadedBooks = await reloadedAuthor.books.load();
+```
+
+`DeepNew` does not synchronize writes from another `EntityManager`. If a
+relation was not part of the factory-created graph, use an intentional
+populate, or use Joist's `run` helper when testing a separate production unit
+of work. Do not silence a legitimate unloaded-relation boundary with arbitrary
+test-only loads.
+
+## Use run for Production Isolation
+
+Joist's `run(ctx, fn)` executes `fn` with a fresh production-style context and
+`EntityManager`. Before the callback, it flushes the test factory graph. As the
+callback flushes Joist writes, `RunPlugin` mirrors those writes into the
+original test `EntityManager`. It does not call `EntityManager.refresh`. The
+callback result is also mapped back to entities from the original test
+`EntityManager`.
+
+```ts
+const author = newAuthor(ctx.em, { books: [{ title: "Before" }] });
+const [book] = author.books.get;
+
+// updateBook must own and flush its production unit of work.
+await run(ctx, (ctx) => updateBook(ctx, { id: book.id, title: "After" }));
+
+expect(book).toMatchEntity({ title: "After" });
+```
+
+Many applications expose a project-specific helper created with `makeRun`,
+such as `runMutation` or `runService`. Use that helper instead of manually
+constructing a second `EntityManager`.
+
+`run` deliberately does not flush the callback's `EntityManager`; production
+code under test must own its normal unit-of-work boundary. Unflushed changes,
+direct SQL, and writes outside Joist are not guaranteed to be mirrored into the
+test graph.
+
+Do not write:
+
+```ts
+const result = await runMutation(ctx, () => updateBookInput(book.id));
+const savedBook = await result.book;
+const books = await savedBook.author.load().then((author) => author.books.load());
+```
+
+Keep using `author` and `book`. They are the stable test references.
+
+Call `em.flush()` directly only when the test intentionally needs a persistence
+boundary and its helper does not provide one. Pure entity tests should usually
+avoid unnecessary flushes.
+
+## Register toMatchEntity
+
+Examples assume `toMatchEntity` is imported from the `joist-orm/tests`
+entry point and registered in the project's test setup:
+
+```ts
+import { toMatchEntity } from "joist-orm/tests";
+
+expect.extend({ toMatchEntity });
+```
+
+Use the runner-specific setup and types from the installed Joist version.
+
+## Assert with toMatchEntity
+
+`toMatchEntity` provides `toMatchObject`-style subset assertions while
+understanding Joist references, collections, properties, reactive fields, and
+entity identity. It also produces concise entity IDs in diffs.
+
+`toMatchEntity` synchronously unwraps loaded relations through `.get`; it does
+not query or asynchronously load missing relations. Ensure the asserted graph
+is loaded by the factory, an intentional populate, or `RunPlugin`.
+
+```ts
+expect(author).toMatchEntity({
+  firstName: "Ann",
+  books: [book],
+});
+expect(book).toMatchEntity({ title: "After" });
+```
+
+Pass retained entity constants directly for relationship identity. Use nested
+object literals when the nested values themselves are the assertion:
+
+```ts
+expect(author).toMatchEntity({
+  books: [{ title: "First" }, { title: "Second" }],
+});
+```
+
+For a hard delete, assert both the surviving collection and deletion state
+when deletion semantics matter:
+
+```ts
+expect(author).toMatchEntity({ books: [updatedBook] });
+expect(deletedBook).toMatchEntity({ isDeletedEntity: true });
+```
+
+Do not map entity graphs into temporary POJOs just to use `toEqual`:
+
+```ts
+// Wrong.
+expect((await author.books.load()).map((book) => ({ id: book.id, title: book.title }))).toEqual([
+  { id: updatedBook.id, title: "After" },
+]);
+```
+
+## Keep Tests Focused
+
+One test should describe one coherent boundary. Split a large graph mutation
+into separate tests when failures would otherwise have several unrelated
+causes:
+
+- Updating/deleting members of a parent collection.
+- Updating/deleting grandchildren.
+- Creating a new nested entity.
+- Clearing a collection.
+- Preserving an omitted relation.
+
+Combining an update and delete can be appropriate when they jointly exercise
+one incremental-collection contract. Avoid a kitchen-sink test that performs
+step updates, ingredient updates, note updates, and several unrelated scalar
+changes in one action.
+
+Focused tests produce smaller Given graphs, clearer constants, and useful
+failure messages.
+
+## Factory Defaults
+
+Customize a generated factory only for defaults that make entities valid by
+default across the suite:
+
+```ts
+export function newAuthor(em: EntityManager, opts: FactoryOpts<Author> = {}): DeepNew<Author> {
+  return newTestInstance(em, Author, opts, {
+    age: 40,
+  });
+}
+```
+
+Use `testIndex` for deterministic unique values when a database unique
+constraint requires them. Add collection defaults only for genuine suite-wide
+validity rules, such as every valid author requiring at least one book.
+
+Custom options such as `withSignedContract` can package a commonly repeated
+graph, but use them sparingly. A reader should not need to inspect a factory to
+understand the values directly asserted by the test.
+
+If factory behavior is surprising, enable `useLogging: true` for that call or
+temporarily enable global factory logging. Diagnose the factory scope and
+reuse decisions instead of replacing factories with manual setup.
+
+## Review Checklist
+
+- Test reads as Given, When, Then, with the code under test isolated as a single
+  When.
+- Given state uses minimal factory opts and does not invoke the behavior under
+  test.
+- Important entities have direct, role-based `const` names.
+- Separate production units of work use `run`/`makeRun` and flush normally.
+- Assertions reuse loaded factory entities with `toMatchEntity`.
+- No unnecessary reloads, `load()` calls, assertion awaits, or direct flushes
+  remain.
+- Each test covers one coherent boundary.

package/skills/joist-upsert/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: joist-upsert
+description: Implement partial-update / RPC / GraphQL save endpoints with Joist using setPartial, createPartial, em.upsert, and incremental collection ops. Use when a create/update accepts a subset of fields, treats null as "unset", or saves a parent plus a mix of new and existing children.
+---
+
+<!-- Managed by joist-codegen. Do not edit by hand; re-run codegen to update. -->
+
+# Joist partial updates & upsert
+
+These APIs exist for "partial update" endpoints (REST/GraphQL/gRPC) where the
+input is loosely typed (`string | null | undefined`) and follows the
+conventions:
+
+- A subset of fields may be sent; omitted fields are left as-is.
+- `null` means "unset this field".
+- Children collections can be updated incrementally.
+
+Joist's normal `em.create` / `Entity.set` are intentionally strict and won't
+accept `string | null | undefined`. The partial variants opt into the looser
+semantics.
+
+## `setPartial`
+
+```ts
+// firstName is typed `string | null | undefined` (e.g. from a GraphQL input)
+const author = await em.load(Author, "a:1");
+author.setPartial({ firstName }); // compiles; `set` would not
+```
+
+Semantics, per field:
+
+- Required field (`firstName`): value updates it; `undefined` does nothing;
+  `null` is a **validation error** (required field can't be unset).
+- Optional field (`lastName`): value updates it; `undefined` does nothing;
+  `null` unsets it (sets to `undefined`).
+- Collection (`books`): `[b1]` sets it to exactly `[b1]`; `null` sets it to
+  `[]`; `undefined` does nothing.
+
+`em.createPartial(Author, ...)` and `em.upsert(Author, ...)` share these
+semantics.
+
+## `em.upsert` — parent plus children
+
+`em.upsert` saves a parent and a mix of new/existing children in one call. It is
+**async** (unlike `em.create`) because it may issue `SELECT`s to resolve
+existing child ids.
+
+```ts
+await em.upsert(Author, {
+  id: "a:1",                       // update author 1
+  books: [
+    { title: "new book" },         // no id -> create
+    { id: "b:1" },                 // existing, unchanged
+    { id: "b:2", title: "updated" }, // existing, updated
+  ],
+});
+```
+
+By default a collection is set **exhaustively** — any existing child not listed
+is removed.
+
+## Incremental collections (`op`)
+
+To change only some children without sending the whole collection, add an `op`
+hint to each child:
+
+```ts
+author.setPartial({
+  books: [{ op: "include", title: "b3" }], // adds b3, leaves existing books
+});
+```
+
+- `{ op: "include", id }` — add if needed, or update an existing child
+- `{ op: "remove", id }` — remove from the collection (no delete)
+- `{ op: "delete", id }` — remove and `em.delete` the child
+
+Rules and gotchas:
+
+- If **any** child has an `op`, **all** children must have one.
+- `op` is not a real entity field — it's only a hint on the input type.
+- An **empty** list always clears the collection (it looks like an exhaustive
+  set), so to send "no changes" omit the collection key entirely. Alternatively
+  include a single `{ op: "incremental" }` sentinel child to force incremental
+  semantics without adding/removing anything.
+
+## Legacy keys (soft-deprecated)
+
+Older code used `delete: true` / `remove: true` instead of `op`; still
+supported, but prefer `op` for new code:
+
+```ts
+author.setPartial({
+  books: [{ id: "b:1", delete: true }, { id: "b:2", remove: true }, { id: "b:4" }],
+});
+```