wenay-common2 1.0.63 → 1.0.65

package/doc/ROADMAP.md

@@ -0,0 +1,131 @@
+# wenay-common2 — Roadmap (open / deferred)
+
+> Forward-looking backlog of distributed-state / transport features that are **not fully built**.
+> Everything here sits on top of the existing seams — `{emit,on}` transport, `exposeStore` /
+> `createStoreMirror`, and the replay `seq` / `keyframe` / `frame` contract. None of it requires
+> changing the store core; the store stays single-authority (one `seq` sequencer, last-writer-wins
+> per path), and these features are layers or adapters above that.
+> Status: 🔴 not started · 🟡 partial / ongoing · 🧊 deliberately shelved.
+
+## 0. Distributed Runtime Model
+
+The strategic direction is not "RPC plus store helpers"; it is a small distributed-state runtime:
+application code keeps a stable typed API while lower layers can choose the transport, route, replay
+source, and authority model.
+
+Four concerns must stay explicit:
+
+- **Transport** - how two endpoints exchange `{emit,on}` messages: socket.io, in-process loopback,
+  relay, WebRTC/direct channel, or a future adapter. Transport is replaceable infrastructure.
+- **Routing** - where a logical call or stream goes: server, peer through relay, peer directly, or a
+  promoted relay <-> direct path. Routing must be allowed to change without changing the facade API.
+- **Authority** - who is allowed to write truth: one server, partitioned peer-owned slices, server
+  authority with client prediction, or true multi-writer conflict resolution. This is a semantic
+  decision, not a transport decision.
+- **Replay** - how live state survives reconnect, lag, transport swap, and history playback:
+  `seq` + keyframe/frame + deltas. Replay is the continuity layer that makes route changes boring.
+
+Design rule: direct peer links and relay hand-offs are optimizations of transport/routing. They must
+not silently change auth, ownership, validation, or conflict semantics. If a method is exposed as
+`api.hit(playerId)`, it may travel through the server or a direct channel, but the authority rules
+behind that method must remain the same.
+
+This implies a useful split:
+
+- **API surface** remains facade-shaped and typed.
+- **Transport/routing layer** may substitute sockets and promote paths.
+- **Replay layer** resumes streams and mirrors from the last known `seq`.
+- **Authority layer** decides whether an incoming write is accepted, predicted, reconciled, or merged.
+
+### 0.1 Optional account-to-account route plane ("wrapper over wrappers") 🔴
+
+Some deployments need separate client/account identities to communicate directly when policy and
+network conditions allow it, while still allowing the server/relay to step back into the path later.
+This is not just a socket trick; it is an account-aware routing shell above the existing facade,
+mirror, and replay primitives.
+
+- **Account model:** every participant has its own account/session identity and a scoped facade/store
+  set. Runtime-account maps are a dynamic keyspace, so they should look like `noStrict(accountMap)`
+  rather than a fixed schema. Access checks stay in the facade/policy layer; `noStrict` is not an ACL.
+- **Wrapper over wrappers:** an app-level coordinator owns the set of per-account clients, exposed
+  facades, mirrors, replay subscriptions, and route state. "State of other accounts" is represented as
+  selected `Observe` mirrors/replay/offline resources, ideally started and stopped through
+  `createStoreManager`, not as a new global store core.
+- **Route states:** a pair of accounts may be `relay`, `direct`, `direct+shadowRelay` (audit/observe
+  copy), `blocked`, or `fallback`. Direct links are optional optimizations, useful for latency or
+  traffic cost, not a semantic change.
+- **Re-interposition:** if NDA/privacy policy, audit, moderation, throttling, reauth, direct-link
+  failure, or group topology changes require it, the relay must be able to re-enter the data path.
+  This is the reverse of direct promotion: open the replacement route, resume from the last `seq`,
+  switch consumers after catch-up, then close or demote the old route.
+- **Privacy rule:** direct account links are opt-in and policy-gated. Peers only receive the endpoint
+  and session material needed for that specific relationship; no implicit broad account discovery.
+
+Open questions: account ACL/policy shape; signaling format; whether the relay sees payloads or only
+coordinates encrypted direct streams; how route state is exposed to the app; backpressure across
+multi-hop and direct paths; revocation in the middle of a live stream.
+
+Status: 🔴 not started. This belongs to project-0 architecture: no store-core change, but it defines
+the account/routing shell that later direct-connection work plugs into.
+
+## 1. Connection hand-off — relay ↔ direct promotion ("port forwarding") 🟡
+
+A relay/intermediary bootstraps a connection between two parties, then — on a signal — **steps out
+of the middle**: both ends open a second, direct socket and migrate the live stream onto it,
+bypassing the relay. The same mechanism must work in reverse: the relay can deliberately
+**re-interpose** and become the middleman again. Under the hood the socket substitutes itself; data
+starts flowing on the new path.
+
+- Family: NAT hole-punching / WebRTC TURN→direct promotion, expressed over the existing `{emit,on}`
+  abstraction rather than a specific transport.
+- **Design lead (reuse what exists):** the socket swap is a *stream resume*, which the replay layer
+  already solves. Migrate with `replaySubscribe(..., {since: prev.seq()})` /
+  `syncStoreReplay(..., {since})` on the new socket — the consumer fold is gap-free by contract, so a
+  mid-stream transport change is not a special case. The transport carries only `seq`; the semantics
+  never learn the socket changed.
+- **Implemented foundation (2026-07-08):** `Replay.replayRouteSubscribe(...)` and
+  `Observe.syncStoreReplayRoute(...)` keep the old route alive, subscribe the replacement route,
+  catch it up from the last delivered `seq`, then close the old route. This covers relay → direct
+  promotion and direct → relay re-interposition for any ordered `ReplayRemote`; overlap is deduped by
+  `seq`, and a failed replacement leaves the old route active.
+- Open questions: signaling channel that negotiates the direct endpoint; fallback if the direct path
+  never establishes (stay on relay); auth continuity across the swap; per-socketKey vs whole-connection
+  hand-off; policy trigger and catch-up boundary for direct → relay re-interposition.
+- Status: 🟡 partial. Route hand-off/resume helper is implemented and covered by `replay/route-handoff.test.ts`; signaling, direct endpoint negotiation, NAT/WebRTC adapter, auth-continuity policy, and trigger rules remain open.
+
+## 2. Coordinated fan-out send to a large group 🧊
+
+Synchronized/batched send to a very large audience "at once", as opposed to the current model where
+**each connection is paced independently** (per-connection lag gate + `frame` policy).
+
+- Current reality: pacing is per-recipient by design — every client's link is unique. Even in video
+  fan-out no two receivers drain at the same rate, so the per-connection gate is usually the *correct*
+  answer. That is why this is shelved.
+- When it would matter: true lockstep broadcast (all-or-nothing / same-instant delivery) — rare.
+- Status: 🧊 deliberately shelved. Revisit only against a concrete lockstep requirement.
+
+## 3. Multi-authority stores — two truths, one reconciliation (games) 🔴
+
+Two stores, each **dynamically filled by its own authority ("truth")**, that must agree on a shared
+source of truth. Decompose by write topology:
+
+- **Partitioned authority — fits today.** Each peer authoritative over its own slice → two
+  `exposeStore` / `createStoreMirror` pairs crossed over one duplex `{emit,on}`. No new primitive.
+  "Confirmation" = the per-direction `seq` ack.
+- **Authoritative server + client prediction — small layer on top.** Server store is the truth; the
+  client applies optimistically, then reconciles when the authoritative patch arrives. Build a
+  `predictedStore` = confirmed mirror + a pending-input list, rebased on each `mirror.each()` /
+  `changed` tick. Helper factory, not a core change.
+- **Symmetric co-write of the same path — needs a different model.** LWW-per-path converges but can
+  silently drop a concurrent write. This is the one case that genuinely needs CRDT/OT. Design lead:
+  wrap a Yjs/Automerge doc as a `RemoteStore`-shaped source and mirror from it — the store↔transport
+  decoupling makes this a small adapter, not a rewrite.
+- Status: 🔴 prediction layer + CRDT adapter not started; partitioned-authority already expressible.
+
+## 4. Data-transfer optimization backlog (ongoing) 🟡
+
+Open-ended transfer/perf work, especially for backend-heavy models. Never "done".
+
+- Candidates: tighter `frame` condensation per line; delta/patch minimization; binary framing for hot
+  paths; batching heuristics beyond the current `pipe` / `space` modes.
+- Status: 🟡 ongoing; pick items as real bottlenecks surface, not speculatively.

