docs(migration-graph-rendering): record edges-on-plan and empty-origin-as-null follow-up slices

Signed-off-by: Will Madden <madden@prisma.io>

Author: wmadden

projects/migration-graph-rendering/README.md

@@ -63,6 +63,20 @@ Presentation polish (independent of the sequence above):
   touches the tree renderer + the `graph` command, behind unchanged layout and
   `--json`/`--dot`.
 
+Ledger cleanups (follow-ups from the TML-2769 / PR #665 review; sequenced after the ledger foundation):
+
+- **Consolidate the per-edge breakdown onto the plan** —
+  [`slices/edges-on-plan/spec.md`](./slices/edges-on-plan/spec.md). The ledger
+  foundation threads `migrationEdges` as a sibling of `plan` on the runner
+  options, requiring a hand-maintained consistency guard. This slice moves the
+  breakdown onto `MigrationPlan.edges` so the runner reads one object and the
+  guard's reason to exist disappears.
+- **Stop spelling the empty-contract origin as a fake hash** —
+  [`slices/empty-origin-as-null/spec.md`](./slices/empty-origin-as-null/spec.md).
+  ∅ is modelled as `null` at the read boundary but as `sha256:empty` (not a real
+  hash) in storage/graph, bridged by a coercion helper. This slice gives ∅ one
+  honest representation (cut chosen with the graph-layer owner at pickup).
+
 ## Contents
 
 - [`spec.md`](./spec.md) — **slice 1's spec + dispatch plan.** Pins the

projects/migration-graph-rendering/slices/edges-on-plan/spec.md

@@ -0,0 +1,69 @@
+# Slice: consolidate the per-edge breakdown onto the migration plan
+
+_Parent project `projects/migration-graph-rendering/`. Outcome this slice contributes to: the ledger-foundation slice (TML-2769) threads the per-edge breakdown to the runners as a **sibling field** (`migrationEdges`) next to `plan: MigrationPlan`. The edges are really the plan's own finer structure, so the two fields must be kept consistent by hand (a `Σ operationCount === plan.operations.length` guard exists only because they can desync). This slice moves the breakdown **onto the plan** so the runner reads `plan.edges`, the sibling field disappears, and the guard's reason to exist goes away._
+
+## At a glance
+
+Today — two parallel fields the runner must reconcile:
+
+```ts
+runner.execute({
+  plan: MigrationPlan,        // aggregate shape: origin → destination + flat operations[]
+  migrationEdges: [           // sibling: per-edge breakdown (dirName, hash, from, to, opCount)
+    { migrationHash, dirName, from, to, operationCount },
+  ],
+  // …
+});
+```
+
+After — the breakdown is part of the plan:
+
+```ts
+runner.execute({
+  plan: {
+    ...MigrationPlan,
+    edges: [{ migrationHash, dirName, from, to, operationCount }],
+  },
+  // …
+});
+```
+
+## Chosen design
+
+`MigrationPlan` carries only the aggregate shape — one `origin`→`destination` and a **flat** `operations[]`. The per-edge breakdown (per-edge `dirName`, `migrationHash`, intermediate `from`/`to`, per-edge `operationCount`) is what the ledger journal needs (one row per applied migration), and it is **not** a pure duplicate of the plan — only the endpoints (first edge's `from` = `plan.origin`, last edge's `to` = `plan.destination`) and the op-count total overlap. But threading it as a **sibling** of `plan` on the runner options is the smell: `PerSpacePlan` already carries `migrationEdges` (the planner builds it alongside the plan), and the producer copies it onto the runner options next to `plan`, so the runner receives two fields describing the same apply and must guard against their desync.
+
+This slice:
+
+- **Adds `readonly edges` to `MigrationPlan`** (in `framework-components`). The element type stays a **structural inline** object (`{ migrationHash; dirName; from; to; operationCount }`) for the same layering reason the sibling field is inline today: `framework-components` (layer 1-core) cannot import `AggregateMigrationEdgeRef` from `migration-tools` (layer 3-tooling).
+- **Runners read `plan.edges`** instead of `options.migrationEdges` (mongo, postgres, sqlite).
+- **Drops the sibling `migrationEdges`** from `MigrationRunnerPerSpaceOptions`, `MongoMigrationRunnerExecuteOptions`, and the SQL family's per-space option shape.
+- **Producer stamps `edges` onto the plan it already builds.** The planner already holds `PerSpacePlan.migrationEdges`; it sets `plan.edges` from the same source rather than emitting a separate field. `apply.ts` no longer copies a sibling.
+- **Retires the `Σ operationCount === plan.operations.length` desync guard** — once `edges` and `operations` are constructed together on one object, they can't drift independently. (Optionally keep it as a cheap internal `assert` in the runner; settle at pickup.)
+
+## Scope
+
+**In:**
+
+- `MigrationPlan.edges` (structural inline, framework-components).
+- Runners read `plan.edges`; sibling `migrationEdges` removed from all runner-option shapes.
+- Producer (`apply.ts` / planner) stamps `edges` onto the plan.
+- Migrate every construction site — the package runner tests (`synthEdges(plan)` helpers) and the five example-app manual/chain tests — from sibling `migrationEdges` to `plan.edges`.
+
+**Out:**
+
+- The per-edge data itself (unchanged — same five fields).
+- `PerSpacePlan.migrationEdges` naming on the planner side (internal; can stay or be renamed `edges` for symmetry — decide at pickup).
+- The ∅-origin spelling (`from: ''` / `sha256:empty` / `null`) — see sibling slice `empty-origin-as-null`.
+
+## Open Questions
+
+1. **Keep the op-count guard as an internal assertion?** Once edges live on the plan the desync path is gone, but a cheap `assert(Σ edges.operationCount === operations.length)` in the runner still catches a malformed producer. Decide whether the assertion earns its keep.
+2. **`edges` required vs optional on `MigrationPlan`.** The sibling field is currently required (synth/at-head plans carry a single synthesised edge). Keep it required for the same reason, or model at-head as an empty array — settle at pickup.
+3. **Rename `PerSpacePlan.migrationEdges` → `edges`?** Cosmetic symmetry with the new plan field; optional.
+
+## References
+
+- Parent project: `projects/migration-graph-rendering/spec.md`.
+- Predecessor: `slices/ledger-foundation/spec.md` (TML-2769) introduced the sibling `migrationEdges`; this slice consolidates it.
+- Surfaced by the TML-2769 / PR #665 review (the "single structure of migration runners" thread). The blast radius of making the sibling field required — five example-app call sites plus every runner-option test — is itself evidence that the breakdown belongs on the plan.
+- Linear issue: _to be filed at pickup (standalone, related to TML-2769 / TML-2774)._

projects/migration-graph-rendering/slices/empty-origin-as-null/spec.md

@@ -0,0 +1,63 @@
+# Slice: stop spelling the empty-contract origin as a fake hash
+
+_Parent project `projects/migration-graph-rendering/`. Outcome this slice contributes to: the "no origin" state (the very first migration, from ∅) is modelled inconsistently. The read boundary models it honestly as `null` (`LedgerEntryRecord.from: string | null`), but the storage/graph layer spells it `sha256:empty` — a string that is **not a valid sha256 hash** masquerading as one. A coercion helper (`ledgerOriginFromStored`) exists only to bridge the two. This slice removes the typology lie so ∅ has one honest representation._
+
+## At a glance
+
+The same "no origin" fact, spelled three ways:
+
+```ts
+// read boundary — honest: null means "no origin"
+interface LedgerEntryRecord {
+  readonly from: string | null;   // ∅ ⇒ null
+  // …
+}
+
+// storage / graph — a fake hash used as an in-band node key
+const EMPTY_CONTRACT_HASH = 'sha256:empty';   // not a real sha256
+
+// the bridge that only exists because of the divergence
+ledgerOriginFromStored(stored);   // '' | 'sha256:empty' | null → null
+```
+
+The question this slice answers: _if `from` permits `null`, why does `sha256:empty` exist at all?_
+
+## Chosen design
+
+Deferred — the **shape** of the fix is settled, the exact cut is chosen at pickup because the blast radius reaches the graph layer. Two candidate cuts:
+
+1. **Model ∅ as `null` end-to-end.** Graph nodes keyed by `string | null`, edge `from` nullable, no sentinel anywhere. Honest, but the largest blast radius: `migration-graph` (the node map keys nodes by string hash), `graph-walk`, `check-integrity`, and the renderer all assume a non-null string key today.
+2. **Keep a sentinel but drop the misleading `sha256:` prefix** (e.g. a bare `∅` / `empty` token). Smaller than (1), but still touches every site that compares against or emits the constant, and a sentinel string is still a weaker model than `null`.
+
+The operator has ruled that the **constant's value is owned by the graph/storage layer** ("not our fight" — TML-2769 review): this slice is about the **typology honesty at the boundary**, not about unilaterally reformatting a value the graph layer depends on. So the realistic scope is: pick the cut with the graph layer's owner, then land it.
+
+Cheap immediate win, independent of the cut (can land first):
+
+- **One-line doc note on `LedgerEntryRecord.from`** explaining `null` = ∅, and that the storage/graph spelling (`sha256:empty`) is normalised to `null` on read by `ledgerOriginFromStored`. Stops the next reader asking the same question.
+
+Already done in TML-2769 / PR #665 (not re-litigated here): the constant was **deduplicated** — Mongo no longer redefines its own `EMPTY_ORIGIN_HASH`; it imports the shared one.
+
+## Scope
+
+**In:**
+
+- The doc note on `LedgerEntryRecord.from` (immediate).
+- Whichever ∅-spelling cut is agreed with the graph-layer owner: either ∅ = `null` end-to-end, or a de-prefixed sentinel.
+- Collapse `ledgerOriginFromStored` accordingly (it disappears entirely under cut 1; it simplifies under cut 2).
+
+**Out:**
+
+- The ledger journal structure (TML-2769) and the per-edge breakdown (`edges-on-plan` slice) — orthogonal.
+- Unilaterally changing the constant's value without the graph layer's owner — explicitly not in scope.
+
+## Open Questions
+
+1. **Which cut — `null` end-to-end or a de-prefixed sentinel?** Settle with whoever owns `migration-graph`'s node-keying. (1) is the honest model; (2) is the smaller change. The decision turns on how much the graph node map and renderer rely on a non-null string key.
+2. **Does the graph node map tolerate a `null` key?** If yes, cut (1) is much cheaper than it looks. Investigate at pickup.
+
+## References
+
+- Parent project: `projects/migration-graph-rendering/spec.md`.
+- Predecessor: `slices/ledger-foundation/spec.md` (TML-2769) — introduced `LedgerEntryRecord.from: string | null` and the `ledgerOriginFromStored` bridge; deduped the constant.
+- Surfaced by the TML-2769 / PR #665 review (the `sha256:empty`-is-not-a-hash comment and the `from`-permits-null-but-we-use-the-constant comment).
+- Linear issue: _to be filed at pickup (standalone, related to TML-2769 / TML-2774)._