@50arms/ui 0.0.0-stage → 35.1.0

package/dist/lib/realtime/registry.js

@@ -0,0 +1,472 @@
+import { devWarn as m } from "../dev-warn.js";
+import { normalizeTypeName as y, recordKey as k } from "../records/wire.js";
+import { write as E } from "../records/store.js";
+const A = 6e4, S = 6e4, w = 1e3, M = 3e4, x = 6;
+let p = 0;
+const f = /* @__PURE__ */ new Set(), u = /* @__PURE__ */ new Set();
+function D() {
+  return p;
+}
+function N(i) {
+  return f.add(i), () => f.delete(i);
+}
+function K(i) {
+  return u.add(i), () => u.delete(i);
+}
+function F() {
+  p += 1;
+  for (const i of [...f]) i();
+}
+function $() {
+  p = 0, f.clear(), u.clear();
+}
+function g(i) {
+  return i === "all" ? { kind: "all" } : Array.isArray(i) ? { kind: "ids", ids: [...new Set(i.map((t) => String(t)))].sort() } : { kind: "filter", filter: i.filter };
+}
+function R(i) {
+  return i.kind === "all" ? "all" : i.kind === "ids" ? `ids:${i.ids.join(",")}` : `filter:${v(i.filter)}`;
+}
+function T(i, e) {
+  const t = C(e) ? e : g(e);
+  return `${y(i)}|${R(t)}`;
+}
+function C(i) {
+  return typeof i == "object" && i !== null && !Array.isArray(i) && "kind" in i;
+}
+function v(i) {
+  return i === null || typeof i != "object" ? JSON.stringify(i) ?? "null" : Array.isArray(i) ? `[${i.map(v).join(",")}]` : `{${Object.entries(i).sort(([t], [s]) => t < s ? -1 : t > s ? 1 : 0).map(([t, s]) => `${JSON.stringify(t)}:${v(s)}`).join(",")}}`;
+}
+class B {
+  transport;
+  entries = /* @__PURE__ */ new Map();
+  channels = /* @__PURE__ */ new Map();
+  options;
+  healthListeners = /* @__PURE__ */ new Set();
+  tenant;
+  connection;
+  stopConnectionObserver = null;
+  timer = null;
+  healthSnapshot = null;
+  lastError;
+  started = !1;
+  disposed = !1;
+  constructor(e) {
+    this.transport = e.transport, this.tenant = e.tenant, this.options = {
+      keepaliveIntervalMs: e.keepaliveIntervalMs ?? A,
+      expiryMarginMs: e.expiryMarginMs ?? S,
+      baseBackoffMs: e.baseBackoffMs ?? w,
+      maxBackoffMs: e.maxBackoffMs ?? M,
+      maxAttempts: e.maxAttempts ?? x,
+      createdEventName: e.createdEventName ?? "created",
+      now: e.now ?? Date.now,
+      isSelfEvent: e.isSelfEvent,
+      onDiagnostic: e.onDiagnostic
+    }, this.connection = c(() => this.transport.connectionState(), "connecting");
+  }
+  /* --- Lifecycle ----------------------------------------------------------- */
+  /**
+   * Begin observing the connection and renewing leases.
+   *
+   * THE TIMER STARTS HERE, NEVER ON IMPORT. A design-system module that starts
+   * an interval because somebody imported it is a worse defect than the leak it
+   * would be preventing: it runs in every consumer, including the ones that
+   * never touch realtime at all.
+   */
+  start() {
+    this.started || (this.started = !0, this.disposed = !1, this.stopConnectionObserver = c(
+      () => this.transport.observeConnection((e) => this.onConnectionState(e)),
+      () => {
+      }
+    ), this.timer = setInterval(() => this.tick(), this.options.keepaliveIntervalMs), typeof document < "u" && document.addEventListener("visibilitychange", this.handleVisibilityChange), typeof window < "u" && window.addEventListener("pageshow", this.handlePageShow));
+  }
+  /**
+   * The document became visible again, or the page was restored from the
+   * back/forward cache — either way, a gap of UNKNOWN length just ended.
+   *
+   * `pusher:subscription_succeeded`/`state_change` (what `onConnectionState`
+   * listens for) is the transport TELLING us the socket dropped and came
+   * back. It is not the only way a gap happens: the OS suspending the
+   * machine, or the browser freezing a backgrounded tab under memory
+   * pressure, pauses this process's OWN timers along with everything else —
+   * including whatever ping/pong loop the transport uses to notice its own
+   * connection died. A transport that never got to run its detection code
+   * has nothing to report, so `connectionState()` can read "connected"
+   * throughout a gap the socket did not actually survive, and `tick()`'s own
+   * `isDead()` check — which trusts that string — has nothing to catch.
+   *
+   * Pusher has no event replay. Broadcasting is also gated server-side on a
+   * short-TTL registration (`PusherSubscriptionService`, 300s) that a long
+   * enough gap can outlive on its own. Either way, "did we actually miss
+   * anything" has no answer worth computing — the same reasoning
+   * `onConnectionState`'s reconnect branch already acts on — so becoming
+   * visible again is treated exactly like a reconnect: every entry is
+   * resubscribed (which the SubscriptionRegistry itself dedupes against
+   * one that is still genuinely healthy — a resubscribe is bounded, cheap,
+   * and correctness-preserving even when it turns out to have been
+   * unnecessary), and the epoch bumps on each success, which is what
+   * drives every mounted read (`reads/refetch.ts`'s `onEpoch`) to reissue
+   * the request it already made.
+   */
+  onResume() {
+    if (!this.disposed) {
+      for (const e of this.entries.values())
+        e.subscribers !== 0 && (this.clearRetry(e), e.attempts = 0, this.subscribeEntry(e, !0));
+      this.notifyHealth();
+    }
+  }
+  handleVisibilityChange = () => {
+    typeof document < "u" && document.visibilityState === "visible" && this.onResume();
+  };
+  /** `event.persisted` is a bfcache restore — a full page resume with no `visibilitychange` of its own. */
+  handlePageShow = (e) => {
+    e.persisted && this.onResume();
+  };
+  /**
+   * Stop the timers. REVERSIBLE, and it keeps every entry and every channel.
+   *
+   * THIS IS WHAT STRICTMODE REQUIRES. React mounts every effect, unmounts it,
+   * and mounts it again in development — so a teardown that dropped the entries
+   * would make the remount issue a SECOND subscribe for a registration that is
+   * still perfectly live, and the whole misbehaviour would exist only in
+   * development, which is the worst place for a realtime bug to live because it
+   * is where the thing is being debugged.
+   *
+   * IT DOES NOT UNSUBSCRIBE, and it does not leave the socket channels. Unmount
+   * never touches the server-side registry — the entry lapses against its own
+   * TTL — and the socket belongs to the application that injected it. A tenant
+   * switch is the one place either of those happens, and it has its own method.
+   */
+  stop() {
+    this.started = !1, this.timer !== null && (clearInterval(this.timer), this.timer = null), this.stopConnectionObserver?.(), this.stopConnectionObserver = null, typeof document < "u" && document.removeEventListener("visibilitychange", this.handleVisibilityChange), typeof window < "u" && window.removeEventListener("pageshow", this.handlePageShow);
+    for (const e of this.entries.values()) this.clearRetry(e);
+  }
+  /**
+   * Full teardown: stop, leave every channel, forget every entry.
+   *
+   * NOT what a component unmount calls — see `stop`. This exists for an
+   * application deliberately switching realtime off, which is a decision no
+   * lifecycle can infer.
+   */
+  dispose() {
+    this.stop(), this.disposed = !0, this.leaveAllChannels(), this.entries.clear(), this.healthSnapshot = null, this.notifyHealth();
+  }
+  /**
+   * Switch tenants: tear the server-side registrations down, clear the socket,
+   * and re-establish everything still mounted under the new tenant.
+   *
+   * THIS IS THE ONE PLACE `unsubscribe` IS CALLED. Never-unsubscribe applies to
+   * UNMOUNT, where tearing down can kill another tab's subscription; a
+   * subscription left lapsing on the PREVIOUS tenant's channel is a leak of a
+   * different kind, and one this library can close on its own.
+   */
+  setTenant(e) {
+    if (e !== this.tenant) {
+      for (const t of this.entries.values())
+        this.clearRetry(t), t.everRegistered && this.callTransport(
+          () => this.transport.unsubscribe(this.requestFor(t, this.tenant)),
+          "unsubscribed",
+          t
+        ), t.registered = !1, t.everRegistered = !1, t.expiresAt = void 0, t.serverKeys = [], t.keepaliveFailed = !1, t.attempts = 0, t.lastError = void 0;
+      this.leaveAllChannels(), this.tenant = e;
+      for (const t of this.entries.values()) {
+        if (t.subscribers === 0) {
+          this.entries.delete(t.key);
+          continue;
+        }
+        this.ensureChannel(t.type, t.events), this.subscribeEntry(t, !1);
+      }
+      this.notifyHealth();
+    }
+  }
+  getTenant() {
+    return this.tenant;
+  }
+  /* --- Acquire / release --------------------------------------------------- */
+  /**
+   * Declare interest in a (type, scope) with a set of event names.
+   *
+   * THE RETURNED RELEASE IS IDEMPOTENT AND EXACTLY PAIRED, which is what makes
+   * StrictMode's mount / unmount / mount leave exactly ONE subscription: the
+   * refcount goes 1, 0, 1 while the server-side registration is never dropped,
+   * so the remount reuses the live lease instead of issuing a second subscribe.
+   */
+  acquire(e, t, s) {
+    const n = y(e), r = g(t), o = T(n, r);
+    let a = this.entries.get(o);
+    a || (a = {
+      key: o,
+      type: n,
+      scope: r,
+      events: /* @__PURE__ */ new Set(),
+      subscribers: 0,
+      expiresAt: void 0,
+      keepaliveFailed: !1,
+      registered: !1,
+      inFlight: !1,
+      attempts: 0,
+      retry: null,
+      lastError: void 0,
+      everRegistered: !1,
+      serverKeys: []
+    }, this.entries.set(o, a)), a.subscribers += 1;
+    let l = !1;
+    for (const h of s)
+      a.events.has(h) || (a.events.add(h), l = !0);
+    this.ensureChannel(n, a.events), l && this.notifyHealth(), !a.registered && !a.inFlight ? this.subscribeEntry(a, !1) : this.notifyHealth();
+    let b = !1;
+    return () => {
+      if (b) return;
+      b = !0;
+      const h = this.entries.get(o);
+      h && (h.subscribers = Math.max(0, h.subscribers - 1), this.notifyHealth());
+    };
+  }
+  /* --- Subscribing --------------------------------------------------------- */
+  async subscribeEntry(e, t) {
+    if (!(this.disposed || e.inFlight)) {
+      e.inFlight = !0, this.notifyHealth();
+      try {
+        const s = await this.transport.subscribe(this.requestFor(e, this.tenant));
+        if (this.disposed) return;
+        e.registered = !0, e.everRegistered = !0, e.keepaliveFailed = !1, e.expiresAt = s?.expiresAt, e.serverKeys = s?.keys ?? [], e.attempts = 0, e.lastError = void 0, this.diagnose({ kind: t ? "resubscribed" : "subscribed", key: e.key, type: e.type }), t && F();
+      } catch (s) {
+        if (this.disposed) return;
+        e.registered = !1, e.attempts += 1, e.lastError = d(s), this.lastError = e.lastError, this.diagnose({
+          kind: "subscribe-failed",
+          key: e.key,
+          type: e.type,
+          message: e.lastError
+        }), this.scheduleRetry(e);
+      } finally {
+        e.inFlight = !1, this.notifyHealth();
+      }
+    }
+  }
+  /**
+   * Bounded exponential backoff, then a terminal DEAD state.
+   *
+   * NOTHING IS ESCALATED, EVER. The failure that motivates this is a 401 on a
+   * background resubscribe: routed through an app's ordinary HTTP error path it
+   * clears the session and logs somebody out mid-screen. Here it is a number in
+   * `attempts`, a string in `lastError`, and a status a screen can print.
+   */
+  scheduleRetry(e) {
+    if (this.clearRetry(e), e.attempts >= this.options.maxAttempts) {
+      m(
+        "realtime",
+        `${e.key} stayed dead after ${e.attempts} attempts — it is rendered as dead rather than retried forever.`
+      );
+      return;
+    }
+    const t = Math.min(this.options.baseBackoffMs * 2 ** (e.attempts - 1), this.options.maxBackoffMs);
+    e.retry = setTimeout(() => {
+      e.retry = null, e.subscribers !== 0 && this.subscribeEntry(e, !0);
+    }, t);
+  }
+  clearRetry(e) {
+    e.retry !== null && (clearTimeout(e.retry), e.retry = null);
+  }
+  /* --- Liveness ------------------------------------------------------------ */
+  /**
+   * Is this subscription failing to deliver?
+   *
+   * THREE INPUTS, ANY ONE SUFFICIENT, and the first is the one no reconnect
+   * hook can see: the lease simply runs out while everything else looks
+   * healthy.
+   */
+  isDead(e) {
+    return e.subscribers === 0 ? !1 : !!(this.connection !== "connected" || e.keepaliveFailed || !e.registered || e.expiresAt !== void 0 && this.options.now() > e.expiresAt - this.options.expiryMarginMs);
+  }
+  /**
+   * One pass: renew what is live, revive what is dead.
+   *
+   * Exposed so a consumer — or a test — can run it without waiting for the
+   * interval. Everything it does is idempotent.
+   */
+  tick() {
+    if (this.disposed) return;
+    const e = [...this.entries.values()].filter((s) => s.subscribers > 0);
+    if (e.length === 0) return;
+    const t = e.filter((s) => s.registered && !this.isDead(s));
+    t.length > 0 && this.keepalive(t);
+    for (const s of e)
+      this.isDead(s) && (s.inFlight || s.retry !== null || this.connection === "connected" && (s.expiresAt !== void 0 && this.options.now() > s.expiresAt - this.options.expiryMarginMs && this.diagnose({ kind: "expired", key: s.key, type: s.type }), this.subscribeEntry(s, !0)));
+    this.notifyHealth();
+  }
+  async keepalive(e) {
+    const t = e.map((s) => this.requestFor(s, this.tenant));
+    try {
+      const s = await this.transport.keepalive(t);
+      if (this.disposed) return;
+      e.forEach((n, r) => {
+        n.keepaliveFailed = !1;
+        const o = s?.[r];
+        o?.expiresAt !== void 0 && (n.expiresAt = o.expiresAt), o?.keys !== void 0 && (n.serverKeys = o.keys);
+      });
+    } catch (s) {
+      if (this.disposed) return;
+      const n = d(s);
+      for (const r of e)
+        r.keepaliveFailed = !0, r.lastError = n;
+      this.lastError = n, this.diagnose({ kind: "keepalive-failed", message: n });
+      for (const r of e)
+        this.connection === "connected" && !r.inFlight && r.retry === null && this.subscribeEntry(r, !0);
+    } finally {
+      this.notifyHealth();
+    }
+  }
+  onConnectionState(e) {
+    if (e !== this.connection) {
+      if (this.connection = e, e !== "connected") {
+        this.diagnose({ kind: "disconnected", message: e }), this.notifyHealth();
+        return;
+      }
+      this.onResume();
+    }
+  }
+  /* --- Channels and delivery ----------------------------------------------- */
+  ensureChannel(e, t) {
+    let s = this.channels.get(e);
+    if (!s) {
+      const n = c(() => this.transport.channel(e, this.tenant), null);
+      if (!n) return;
+      s = { channel: n, bound: /* @__PURE__ */ new Set(), tenant: this.tenant }, this.channels.set(e, s);
+    }
+    for (const n of t) {
+      if (s.bound.has(n)) continue;
+      s.bound.add(n);
+      const r = s.tenant;
+      s.channel.bind(n, (o) => this.deliver(e, n, o, r));
+    }
+  }
+  leaveAllChannels() {
+    for (const e of this.channels.values()) c(() => e.channel.leave(), void 0);
+    this.channels.clear();
+  }
+  /**
+   * One broadcast: filter, write, announce.
+   *
+   * THE TENANT IS THE ONE THE CHANNEL WAS JOINED UNDER, captured at bind time
+   * and never read at delivery time. Reading it on arrival reads the tenant as
+   * it is NOW, which is precisely how a payload from the team you just left
+   * lands in the store as the team you just joined.
+   */
+  deliver(e, t, s, n) {
+    if (this.options.isSelfEvent?.(s)) {
+      this.diagnose({ kind: "self-event-dropped", type: e, event: t });
+      return;
+    }
+    const r = E(s, { source: "broadcast", tenant: n }), o = r.verdict === "applied" || r.verdict === "unchanged" ? L(s) : void 0;
+    this.diagnose({ kind: "event", type: e, event: t, key: o, message: r.verdict });
+    const a = {
+      type: e,
+      event: t,
+      key: o,
+      payload: s,
+      tenant: n,
+      isCreate: t === this.options.createdEventName,
+      subscriptions: this.attribute(e, s)
+    };
+    for (const l of [...u]) l(a);
+  }
+  /**
+   * This client's subscriptions a broadcast satisfied, translated from the
+   * server's names through each entry's lease keys.
+   *
+   * THE WHOLE REASON THIS IS NEEDED: the channel is per type per tenant, so an
+   * event arrives here whenever ANY subscription on the tenant matched — a
+   * teammate's unfiltered list included. Arrival says "somebody on this team
+   * asked"; only this says "you asked". `undefined` when the transport cannot
+   * say, which is a different answer from `[]` ("it said, and none were yours").
+   */
+  attribute(e, t) {
+    const s = this.transport.subscriptionsOf;
+    if (!s) return;
+    const n = c(() => s.call(this.transport, t), void 0);
+    if (n === void 0) return;
+    const r = new Set(n), o = [];
+    for (const a of this.entries.values())
+      a.type === e && a.serverKeys.some((l) => r.has(l)) && o.push(a.key);
+    return o;
+  }
+  /** The event name that means "entered the set", for the read binding. */
+  get createdEventName() {
+    return this.options.createdEventName;
+  }
+  /* --- Health -------------------------------------------------------------- */
+  subscribeToHealth = (e) => (this.healthListeners.add(e), () => this.healthListeners.delete(e));
+  /**
+   * The renderable state, memoized so `getSnapshot` returns the identical
+   * object when nothing changed — the constraint every store in this package is
+   * written around.
+   */
+  readHealth = () => {
+    if (this.healthSnapshot) return this.healthSnapshot;
+    const e = [...this.entries.values()].filter((t) => t.subscribers > 0 || t.registered).map((t) => ({
+      key: t.key,
+      type: t.type,
+      scope: t.scope,
+      events: [...t.events].sort(),
+      subscribers: t.subscribers,
+      expiresAt: t.expiresAt,
+      dead: this.isDead(t),
+      attempts: t.attempts,
+      lastError: t.lastError
+    }));
+    return this.healthSnapshot = Object.freeze({
+      status: this.deriveStatus(e),
+      connection: this.connection,
+      subscriptions: Object.freeze(e),
+      epoch: p,
+      lastError: this.lastError
+    }), this.healthSnapshot;
+  };
+  deriveStatus(e) {
+    const t = e.filter((s) => s.subscribers > 0);
+    return t.length === 0 ? "idle" : t.some((s) => s.dead) ? t.some((n) => n.attempts > 0 || n.expiresAt !== void 0) || this.connection !== "connected" ? "dead" : "connecting" : "live";
+  }
+  notifyHealth() {
+    this.healthSnapshot = null;
+    for (const e of [...this.healthListeners]) e();
+  }
+  /* --- Small helpers ------------------------------------------------------- */
+  requestFor(e, t) {
+    return { type: e.type, scope: e.scope, tenant: t, key: e.key };
+  }
+  async callTransport(e, t, s) {
+    try {
+      await e(), this.diagnose({ kind: t, key: s.key, type: s.type });
+    } catch (n) {
+      this.diagnose({ kind: t, key: s.key, type: s.type, message: d(n) });
+    }
+  }
+  diagnose(e) {
+    this.options.onDiagnostic?.({ ...e, at: this.options.now() });
+  }
+}
+function L(i) {
+  const e = i.__type, t = i.id;
+  if (!(typeof e != "string" || e === "") && !(typeof t != "string" && typeof t != "number"))
+    return k(e, t);
+}
+function d(i) {
+  return i instanceof Error ? i.message : typeof i == "string" ? i : String(i);
+}
+function c(i, e) {
+  try {
+    return i();
+  } catch (t) {
+    return m("realtime", `the injected transport threw: ${d(t)}`), e;
+  }
+}
+export {
+  B as SubscriptionRegistry,
+  g as normalizeScope,
+  D as readRealtimeEpoch,
+  $ as resetRealtimeSignals,
+  R as scopeKey,
+  N as subscribeToRealtimeEpoch,
+  K as subscribeToRealtimeEvents,
+  T as subscriptionKey
+};
+//# sourceMappingURL=registry.js.map

