persistence: remember the last successfully activated document across reload

[Jah-yee]

Verified future problem

Current main always hydrates the fixture tree id, but it does not yet contain the foreign-id archive import/runtime-switch path. The unreachable-import scenario becomes real when that archive WIP lands. The same bootstrap boundary also owns a verified current-main load-window hazard.

Status: blocked on the active-document bootstrap

Do not open a narrow active-pointer PR until the bootstrap order is frozen. There is no safe document pointer if durable editing can begin before the home document is known and activated.

Before implementation, freeze:

• the IndexedDB v1 to v2 metadata migration for one strict active-document pointer;
• multi-tab compare-and-swap ownership for publishing that pointer;
• the atomic order: pointer load, record load, validation, runtime activation, then durable mutation enablement;
• archive decode, document save, runtime switch, and pointer publication/rollback ownership;
• failure and corrupt-pointer fallback to the fixture document without hidden retrieval.

Blocking correction from WIP review

Do not merge the current resolveHydrationDecision revision comparator.

A tree revision is monotonic only inside a known lineage. It is not a snapshot hash or a cross-session timestamp. If initial rev5 loads stored rev6 A while a load-window edit creates live rev6 B, automatically hydrating A discards B without a gesture. Current main is also unsafe: equal revisions can be treated as already saved even when contents differ, while a higher live revision can CAS-overwrite stored material without an explicit conflict.

Changing <= to < does not solve this; equal revision with different content is the critical case.

Accepted outcome

The last document that was successfully activated becomes the local home document. Prefer gating admission, branch, undo, and import replacement until pointer load, record load, validation, and runtime activation complete. Pure transient navigation may remain available.

If product intent insists on durable edits during the load window, any live tree that diverges from the initial snapshot while stored material exists must enter explicit conflict. It must never auto-hydrate or auto-publish by revision ordering.

A failed or merely validated import must not move the active pointer. Missing or corrupt metadata falls back explicitly to the fixture document. This is document choice, not navigation state or hidden retrieval.

Proof

Use a delayed repository integration test, not only a pure revision comparator. Cover:

• no stored record;
• unchanged initial tree plus valid stored record;
• stored and live different content at the same revision;
• stored numerically higher and lower than a load-window edit;
• corrupt/missing active pointer;
• failed import and failed pointer publication;
• same-id import and multi-tab pointer conflict;
• mid-load foreign-id switch.

Every divergent load-window case must preserve local material behind an explicit conflict or prevent the durable edit from starting.

Non-goals

No document picker, account, sync, recent-files list, hidden session history, multiple open documents, or revision-based merge.

[Jah-yee]

The blocking correction in this issue is satisfied in Preview.19, and the load-window hazard it names on current main is fixed. The pointer itself is still open.

What shipped

This issue said, in bold: do not merge the current resolveHydrationDecision revision comparator, and changing <= to < does not solve this; equal revision with different content is the critical case. Both are now true in code.

The comparator is gone. A revision is monotonic only inside one lineage, and the two trees in that window are not one lineage — the live one descends from the seeded document, the stored one from the last session. Comparing their numbers compared nothing, and it lost material in both directions:

stored r6, live r6   hydrated stored; the sentence just spoken disappeared
stored r6, live r7   published live; the whole prior session was gone

Divergence decides now, and it is answered by identity rather than arithmetic: the runtime freezes state on every commit, so an untouched load window is the same object it started with. Anything else is diverged — including the rare case of a new object with identical content, because refusing to guess costs one gesture and guessing wrong costs a session.

A divergent load window raises PERSISTENCE_CONFLICT, which is the state a second tab already raises and the same situation: two versions exist and only the person knows which they meant. It reaches them through the copy and the reload button the material index already has, so no new interface. Neither version is written over the other while it is unresolved, and a later commit does not quietly resume saving over the stored session.

Tests cover no stored record, an untouched window, a mid-load commit behind stored material, equal revisions with different lineage, a newer live tree, an identical-looking new object, and a mid-load document switch — plus a controller-level case proving nothing is written, that a later publish still writes nothing, and that the existing gesture resolves it.

Still open here, unchanged

• the IndexedDB v1→v2 metadata migration for one strict active-document pointer;
• multi-tab compare-and-swap ownership for publishing it;
• the atomic order: pointer load, record load, validation, runtime activation, then durable mutation enablement;
• archive decode / document save / runtime switch / pointer publication and rollback ownership;
• corrupt-pointer fallback to the seeded document without hidden retrieval.

One addition to that list: #46 closed with the two label record kinds still sharing one object store. Separating them needs the same v1→v2 migration, and doing it twice separately is how a schema upgrade race gets written. It belongs in this slice.

What is no longer true is the framing that nothing here can be safely fixed before the bootstrap is frozen. The load-window data loss was independent of the pointer, it was live on matter.ptoq.io, and it is fixed.

[Jah-yee]

Status audit: the blocking correction has landed; the pointer has not

Re-read against current main (0.2.0-preview.19).

Resolved. The blocking correction in this issue — "do not merge the current resolveHydrationDecision revision comparator", and the observation that equal revisions with different content are the critical case — is answered. features/matter/persistence/hydration-decision.ts no longer compares revisions at all. It decides by object identity: the runtime freezes state on every commit, so an untouched load window is the same object it started with, and anything else is diverged. A diverged load window raises the same explicit conflict a second tab raises, and neither version is written over the other. The rare identical-content-new-object case is treated as diverged too, which costs one gesture and never costs a session. Recorded in docs/changes.md under 2026-08-09.

Still blocked, correctly. Everything this issue calls the active-document bootstrap is untouched and should stay untouched until it is frozen:

• the IndexedDB v1→v2 metadata migration for one strict active-document pointer;
• multi-tab compare-and-swap ownership for publishing that pointer;
• the atomic order — pointer load, record load, validation, runtime activation, then durable mutation enablement;
• archive decode, document save, runtime switch, and pointer publication/rollback ownership;
• corrupt-pointer fallback to the fixture document.

The foreign-id archive import/runtime-switch path that makes the unreachable-import scenario real still does not exist on main, so the P0 remains a verified future problem rather than a live one.

Suggested next step, if this is to move: freeze the bootstrap order as a plan slice in plans/ first, since the issue itself says there is no safe document pointer while durable editing can begin before the home document is known. The delayed-repository integration test listed under Proof is the right shape and should be written against the frozen order, not ahead of it.