Send only unsaved links in a new card's included, not resident saved ones

[lukemelia]

Problem

When a new card is written, the serializer inlines into included[] every linked card the store has resident — saved or not. The realm keeps only the primary card plus any brand-new, unsaved links being created in the same request (identified by lid), and discards the already-saved ones. So every new-card save from a busy tab serialises, transmits, and then has the server throw away hundreds of KB of resident linked cards.

Fix

Push the realm's write-retention rule into the serializer, as an includedScope option on SerializeOpts:

• 'all' — every resident link target rides along in included[]. The default, and what a direct serializeCard call gets.
• 'local' — only the local (unsaved, lid-bearing) targets the card links to directly. The write shape: included is a co-creation manifest and saved targets are reference-only.
• 'none' — no link targets at all.

An excluded target isn't serialized and its own graph isn't traversed, so the cost is skipped rather than filtered away afterwards: a new card linking into a large saved graph now serialises none of that graph on save. Its relationship entry is unchanged — links.self + id for a saved target, lid for a local one, which is exactly what the full walk's tail emits.

CardService#serializeCard maps the caller's intent onto a scope. The new-card save asks for withLocalResourcesIncluded and gets 'local'; every other caller gets 'none', which is the document they already received, since the service deleted included from it regardless.

The document sent on a new-card save now equals what the realm stores.

What a write co-creates

Under 'local', an unsaved card reachable only through a saved link is no longer co-created. Nothing the write persists could reference it: the saved link's own file isn't rewritten, and the write's response names only the primary card, so the co-created card's id would never reach the client — the realm would write an orphan file.

Relationship to #6160

#6160 (merged) fixed the "Card size exceeds maximum" failure this inflation caused, by measuring the size limit per-file. This change removes the wasted payload itself. They are separate because this one changes the serialised document shape, where #6160 only changed how the limit is measured.

Test

Integration | Store gains a case covering all three scopes: which targets reach included under each, that withLocalResourcesIncluded maps onto 'local', and — the assertion with the widest blast radius — that the primary resource is deep-equal under all three scopes. That equivalence is what makes 'none' safe as the default for the patch, copy, file-def and AI-tool callers, and it now fails loudly if either branch drifts.

Verification

• ESLint and ember-tsc: clean locally
• Host suite: in CI on this head, which is main merged forward rather than the base the earlier green run used

🤖 Generated with Claude Code

[lukemelia]

[Claude Code 🤖] Review focused on enumerating the consumers of withIncluded serialization and on pinning the new test to the filter; the base PR of this stack was reviewed separately.

Bottom line: no blocking issues. withIncluded: true has exactly one call site (persistAndUpdate in store.ts), which serializes both creates and PATCHes — and the realm's PATCH handler retains and co-creates lid members with the same machinery as POST, so the filter is semantics-preserving on both verbs. The new test fails with the filter hunk removed ("a resident saved link is not inlined") — it pins the change.

1. Extract the lid-retention predicate to a single home — inline comment on serializeCard in card-service.ts. Non-blocking.

Contract note: after this change the write document reads coherently — included on a write is a co-creation manifest (lid-bearing resources), references stay in relationships, and the client sends exactly what the realm retains. The realm's silent discard of non-lid members becomes pure backward-compatibility tolerance; a follow-up could warn on (or eventually reject) them, so the next client-side drift fails loudly instead of re-inflating payloads unnoticed.

[habdelra]

[Claude Code 🤖] Reviewed the second commit only (the diff against its stacked base): the includedScope skip in LinksTo/LinksToMany, the CardService default flip, and the new tests. I traced the emitted relationship shapes and the realm's own create/patch retention loops against the new scopes; I did not run the host suite (CI is still queued).

No blocking issues. The retention rule the client now applies matches what the realm keeps — serializeCardResource emits id and lid mutually exclusively, so the realm's typeof resource.lid !== 'string' skip discards exactly the saved members this change stops sending, and the skip branch's relationship output is identical to the full branch's for both the id and lid spellings.

Recommendations:

1. Narrow CardService#serializeCard's parameter to Omit<SerializeOpts, 'includedScope'> — the spread silently discards a caller-supplied scope. See the thread on card-service.ts.
2. Confirm the intent of no longer co-creating unsaved cards reachable only through a saved link, and say it in the includedScope doc comment. See the thread on card-serialization.ts.
3. Collapse the now-threefold reference-relationship spelling (and the duplicated skip predicate) behind two helpers. See the thread on card-api.gts.
4. Drop the first new test as subsumed, and pin the 'all' vs 'none' relationship equivalence instead — that equivalence is what makes the default flip safe for the patch / copy / file-def / AI-tool callers, and nothing asserts it. See the thread on store-test.gts.

The PR description still describes the earlier post-serialization filter and calls skipping the serializer walk "a possible follow-up in the base card API" — the merged shape of this branch does that skip. Worth refreshing before it becomes the merge commit message.

Adjacent, out of scope: the PATCH path's included.length === 0 && isEqual(primaryResource, original) short-circuit in realm.ts was previously near-unreachable from the host, because any resident saved link made included non-empty. With this change it starts firing on genuinely no-op saves, which is the behavior it was written for — worth knowing it is now live rather than dormant.

---

Generated by Claude Code

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files  ±0      1 suites  ±0   2h 20m 28s ⏱️ -54s
4 859 tests  - 1  4 845 ✅  - 1  14 💤 ±0  0 ❌ ±0 
4 874 runs   - 1  4 860 ✅  - 1  14 💤 ±0  0 ❌ ±0 

Results for commit 0209738. ± Comparison against earlier commit 95da05c.

Realm Server Test Results

    1 files  ± 0    235 suites  ±0   1h 20m 19s ⏱️ - 4m 28s
3 395 tests +19  3 395 ✅ +19  0 💤 ±0  0 ❌ ±0 
3 444 runs  +21  3 444 ✅ +21  0 💤 ±0  0 ❌ ±0 

Results for commit 0209738. ± Comparison against earlier commit 95da05c.

[backspace]

[Claude Code 🤖] Pushed 0209738ad0 addressing all four recommendations, one commit each, plus:

• PR description rewritten — it described the post-serialization filter from the first commit rather than the merged includedScope shape.
• main merged forward; the branch was 37 commits behind and its green run was on the older base.

On the adjacent note: agreed, and it survives the card-operations refactor — the no-op short-circuit is now executors.ts:746, and it does start firing on genuinely no-op saves, which is the behaviour it was written for.