@fairfox/polly 0.59.0 → 0.60.0

package/dist/src/shared/lib/mesh-client.d.ts

@@ -23,7 +23,7 @@ import { Repo, type StorageAdapterInterface } from "@automerge/automerge-repo/sl
 import type { KeyringStorage } from "./keyring-storage";
 import { type MeshKeyring, MeshNetworkAdapter } from "./mesh-network-adapter";
 import { MeshSignalingClient, type MeshSignalingClientOptions } from "./mesh-signaling-client";
-import { type MeshStateLoadedRejectionBreadcrumb } from "./mesh-state";
+import { type MeshStateLazyWrapperRecord, type MeshStateLoadedRejectionBreadcrumb } from "./mesh-state";
 import { MeshWebRTCAdapter, type MeshWebRTCAdapterOptions } from "./mesh-webrtc-adapter";
 /** Options for {@link createMeshClient}. */
 export interface CreateMeshClientOptions {
@@ -255,6 +255,20 @@ export interface MeshStateModuleDiagnostics {
      * silently. `undefined` means no rejection has escaped any
      * wrapper on THIS module instance since module load. */
     lastLoadedRejection: MeshStateLoadedRejectionBreadcrumb | undefined;
+    /** Polly#107 post-v0.59 instrumentation. Per-factory-invocation
+     * structured log — one record per `$mesh*` wrapper's lazy handle
+     * factory call, ring-buffered at 64 entries. Each row names the
+     * exit path (`returned-cached`, `loaded-from-storage`,
+     * `seeded-and-imported`, `threw`) and the synchronous peek at
+     * `repo.handles[docId]` taken in the factory's `finally`. The
+     * v0.59.0 fingerprint had `lazyInvocations === lazyReachedRepo`
+     * and no `lastLoadedRejection`; this field disambiguates which
+     * exit path each "successful" invocation actually took and
+     * whether the Repo registered the handle in spite of the lack of
+     * a thrown error. The smoking gun for H-Q1 is rows with
+     * `exitReason: "seeded-and-imported"` and
+     * `handleRegistered: false`. */
+    lazyWrappers: MeshStateLazyWrapperRecord[];
 }
 /** The mesh client's enriched per-peer state snapshot. Mirrors the
  * underlying {@link MeshWebRTCAdapter.getPeerStateSnapshot} shape but

package/dist/src/shared/lib/mesh-state.d.ts

@@ -140,6 +140,69 @@ export interface MeshStateLoadedRejectionBreadcrumb {
 /** Returns the most recent rejection escaping a `$meshState` factory
  * invocation since module load. See {@link lastLoadedRejection}. */
 export declare function getLastLoadedRejection(): MeshStateLoadedRejectionBreadcrumb | undefined;
+/** Polly#107 post-v0.59 instrumentation. Categorises the exit path
+ * a `$mesh*` lazy factory invocation took. The v0.59.0 fingerprint
+ * showed `lazyInvocations === lazyReachedRepo === 17` and no
+ * `lastLoadedRejection` — every factory reached the first
+ * `repo.handles[docId]` access, none rejected loudly, yet 16 of 17
+ * handles never landed in `repo.handles`. Without per-exit detail
+ * the snapshot cannot disambiguate "factory returned the cached
+ * handle", "factory hydrated from storage", "factory seeded and
+ * imported a fresh doc", or "factory took the cached branch but
+ * `whenReady` resolved to `unavailable` and the code fell
+ * through". Each exit reason corresponds to a single line in
+ * {@link buildHandleFactory}; the snapshot record names it
+ * verbatim so the operator can grep the source from one read. */
+export type LazyWrapperExitReason = "returned-cached" | "loaded-from-storage" | "seeded-and-imported" | "threw";
+/** Polly#107 post-v0.59 instrumentation. One record per factory
+ * invocation, ring-buffered on the module and surfaced through
+ * `MeshClient.getPeerStateSnapshot()` as
+ * `meshStateModule.lazyWrappers`. The five fields together answer
+ * the post-v0.59 question "if every factory reached the Repo and
+ * nothing rejected, why are 16 of 17 handles absent from
+ * `repo.handles`?" — `exitReason` names which of the three success
+ * paths each took, `handleRegistered` is the synchronous peek at
+ * `repo.handles[docId]` taken in the factory's `finally` (i.e. at
+ * the moment of would-be return), and `handleState` is the
+ * lifecycle state observed in that peek. A row where
+ * `exitReason: "seeded-and-imported"` and `handleRegistered: false`
+ * is the smoking gun for H-Q1 (`repo.import` returned without
+ * registering); rows where `exitReason: "returned-cached"` repeats
+ * for sixteen of seventeen distinct keys indicates collisions or
+ * that the factory is being called multiple times against a
+ * Repo-state-machine that has already filled the slot. */
+export interface MeshStateLazyWrapperRecord {
+    /** The logical application key passed to `$meshState(key, ...)`. */
+    key: string;
+    /** Stringified Automerge `DocumentId` derived from the key. */
+    docId: string;
+    /** `Date.now()` captured at the moment the factory was about to
+     * return (or rethrow). */
+    at: number;
+    /** Which of the four exit paths the factory took. See
+     * {@link LazyWrapperExitReason}. */
+    exitReason: LazyWrapperExitReason;
+    /** Snapshot peek `repo.handles[docId] !== undefined` taken in the
+     * factory's `finally` clause. `true` means the local Repo
+     * registered the handle; `false` means the factory thinks it
+     * succeeded but the Repo does not hold the handle for this
+     * documentId. The "polly#107 post-v0.59" smoking gun is
+     * `exitReason: "seeded-and-imported", handleRegistered: false`. */
+    handleRegistered: boolean;
+    /** Lifecycle state of `repo.handles[docId]` at the synchronous
+     * peek time. `undefined` when the handle was not registered.
+     * Useful for distinguishing the "registered as loading/unavailable"
+     * case from the "registered as ready" case. */
+    handleState: string | undefined;
+    /** Error message if `exitReason === "threw"`; `undefined`
+     * otherwise. The full rejection still flows into
+     * {@link lastLoadedRejection}; this field is the row-local
+     * summary so the snapshot can show the failure cause inline. */
+    errorMessage: string | undefined;
+}
+/** Returns a copy of the lazy-wrapper invocation log. See
+ * {@link MeshStateLazyWrapperRecord}. */
+export declare function getLazyWrappers(): MeshStateLazyWrapperRecord[];
 /**
  * Create a peer-replicated state primitive backed by Automerge with a mesh
  * transport. Every device holds a full replica; no central server holds a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairfox/polly",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "private": false,
   "type": "module",
   "description": "Multi-execution-context framework with reactive state and cross-context messaging for Chrome extensions, PWAs, and worker-based applications",