package/dist/lib/realtime/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sources":["../../../src/lib/realtime/registry.ts"],"sourcesContent":["import { devWarn } from \"../dev-warn\";\nimport { normalizeTypeName, recordKey, write } from \"../records\";\nimport type {\n  RealtimeChannel,\n  RealtimeConnectionState,\n  RealtimeDiagnostic,\n  RealtimeEvent,\n  RealtimeHealth,\n  RealtimeScope,\n  RealtimeScopeInput,\n  RealtimeStatus,\n  RealtimeTransport,\n  SubscriptionHealth,\n  SubscriptionRequest,\n} from \"./types\";\nimport type { RecordPayload } from \"../records\";\n\n/* ============================================================================\n   THE SUBSCRIPTION REGISTRY.\n\n   THE FAILURE THIS IS BUILT AROUND, stated once so every rule below has a\n   reason attached: broadcasting is gated SERVER-SIDE on a registry entry with a\n   short TTL. When that entry lapses, the broadcast job is never enqueued, while\n   the socket stays connected, stays subscribed, and receives nothing. The\n   connection state never changes. There is no disconnect event to hang a\n   refetch off, because there is no disconnect.\n\n   So a subscription is a THIRD STATE — dead, not quiet — and it is computed\n   from three inputs, any one of which is sufficient:\n\n     1. the clock has passed the lease's `expires_at` minus a margin;\n     2. the last keepalive failed;\n     3. the connection is not connected.\n\n   Dead means RESUBSCRIBE, then REFETCH, automatically. Never \"let it expire\n   naturally\" — that is the prior art's own comment and its own bug.\n\n   FOUR MORE RULES, each preventing a specific observed defect:\n\n   THE UNION OF EVENT NAMES IS BOUND, and bound AGAIN when a later subscriber\n   brings a new one. The prior art returns before its bind call when the channel\n   already exists, so the second of two real subscribers is silently dead in\n   production right now. This is the only rule in this module written against a\n   bug that was SEEN rather than reasoned about.\n\n   SUBSCRIBERS ARE COALESCED BY REFCOUNT, and release is idempotent and exactly\n   paired with acquire. The prior art dedupes by key with no count at all, so\n   the FIRST unmount tears the subscription down for every other consumer.\n\n   UNSUBSCRIBE IS NEVER CALLED ON UNMOUNT. The server keys its entry by user, so\n   two tabs are one entry and one tab's teardown kills the other's. It IS called\n   on a tenant switch, where a lapsing subscription to the previous tenant's\n   channel is the leak.\n\n   A FAILED RESUBSCRIBE IS HANDLED HERE AND NOWHERE ELSE. Bounded backoff, a\n   cap, and a terminal DEAD state that is rendered. It is never escalated —\n   escalating a background 401 into an app's session handler logs somebody out\n   mid-screen, which is strictly worse than the staleness the resubscribe was\n   fixing.\n   ========================================================================= */\n\nconst DEFAULT_KEEPALIVE_INTERVAL_MS = 60_000;\n/**\n * How long before a lease's expiry a subscription is already considered dead.\n *\n * Generous on purpose. The alternative — resubscribing at the last moment —\n * makes correctness depend on one request winning a race against a TTL, and the\n * cost of being early is one extra HTTP call.\n */\nconst DEFAULT_EXPIRY_MARGIN_MS = 60_000;\nconst DEFAULT_BASE_BACKOFF_MS = 1_000;\nconst DEFAULT_MAX_BACKOFF_MS = 30_000;\n/** Attempts before a subscription stays dead until something else wakes it. */\nconst DEFAULT_MAX_ATTEMPTS = 6;\n\nexport interface RegistryOptions {\n  readonly transport: RealtimeTransport;\n  readonly tenant?: string | number;\n  readonly keepaliveIntervalMs?: number;\n  readonly expiryMarginMs?: number;\n  readonly baseBackoffMs?: number;\n  readonly maxBackoffMs?: number;\n  readonly maxAttempts?: number;\n  /**\n   * The event name that means \"this record just entered the set\".\n   *\n   * Configurable because the name is the backend's, not this library's, and\n   * hard-coding one would be the only domain fact in this module.\n   */\n  readonly createdEventName?: string;\n  /**\n   * Drop a broadcast this client caused.\n   *\n   * A PREDICATE RATHER THAN A FIELD NAME, because the field that says who\n   * caused a change belongs to a wire format, not to a design system. Supplied\n   * by the app or absent; absent means every broadcast is written.\n   *\n   * IT APPLIES TO BROADCASTS ONLY, structurally — a fetch and a mutation's\n   * returned item never pass through here at all. That matters: a mutation\n   * response is self-caused BY DEFINITION, and dropping it would discard the\n   * server-computed fields the client asked for.\n   */\n  readonly isSelfEvent?: (payload: RecordPayload) => boolean;\n  readonly onDiagnostic?: (diagnostic: RealtimeDiagnostic) => void;\n  /** Test seam. Defaults to `Date.now`. */\n  readonly now?: () => number;\n}\n\ninterface Entry {\n  readonly key: string;\n  readonly type: string;\n  readonly scope: RealtimeScope;\n  /** Bound event names contributed by every subscriber of this entry. */\n  readonly events: Set<string>;\n  subscribers: number;\n  expiresAt: number | undefined;\n  keepaliveFailed: boolean;\n  /** True once a subscribe has succeeded and the lease is still good. */\n  registered: boolean;\n  inFlight: boolean;\n  attempts: number;\n  retry: ReturnType<typeof setTimeout> | null;\n  lastError: string | undefined;\n  /** Set once this entry has been registered at least once under this tenant. */\n  everRegistered: boolean;\n  /**\n   * The server's names for this registration, from the last successful\n   * subscribe (`SubscriptionLease.keys`). What a broadcast's attribution is\n   * matched against; empty until registered, and after a tenant switch.\n   */\n  serverKeys: readonly string[];\n}\n\ninterface ChannelEntry {\n  readonly channel: RealtimeChannel;\n  /** Event names already bound on THIS channel object. */\n  readonly bound: Set<string>;\n  readonly tenant: string | number | undefined;\n}\n\n/* --- Module-level signals -------------------------------------------------- */\n\n/**\n * The epoch and the event stream are MODULE-LEVEL, not context.\n *\n * The read binding consumes both and must work with no provider mounted at all\n * — an application with realtime switched off still fetches, still renders, and\n * must never crash because an optional capability is absent. A design system\n * that hard-fails when an optional capability is missing is not optional. So\n * these are plain pub/subs that simply never fire when nothing is publishing.\n */\nlet epoch = 0;\nconst epochListeners = new Set<() => void>();\nconst eventListeners = new Set<(event: RealtimeEvent) => void>();\n\nexport function readRealtimeEpoch(): number {\n  return epoch;\n}\n\nexport function subscribeToRealtimeEpoch(listener: () => void): () => void {\n  epochListeners.add(listener);\n  return () => epochListeners.delete(listener);\n}\n\n/** Every broadcast, AFTER it has been written to the store. */\nexport function subscribeToRealtimeEvents(listener: (event: RealtimeEvent) => void): () => void {\n  eventListeners.add(listener);\n  return () => eventListeners.delete(listener);\n}\n\nfunction bumpEpoch(): void {\n  epoch += 1;\n  for (const listener of [...epochListeners]) listener();\n}\n\n/** Test seam. Nothing in the library calls this. */\nexport function resetRealtimeSignals(): void {\n  epoch = 0;\n  epochListeners.clear();\n  eventListeners.clear();\n}\n\n/* --- Scope ----------------------------------------------------------------- */\n\n/**\n * Normalize a caller's scope and give it a stable key.\n *\n * IDS ARE SORTED AND STRINGIFIED so two components asking for the same rows in\n * a different order coalesce onto one subscription rather than opening two —\n * and so a numeric id and its string form never split an entry, exactly as the\n * store keys records.\n */\nexport function normalizeScope(input: RealtimeScopeInput): RealtimeScope {\n  if (input === \"all\") return { kind: \"all\" };\n  if (Array.isArray(input)) {\n    const ids = [...new Set(input.map((id) => String(id)))].sort();\n    return { kind: \"ids\", ids };\n  }\n  return { kind: \"filter\", filter: (input as { filter: Record<string, unknown> }).filter };\n}\n\nexport function scopeKey(scope: RealtimeScope): string {\n  if (scope.kind === \"all\") return \"all\";\n  if (scope.kind === \"ids\") return `ids:${scope.ids.join(\",\")}`;\n  return `filter:${stableStringify(scope.filter)}`;\n}\n\n/**\n * The registry's key for a (type, scope) subscription — the identity\n * `RealtimeEvent.subscriptions` names.\n *\n * ONE FUNCTION FOR BOTH SIDES. The registry keys its entries with it and a list\n * slot keys its declared `createdScope` with it, so the two cannot disagree\n * about what \"the same subscription\" means — a type spelled `WorkflowInput`\n * here and `WorkflowInputResource` there would silently never match.\n */\nexport function subscriptionKey(type: string, scope: RealtimeScopeInput | RealtimeScope): string {\n  const normalized = isNormalizedScope(scope) ? scope : normalizeScope(scope);\n  return `${normalizeTypeName(type)}|${scopeKey(normalized)}`;\n}\n\nfunction isNormalizedScope(scope: RealtimeScopeInput | RealtimeScope): scope is RealtimeScope {\n  return typeof scope === \"object\" && scope !== null && !Array.isArray(scope) && \"kind\" in scope;\n}\n\n/** Key order must not decide identity — two equal filters are one subscription. */\nfunction stableStringify(value: unknown): string {\n  if (value === null || typeof value !== \"object\") return JSON.stringify(value) ?? \"null\";\n  if (Array.isArray(value)) return `[${value.map(stableStringify).join(\",\")}]`;\n  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n  return `{${entries.map(([key, nested]) => `${JSON.stringify(key)}:${stableStringify(nested)}`).join(\",\")}}`;\n}\n\n/* --- The registry ---------------------------------------------------------- */\n\nexport class SubscriptionRegistry {\n  private readonly transport: RealtimeTransport;\n  private readonly entries = new Map<string, Entry>();\n  private readonly channels = new Map<string, ChannelEntry>();\n  private readonly options: Required<Omit<RegistryOptions, \"transport\" | \"tenant\" | \"isSelfEvent\" | \"onDiagnostic\">> &\n    Pick<RegistryOptions, \"isSelfEvent\" | \"onDiagnostic\">;\n  private readonly healthListeners = new Set<() => void>();\n\n  private tenant: string | number | undefined;\n  private connection: RealtimeConnectionState;\n  private stopConnectionObserver: (() => void) | null = null;\n  private timer: ReturnType<typeof setInterval> | null = null;\n  private healthSnapshot: RealtimeHealth | null = null;\n  private lastError: string | undefined;\n  private started = false;\n  private disposed = false;\n\n  constructor(options: RegistryOptions) {\n    this.transport = options.transport;\n    this.tenant = options.tenant;\n    this.options = {\n      keepaliveIntervalMs: options.keepaliveIntervalMs ?? DEFAULT_KEEPALIVE_INTERVAL_MS,\n      expiryMarginMs: options.expiryMarginMs ?? DEFAULT_EXPIRY_MARGIN_MS,\n      baseBackoffMs: options.baseBackoffMs ?? DEFAULT_BASE_BACKOFF_MS,\n      maxBackoffMs: options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS,\n      maxAttempts: options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,\n      createdEventName: options.createdEventName ?? \"created\",\n      now: options.now ?? Date.now,\n      isSelfEvent: options.isSelfEvent,\n      onDiagnostic: options.onDiagnostic,\n    };\n    this.connection = safely(() => this.transport.connectionState(), \"connecting\");\n  }\n\n  /* --- Lifecycle ----------------------------------------------------------- */\n\n  /**\n   * Begin observing the connection and renewing leases.\n   *\n   * THE TIMER STARTS HERE, NEVER ON IMPORT. A design-system module that starts\n   * an interval because somebody imported it is a worse defect than the leak it\n   * would be preventing: it runs in every consumer, including the ones that\n   * never touch realtime at all.\n   */\n  start(): void {\n    if (this.started) return;\n    this.started = true;\n    this.disposed = false;\n\n    this.stopConnectionObserver = safely(\n      () => this.transport.observeConnection((state) => this.onConnectionState(state)),\n      () => {},\n    );\n    this.timer = setInterval(() => this.tick(), this.options.keepaliveIntervalMs);\n\n    /* THE SECOND, INDEPENDENT WAY A GAP OF UNKNOWN LENGTH BEGINS AND ENDS —\n       see `onResume`'s own docblock for why a Pusher connection-state change\n       is not a sufficient trigger on its own. Guarded for non-browser\n       environments (SSR, this library's own non-DOM tests): a design system\n       that throws when `document`/`window` are absent is not usable there. */\n    if (typeof document !== \"undefined\") {\n      document.addEventListener(\"visibilitychange\", this.handleVisibilityChange);\n    }\n    if (typeof window !== \"undefined\") {\n      window.addEventListener(\"pageshow\", this.handlePageShow);\n    }\n  }\n\n  /**\n   * The document became visible again, or the page was restored from the\n   * back/forward cache — either way, a gap of UNKNOWN length just ended.\n   *\n   * `pusher:subscription_succeeded`/`state_change` (what `onConnectionState`\n   * listens for) is the transport TELLING us the socket dropped and came\n   * back. It is not the only way a gap happens: the OS suspending the\n   * machine, or the browser freezing a backgrounded tab under memory\n   * pressure, pauses this process's OWN timers along with everything else —\n   * including whatever ping/pong loop the transport uses to notice its own\n   * connection died. A transport that never got to run its detection code\n   * has nothing to report, so `connectionState()` can read \"connected\"\n   * throughout a gap the socket did not actually survive, and `tick()`'s own\n   * `isDead()` check — which trusts that string — has nothing to catch.\n   *\n   * Pusher has no event replay. Broadcasting is also gated server-side on a\n   * short-TTL registration (`PusherSubscriptionService`, 300s) that a long\n   * enough gap can outlive on its own. Either way, \"did we actually miss\n   * anything\" has no answer worth computing — the same reasoning\n   * `onConnectionState`'s reconnect branch already acts on — so becoming\n   * visible again is treated exactly like a reconnect: every entry is\n   * resubscribed (which the SubscriptionRegistry itself dedupes against\n   * one that is still genuinely healthy — a resubscribe is bounded, cheap,\n   * and correctness-preserving even when it turns out to have been\n   * unnecessary), and the epoch bumps on each success, which is what\n   * drives every mounted read (`reads/refetch.ts`'s `onEpoch`) to reissue\n   * the request it already made.\n   */\n  private onResume(): void {\n    if (this.disposed) return;\n    for (const entry of this.entries.values()) {\n      if (entry.subscribers === 0) continue;\n      this.clearRetry(entry);\n      entry.attempts = 0;\n      void this.subscribeEntry(entry, true);\n    }\n    this.notifyHealth();\n  }\n\n  private handleVisibilityChange = (): void => {\n    if (typeof document !== \"undefined\" && document.visibilityState === \"visible\") this.onResume();\n  };\n\n  /** `event.persisted` is a bfcache restore — a full page resume with no `visibilitychange` of its own. */\n  private handlePageShow = (event: PageTransitionEvent): void => {\n    if (event.persisted) this.onResume();\n  };\n\n  /**\n   * Stop the timers. REVERSIBLE, and it keeps every entry and every channel.\n   *\n   * THIS IS WHAT STRICTMODE REQUIRES. React mounts every effect, unmounts it,\n   * and mounts it again in development — so a teardown that dropped the entries\n   * would make the remount issue a SECOND subscribe for a registration that is\n   * still perfectly live, and the whole misbehaviour would exist only in\n   * development, which is the worst place for a realtime bug to live because it\n   * is where the thing is being debugged.\n   *\n   * IT DOES NOT UNSUBSCRIBE, and it does not leave the socket channels. Unmount\n   * never touches the server-side registry — the entry lapses against its own\n   * TTL — and the socket belongs to the application that injected it. A tenant\n   * switch is the one place either of those happens, and it has its own method.\n   */\n  stop(): void {\n    this.started = false;\n    if (this.timer !== null) {\n      clearInterval(this.timer);\n      this.timer = null;\n    }\n    this.stopConnectionObserver?.();\n    this.stopConnectionObserver = null;\n    if (typeof document !== \"undefined\") {\n      document.removeEventListener(\"visibilitychange\", this.handleVisibilityChange);\n    }\n    if (typeof window !== \"undefined\") {\n      window.removeEventListener(\"pageshow\", this.handlePageShow);\n    }\n    for (const entry of this.entries.values()) this.clearRetry(entry);\n  }\n\n  /**\n   * Full teardown: stop, leave every channel, forget every entry.\n   *\n   * NOT what a component unmount calls — see `stop`. This exists for an\n   * application deliberately switching realtime off, which is a decision no\n   * lifecycle can infer.\n   */\n  dispose(): void {\n    this.stop();\n    this.disposed = true;\n    this.leaveAllChannels();\n    this.entries.clear();\n    this.healthSnapshot = null;\n    this.notifyHealth();\n  }\n\n\n  /**\n   * Switch tenants: tear the server-side registrations down, clear the socket,\n   * and re-establish everything still mounted under the new tenant.\n   *\n   * THIS IS THE ONE PLACE `unsubscribe` IS CALLED. Never-unsubscribe applies to\n   * UNMOUNT, where tearing down can kill another tab's subscription; a\n   * subscription left lapsing on the PREVIOUS tenant's channel is a leak of a\n   * different kind, and one this library can close on its own.\n   */\n  setTenant(tenant: string | number | undefined): void {\n    if (tenant === this.tenant) return;\n\n    for (const entry of this.entries.values()) {\n      this.clearRetry(entry);\n      if (entry.everRegistered) {\n        void this.callTransport(\n          () => this.transport.unsubscribe(this.requestFor(entry, this.tenant)),\n          \"unsubscribed\",\n          entry,\n        );\n      }\n      entry.registered = false;\n      entry.everRegistered = false;\n      entry.expiresAt = undefined;\n      entry.serverKeys = [];\n      entry.keepaliveFailed = false;\n      entry.attempts = 0;\n      entry.lastError = undefined;\n    }\n\n    this.leaveAllChannels();\n    this.tenant = tenant;\n\n    /* Re-bind and re-subscribe only what is still MOUNTED. An entry whose\n       subscribers have gone belongs to the tenant that just left. */\n    for (const entry of this.entries.values()) {\n      if (entry.subscribers === 0) {\n        this.entries.delete(entry.key);\n        continue;\n      }\n      this.ensureChannel(entry.type, entry.events);\n      void this.subscribeEntry(entry, false);\n    }\n\n    this.notifyHealth();\n  }\n\n  getTenant(): string | number | undefined {\n    return this.tenant;\n  }\n\n  /* --- Acquire / release --------------------------------------------------- */\n\n  /**\n   * Declare interest in a (type, scope) with a set of event names.\n   *\n   * THE RETURNED RELEASE IS IDEMPOTENT AND EXACTLY PAIRED, which is what makes\n   * StrictMode's mount / unmount / mount leave exactly ONE subscription: the\n   * refcount goes 1, 0, 1 while the server-side registration is never dropped,\n   * so the remount reuses the live lease instead of issuing a second subscribe.\n   */\n  acquire(type: string, scopeInput: RealtimeScopeInput, events: readonly string[]): () => void {\n    const normalizedType = normalizeTypeName(type);\n    const scope = normalizeScope(scopeInput);\n    const key = subscriptionKey(normalizedType, scope);\n\n    let entry = this.entries.get(key);\n    if (!entry) {\n      entry = {\n        key,\n        type: normalizedType,\n        scope,\n        events: new Set(),\n        subscribers: 0,\n        expiresAt: undefined,\n        keepaliveFailed: false,\n        registered: false,\n        inFlight: false,\n        attempts: 0,\n        retry: null,\n        lastError: undefined,\n        everRegistered: false,\n        serverKeys: [],\n      };\n      this.entries.set(key, entry);\n    }\n\n    entry.subscribers += 1;\n    let broughtNewEvents = false;\n    for (const event of events) {\n      if (!entry.events.has(event)) {\n        entry.events.add(event);\n        broughtNewEvents = true;\n      }\n    }\n\n    /* THE UNION, BOUND EVERY TIME. `ensureChannel` binds only the names not yet\n       bound on this channel object, so a later subscriber's events reach the\n       same channel the first subscriber joined. Returning early here — the\n       prior art's shape — is what leaves one of two live subscribers dead. */\n    this.ensureChannel(normalizedType, entry.events);\n    if (broughtNewEvents) this.notifyHealth();\n\n    if (!entry.registered && !entry.inFlight) void this.subscribeEntry(entry, false);\n    else this.notifyHealth();\n\n    let released = false;\n    return () => {\n      if (released) return;\n      released = true;\n      const current = this.entries.get(key);\n      if (!current) return;\n      current.subscribers = Math.max(0, current.subscribers - 1);\n      /* NO unsubscribe, and no channel teardown. The entry stays so a remount\n         within the lease reuses it. */\n      this.notifyHealth();\n    };\n  }\n\n  /* --- Subscribing --------------------------------------------------------- */\n\n  private async subscribeEntry(entry: Entry, isResubscribe: boolean): Promise<void> {\n    if (this.disposed || entry.inFlight) return;\n    entry.inFlight = true;\n    this.notifyHealth();\n\n    try {\n      const lease = await this.transport.subscribe(this.requestFor(entry, this.tenant));\n      if (this.disposed) return;\n      entry.registered = true;\n      entry.everRegistered = true;\n      entry.keepaliveFailed = false;\n      entry.expiresAt = lease?.expiresAt;\n      entry.serverKeys = lease?.keys ?? [];\n      entry.attempts = 0;\n      entry.lastError = undefined;\n      this.diagnose({ kind: isResubscribe ? \"resubscribed\" : \"subscribed\", key: entry.key, type: entry.type });\n\n      /* THE REFETCH HALF OF \"dead means resubscribe THEN refetch\". A first\n         subscribe bumps nothing — the reader is about to fetch anyway — but a\n         RE-subscribe means events were missed during a window nobody can\n         enumerate, so the only honest signal is \"something may be gone\". */\n      if (isResubscribe) bumpEpoch();\n    } catch (error) {\n      if (this.disposed) return;\n      entry.registered = false;\n      entry.attempts += 1;\n      entry.lastError = messageOf(error);\n      this.lastError = entry.lastError;\n      this.diagnose({\n        kind: \"subscribe-failed\",\n        key: entry.key,\n        type: entry.type,\n        message: entry.lastError,\n      });\n      this.scheduleRetry(entry);\n    } finally {\n      entry.inFlight = false;\n      this.notifyHealth();\n    }\n  }\n\n  /**\n   * Bounded exponential backoff, then a terminal DEAD state.\n   *\n   * NOTHING IS ESCALATED, EVER. The failure that motivates this is a 401 on a\n   * background resubscribe: routed through an app's ordinary HTTP error path it\n   * clears the session and logs somebody out mid-screen. Here it is a number in\n   * `attempts`, a string in `lastError`, and a status a screen can print.\n   */\n  private scheduleRetry(entry: Entry): void {\n    this.clearRetry(entry);\n    if (entry.attempts >= this.options.maxAttempts) {\n      devWarn(\n        \"realtime\",\n        `${entry.key} stayed dead after ${entry.attempts} attempts — it is rendered as dead rather than retried forever.`,\n      );\n      return;\n    }\n    const delay = Math.min(this.options.baseBackoffMs * 2 ** (entry.attempts - 1), this.options.maxBackoffMs);\n    entry.retry = setTimeout(() => {\n      entry.retry = null;\n      if (entry.subscribers === 0) return;\n      void this.subscribeEntry(entry, true);\n    }, delay);\n  }\n\n  private clearRetry(entry: Entry): void {\n    if (entry.retry !== null) {\n      clearTimeout(entry.retry);\n      entry.retry = null;\n    }\n  }\n\n  /* --- Liveness ------------------------------------------------------------ */\n\n  /**\n   * Is this subscription failing to deliver?\n   *\n   * THREE INPUTS, ANY ONE SUFFICIENT, and the first is the one no reconnect\n   * hook can see: the lease simply runs out while everything else looks\n   * healthy.\n   */\n  private isDead(entry: Entry): boolean {\n    if (entry.subscribers === 0) return false;\n    if (this.connection !== \"connected\") return true;\n    if (entry.keepaliveFailed) return true;\n    if (!entry.registered) return true;\n    if (entry.expiresAt !== undefined && this.options.now() > entry.expiresAt - this.options.expiryMarginMs) {\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * One pass: renew what is live, revive what is dead.\n   *\n   * Exposed so a consumer — or a test — can run it without waiting for the\n   * interval. Everything it does is idempotent.\n   */\n  tick(): void {\n    if (this.disposed) return;\n    const active = [...this.entries.values()].filter((entry) => entry.subscribers > 0);\n    if (active.length === 0) return;\n\n    const renewable = active.filter((entry) => entry.registered && !this.isDead(entry));\n    if (renewable.length > 0) void this.keepalive(renewable);\n\n    for (const entry of active) {\n      if (!this.isDead(entry)) continue;\n      if (entry.inFlight || entry.retry !== null) continue;\n      if (this.connection !== \"connected\") continue;\n      if (entry.expiresAt !== undefined && this.options.now() > entry.expiresAt - this.options.expiryMarginMs) {\n        this.diagnose({ kind: \"expired\", key: entry.key, type: entry.type });\n      }\n      void this.subscribeEntry(entry, true);\n    }\n    this.notifyHealth();\n  }\n\n  private async keepalive(entries: readonly Entry[]): Promise<void> {\n    const requests = entries.map((entry) => this.requestFor(entry, this.tenant));\n    try {\n      const leases = await this.transport.keepalive(requests);\n      if (this.disposed) return;\n      entries.forEach((entry, index) => {\n        entry.keepaliveFailed = false;\n        const lease = leases?.[index];\n        if (lease?.expiresAt !== undefined) entry.expiresAt = lease.expiresAt;\n        if (lease?.keys !== undefined) entry.serverKeys = lease.keys;\n      });\n    } catch (error) {\n      if (this.disposed) return;\n      /* A FAILED KEEPALIVE IS A DEAD SUBSCRIPTION, NOT A WARNING. The prior art\n         deletes the subscription here and deliberately does not retry, with the\n         comment \"let subscriptions expire naturally\" — two failures inside one\n         TTL window and that resource stops updating forever. */\n      const message = messageOf(error);\n      for (const entry of entries) {\n        entry.keepaliveFailed = true;\n        entry.lastError = message;\n      }\n      this.lastError = message;\n      this.diagnose({ kind: \"keepalive-failed\", message });\n      for (const entry of entries) {\n        if (this.connection === \"connected\" && !entry.inFlight && entry.retry === null) {\n          void this.subscribeEntry(entry, true);\n        }\n      }\n    } finally {\n      this.notifyHealth();\n    }\n  }\n\n  private onConnectionState(state: RealtimeConnectionState): void {\n    if (state === this.connection) return;\n    this.connection = state;\n    if (state !== \"connected\") {\n      this.diagnose({ kind: \"disconnected\", message: state });\n      this.notifyHealth();\n      return;\n    }\n    /* Coming back is not enough on its own — the server-side entry may have\n       lapsed while the socket was away, and it reports nothing when it has. So\n       every active entry is re-registered rather than assumed — the same\n       \"gap of unknown length just ended\" handling `onResume` gives a tab\n       becoming visible again, below. */\n    this.onResume();\n  }\n\n  /* --- Channels and delivery ----------------------------------------------- */\n\n  private ensureChannel(type: string, events: ReadonlySet<string>): void {\n    let channelEntry = this.channels.get(type);\n    if (!channelEntry) {\n      const channel = safely(() => this.transport.channel(type, this.tenant), null);\n      if (!channel) return;\n      channelEntry = { channel, bound: new Set(), tenant: this.tenant };\n      this.channels.set(type, channelEntry);\n    }\n\n    for (const event of events) {\n      if (channelEntry.bound.has(event)) continue;\n      channelEntry.bound.add(event);\n      const tenantAtBind = channelEntry.tenant;\n      channelEntry.channel.bind(event, (payload) => this.deliver(type, event, payload, tenantAtBind));\n    }\n  }\n\n  private leaveAllChannels(): void {\n    for (const entry of this.channels.values()) safely(() => entry.channel.leave(), undefined);\n    this.channels.clear();\n  }\n\n  /**\n   * One broadcast: filter, write, announce.\n   *\n   * THE TENANT IS THE ONE THE CHANNEL WAS JOINED UNDER, captured at bind time\n   * and never read at delivery time. Reading it on arrival reads the tenant as\n   * it is NOW, which is precisely how a payload from the team you just left\n   * lands in the store as the team you just joined.\n   */\n  private deliver(type: string, event: string, payload: RecordPayload, tenant: string | number | undefined): void {\n    if (this.options.isSelfEvent?.(payload)) {\n      this.diagnose({ kind: \"self-event-dropped\", type, event });\n      return;\n    }\n\n    const result = write(payload, { source: \"broadcast\", tenant });\n    /* The key is derived from the payload rather than read out of the write's\n       touched set: a write refused for tenancy touches nothing, and a `created`\n       event whose record was refused must not reach a list slot either — so the\n       key is only announced when the write actually landed. */\n    const key = result.verdict === \"applied\" || result.verdict === \"unchanged\" ? keyOf(payload) : undefined;\n    this.diagnose({ kind: \"event\", type, event, key, message: result.verdict });\n\n    const realtimeEvent: RealtimeEvent = {\n      type,\n      event,\n      key,\n      payload,\n      tenant,\n      isCreate: event === this.options.createdEventName,\n      subscriptions: this.attribute(type, payload),\n    };\n    for (const listener of [...eventListeners]) listener(realtimeEvent);\n  }\n\n  /**\n   * This client's subscriptions a broadcast satisfied, translated from the\n   * server's names through each entry's lease keys.\n   *\n   * THE WHOLE REASON THIS IS NEEDED: the channel is per type per tenant, so an\n   * event arrives here whenever ANY subscription on the tenant matched — a\n   * teammate's unfiltered list included. Arrival says \"somebody on this team\n   * asked\"; only this says \"you asked\". `undefined` when the transport cannot\n   * say, which is a different answer from `[]` (\"it said, and none were yours\").\n   */\n  private attribute(type: string, payload: RecordPayload): readonly string[] | undefined {\n    const subscriptionsOf = this.transport.subscriptionsOf;\n    if (!subscriptionsOf) return undefined;\n    const named = safely(() => subscriptionsOf.call(this.transport, payload), undefined);\n    if (named === undefined) return undefined;\n\n    const satisfied = new Set(named);\n    const mine: string[] = [];\n    for (const entry of this.entries.values()) {\n      if (entry.type !== type) continue;\n      if (entry.serverKeys.some((serverKey) => satisfied.has(serverKey))) mine.push(entry.key);\n    }\n    return mine;\n  }\n\n  /** The event name that means \"entered the set\", for the read binding. */\n  get createdEventName(): string {\n    return this.options.createdEventName;\n  }\n\n  /* --- Health -------------------------------------------------------------- */\n\n  subscribeToHealth = (listener: () => void): (() => void) => {\n    this.healthListeners.add(listener);\n    return () => this.healthListeners.delete(listener);\n  };\n\n  /**\n   * The renderable state, memoized so `getSnapshot` returns the identical\n   * object when nothing changed — the constraint every store in this package is\n   * written around.\n   */\n  readHealth = (): RealtimeHealth => {\n    if (this.healthSnapshot) return this.healthSnapshot;\n\n    const subscriptions: SubscriptionHealth[] = [...this.entries.values()]\n      .filter((entry) => entry.subscribers > 0 || entry.registered)\n      .map((entry) => ({\n        key: entry.key,\n        type: entry.type,\n        scope: entry.scope,\n        events: [...entry.events].sort(),\n        subscribers: entry.subscribers,\n        expiresAt: entry.expiresAt,\n        dead: this.isDead(entry),\n        attempts: entry.attempts,\n        lastError: entry.lastError,\n      }));\n\n    this.healthSnapshot = Object.freeze({\n      status: this.deriveStatus(subscriptions),\n      connection: this.connection,\n      subscriptions: Object.freeze(subscriptions),\n      epoch,\n      lastError: this.lastError,\n    });\n    return this.healthSnapshot;\n  };\n\n  private deriveStatus(subscriptions: readonly SubscriptionHealth[]): RealtimeStatus {\n    const active = subscriptions.filter((subscription) => subscription.subscribers > 0);\n    if (active.length === 0) return \"idle\";\n    if (active.some((subscription) => subscription.dead)) {\n      /* A first subscribe still in flight is \"connecting\", not \"dead\" — the\n         difference is between \"not yet\" and \"not any more\", and a screen says\n         different things for each. */\n      const settled = active.some((subscription) => subscription.attempts > 0 || subscription.expiresAt !== undefined);\n      return settled || this.connection !== \"connected\" ? \"dead\" : \"connecting\";\n    }\n    return \"live\";\n  }\n\n  private notifyHealth(): void {\n    this.healthSnapshot = null;\n    for (const listener of [...this.healthListeners]) listener();\n  }\n\n  /* --- Small helpers ------------------------------------------------------- */\n\n  private requestFor(entry: Entry, tenant: string | number | undefined): SubscriptionRequest {\n    return { type: entry.type, scope: entry.scope, tenant, key: entry.key };\n  }\n\n  private async callTransport(\n    call: () => Promise<unknown>,\n    kind: RealtimeDiagnostic[\"kind\"],\n    entry: Entry,\n  ): Promise<void> {\n    try {\n      await call();\n      this.diagnose({ kind, key: entry.key, type: entry.type });\n    } catch (error) {\n      /* Even a teardown failure is swallowed. There is nothing useful an app\n         can do with it, and the one thing it must not do is surface it as an\n         auth failure. */\n      this.diagnose({ kind, key: entry.key, type: entry.type, message: messageOf(error) });\n    }\n  }\n\n  private diagnose(diagnostic: Omit<RealtimeDiagnostic, \"at\">): void {\n    this.options.onDiagnostic?.({ ...diagnostic, at: this.options.now() });\n  }\n}\n\n/** `Type:id` for a payload that carries both, or `undefined`. */\nfunction keyOf(payload: RecordPayload): string | undefined {\n  const type = payload.__type;\n  const id = payload.id;\n  if (typeof type !== \"string\" || type === \"\") return undefined;\n  if (typeof id !== \"string\" && typeof id !== \"number\") return undefined;\n  return recordKey(type, id);\n}\n\nfunction messageOf(error: unknown): string {\n  if (error instanceof Error) return error.message;\n  if (typeof error === \"string\") return error;\n  return String(error);\n}\n\n/** A transport is a foreign object; a throw from one must not take the app out. */\nfunction safely<T>(call: () => T, fallback: T): T {\n  try {\n    return call();\n  } catch (error) {\n    devWarn(\"realtime\", `the injected transport threw: ${messageOf(error)}`);\n    return fallback;\n  }\n}\n"],"names":["DEFAULT_KEEPALIVE_INTERVAL_MS","DEFAULT_EXPIRY_MARGIN_MS","DEFAULT_BASE_BACKOFF_MS","DEFAULT_MAX_BACKOFF_MS","DEFAULT_MAX_ATTEMPTS","epoch","epochListeners","eventListeners","readRealtimeEpoch","subscribeToRealtimeEpoch","listener","subscribeToRealtimeEvents","bumpEpoch","resetRealtimeSignals","normalizeScope","input","id","scopeKey","scope","stableStringify","subscriptionKey","type","normalized","isNormalizedScope","normalizeTypeName","value","a","b","key","nested","SubscriptionRegistry","options","safely","state","entry","event","tenant","scopeInput","events","normalizedType","broughtNewEvents","released","current","isResubscribe","lease","error","messageOf","devWarn","delay","active","renewable","entries","requests","leases","index","message","channelEntry","channel","tenantAtBind","payload","result","write","keyOf","realtimeEvent","subscriptionsOf","named","satisfied","mine","serverKey","subscriptions","subscription","call","kind","diagnostic","recordKey","fallback"],"mappings":"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"}

