wenay-common2 1.0.62 → 1.0.64

package/CLAUDE.md

@@ -0,0 +1,63 @@
+# Code style (author preferences)
+
+Write new code in this style by default — no need to ask.
+
+## Prohibited
+- Never write new logic without first checking if it already exists in the codebase
+- Never change public interfaces without explicit discussion
+
+## Architecture
+- **Closure factories instead of classes.** `function createX(deps) { ... return { ... } }`.
+  Keep state in the closure; avoid classes and `this`.
+- **DI at the boundary, closures inside.** A *reusable / exported* factory takes its
+  dependencies as an explicit `deps` object, so it can move to its own file unchanged.
+  *Inside* a factory, nesting is normal and encouraged — inner factories and helper
+  functions freely close over the enclosing scope (that captured state is the whole point
+  of closures). Factories don't have to be flat.
+- A factory's returned object is a namespace of functions (functional style,
+  an "object with meaning"). Split the return **by audience** when there's more than one —
+  `control` (what goes *into* the owning unit) vs `api` (what's exposed *outward*). The
+  number of facades follows the need: **one** flat object when there's a single audience,
+  **two** (`control`/`api`) for the common in/out split, **more** when distinct consumers
+  warrant it (e.g. `control` / `api` / `debug`). Don't force two if one is clearer.
+- **Layering — separate resource / utility / business logic.** Keep the *resource* part
+  (sockets, adapters, connections, stores) apart from *utilities* (pure, reusable helpers)
+  and from *business logic*. Business logic is **local**: each layer has its own — the
+  API-description layer carries the business rules for that API; a higher layer carries the
+  business rules of *using* those APIs. Wherever it lives, mark it clearly (section dividers).
+  Utility-leaning functions are better *extracted* (own function / file) so they don't blur
+  into business logic.
+- **Multi-level facades are fine** — `listen` (or other callbacks) may be installed at
+  any nesting depth. Closures are fine. Inner factories and captured state are encouraged.
+- **Expose callbacks outward.** `listen` streams that callers will subscribe to belong in
+  the `api` surface — prefer over-exposing event streams to hiding them.
+- Registries/tables — `as const` + inferred literal types (type-safe).
+
+## Syntax
+- **`==` / `!=`**, not `===` / `!==` (unless strict comparison is genuinely needed).
+- **Don't annotate function return types** (`: Promise<void>`, `: number`, etc.) — let them
+  be inferred. Exception: when the type genuinely helps the reader or narrows inference.
+- Single quotes, 4-space indent, no semicolons.
+- **Named functions over anonymous arrows for anything non-trivial.** A named `function foo()`
+  shows up by name in stack traces / logs; an anonymous arrow is `<anonymous>`. So: real logic,
+  anything that can throw, async handlers, event callbacks → name them. Trivial one-liners where
+  an error is impossible (simple getters, mappers, predicates) — arrow is fine, no need to fuss.
+
+## Types
+- Union and primitive aliases — `t` prefix: `tNum`, `tSide`, `tOrderId`.
+- Generic parameters — uppercase `T`, `K`, `Cb`.
+- Derive public types from the implementation: `type X = ReturnType<typeof createX>`.
+
+## Comments
+- Section dividers like `// ===...===` with a block heading.
+- Explain "why", not "what". Keep them short.
+## Documentation and release notes
+
+- `README.md` is navigation only. Do not put API guides, examples, or long explanations there.
+- The brief public surface lives in `doc/wenay-common2.md`.
+- The extended/rare public surface lives in `doc/wenay-common2-rare.md`.
+- Naming migrations live in `doc/NAMING_RENAMES.md`.
+- Recent changes live in `doc/changes/` as one markdown file per published version, named `<version>.md`.
+- Every release/change intended for publication must add or update the current version file in `doc/changes/` with a short commit-style summary of what changed.
+- Keep only the latest 10 version files in `doc/changes/`; delete older version files when adding a new one.
+- Do not publish until brief docs, rare docs, and the current version change file match the code being published.

package/README.md

@@ -1,325 +1,9 @@
 # wenay-common2
 
-A set of common utilities and components for TypeScript/Node.js projects.
+## Documentation
 
-## 📦 Library Structure
-
-### 🔧 **core/** — Base Utilities
-- **`common.ts`** — deep/shallow cloning and comparison, binary search (`BSearch*`), number conversion, timers, mutex, helper structures (`MyMap`, `StructMap`), clipboard handling
-- **`BaseTypes.ts`** — `Immutable`/`Mutable` types, `const_Date`, type utilities (`PickTypes`, `OmitTypes`, `KeysByType`)
-- **`Decorator.ts`** — function decorators/transformers (before/after call, result processing)
-- **`MemoFunc.ts`** — memoization with TTL and limits, LRU eviction
-
-### 📊 **data/** — Data Structures and Serialization
-- **`List.ts`** — doubly linked list `CList` with immutable interfaces
-- **`ListNodeAnd.ts`** — alternative doubly linked list nodes with a sentinel element
-- **`ByteStream.ts`** — binary serialization: `ByteStreamW` (write) and `ByteStreamR` (read), support for numeric types and arrays
-- **`objectPath.ts`** — working with object paths (`objectGetValueByPath`, `objectSetValueByPath`, iteration via `iterateDeepObjectEntries`)
-
-### ⏱️ **async/** — Async Utilities
-- **`waitRun.ts`** — throttle/debounce (`enhancedWaitRun`), async queues (`createAsyncQueue`, `queueRun`), task queue with readiness control (`createTaskQueue`)
-- **`promiseProgress.ts`** — processing an array of promises with success/error subscriptions
-- **`createIterableObject.ts`** — proxy for iterable objects (readonly/read-write)
-
-### 🔔 **events/** — Events and Subscriptions
-- **`Listen.ts`** — subscription system (`listen`, `createListen`), `isListenCallback` check
-- **`event.ts`** — event handler collections (`CObjectEventsArr`, `CObjectEventsList`)
-- **`SocketBuffer.ts`** — socket callback buffering (`socketBuffer`, `listenSnapshot`)
-- **`SocketServerHook.ts`** — tag-based subscription wrappers for socket communication (`SocketServerHook`, `WebSocketServerHook`)
-- **`joinListens.ts`** — merging multiple subscription streams into one (`joinListens`)
-- **`listen-socket.ts`** — bridge between event system and RPC (`listenSocket`, `listenSocketFirst`, `listenSocketAll`, `listenSocketSmart`)
-
-### 🌐 **rpc/** — RPC System
-**Core:**
-- **`rpc-protocol.ts`** — RPC protocol (packet types `Pkt`, `SocketTmpl`)
-- **`rpc-client.ts`** — RPC client (`createRpcClient`, `ClientAPI`)
-- **`rpc-server.ts`** — RPC server (`createRpcServer`, hooks `PromiseServerHooks`)
-- **`rpc-walk.ts`** — structure traversal (callback serialization, `pack`/`unpack`, `resolveCA`)
-- **`rpc-limits.ts`** — security limits (`RpcLimits`, `PayloadLimitError`, `isSafeKey`)
-- **`rpc-dynamic.ts`** — dynamic object marking (`noStrict`, `isNoStrict`)
-- **`id-pool.ts`** — reusable ID pool (`createIdPool`)
-
-**Automation:**
-- **`rpc-client-auto.ts`** — client with automatic event subscription (`createRpcClientAuto`, modes `smart`/`first`/`all`)
-- **`rpc-server-auto.ts`** — server with automatic subscription handling (`createRpcServerAuto`)
-- **`listen-deep.ts`** — deep object transformation for subscriptions (`deepListenFirst`, `deepListenAll`, `deepListenSmart`)
-
-### 📡 **network/** — Network Utilities
-- **`WebHook3.ts`** — webhook server/client on Express
-  - **Server:** `createWebhookServer({ authToken, port, app? })`
-  - **Client:** `createWebhookClient({ serverUrl, clientPort, authToken, autoRenew? })`
-  - Support for legacy (`tag`) and new (`tags`) format in `subscribers.json`
-
-### ⏰ **time/** — Time Handling
-- **`Time.ts`** — timeframes (`TF`), periodics (`Period`), time formatting, date conversion (`timeToStr_*`, `timeLocalToStr_*`)
-- **`funcTimeWait.ts`** — request time tracking by keys (`funcTimeW`, `FuncTimeWait`)
-
-### 🎨 **utils/** — Helper Utilities
-- **`Color.ts`** — color handling (`ColorString`, `rgb`, generators `colorGenerator`, similarity check `isSimilarColors`)
-- **`Math.ts`** — Pearson correlation calculation (`CorrelationRollingByBuffer`)
-- **`isProxy.ts`** — Proxy object detection (Node.js + browser)
-- **`fsKeyVolume.ts`** — file system key-value storage (`saveKeyValue`)
-- **`inputAutoStep.ts`** — automatic step control for `<input>` (`SetAutoStepForElement`)
-- **`node_console.ts`** — enhanced console output with source maps (clickable links in IDE)
-
----
-
-## 🚀 Quick Start
-
-### Installation
-```bash
-npm install wenay-common2
-```
-
-Here is a comprehensive guide in a concise style. I've taken into account the architecture, backend, frontend (with the new `Hub` pattern), serialization nuances, limits, and hooks.
-
-# wenay-common2 RPC: Complete Guide
-
-Bidirectional, strongly-typed RPC protocol over sockets (Socket.IO or similar).
-**Essence:** Server exposes a nested JS object $\to$ Client receives a typed proxy.
-
----
-
-## 1. Architecture and Limitations
-
-*   **Multiplexing:** A single physical socket hosts independent channels (`socketKey`), each with its own API object.
-*   **Data Types:** Works with JSON-compatible data plus `Date`, `Map`, `Set`, `RegExp`, and `BigInt`. Class instances are sent as plain enumerable object data; methods/prototypes are not preserved.
-*   **Security (RpcLimits):** Server is protected from DDoS attacks. Strict limits on: `maxDepth`, `maxKeys`, `maxArrayLen`, `maxStringLen`, `maxCallbacks`. Exceeding throws `PayloadLimitError`.
-
----
-
-## 2. Server (Backend)
-
-### 2.1 Socket Connection
-```typescript
-import { createRpcServerAuto, listen } from "wenay-common2";
-
-io.sockets.on('connection', (socket) => {
-  // 1. Create unsubscribe trigger for memory cleanup
-  const [stop, listenStop] = listen<[]>();
-  socket.on('disconnect', stop);
-
-  // 2. Initialize RPC channel on this socket
-  createRpcServerAuto({
-    socket,
-    socketKey: "mainAPI",         // Channel identifier
-    object: buildFacade(client),  // Target API object
-    disconnectListen: listenStop, // Auto-unsubscribe from Listen on disconnect
-    debug: process.env.DEV,       // Packet logging
-  });
-});
-```
-
-### 2.2 Building API Object (Facade)
-The object is traversed by the server to build a "Schema" that is sent to the client.
-```typescript
-import { noStrict, listen } from "wenay-common2";
-
-// Create pub/sub event system
-const [sendEvent, listenEvent] = listen<[string]>();
-
-export function buildFacade(client) {
-  const role = (...roles) => hasRole(client, roles) ? true : null;
-
-  return {
-    // 1. Regular method
-    ping: () => "pong",
-
-    // 2. Nested namespaces + Role model
-    // If role() returns null, the method won't be sent to the client (returns null in schema)
-    admin: {
-      deleteUser: role("admin") && ((id) => db.delete(id)),
-    },
-
-    // 3. Dynamic objects (Proxy, ORM)
-    // Wrap in noStrict so the server doesn't try to read keys.
-    // Client will work with it in "blind" mode (without schema).
-    dbRef: noStrict(getProxyDb()),
-
-    // 4. Events
-    // Client will receive a Listen surface: .on(cb), .once(cb), .close()
-    events: { listenEvent },
-
-    // 5. Method with callback in arguments
-    // Callback lives ONLY while await is executing! After return, client deletes it.
-    stream: async (cb: (chunk: number) => void) => {
-      for(let i=0; i<10; i++) { cb(i); await sleep(50); }
-      return "done";
-    }
-  };
-}
-```
-
-### 2.3 Server Hooks (Interceptors)
-Use hooks to validate incoming packets.
-```typescript
-createRpcServerAuto({
-  /*...*/
-  hooks: {
-    onRequest: async ({ key, request, fnName, fn }) => {
-      // Return false to block the call
-      return true;
-    },
-    onInvalid: ({ reason, key, request }) => {
-      console.warn(`RPC Attack/Error [${reason}]:`, key);
-    }
-  }
-})
-```
-
----
-
-## 3. Client (Frontend)
-
-**Hub Pattern:** The frontend library doesn't depend on `socket.io-client`. Developer injects the socket factory into `createRpcClientHub`.
-
-### 3.1 Hub Initialization
-```typescript
-import { io } from "socket.io-client";
-import { createRpcClientHub, rpc } from "wenay-common2";
-import type { MainFacade } from "../server/facade";
-
-export const Api = createRpcClientHub(
-  // 1. Socket factory (DI)
-  (token) => io("http://localhost:4021", {
-    transports: ["websocket"],
-    query: token ? { token } : {}
-  }),
-
-  // 2. Channel registration
-  // rpc() accepts Facade type. Property name ("mainAPI") becomes socketKey.
-  (rpc) => ({
-    mainAPI: rpc<MainFacade>(),
-  })
-);
-```
-
-### 3.2 Connection Lifecycle
-```typescript
-// Listen to statuses
-Api.onConnect((count) => console.log(`Socket connected (attempt ${count})`));
-
-// Initiate connect. Creates socket, all channels automatically start.
-await Api.connect("USER_SECRET_TOKEN");
-
-// Disconnect
-// await Api.connect(null);
-```
-
-### 3.3 Call Modes
-Access API channel: `Api.facade.mainAPI`. Hub initializes all channels, so schema loads automatically.
-
-```typescript
-const api = Api.facade.mainAPI;
-
-// Wait for schema (REQUIRED before UI render)
-await api.ready();
-
-// --- 1. STRICT (Recommended) ---
-// Safe call. Use `?.` since method may be `null` (closed by roles).
-// If method is closed, returns `undefined` without sending network request.
-const res = await api.strict.admin?.deleteUser?.(5);
-
-// --- 2. FUNC (Standard) ---
-const res2 = await api.func.ping();
-
-// --- 3. PIPE (Pipeline) ---
-// Entire chain goes to server in ONE network packet.
-const data = await api.pipe.dbRef.users.find(1).getName();
-
-// --- 4. SPACE (Fire-and-Forget) ---
-// Doesn't wait for response, Promise resolves immediately.
-api.space.admin.logAction("clicked");
-```
-
-### 3.4 Client Subscriptions (Listen)
-`createRpcServerAuto` exposes server `listen` values as RPC Listen nodes. New code uses `on`/`once` and keeps the returned `off` handle. For TypeScript, project `client.func` to `DeepSocketListen<ServerFacade>`; this mirrors the runtime shape and keeps event argument types.
-```typescript
-import type { DeepSocketListen } from "wenay-common2";
-
-function webListen<T extends object>(client: { func: unknown }) {
-  return client.func as DeepSocketListen<T>;
-}
-
-const events = webListen<MainFacade>(api).events;
-
-// Subscribe
-const off = events.listenEvent.on((msg) => {
-  console.log("Push from server:", msg);
-});
-
-// Unsubscribe. The handle is callable and also thenable.
-off();
-// await off; // waits until the stream ends
-
-// One event, then automatic unsubscribe
-const done = events.listenEvent.once((msg) => {
-  console.log("First push:", msg);
-});
-await done;
-```
-
-Compatibility names `.callback(cb)`, `.removeCallback()`, and `.unsubscribe()` still exist for old clients, but they are not the recommended API.
-
-
-### 3.5 Request Management and Debug
-Each facade has a system object `api` for low-level control, as well as a couple of methods in the root:
-
-```typescript
-const { api, abortAll, schema } = Api.facade.mainAPI;
-
-// --- 1. Monitoring and Debug ---
-api.pending();          // Current number of pending responses (Promises)
-api.callbacks();        // Current number of live callback ids in memory
-api.log(true);          // Enable logging of all incoming/outgoing packets to console
-
-// --- 2. Targeted cleanup (inside .api) ---
-api.clearPromises(true); // Reject (cancel) all current requests
-api.clearCallbacks();    // Force clear all callbacks
-api.remove(myFunc);      // Force-release a specific callback id (alias: .end)
-
-// --- 3. Global facade methods ---
-abortAll("User logout"); // Hard reset: reject all promises with RPC_ABORT error + clear all callback ids
-const map = schema();    // Get raw schema tree (MAP) sent by server
-```
-
-
----
-
-## 4. Advanced Features
-
-### 4.1 Listen Argument Interception Modes
-When using events, the client auto-handler (`mode: "smart"`) by default flexibly adapts arguments. If server sends one argument — it comes as a value, if multiple — as an array.
-If you create a client manually without Hub, you can set a strict mode:
-```typescript
-// "first" — listener always receives only the first argument
-// "all" — listener always receives all arguments
-// "smart" — (default) auto-detection
-const autoApi = createRpcClientAuto(api.func, { mode: "first" });
-```
-
-
-### 4.2 Manual Callback Termination from Server
-This is a low-level escape hatch for callbacks passed as ordinary function arguments. For Listen subscriptions prefer `off()`/`.once()`.
-```typescript
-import { endCallback } from "wenay-common2";
-
-async function myMethod(cb: (data: any) => void) {
-  cb("chunk 1");
-  endCallback(cb); // Alias: rpcEndCallback. Sends "___STOP" to client.
-  // Client callback id is deleted, subsequent cb() calls won't go anywhere.
-}
-```
-
-### 4.3 Call / Apply Support on Client
-The client proxy can transparently handle standard JS `call` and `apply` calls. Server correctly normalizes them ("collapses" the path):
-```typescript
-// Both variants correctly call `api.users.create("Ivan")` on server
-await api.func.users.create.call(null, "Ivan");
-await api.func.users.create.apply(null, ["Ivan"]);
-```
-
-
-### 4.4 Transparent PIPE Request Transit
-For microservice architecture. If your Node server itself is a client of another RPC node (via `pipe`), it can "pass through" the remainder of the pipe chain further using `__executeRemainingPipe`, without waiting for an intermediate response.
-This covers the important RPC mechanics (Listen `on/once/off`, `endCallback`, `call/apply`, `pipe-transit`) while maintaining readability.
+- Brief API cheat sheet: [`doc/wenay-common2.md`](doc/wenay-common2.md)
+- Extended API cheat sheet: [`doc/wenay-common2-rare.md`](doc/wenay-common2-rare.md)
+- Naming migrations: [`doc/NAMING_RENAMES.md`](doc/NAMING_RENAMES.md)
+- Recent changes: [`doc/changes/`](doc/changes/)
+- Project rules for AI/code maintenance: [`CLAUDE.md`](CLAUDE.md)

package/doc/NAMING_RENAMES.md

@@ -0,0 +1,36 @@
+# Карта переименований
+
+Breaking migration: старые имена не оставляем алиасами.
+
+| Было | Стало |
+| --- | --- |
+| `UseListen` | `listen` |
+| `UseListenStore` | `listenStore` |
+| `UseListen2` | `slimListen` |
+| `toListen2` | `toSlimListen` |
+| `UseListenTransform` | `mapListen` |
+| `funcListenCallbackBase` | `createListen` |
+| `funcListenCallbackFast` | `createFastListen` |
+| `funcListenCallbackStore` | `createStoreListen` |
+| `funcListenCore` | `createListenCore` |
+| `addListen` | `on` |
+| `removeListen` | `off` |
+| `eventClose` | `onClose` |
+| `removeEventClose(cb)` | `const off = onClose(cb); off()` |
+| `addListenClose` | `closeOn` |
+| `tSubHandle` | `SubscriptionHandle` |
+| `PromiseArrayListen` | `promiseProgress` |
+| `listenOk` / `listenError` | `onOk` / `onError` |
+| `promise.all()` / `promise.allSettled()` | `all()` / `allSettled()` |
+| `getData()` / `status()` | `items()` / `stats()` |
+| `realSocket2` | `SocketSource` |
+| `getTypeCallback` | `SocketPayload` |
+| `socketBuffer3` | `socketBuffer` |
+| `funcListenCallbackSnapshot` | `listenSnapshot` |
+| `createRpcServerAuto2` | `createRpcServerAutoDetect` |
+| `UseReplayListen` | `replayListen` |
+| `ListenNext` | root exports from `wenay-common2` (`listen`, `listenStore`, `slimListen`) |
+| `wenay-common2/listen2` | removed; use root exports from `wenay-common2` |
+| `ObserveAll2` | `Observe` |
+| `wenay-common2/observe-all2` | `wenay-common2/observe` |
+| `src/Common/ObserveAll2` | `src/Common/Observe` |

package/doc/RECOMMENDATIONS.md

@@ -0,0 +1,56 @@
+# Recommendations — Listen / Observe / RPC integration
+
+Status refreshed 2026-07-08. This document is now a current checklist, not the
+old 2026-07-02 migration scratchpad. Public code should import the canonical
+surfaces (`wenay-common2`, `wenay-common2/observe`, `wenay-common2/replay`, or
+`src/Common/events/Listen` inside the repo). Numbered implementation artifacts
+such as `Listen3` and `reactive2` are compatibility shims only.
+
+## 1. Naming cleanup
+
+- **DONE** `src/Common/events/Listen.ts` is the real implementation file.
+  `Listen3.ts` remains only as an internal deep-import shim.
+- **DONE** `src/Common/Observe/reactive.ts` is the real reactive implementation.
+  `reactive2.ts` remains only as an internal deep-import shim.
+- **DONE** the oracle folder is `observe/`, not `observable2/`.
+- **RULE** new code and docs should not introduce `UseListen`, `Listen3`,
+  `reactive2`, or `observable2` outside `NAMING_RENAMES.md`, historical `doc/changes/` notes, or shim comments.
+
+## 2. Observe store status
+
+- **DONE** circular `Map`/`Set` snapshots are guarded by `seen` before container
+  traversal.
+- **DONE** `createStoreMirror.sync` reports failed re-pulls through
+  `StoreSyncOpts.onError`; initial pull failure still rejects the awaited sync.
+- **DONE** path cache identity separates dotted keys and distinct symbols.
+- **DONE** brief/rare docs describe the store layer as separate from the coarse
+  reactive core.
+- **OPEN** `_nodeCache` and `_counts` are unbounded for dynamic path spaces.
+  Either document bounded-path expectations for applications or add eviction.
+- **OPEN** `schedule` / `createDrained` in `store.ts` still duplicate scheduler
+  logic from `reactive.ts`; extract only if more local schedulers appear.
+
+## 3. Store manager direction
+
+The universal manager should stay above `Observe.createStore` / replay / offline.
+It should not make the store core know about products, routes, user habits, or
+large-resource policy. The manager owns resource declarations, priority, tags,
+usage scoring, explicit-only gates, and start/stop lifecycle.
+
+Current implementation target: `Observe.createStoreManager` with `managedStore`
+builders for `mirror`, `replay`, and `offline` resources.
+
+## 4. RPC current over wire
+
+Still open. The client dedup key already includes non-function args, but the
+server subscription path does not yet whitelist and forward `{current:true}` to
+Listen store decorators. Do not document `{current:true}` over RPC as supported
+until server forwarding and late-join replay are implemented together.
+
+## 5. Suggested order
+
+1. Keep naming cleanup green with `rg` before release.
+2. Add tests for `createStoreManager` planning, explicit gates, mirror sync, and
+   offline/replay startup.
+3. Update brief and rare docs only after tests pass.
+4. Bump patch version, build, then publish from `dist`.

package/doc/REPLAY-PLAN.md

@@ -0,0 +1,81 @@
+# Snapshot + Sequenced Delta Line — universal state sync
+
+One pattern for everything: **keyframe (snapshot) + numbered line of deltas + recovery via fresh keyframe**.
+Payload-agnostic: store patches, ticks, any events. Same figure as market-data feeds
+(incremental + snapshot channel), DB replication (basebackup + WAL), video (I/P frames), Kafka.
+
+## Invariants
+
+- **seq is the coordinate, time is an attribute.** Every journaled event: `{seq, ts, event}`.
+  seq = monotonic counter → strict order, gap detection, exact replay→live handover.
+  Time is for humans only: "rewind to 12:00" resolves to nearest keyframe ≤ ts → its seq.
+- **Keyframe = state as of seq S.** Rule of the whole system:
+  `keyframe(S) + events S+1…K = exact state at K`.
+- **Memory stays external** (lambda providers), decorators own no data they don't have to.
+- **Additive only.** The canonical Listen surface is untouched; new surface = decorator + opts.
+- The live store is never reset: archiving = take a labeled copy, keep mutating the same store.
+
+## The killer property (drives everything)
+
+A lagging/late/reconnecting consumer never gets a queue backlog — it gets a **fresh keyframe
++ the line from there**. This is both the catch-up mechanism AND the backpressure policy
+(conflation + snapshot recovery). No unbounded buffering, ever.
+
+## Layers
+
+### A. Listen replay decorator — `withReplayListen` (universal, payload-agnostic)
+
+Decorator over `ListenApi`, exact shape of `withStoreListen`:
+
+```
+withReplayListen(base, {
+    current,                       // () => keyframe        — external memory lambda (exists: layer 3)
+    history?: number,              // ring buffer size N (internal) …
+    getSince?: (seq) => events[],  // …or external journal lambda (memory outside — preferred)
+})
+```
+
+Subscription modes:
+- `on(cb)` — live only (unchanged)
+- `on(cb, {current: true})` — keyframe + live (unchanged, layer 3)
+- `on(cb, {since: seq})` — catch-up: replay journal from seq+1, queue live events by seq
+  during replay, dedup by seq, seamless switch to live. seq evicted from journal →
+  fallback: keyframe + live.
+
+The handover (replay→live without gap or dup) is the ONLY subtle code in the plan.
+Everything else is mechanics.
+
+### B. Observe store integration
+
+- `exposeStore`: patch journal — every emitted `StorePatch` gets seq; keep last N (ring).
+  `snapshot()` responses carry the seq they correspond to.
+- `createStoreMirror`: sync = "I have seq K" → tail of patches, or snapshot(S) + live from S+1.
+  Reconnect stops costing a full snapshot when the tail suffices.
+- Uses layer A; store adds nothing but "patch as the event type".
+
+### C. History storage (optional, lazy, fully external)
+
+For seek into the past — not needed for live sync:
+- periodic archiving: keyframe every N events OR T seconds, whichever first (GOP tradeoff:
+  dense = fast seek / more space, sparse = cheap / longer replay);
+- providers: `getKeyframe(seqOrTs)`, `getEvents(from, to)` — file/DB/anything, behind lambdas;
+- a history reader is the SAME subscriber interface: subscribe `{since}` → archive replay →
+  journal catch-up → live. One mechanism for playback and live.
+
+### D. Transport hardening (independent add-ons, any order, later)
+
+- **Per-client conflation**: outgoing buffer over threshold → stop deltas for that client,
+  mark "needs keyframe"; buffer drained → fresh snapshot + resume from current seq.
+- **Serialize once, fan out**: pack a tick once, send bytes to all subscribers
+  (extends existing Caps.COMPACT / shape packing).
+- **Coalescing**: N updates of one key while client lagged → send only the last.
+- **Binary passthrough** in `rpc-walk`: TypedArray/ArrayBuffer/Buffer as leaf values
+  (socket.io carries binary natively; today walk() mangles them into `{0:…,1:…}`).
+
+## Stages
+
+1. `withReplayListen` decorator + seq handover (layer A) — the core, small.
+2. Patch journal in `exposeStore` + `since`-sync in mirror (layer B).
+3. Conflation + snapshot recovery on the wire (first item of D) — this is what turns
+   "semi-pro" into pro for fan-out.
+4. C and the rest of D — on demand.

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/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.