@fairfox/polly 0.58.0 → 0.60.0

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

@@ -23,6 +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 MeshStateLazyWrapperRecord, type MeshStateLoadedRejectionBreadcrumb } from "./mesh-state";
 import { MeshWebRTCAdapter, type MeshWebRTCAdapterOptions } from "./mesh-webrtc-adapter";
 /** Options for {@link createMeshClient}. */
 export interface CreateMeshClientOptions {
@@ -232,6 +233,42 @@ export interface MeshStateModuleDiagnostics {
      * true` (they're using a module instance no mesh client ever
      * configured). */
     wasResolved: boolean;
+    /** Polly#107 post-H5 instrumentation. Count of `$meshState`-family
+     * lazy factory invocations since module load. Once the consumer's
+     * pre-warm pass completes, this equals the number of distinct
+     * `$mesh*` wrappers whose handles the loader actually tried to
+     * resolve. Compared to {@link lazyReachedRepo}: gap = throws
+     * before any Repo work. */
+    lazyInvocations: number;
+    /** Polly#107 post-H5 instrumentation. Count of factory invocations
+     * that reached the Repo subsystem (`repo.handles[...]`, `repo.find`
+     * or `repo.import`) before returning or throwing. If
+     * {@link lazyInvocations} is N and this is N, every wrapper
+     * touched the Repo — any missing handles are downstream of Repo
+     * registration. If this is < N, the gap is the call site to
+     * instrument next. */
+    lazyReachedRepo: number;
+    /** Polly#107 post-H5 instrumentation. Breadcrumb for the most
+     * recent rejection from a `$meshState`-family `loaded` promise
+     * (or its factory). Captured even when the consumer's wrapper
+     * never awaits `loaded` and the rejection would otherwise vanish
+     * 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

@@ -113,6 +113,96 @@ export declare function isMeshStateConfigured(): boolean;
  * called against this module instance. See
  * {@link meshStateEverResolved}. */
 export declare function wasMeshStateResolved(): boolean;
+/** Returns the count of factory invocations since module load. See
+ * {@link lazyInvocations}. */
+export declare function getLazyInvocations(): number;
+/** Returns the count of factory invocations that reached
+ * `repo.find` / `repo.import` since module load. See
+ * {@link lazyReachedRepo}. */
+export declare function getLazyReachedRepo(): number;
+/** Polly#107 post-H5 instrumentation. Records the most recent
+ * rejection (or synchronous throw) escaping the factory body — the
+ * `loaded` promise's rejection path. Today an unawaited rejection
+ * inside a consumer wrapper vanishes without trace; capturing the
+ * message + stack here on the module and exposing it via the
+ * snapshot leaves a breadcrumb the operator can read in one paste.
+ *
+ * The format is the JSON-safe `{ name, message, stack, at }` shape
+ * so the snapshot read does not have to traffic in `Error`
+ * instances. `at` is `Date.now()` at the time the rejection was
+ * captured. */
+export interface MeshStateLoadedRejectionBreadcrumb {
+    name: string;
+    message: string;
+    stack: string | undefined;
+    at: number;
+}
+/** 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.58.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",