Reconciliation-generated nodes have no defined path to collaborators

[Aymericr]

Problem

Nodes that space-detection reconciliation generates — auto slabs, auto ceilings, auto zones, frontSide/backSide surface flips, and the level.children growth that comes with them — have no defined way to reach collaborators. Anything that moves reconciliation after the commit snapshot silently stops replicating.

Today it works by accident of ordering. initSpaceDetectionSync subscribes to the store, so its writes land before zundo's onSave snapshots the transaction, and the hosted editor's

// apps/community — use-project-scene-collaboration.ts:552
const diff = deriveSceneOperationChanges(commit.before, commit.current)

picks them up inside commit.current. Nothing states this as a contract, and nothing tests it.

Why it needs writing down

#554 restructured reconciliation to run from subscribeSceneCommits instead — a reasonable design in isolation, since it gives reconciliation the before/after pair it needs for delta work. But commit listeners run after both snapshots are taken, and reconciliation writes under pauseSceneHistory, so they emit no commit of their own. Measured on that branch versus main, same four-walls-closing-a-room scenario:

	commit current.nodes	live store	never in any commit
main	8	8	—
#554	6	8	the auto slab + ceiling

The author gets a floor and a ceiling; collaborators get a bare wall and a divergent level.children. That drift doesn't self-heal.

What would resolve it

1. State the contract. Either "reconciliation must write within the triggering commit's transaction" or "reconciliation must emit its own commit that collaboration can transmit." Then document it in wiki/architecture/ next to the space-detection notes.
2. Test it at the boundary. A core-level test asserting that reconciliation-generated nodes appear in the emitted commit would have caught editor: keep room surfaces in sync with wall topology #554 automatically. The check is cheap: close a room, capture commits, assert every live node id appears in some current.nodes.
3. Decide about pauseSceneHistory. Reconciliation pauses history so its writes don't become a separate undo step, which is correct for undo but is also what suppresses the commit. Whether "one undo step" and "one transmittable commit" can be the same thing is the crux.

Option 2 is worth doing regardless of which way 1 goes — right now the invariant is enforced only by call ordering that any refactor can reverse without a single test turning red.

Context: #554 (closed; the TopologyIndex half is expected to return as a focused PR).

[blackwellmiranda8]

⚙️ RAG 这块切分粒度怎么定的

[dunncharles0112]

🤝🚀✨ 限流熔断默认参数偏保守吗

[Aymericr]

Two additions from a deeper pass over #554, both of which tighten what this issue is asking for.

1. The contract has a second half I didn't state: origin: 'host' commits.

The body above frames this as "reconciliation writes must reach collaborators." There's a mirror-image case. When a remote peer's edit arrives, applySceneOperationPatch emits notifySceneCommit({origin:'host'}) from inside withSceneMutationLock, so it runs while readOnly === true — and every space-detection write path bails on readOnly at its first line (node-actions.ts:787, :984, :1073).

That guard is correct and I don't want it removed; it's what stops each client minting its own differently-id'd slab from the same remote wall. But it means the receiving peer gets no surfaces, and a later local edit to that room doesn't backfill them. So the contract needs to answer both directions:

• the originating peer's commit must carry the generated surfaces (what this issue says today), and
• given that it does, the receiving peer must apply them rather than regenerate them.

The second falls out of the first if surfaces travel in the commit — which is an argument for option 1 in the body over anything that has each client re-derive locally. Worth making explicit, because "each client reconciles independently" is a tempting design that this rules out.

2. The proposed test would not have caught two related defects. Widening the ask.

The body proposes asserting that reconciliation-generated nodes appear in the emitted commit. Good, and cheap. But #554 also had two defects where reconciliation ran and produced the wrong answer, which no commit-visibility assertion would notice:

• A room newly enclosed between two existing rooms gets no slab, no ceiling, and no Space — the candidate-wall walk stops at any wall already owned by a room, so the new enclosure's far wall is never enumerated. Worse, wallClosesRoom returns true, so the wall tool auto-stops the chain: the two systems that tool.tsx:740 says "never disagree" now disagree.
• changedNodeIds is frozen by runWithSceneCommitNodeIds before deleteNodesAction grows the real id set via collect() and wall-merge plans, so cascade-deleted and merged-away walls are invisible to scoped reconciliation. A deleted level leaves its Space published; a merged wall stays in boundaryFaces.

Both were measured against the merge base to confirm they're regressions rather than inherited. Details and repros are on #554.

The property that covers all three is stronger than commit visibility and still cheap to state:

For a representative set of edits, scoped reconciliation produces the same spaces and the same surfaces as a full detectSpacesFromWalls over the level.

That's the actual contract any incremental reconciliation has to meet — the narrow scan must be equivalent to the wide one, not merely faster. Since the whole value of scoping is that it's an optimisation, an equivalence harness is the right place to enforce it, and it subsumes the visibility test rather than replacing it.

Not asking for this before the TopologyIndex work returns — it's the kind of harness that's most useful alongside it, since it's what makes the optimisation reviewable at all.

One clarification on scope, since I found it while checking: none of this affects the standalone editor's persistence. Its onSave serialises the live store via snapshotCurrentSceneGraph, so local-storage keeps the auto surfaces. The exposure is limited to consumers that reconstruct state from before → current diffs — the collaboration layer and the version diff.

[harrisonmichael809]

国际化文案抽离得干净吗 🚀🚀

[mclaughlinmichael08]

😄🙌 边界条件处理得很细致

[dunncharles0112]

插件机制扩展性够不够 ✨⭐⭐

[barrettchelsea0]

破坏性变更提前多久公示 ⭐🚀💡

[mclaughlinmichael08]

token 成本有没有做过粗算 👍🧠

[wellsashley00]

🔥 测试覆盖到关键路径了吗

[hansenisaac8461]

🧪📦🚀 学到了，感谢维护者持续更新

[harveysamuel99]

🤝⭐🧠 对标竞品差异点能列一下吗

[hansenisaac8461]

边界条件处理得很细致 ⭐🚀🧪