package/doc/changes/1.0.63.md

@@ -0,0 +1,8 @@
+# 1.0.63
+
+- Add `Observe.createStoreManager` and `Observe.managedStore` resource builders for declarative mirror/replay/offline store startup.
+- Add manager planning with priority, tags, usage scoring, `large`, and `explicitOnly` gates.
+- Add manager lifecycle helpers: `start`, `startPlanned`, `stop`, `stopAll`, `get`, `touch`, `usage`, `statusListen`, and typed `handles`.
+- Rename public-facing Observe oracle folder from `observable2` to `observe` and make `Listen.ts` / `reactive.ts` the canonical source files, leaving numbered files as compatibility shims.
+- Update brief and extended API docs for the store manager and current naming.
+- Publish package `wenay-common2@1.0.63`.

package/doc/changes/1.0.64.md

@@ -0,0 +1,10 @@
+# 1.0.64
+
+- Make `README.md` navigation-only and point it to the brief docs, rare docs, naming migrations, recent changes, and project rules.
+- Add the `doc/changes/` release-note catalog rule to `CLAUDE.md`: one file per published version, commit-style summary, latest 10 versions only.
+- Add the recent changes catalog README and keep the current release notes under `doc/changes/`.
+- Package documentation, `CLAUDE.md`, and `rpc.md` into `dist` so README links work in the npm package.
+- Restore the `noStrict` dynamic-map contract in the extended docs after removing a duplicated store-manager block.
+- Move regression oracles to the canonical `observe/reactive` names after the `observable2/reactive2` rename.
+- Normalize npm repository metadata.
+- Publish package `wenay-common2@1.0.64`.

package/doc/changes/1.0.65.md

@@ -0,0 +1,7 @@
+# 1.0.65
+
+- Add `Replay.replayRouteSubscribe` for transport-agnostic replay route hand-off: keep the old route live, catch up the replacement route by `seq`, then close the old route.
+- Add `Observe.syncStoreReplayRoute` for store mirrors that can switch relay/direct routes without gaps or duplicate patch delivery.
+- Add `replay/route-handoff.test.ts` covering relay -> direct promotion, direct -> relay re-interposition, failed replacement fallback, and store mirror convergence.
+- Update roadmap/replay docs to mark connection hand-off as partially implemented and keep signaling/WebRTC/policy triggers explicitly open.
+- Normalize package metadata for `wenay-common2@1.0.65`.

package/doc/changes/README.md

@@ -0,0 +1,8 @@
+# Recent changes
+
+This directory keeps one file per published version.
+
+Rules:
+- file name: `<version>.md`, for example `1.0.63.md`;
+- each file contains a short commit-style summary of what changed;
+- keep only the latest 10 version files, deleting older version files when adding a new one.