@fairfox/polly 0.57.0 → 0.59.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 MeshStateLoadedRejectionBreadcrumb } from "./mesh-state";
 import { MeshWebRTCAdapter, type MeshWebRTCAdapterOptions } from "./mesh-webrtc-adapter";
 /** Options for {@link createMeshClient}. */
 export interface CreateMeshClientOptions {
@@ -197,6 +198,64 @@ export interface MeshClientHandleSnapshot {
      * asking. */
     lastSyncMessageOutType: string | undefined;
 }
+/** Polly#107 H5 diagnostics: surfaces the `mesh-state` module
+ * instance identity so a single snapshot read tells the operator
+ * whether the consumer's `$meshState` wrappers are resolving against
+ * the same module instance `createMeshClient` configured. A mismatch
+ * here IS the bundle-time module duplication bug. */
+export interface MeshStateModuleDiagnostics {
+    /** The id stamped at import time on the `mesh-state` module
+     * instance THIS mesh client was constructed against. Compare to
+     * the id seen at the `$meshState` call site (also importable as
+     * `MESH_STATE_MODULE_ID` from `@fairfox/polly/mesh`). Two different
+     * ids means the consumer is reaching a duplicated copy of
+     * `mesh-state.ts` — wrappers register handles against a Repo this
+     * mesh client never saw. */
+    moduleId: string;
+    /** `true` iff THIS module instance has a configured `defaultRepo`.
+     * In the H5 scenario, this is `true` for the mesh-client-side
+     * snapshot (because `createMeshClient` always calls
+     * `configureMeshState` on the module it imports), but the same
+     * field read from the consumer's `$meshState` call site would
+     * be `false`. */
+    configured: boolean;
+    /** `peerId` of the most recent Repo wired through
+     * `configureMeshState` against THIS module instance. Compared to
+     * `client.repo.peerId` and the consumer's wrappers' resolved Repo
+     * tells the full story. */
+    lastConfiguredRepoPeerId: string | undefined;
+    /** `true` if any `$meshState`-family wrapper has been called
+     * against THIS module instance at any point. The polly#107 H5
+     * fingerprint pair: `configured: true, wasResolved: false` on
+     * the mesh-client-side snapshot (the wrappers never reached us);
+     * the consumer's wrapper code reading the same field from THEIR
+     * `$meshState` import would see `configured: false, wasResolved:
+     * 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;
+}
 /** The mesh client's enriched per-peer state snapshot. Mirrors the
  * underlying {@link MeshWebRTCAdapter.getPeerStateSnapshot} shape but
  * replaces the slot's `handles` map with the Repo-enriched view
@@ -211,6 +270,19 @@ export interface MeshClientPeerStateSnapshot {
             handles: Record<string, MeshClientHandleSnapshot>;
         });
     }>;
+    /** polly#107 H5 diagnostics. See {@link MeshStateModuleDiagnostics}. */
+    meshStateModule: MeshStateModuleDiagnostics;
+    /** Count of handles known to the Repo this client owns. Compared
+     * to the count the consumer's `$meshState` wrappers should have
+     * registered: a mismatch (e.g. consumer pre-warmed 14 wrappers,
+     * snapshot reports 1) confirms the H5 module-duplication
+     * fingerprint without needing a separate read. */
+    repoHandleCount: number;
+    /** All handle ids the Repo this client owns currently caches.
+     * Together with `repoHandleCount` and `meshStateModule.moduleId`,
+     * this answers "did the consumer's wrappers land their handles in
+     * THIS Repo?" in one read. */
+    repoHandleIds: string[];
 }
 /** Handle returned by {@link createMeshClient}. */
 export interface MeshClient {

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

@@ -56,6 +56,41 @@ export interface MeshStateOptions {
      * a public-key set used by the signing layer to verify incoming ops. */
     access?: Access;
 }
+/** Per-module-instance identifier stamped at import time. Two distinct
+ * module instances (e.g. duplicated under a bundler that hoists
+ * differently for the consumer's app code and `@fairfox/polly`'s own
+ * imports) produce two different ids — and therefore two different
+ * `defaultRepo` globals.
+ *
+ * The polly#107 fingerprint reading is exactly that: `configureMeshState`
+ * runs on one module instance (the one `createMeshClient` imports);
+ * the consumer's `$meshState(key, initial)` calls run on a different
+ * instance, whose `defaultRepo` was never set. `resolveRepo` either
+ * throws (caught silently by consumer wrappers) or returns the
+ * unconfigured fallback — either way, the handle that should land
+ * in the mesh `Repo` lands somewhere else (or nowhere), Automerge's
+ * NetworkSubsystem never sees it, and inbound sync from the daemon
+ * has nowhere to go.
+ *
+ * Exported so consumers can compare the id seen at the `$meshState`
+ * call site against the id seen at the `configureMeshState` call
+ * site. A mismatch IS the bundle-duplication bug; a match rules it
+ * out. The id is also surfaced via {@link getMeshStateModuleId} on
+ * every `MeshClient.getPeerStateSnapshot()` so a single one-line
+ * read from the failing tab tells the operator which module
+ * instance the snapshot is rendered from.
+ *
+ * Polly issue #107 H5 (mesh-state module duplication). */
+export declare const MESH_STATE_MODULE_ID: string;
+/** Returns the per-module-instance id stamped at import time. See
+ * {@link MESH_STATE_MODULE_ID}. */
+export declare function getMeshStateModuleId(): string;
+/** Returns the `peerId` of the most recent Repo wired through
+ * {@link configureMeshState} against this module instance. Surfaced
+ * via the mesh client snapshot so a consumer can answer "did
+ * configureMeshState run on the same module instance the wrappers
+ * are using" in one read. */
+export declare function getLastConfiguredRepoPeerId(): string | undefined;
 /**
  * Set the default Repo that the $mesh* primitives use when no `repo` option
  * is supplied. Production code typically calls this once at application
@@ -68,6 +103,43 @@ export declare function configureMeshState(repo: Repo): void;
  * Intended for tests; production code should not call this.
  */
 export declare function resetMeshState(): void;
+/** Returns whether this module instance's `defaultRepo` was ever
+ * set via {@link configureMeshState}. Distinct from "was set and
+ * then reset" — `resetMeshState` clears it. The polly#107 H5
+ * fingerprint is `false` here on the module instance the consumer's
+ * `$meshState` calls resolve from. */
+export declare function isMeshStateConfigured(): boolean;
+/** Returns `true` once any `$meshState`-family wrapper has been
+ * 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;
 /**
  * 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.57.0",
+  "version": "0.59.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",