package/dist/lib/records/define-record-type.js

@@ -0,0 +1,33 @@
+import { devWarn as l } from "../dev-warn.js";
+import { normalizeTypeName as d } from "./wire.js";
+const r = /* @__PURE__ */ new Map();
+function u(e, i = {}) {
+  const t = d(e);
+  t !== e && l(
+    "defineRecordType",
+    `"${e}" carries a Resource suffix — register the model name ("${t}"). The store normalizes it either way, but a caller writing the suffixed name usually also expects reads to key on it, and they do not.`
+  );
+  const n = i.staleFields ?? [], s = r.get(t);
+  if (s)
+    return a(s.staleFields, n) || l(
+      "defineRecordType",
+      `"${t}" is registered twice with different staleFields — the first registration wins.`
+    ), s;
+  const o = { type: t, staleFields: n };
+  return r.set(t, o), o;
+}
+function a(e, i) {
+  return e === "*" || i === "*" ? e === i : e.length === i.length && e.every((t) => i.includes(t));
+}
+function y(e) {
+  return r.get(e)?.staleFields ?? [];
+}
+function p() {
+  r.clear();
+}
+export {
+  u as defineRecordType,
+  p as resetRecordTypes,
+  y as staleFieldsFor
+};
+//# sourceMappingURL=define-record-type.js.map

