feat(compact): move pairing helpers (PR1 round 1)

2026-07-15 13:22:44 +08:00
parent 34bb75b2d2
commit cc546c4580
17 changed files with 525 additions and 376 deletions
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -196,6 +196,8 @@ export interface SurfaceNode {
 }
 ```

+`SurfaceNode` is positional state, not durable identity. A replacement can remove a caller-retained node or make a copied `next` stale; consumers that cross a surface mutation validate membership and resolve successors from `Session.surface.nodes`. `SurfaceManager.replaceGeneration` increments for each replacement so incremental consumers can distinguish pure tail growth from a rewrite.
+
 ### `SurfaceFoldReplacement` and `SurfaceFoldResult` — a complete surface replay

 `foldSurface(events)` returns detached current nodes together with the actual node seqs shadowed by each declared replacement range. `SurfaceManager` uses the same transition functions for its incremental cache.