ecsly_world_sync 0.1.0

World-sync plugin for ecsly worlds: converts world event-channel events and component deltas into convergence-kernel ops, and folds remote ops back into a world-state projection. Consumes the converge [...]

ecsly_world_sync

World-sync plugin for ecsly worlds: converts world event-channel events and component deltas into convergence-kernel ops, and folds remote ops back into a world-state projection.

Merge semantics are not implemented here. This package consumes universal_storage_convergence (ADR 0011): the kernel owns ordering, hybrid logical clocks, version vectors, dedupe, and fold rules; this plugin only chooses the strategy (LWW map by default), the key mapping, and the compaction policy. The kernel never learns about worlds. See ADR 0001. Since ADR 0004 it also consumes the session core (universal_storage_convergence_session): WorldSync conforms to the core's DeltaReplica seam (so the shared DeltaPlanner can plan against it) and carries an HLC receive watermark — every remote op HLC and adopted snapshot createdAt raises it, and local writes are floored above it, so a local write issued after folding a remote op with an ahead wall clock wins LWW instead of losing forever.

What it does

• WorldSync — one replica of a world over one kernel ConvergenceDoc:
  • applyDelta / applyEvent → one kernel op per keyed piece of state;
  • removeDelta / removeEvent → kernel tombstones;
  • applyRemote → folds remote ops (kernel dedupe + HLC ordering);
  • projection → read-only world state (tombstones excluded);
  • opsFor(vv) / snapshotFor / adoptSnapshot / compact → dual-mode anti-entropy, all executed by the kernel.
• FakeTransport — in-memory, test-only transport. No real networking; sockets, presence, rollback/re-simulation, and host integration are later phases (ADR 0001 non-claims).

Identity model

Keys name state by stable identity — <entityKey>/<component>/<field> and event/<name>/<key> — matching the ecsly_serialization rule: runtime Entity handles are world-local and never travel.

Why this package has no Plugin of its own

The charter (ADR 0001, kept by ADR 0002): this kernel adapter imports no core ecsly — it translates deltas and events, and folds remote ops, without ever touching a live World. An ecsly Plugin would reverse that dependency. The plugin face of world sync lives one layer up, where the ecsly dependency is legitimate: WorldSyncBridgePlugin in ecsly_world_sync_bridge installs the live-World binding (and optionally the session) through world.addPlugin(...).

Dependencies

The convergence kernel (universal_storage_convergence) and the session core (universal_storage_convergence_session) are published on pub.dev (0.1.0-dev.1, 2026-10-12) and resolve as ordinary hosted dependencies — the bootstrap path overrides this package carried until then are removed (ADR 0001 §3, ADR 0004).

Status and validate

In the repo, in active development; not published (publish_to: none). Depend on it through the pub workspace inside this repo, or via a git dependency outside it.

dart pub get        # from the repo root (pub workspace)
cd plugins/ecsly_world_sync
dart analyze
dart test           # 11 tests