package/dist/lib/records/define-record-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-record-type.js","sources":["../../../src/lib/records/define-record-type.ts"],"sourcesContent":["import { devWarn } from \"../dev-warn\";\nimport type { RecordTypeOptions, RecordTypeToken } from \"./types\";\nimport { normalizeTypeName } from \"./wire\";\n\n/* ============================================================================\n   TYPE REGISTRATION — a token carrying both the runtime string and the\n   compile-time type, so the two can never drift.\n\n   WHY A TOKEN RATHER THAN A STRING OR A GENERIC. A bare string key returning\n   `unknown` is unusable in a TypeScript app. A caller-supplied generic —\n   `useRecord<WorkflowRun>(\"WorkflowRun\", id)` — is honest but UNCHECKED:\n   nothing stops the string and the type disagreeing, and that mistake is\n   invisible until runtime. Global declaration merging gives the nicest call\n   site and forces every consumer to maintain an ambient module block, which\n   fails this library's generality test.\n\n   This is also not a new idea here. It is the only answer this package has\n   ever given to this question — `createSimStore`'s factory and `DataTable`'s\n   `TData` both do it. Matching an existing convention beats inventing a third.\n\n   ONE DELIBERATE REVERSAL, DOCUMENTED BECAUSE IT CONTRADICTS A STATED\n   PRINCIPLE IN THIS SAME PACKAGE. `createSimStore` takes a caller-supplied\n   `getId` and says in so many words that it never assumes a field called `id`,\n   because this library's own simulated entities do not agree on one\n   (`Role.id`, `Permission.key`, `UseCase.ref`). THIS store DOES assume `id`,\n   unconditionally, and does not accept a `getId`.\n\n   The reason is that the two are answering different questions. `createSimStore`\n   holds whatever a caller invents; this store holds records off ONE wire\n   format, and that format guarantees `id`: the serializer prepends `id`,\n   `__type`, `__timestamp` and `__deleted_at` to every payload AFTER the field\n   whitelist is applied, so a whitelist cannot remove them. Accepting a `getId`\n   here would offer a choice that has exactly one correct answer, and would\n   invite a caller to key on `name` — which merges two different rows the day\n   two of them share one. It is a defensible narrowing of a general tool into a\n   specific one; it is written down here so a future reader does not think it\n   was overlooked.\n   ========================================================================= */\n\nconst registry = new Map<string, RecordTypeToken<unknown>>();\n\n/**\n * Declare a record type.\n *\n * THE NAME IS THE NORMALIZED MODEL NAME — `\"WorkflowRun\"`, NEVER\n * `\"WorkflowRunResource\"`. This is the single most likely thing in this module\n * to be built wrong, because both readings are plausible and exactly one\n * matches: the store strips a trailing `Resource` from every incoming `__type`\n * before keying (created payloads carry the suffix, deletes do not), so the\n * caller always writes the model name. The wrong one produces a store that\n * fills up and a screen that never moves, with no error anywhere — which is\n * why passing the suffixed name warns loudly rather than quietly working.\n *\n * @param name normalized model name, e.g. `\"WorkflowRun\"`\n * @param options `staleFields` — the fields this type's broadcast cannot carry\n */\nexport function defineRecordType<T>(name: string, options: RecordTypeOptions = {}): RecordTypeToken<T> {\n  const type = normalizeTypeName(name);\n\n  if (type !== name) {\n    devWarn(\n      \"defineRecordType\",\n      `\"${name}\" carries a Resource suffix — register the model name (\"${type}\"). ` +\n        \"The store normalizes it either way, but a caller writing the suffixed name \" +\n        \"usually also expects reads to key on it, and they do not.\",\n    );\n  }\n\n  const staleFields = options.staleFields ?? [];\n  const existing = registry.get(type);\n\n  if (existing) {\n    /* Re-registration is normal — module reload, a second import of the same\n       declaration file. Re-registration with DIFFERENT stale fields is not:\n       whichever call ran last would silently decide what a broadcast is\n       allowed to be trusted for. */\n    if (!sameStaleFields(existing.staleFields, staleFields)) {\n      devWarn(\n        \"defineRecordType\",\n        `\"${type}\" is registered twice with different staleFields — the first registration wins.`,\n      );\n    }\n    return existing as RecordTypeToken<T>;\n  }\n\n  const token: RecordTypeToken<T> = { type, staleFields };\n  registry.set(type, token as RecordTypeToken<unknown>);\n  return token;\n}\n\nfunction sameStaleFields(a: readonly string[] | \"*\", b: readonly string[] | \"*\"): boolean {\n  if (a === \"*\" || b === \"*\") return a === b;\n  return a.length === b.length && a.every((field) => b.includes(field));\n}\n\n/**\n * What a type declared, for the store's own use.\n *\n * An UNREGISTERED type is not an error: a nested child of a type nobody\n * declared is still a record with an identity, and refusing it would lose data\n * the parent legitimately carries. It simply has no stale fields, which is the\n * correct default — a type that never declared a gap in its broadcast is\n * treated as having none.\n */\nexport function staleFieldsFor(type: string): readonly string[] | \"*\" {\n  return registry.get(type)?.staleFields ?? [];\n}\n\n/** Test seam. Nothing in the library calls this. */\nexport function resetRecordTypes(): void {\n  registry.clear();\n}\n"],"names":["registry","defineRecordType","name","options","type","normalizeTypeName","devWarn","staleFields","existing","sameStaleFields","token","a","b","field","staleFieldsFor","resetRecordTypes"],"mappings":";;AAuCA,MAAMA,wBAAe,IAAA;AAiBd,SAASC,EAAoBC,GAAcC,IAA6B,IAAwB;AACrG,QAAMC,IAAOC,EAAkBH,CAAI;AAEnC,EAAIE,MAASF,KACXI;AAAA,IACE;AAAA,IACA,IAAIJ,CAAI,2DAA2DE,CAAI;AAAA,EAAA;AAM3E,QAAMG,IAAcJ,EAAQ,eAAe,CAAA,GACrCK,IAAWR,EAAS,IAAII,CAAI;AAElC,MAAII;AAKF,WAAKC,EAAgBD,EAAS,aAAaD,CAAW,KACpDD;AAAA,MACE;AAAA,MACA,IAAIF,CAAI;AAAA,IAAA,GAGLI;AAGT,QAAME,IAA4B,EAAE,MAAAN,GAAM,aAAAG,EAAA;AAC1C,SAAAP,EAAS,IAAII,GAAMM,CAAiC,GAC7CA;AACT;AAEA,SAASD,EAAgBE,GAA4BC,GAAqC;AACxF,SAAID,MAAM,OAAOC,MAAM,MAAYD,MAAMC,IAClCD,EAAE,WAAWC,EAAE,UAAUD,EAAE,MAAM,CAACE,MAAUD,EAAE,SAASC,CAAK,CAAC;AACtE;AAWO,SAASC,EAAeV,GAAuC;AACpE,SAAOJ,EAAS,IAAII,CAAI,GAAG,eAAe,CAAA;AAC5C;AAGO,SAASW,IAAyB;AACvC,EAAAf,EAAS,MAAA;AACX;"}