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

package/skills/joist-docs/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: entity-docs
+description: Read the `src/entities/<Entity>.md` business-docs when working on an entity, its resolvers, jobs, or tests. Add only durable, non-obvious domain knowledge that helps readers understand a business rule or avoid a likely mistake; prioritize succinctness, clarity, and discretion. Also covers how `## Overview` and `## Fields`/`### fieldName` sections sync to JSDocs via `yarn joist-codegen`.
+---
+
+# Entity docs (`src/entities/<Entity>.md`)
+
+Many Joist entities have a sibling Markdown doc — `src/entities/Author.ts` ↔
+`src/entities/Author.md` (same basename; enums under `src/entities/enums/` too). These files hold the
+**"why"** that code can't: business rationale, worked scenarios, gotchas, domain vocabulary, and
+cross-entity workflows. They are written for **both humans and agents** — you are a primary audience.
+
+Read routinely; write selectively:
+
+1. **Read** the sibling `.md` before/while you work on an entity, to get domain context.
+2. **Write** only when a concise addition would give future readers important context they cannot
+   readily get from the code or existing docs. Leaving the docs unchanged is often the right outcome.
+
+## 1. Read it first
+
+Before editing an entity — its `src/entities/<Entity>.ts`, its resolvers, a job that touches it, or its
+tests — open `src/entities/<Entity>.md` if one exists. It routinely explains things you would otherwise
+have to reverse-engineer or would get subtly wrong:
+
+- **Business rationale** — *why* a field/entity exists and what real-world thing it models
+  (e.g. `PurchaseOrder.md` on tracking "what and why" a project's cost changed).
+- **Worked scenarios** — concrete `I.e.` walkthroughs with real values ("when an `Employee` is termined, the status workflow is...").
+- **Gotchas & edge cases** — footguns, "this looks stale but isn't", exemptions
+- **Domain vocabulary** — statuses, flags, and other "esoteric unless you know it" domain concepts
+
+Follow relevant cross-links (`[Book](Book.md)`, sometimes with anchors like
+`Book.md#Definitions`) into related docs. A missing or thin doc is not by itself a reason to add content.
+
+## 2. How the file maps to code (the codegen doc-sync)
+
+`joist-config.json` has `"docs": true`, so `yarn joist-codegen` keeps these `.md` files and the entity
+JSDocs in sync. Understanding this is what makes your writing land in the right place.
+
+**Only two heading shapes are parsed and synced; everything else is free-form narrative:**
+
+| `.md` section | Syncs to | Notes |
+|---|---|---|
+| `## Overview` (body) | the entity **class** JSDoc | exact heading `## Overview` |
+| `## Fields` → `### <fieldName>` (body) | that field/property/relation's JSDoc | `### ` heading must be the **exact member name** |
+| any other `## Section` (e.g. `## Hard vs. Soft Costs`, `## DB Constraints`, mermaid) | **nothing** | free-form; lives only in the `.md`, preserved verbatim |
+
+Synced JSDocs are tagged `@generated <Entity>.md` in the `.ts` — that tag means "this comment came from
+the `.md`; edit the `.md`, not here."
+
+**Sync is bidirectional, but the `.md` wins.** `yarn joist-codegen`:
+
+1. **Backfills** the `.md` from any hand-written `.ts` JSDoc that isn't in the `.md` yet (so a jsdoc you
+   write directly on a field gets pulled into `## Fields` for you), then
+2. **Writes the `.md` back into the `.ts`** JSDocs — so for anything already in the `.md`, the `.md` is
+   the source of truth and will overwrite a divergent `.ts` comment.
+
+Net rule: **to durably document an entity or field, edit the `.md`.** Hand-editing a `@generated` JSDoc
+in the `.ts` gets stomped on the next codegen.
+
+### Field-heading constraints (easy to get wrong)
+
+- `### <fieldName>` must be a **single word** — the parser matches `\w+` only. `### excludeFromBudget`
+  works; `### is excluded`, `` ### `excludeFromBudget` ``, or `### excludeFromBudget (derived)` are **not**
+  recognized as field docs.
+- It must be the **exact** name of a field, relation, or property on the entity, and must sit **under the
+  `## Fields` heading**. Any other `##` heading ends the fields section — so keep all `### fieldName`
+  entries together under the one `## Fields` section (conventionally at the bottom of the file).
+- **Methods don't sync** — only fields/getters/properties/relations get their JSDoc updated.
+
+## 3. Choose what is worth documenting
+
+Add a note only when the knowledge is durable, non-obvious, and useful for a future domain decision or
+for avoiding a likely mistake. Possible candidates, not a checklist to fill:
+
+- You just figured out **why** an entity or field exists, or what it really models.
+- A **non-obvious business rule**, invariant, or "this only applies to X clients" exemption.
+- A **gotcha / footgun** — a value that looks stale but isn't, an ordering requirement, a special-cased
+  type.
+- A **cross-entity interaction** or workflow that isn't visible from one file.
+- **Domain vocabulary** a newcomer (human or agent) wouldn't know.
+- A **worked scenario** needed to resolve an ambiguity that a short explanation cannot.
+
+**Omit** what the code already says plainly, transient implementation details, exhaustive edge-case
+lists, and a recap of the work just completed. Do not repeat knowledge already documented elsewhere;
+link to it when readers need it. Correct outdated guidance rather than appending a competing explanation.
+
+**Where to put it:**
+
+- Something specific to one field → a `### <fieldName>` block under `## Fields`. It syncs to that
+  member's JSDoc, so it shows on hover/`@generated` in the `.ts`.
+- The entity's purpose → a short `## Overview`, which syncs to the class JSDoc.
+- Necessary longer explanations or cross-entity workflows → a free-form `##` section, linked from the
+  field doc if needed. Keep synced JSDocs small enough to read comfortably on hover.
+
+**Style** (prioritize succinctness and clarity):
+
+- Lead with business meaning and *why*. Use plain language and state each fact once.
+- Default to one sentence for a field and one short paragraph for an overview. Add detail only when
+  shortening it would hide an important rule or make the meaning ambiguous.
+- Use a single brief `I.e. ...` example with concrete values only when it clarifies a difficult rule.
+  Do not add examples, diagrams, or sections merely to make the doc look complete.
+- Cross-link related entities with relative links: `[Book](Book.md)`.
+- Reference field/entity names in backticks.
+- Before finishing, remove any sentence that does not add necessary meaning. Match existing terminology,
+  but do not copy existing verbosity.
+
+## 4. Workflow to add or update a doc
+
+1. If an addition meets the criteria above, edit `src/entities/<Entity>.md` (create it only if needed — basename must equal the entity, e.g.
+   `Author.md`). For field docs, use the exact member name as a `### ` heading under `## Fields`.
+2. Sync into the JSDocs:
+   ```bash
+   mise exec -- yarn joist-codegen
+   ```
+   (or `mise exec -- yarn codegen` to also run graphql-codegen.)
+3. Verify the `@generated <Entity>.md` JSDoc now appears on the class / field in `src/entities/<Entity>.ts`.
+4. Commit the `.md` **and** the regenerated `.ts` JSDoc changes together.
+
+Never hand-edit a `@generated <Entity>.md` JSDoc in the `.ts` — edit the `.md` and re-run codegen. Do not
+touch files under `src/entities/codegen/` (see the repo's generated-files rules).
+
+## Skeleton for a new doc
+
+Include only the sections and fields that need explanation; this is a structure, not a checklist.
+
+```markdown
+# <Entity>
+
+## Overview
+
+<What this entity models and *why* it exists, in business terms. One short paragraph.>
+
+## <Some Business Concept>   <!-- free-form: rationale, scenarios, gotchas, diagrams; NOT synced -->
+
+<Only if needed: a concise explanation of a non-obvious business concept.>
+
+## Fields   <!-- each ### below syncs into that member's JSDoc -->
+
+### someField
+
+<Usually one sentence: why it exists or the important non-obvious rule.>
+```

package/skills/joist-em-basics/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: joist-em-basics
+description: Create, load, find, mutate, and save entities with Joist's EntityManager. Use when writing data-access or business logic in a Joist project — anything using em.create, em.load, em.find, em.flush, or walking the entity graph.
+---
+
+<!-- Managed by joist-codegen. Do not edit by hand; re-run codegen to update. -->
+
+# Joist EntityManager basics
+
+The `EntityManager` (`em`) is how entities are loaded from and saved to the
+database. It is a Unit of Work: each request gets its own `em`, which tracks
+the entities it has loaded/created and writes them all out on `em.flush()`.
+
+Entities are always loaded/created _through_ the `em`, never via static methods
+on the class (Joist is not ActiveRecord). IDs are tagged strings like `"a:1"`.
+
+## Creating
+
+`em.create` is synchronous and returns the new entity immediately:
+
+```ts
+const author = em.create(Author, { firstName: "a1" });
+// Nested/related entities can be created inline
+const author = em.create(Author, { firstName: "a1", address: { street: "123 Main" } });
+```
+
+## Loading by id
+
+Use tagged ids. These throw if the id does not exist (except the `IfExists`
+variants):
+
+```ts
+const a = await em.load(Author, "a:1");
+const as = await em.loadAll(Author, ["a:1", "a:2"]);
+const as = await em.loadAllIfExists(Author, ["a:1", "a:2"]); // skips missing ids
+```
+
+To eagerly load relations, pass a populate hint as the 3rd argument; the
+returned entity is typed as "loaded" so the relations can be read synchronously:
+
+```ts
+const a = await em.load(Author, "a:1", { books: "reviews" });
+a.books.get.flatMap((b) => b.reviews.get);
+```
+
+## Walking the graph
+
+~90% of reads are just navigating relations from an entity you already have.
+These are guaranteed N+1-safe, even in a loop:
+
+```ts
+const author = await book.author.load();        // load a single relation
+const reviews = await publisher.load((p) => p.books.reviews); // lens
+const loaded = await author.populate({ books: "reviews" });   // populate + .get
+```
+
+## Finding (filtered queries)
+
+`em.find` issues a `SELECT` with a "join literal" of nested relations plus
+inline `WHERE` conditions. It is batch/N+1-safe.
+
+```ts
+const books = await em.find(Book, { author: { firstName: "a1" } });
+const recent = await em.find(Book, { publishedAt: { gte: jan1 } });
+const some = await em.find(Author, { firstName: { in: ["a1", "a2"] } });
+
+const one = await em.findOne(Book, { title: "b1" });        // undefined if none
+const one = await em.findOneOrFail(Book, { title: "b1" });  // throws if none
+const one = await em.findOrCreate(Author, { email: "a@b.com" });
+```
+
+`undefined` values are pruned (the condition and any now-unused join are
+dropped), so filters compose cleanly. To filter for null, pass `null`
+explicitly, e.g. `{ firstName: null }`. For `OR` / nested boolean logic, use
+`alias`/`aliases` with a `conditions` argument. For aggregates or group-bys,
+drop down to Knex/Kysely — Joist's `find` only returns whole entities.
+
+## Mutating
+
+Assign fields directly, or use `.set` for a batch of changes:
+
+```ts
+author.firstName = "a2";
+author.set({ firstName: "a2", lastName: "b2" });
+```
+
+For partial/RPC-style updates (treating `null` as "unset"), and for
+incrementally updating children, see the `joist-upsert` skill.
+
+## Deleting
+
+```ts
+const a = await em.load(Author, "a:1");
+em.delete(a);
+```
+
+## Saving with `em.flush()`
+
+`em.flush()` is where everything happens. It is async and:
+
+1. Runs lifecycle hooks and validation rules,
+2. Opens a transaction,
+3. Issues batched `INSERT`/`UPDATE`/`DELETE` (one batch per entity type),
+4. Commits.
+
+You don't write individual SQL statements — let Joist batch them. `flush` can
+be called multiple times as you do more work:
+
+```ts
+const author = em.create(Author, { firstName: "a1" });
+await em.flush();
+author.firstName = "a2";
+await em.flush();
+```

package/skills/joist-partial-updates/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: joist-partial-updates
+description: Joist ORM partial updates, em.upsert, setPartial, nested collection op semantics, and GraphQL/REST/gRPC save inputs. Use when designing, implementing, reviewing, or debugging Joist partial-update or save-input APIs, especially parent-child graphs, id-less nested rows, required-parent validation errors, or accidental collection removal.
+---
+
+# Joist Partial Update APIs
+
+Use Joist's native partial-update contract from the transport through to `EntityManager.upsert` or `Entity.setPartial`. Do not load an existing graph and write custom reconciliation code when IDs and Joist collection operations can express the update.
+
+Authoritative documentation: <https://joist-orm.io/features/partial-update-apis/>
+
+## Non-Negotiable Rules
+
+1. Preserve entity IDs across read, edit, and write boundaries.
+2. Decide whether every supplied collection is exhaustive or incremental before writing the payload.
+3. Omit a field to leave it unchanged. Do not replace omission with `null`, `[]`, or a generated default.
+4. A collection array is exhaustive by default. Omitted existing children are removed from the relation.
+5. A collection becomes incremental when its child objects use `op`.
+6. If any child has `op`, every child in that collection must have `op`, including newly created children.
+7. An empty array is always exhaustive and clears the collection. It never means "no changes."
+8. Use `{ op: "incremental" }` only as a no-op sentinel when the collection key must be present. Prefer omitting the collection key.
+9. Use `include`, `delete`, and `remove` according to their actual relationship semantics.
+10. Test updates against an already-persisted graph and flush the unit of work. Mapper-only tests cannot catch detached required children.
+11. Authorize every supplied ID and operation. Joist enforces persistence rules, not API permissions or tenant boundaries.
+
+## Partial Field Semantics
+
+Joist distinguishes omission, `undefined`, and `null`:
+
+| Input | Scalar or relation behavior | Collection behavior |
+| --- | --- | --- |
+| Omitted | Leave unchanged | Leave unchanged |
+| `undefined` | Leave unchanged | Leave unchanged |
+| `null` | Unset optional value; required value fails validation | Clear the collection |
+| Value or array | Set/update | Exhaustively replace unless `op` enables incremental behavior |
+
+Do not globally normalize `null` to `undefined`. That destroys the caller's ability to explicitly unset an optional field. Adapt only fields whose transport representation differs from the entity graph.
+
+Transport-specific presence rules:
+
+- GraphQL: preserve the difference between an omitted input field and an explicit `null`. Codegen commonly produces `T | null | undefined`; this is what `DeepPartialOrNull` and the partial APIs are designed to accept.
+- REST/JSON: omission means no change; JSON has no `undefined`, so do not synthesize absent keys while decoding or mapping.
+- gRPC/Protobuf: scalar presence can use `optional`, wrappers, or `oneof`, but ordinary repeated fields do not distinguish omitted from empty. Wrap repeated fields in a present message, use a `oneof`, or use a field mask so "unchanged" cannot decode to `[]`.
+
+## Choose the Collection Contract
+
+### Exhaustive Replacement
+
+Use an exhaustive collection only when the caller intentionally sends the complete desired membership:
+
+```ts
+await em.upsert(Author, {
+  id: "a:1",
+  books: [
+    { id: "b:1", title: "Retained and updated" },
+    { title: "New book" },
+  ],
+});
+```
+
+This removes every omitted existing book from `author.books`. It does not imply hard deletion. If the inverse relation is required, detaching an omitted child can produce validation errors such as `Book author is required`.
+
+Do not use exhaustive replacement when:
+
+- The client does not know every existing child.
+- The UI discarded child IDs.
+- Omitted children should remain untouched.
+- Removed children must be hard-deleted rather than merely detached.
+
+### Incremental Update
+
+Use incremental operations when the request describes additions, updates, removals, or deletions without replacing the whole collection:
+
+```ts
+await em.upsert(Author, {
+  id: "a:1",
+  books: [
+    { id: "b:1", op: "include", title: "Updated title" },
+    { op: "include", title: "New book" },
+    { id: "b:2", op: "delete" },
+  ],
+});
+```
+
+Operation meanings:
+
+| Operation | Behavior |
+| --- | --- |
+| `include` | Create or update the child, and ensure it belongs to the collection |
+| `delete` | Remove the child from the collection and call `EntityManager.delete` |
+| `remove` | Detach the child without deleting it |
+| `incremental` | No-op sentinel that enables incremental semantics for an otherwise empty list |
+
+Use `remove` only when the child can validly exist without this parent or is being reparented in the same unit of work. For a required parent relation, `remove` alone usually creates an invalid entity. Use `delete` when the child should cease to exist.
+
+An actual empty array still clears:
+
+```ts
+await em.upsert(Author, { id: "a:1", books: [] });
+```
+
+For an incremental no-op, prefer:
+
+```ts
+await em.upsert(Author, { id: "a:1" });
+```
+
+If a generic payload builder must emit `books`, use:
+
+```ts
+await em.upsert(Author, {
+  id: "a:1",
+  books: [{ op: "incremental" }],
+});
+```
+
+## Stable Identity End to End
+
+IDs are the reliable identity contract for active nested updates. A nested object without an ID is normally a request to create a new entity.
+
+For an editable parent-child graph:
+
+1. Query IDs for the parent and every editable nested entity.
+2. Include those IDs in API response types.
+3. Store IDs in form or draft state.
+4. Send retained rows as `{ id, op: "include", ...changes }`.
+5. Mark deleted persisted rows in place by switching their `op` to `delete` (or `remove`); keep them in the same array rather than moving their IDs to a separate deletion list.
+6. Send new rows without an ID but with `op: "include"`.
+7. Keep the same discipline recursively for grandchildren.
+
+A robust UI row model carries `op` on the row itself, so a deleted book flips to `op: "delete"`/`"remove"` in place instead of moving to a separate collection:
+
+```ts
+interface EditableBook {
+  id?: string;
+  op?: "include" | "remove" | "delete";
+  title: string;
+}
+
+interface AuthorDraft {
+  books: EditableBook[];
+}
+```
+
+Because each row already mirrors `SaveBookInput` (`id`, `op`, scalars), the draft state can go directly onto the wire as the GraphQL input, with no separate deletion list to reconcile back in. Keep the collection incremental (every row has `op`) once any row does.
+
+Do not key editable rows only by array index. Reordering or deleting an earlier row can assign an existing ID to the wrong logical row. Prefer structured row state with stable IDs. If a textarea represents multiple database rows, either maintain line identity explicitly or document why positional identity is safe for that domain.
+
+Do not infer identity from `sortOrder`, names, unique constraints, or array position. Joist may use configured uniqueness for specific upsert cases such as soft-deleted rows, but do not assume `uniqueBy` will match active id-less children. Send the ID unless the current Joist behavior is intentionally relied on and covered by an integration test.
+
+## GraphQL Shape
+
+Make GraphQL inputs mirror Joist's native graph shape:
+
+```graphql
+enum UpsertOp {
+  include
+  remove
+  delete
+  incremental
+}
+
+input SaveAuthorInput {
+  id: ID
+  firstName: String
+  books: [SaveBookInput!]
+}
+
+input SaveBookInput {
+  id: ID
+  op: UpsertOp
+  title: String
+}
+```
+
+The corresponding output query must expose nested IDs:
+
+```graphql
+query EditAuthor($id: ID!) {
+  author(id: $id) {
+    id
+    firstName
+    books {
+      id
+      title
+    }
+  }
+}
+```
+
+Keep the resolver thin when the schema already matches the entity graph:
+
+```ts
+import { type DeepPartialOrNull } from "joist-orm";
+
+async function saveAuthor(input: SaveAuthorInput, em: EntityManager): Promise<Author> {
+  return em.upsert(Author, input as DeepPartialOrNull<Author>);
+}
+```
+
+The cast is appropriate only after checking that relation names, IDs, scalar fields, and nested collection operations align with Joist's expected graph. A cast does not make an incompatible payload safe.
+
+Thin does not mean unchecked. Before calling `upsert`, authorize the parent and every nested ID for the caller's tenant/scope, and validate that each requested attach, reparent, remove, or delete operation is allowed. This security validation is separate from persistence reconciliation.
+
+If the API also accepts convenience fields, such as a textarea that expands into child rows, use a small boundary mapper:
+
+```ts
+type SaveAuthorConvenienceInput = SaveAuthorInput & { booksText?: string | null };
+
+function toAuthorUpsertInput(input: SaveAuthorConvenienceInput): DeepPartialOrNull<Author> {
+  return {
+    id: input.id,
+    firstName: input.firstName,
+    books: mapBooks(input),
+  } as DeepPartialOrNull<Author>;
+}
+
+function mapBooks(input: SaveAuthorConvenienceInput) {
+  if (input.books !== undefined) return input.books;
+  if (input.booksText === undefined) return undefined;
+  return parseLegacyBooks(input.booksText ?? "");
+}
+```
+
+The mapper should transform representation, not reconcile persistence. It must preserve `books: null` as an explicit clear and preserve omission as `undefined`; do not use `??` when `null` and omission have different meanings.
+
+## REST and gRPC Shapes
+
+Use the same graph contract regardless of transport. For example, a REST PATCH body can be:
+
+```json
+{
+  "id": "a:1",
+  "books": [
+    { "id": "b:1", "op": "include", "title": "Updated title" },
+    { "id": "b:2", "op": "delete" }
+  ]
+}
+```
+
+A gRPC message should model the same operations with an enum and explicit collection presence. A plain `repeated SaveBookInput books` field is unsafe for a partial update because its decoded empty list cannot distinguish "omitted" from "clear." Use a wrapper message inside a `oneof`, or an equivalent field-mask convention:
+
+```proto
+message BookChanges {
+  repeated SaveBookInput values = 1;
+}
+
+message SaveAuthorRequest {
+  optional string id = 1;
+  oneof books_update {
+    BookChanges books = 2;
+    bool clear_books = 3;
+  }
+}
+```
+
+An unset `books_update` means unchanged; a present `books` wrapper carries incremental or exhaustive values; `clear_books: true` explicitly clears. Convert generated enum values to Joist's lowercase strings at the boundary if necessary.
+
+Do not invent transport-specific reconciliation semantics. GraphQL, REST, and gRPC should all produce the same `DeepPartialOrNull<Entity>` graph before calling Joist.
+
+## Implementation Workflow
+
+1. Read the entity metadata and identify required inverse relations and delete behavior.
+2. Trace the complete read-edit-write path, not only the resolver.
+3. Verify every editable output type and query includes stable nested IDs.
+4. Verify client state retains those IDs after parsing, normalization, and form edits.
+5. Choose exhaustive or incremental semantics independently for every nested collection.
+6. Make transport inputs match Joist's graph and expose `op` where incremental updates are needed.
+7. Add only the smallest representation mapper required by the transport.
+8. Call `em.upsert`, `entity.setPartial`, or a thin shared helper that delegates to them.
+9. Flush in an integration test and assert identity, membership, deletion, and untouched fields.
+
+## Failure Signatures
+
+### `<Child> <parent> is required` after updating a parent
+
+Likely cause: an id-less or incomplete child array was interpreted as exhaustive replacement. Joist created new children and detached omitted persisted children, whose required parent relation then failed validation.
+
+Fix: preserve child IDs and either send the complete exhaustive graph or use `op: "include"`/`"delete"` incrementally.
+
+### Duplicate children after each save
+
+Likely cause: existing child IDs are missing from the write payload, so each row is treated as new.
+
+Fix: query, retain, and resend IDs. Do not match by sort order or content on the server.
+
+### All children disappear on a no-change save
+
+Likely cause: a payload builder emitted `children: []`, which is an exhaustive clear.
+
+Fix: omit `children`, or emit `[{ op: "incremental" }]` only if the key is mandatory.
+
+### Incremental update is rejected or behaves exhaustively
+
+Likely cause: only some children have `op`.
+
+Fix: give every child in that collection an operation, including new children.
+
+### GraphQL input does not type-check against Joist
+
+Likely cause: generated nullable input types do not directly match strict entity setters, or the API has convenience fields not present on the entity.
+
+Fix: target `DeepPartialOrNull<Entity>` and use a narrow boundary mapper. Do not weaken unrelated types or write a persistence reconciliation layer.
+
+## Anti-Patterns
+
+Never solve a partial-update mismatch by defaulting to these approaches:
+
+- Loading all existing children in the resolver to assign IDs by array position.
+- Diffing old and new child arrays manually.
+- Appending custom delete markers after comparing database state.
+- Matching active children by `sortOrder`, name, or another mutable field.
+- Assuming a database unique constraint supplies identity to an id-less upsert.
+- Dropping nested IDs from API output, DTOs, parsers, or form state.
+- Mapping an omitted collection to `[]`.
+- Mixing children with and without `op` in one collection.
+- Using `remove` for a child whose parent relation is required.
+- Treating an empty array as an incremental no-op.
+- Converting every GraphQL `null` to `undefined`.
+- Adding backward-compatibility reconciliation without a concrete shipped caller that requires it.
+
+Custom reconciliation is justified only when the API contract fundamentally cannot carry stable identity or Joist operations, and changing that contract is impossible. Document that constraint before adding such code.
+
+## Regression Tests
+
+For a nested update bug, build a persisted graph before invoking the real API boundary:
+
+1. Create a parent with at least three children.
+2. Give one child at least two grandchildren.
+3. Update retained entities using their IDs and `op: "include"`.
+4. Add one new id-less entity with `op: "include"`.
+5. Delete one persisted entity with `op: "delete"`.
+6. Omit another relation and prove it remains unchanged.
+7. Flush and reload.
+8. Assert retained IDs are unchanged, new IDs were created, deleted entities are gone, and no duplicates exist.
+
+Do not re-test `em.upsert`'s own collection semantics (omitted vs `[]` vs `[{ op: "incremental" }]`, `remove` vs `delete`, mixed-`op` rejection) — Joist owns and tests those. Test what is yours: that nested IDs and operations survive the transport boundary and reach the resolver. Do not stop at payload snapshots; the original class of failure often appears only during validation or flush.
+
+## Review Checklist
+
+- Are IDs selected for every editable nested entity?
+- Are IDs retained in client or caller state?
+- Does each supplied collection intentionally use exhaustive or incremental semantics?
+- If incremental, does every child have `op`?
+- Are new children marked `include`?
+- Are deleted persisted IDs sent as `delete`?
+- Is `remove` valid for the inverse relation's nullability?
+- Can any no-change path emit `[]` accidentally?
+- Are omitted fields preserved as omitted or `undefined`?
+- Are explicit `null` values preserved where they mean unset?
+- Is the resolver a thin `upsert`/`setPartial` boundary instead of a reconciliation engine?
+- Does an integration test update a persisted graph and verify stable IDs after flush?