Persistence×sharing quadrant + ECS relocation signal (snapshot v2, breaking)

[krisnye]

Summary

Make the ECS's persistence × sharing model real and complete, in one PR (one persistence-format break).

1. Persistence × sharing quadrant (breaking: snapshot v2)

Entity space is partitioned into four quadrants along two orthogonal axes — durability (nonPersistent) and sharing (nonShared) — encoded in the low 2 bits of the entity id (bit0 = nonPersistent, bit1 = nonShared). Replaces the old sign-based scheme where nonPersistent used negative ids and nonShared was declared but inert.

quadrant	scope	persistent	shared
0	document	✅	✅
1	presence	❌	✅
2	settings	✅	❌
3	session	❌	❌

• Core keeps 4 location tables selected by entity & 0x3; archetype/resource creation honor both tags; nonShared is now update-guarded like nonPersistent.
• toData/fromData serialize the two persistent quadrants (document, settings) and reset the two non-persistent ones on load.
• The bit layout lives only in entity/persistence-sharing.ts; consumers use Entity.isPersistent/isShared/…, never raw bits.

⚠️ Breaking — ECS_SNAPSHOT_VERSION 1 → 2. Entity ids, the set of serialized location tables, and the on-disk entity-location file layout all changed, so snapshots written by prior versions no longer load (rejected with a warning; the store keeps its defaults — non-throwing). All persistence-format changes below are folded into this one bump.

2. ECS emits relocations; persistence shadow cache deleted

Swap-remove/migration moves are surfaced as TransactionResult.relocatedEntities (the ECS already computed the moved id for free). This lets @adobe/data-persistence delete its per-entity EntityLocationCache shadow and detectSwapRemoveAt re-derivation — persistence drives full-row writes directly from the relocation signal. Closes a latent hole where a relocation inside an intermediate transaction could desync the persisted image (covered by a regression test).

3. Quadrant-scoped toData / fromData (additive, optional)

toData / fromData take an optional PersistenceScope ({ shared?, nonShared? }) to read/write just one persistent quadrant — enabling e.g. settings in local storage and document via a separate service.

• Scoped toData emits row data only for the in-scope quadrant(s); archetype structure is always emitted so ids stay aligned.
• Scoped fromData restores only the in-scope quadrant(s), leaving every other quadrant untouched, so independent scoped loads compose.
• Fully optional / backward compatible: omit the scope and behavior is unchanged.
• toData now takes an options object ({ copy?, scope? }); Database narrows it to { scope? } so copy stays hidden. createStoragePersistenceService gains a scope option.

4. Component-level nonPersistent and nonShared honoring

Previously the schema flags were only honored for entities/resources; an individual component marked nonPersistent/nonShared was inert (the README even claimed otherwise). Now:

• nonPersistent component is never serialized (core snapshot + data-persistence journal/checkpoint). On load its value is reconstructed by a default-driven hybrid: a real (non-undefined) default → reset to it (including null, 0, false — all valid values); an undefined default (explicit, or an absent default key — the { default: undefined as unknown as GPUBuffer } type-placeholder pattern) → stripped (entity restores into the reduced archetype so a system re-adds it). Exposed via core.reconstructNonPersistentColumns for restore paths that rebuild columns out-of-band. data-gpus derived _-prefixed components were migrated to default: undefined` so their tag-and-exclude / derive-once systems re-run after load.
• nonShared component/resource stays persisted locally but is not replicated: data-sync skips any transaction with no shared effect (only non-shared entities, or only nonShared components). Note: peers replay whole transactions, so a mixed shared/non-shared transaction can't be partially stripped — keep non-shared mutations in their own transactions to keep them local.
• Fixes the inaccurate README claim.

5. Dense on-disk entity-location index

The entity-location index is now one file per persistent quadrant (entity-location-{0,2}.bin), each indexed by the entity's per-quadrant local index — exactly one 8-byte slot per entity, no gaps, for any workload. This replaces the raw-entity-id indexing that was ~2–4× sparse under the quadrant encoding. Part of the same v2 format break (so it's done once).

Verification

• Monorepo typecheck + build + lint clean.
• @adobe/data 1473, @adobe/data-persistence 139 (all round-trip / journal-replay / crash-recovery / worker E2E green), data-sync 29, data-gpu 70, data-lit 5.
• New coverage: relocation signal (swap/migration/value-only), four-quadrant partition + round-trip, nonShared update guard, intermediate-relocation regression, scoped single-quadrant + two-service compose, component-level nonPersistent hybrid (core + full checkpoint/reload), nonShared replication skip, and entity-location file density (exactly one slot per entity).

🤖 Generated with Claude Code