@lunora/do 1.0.0-alpha.16 → 1.0.0-alpha.17

package/dist/index.d.mts

@@ -5846,8 +5846,12 @@ declare abstract class ShardDO {
   * subscriber counts are folded live from each socket's attachment via
   * {@link summarizeFanoutTopics}; the running per-path cost counters are the
   * in-memory {@link ShardDO.fanout} tallies, sharing `metrics.sinceMs` as the
-  * "since this instance woke" epoch. Read-only: touches no SQLite and mutates
-  * no socket state.
+  * "since this instance woke" epoch. Touches no SQLite and mutates no socket
+  * state; it does call `relay.relayCount()`, which advances the promotion
+  * latch — safe here because that transition is a pure, monotonic function of
+  * the live socket count (DOs are single-threaded), so a metrics poll only ever
+  * drives the latch to the same state the routing path would compute for the
+  * same count, never a divergent one.
   */
   private collectFanoutMetrics;
   /** Resolve a `getAuditLog` admin read, parsing the optional `limit`/`sinceSeq` cursor args and ensuring the reserved table first. */

package/dist/index.d.ts

@@ -5846,8 +5846,12 @@ declare abstract class ShardDO {
   * subscriber counts are folded live from each socket's attachment via
   * {@link summarizeFanoutTopics}; the running per-path cost counters are the
   * in-memory {@link ShardDO.fanout} tallies, sharing `metrics.sinceMs` as the
-  * "since this instance woke" epoch. Read-only: touches no SQLite and mutates
-  * no socket state.
+  * "since this instance woke" epoch. Touches no SQLite and mutates no socket
+  * state; it does call `relay.relayCount()`, which advances the promotion
+  * latch — safe here because that transition is a pure, monotonic function of
+  * the live socket count (DOs are single-threaded), so a metrics poll only ever
+  * drives the latch to the same state the routing path would compute for the
+  * same count, never a divergent one.
   */
   private collectFanoutMetrics;
   /** Resolve a `getAuditLog` admin read, parsing the optional `limit`/`sinceSeq` cursor args and ensuring the reserved table first. */

package/dist/index.mjs

@@ -26,7 +26,7 @@ export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_share
 export { buildFtsMatch, ftsTableName, scoreDocument, stringifySearchText, tokenizeSearch } from './packem_shared/buildFtsMatch-BLEMawrp.mjs';
 export { M as MIN_ADMIN_TOKEN_LENGTH, a as MIN_AUTH_SECRET_LENGTH, b as buildSecurityAudit } from './packem_shared/security-audit-CucgBice.mjs';
 export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-ilPZsVwu.mjs';
-export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-CtTkRXH0.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-DDp_NomS.mjs';
 export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-BsAbi5Mn.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-dDcFE1YZ.mjs';
 export { createSystemReader } from './packem_shared/createSystemReader-8CzSZP9V.mjs';

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-CtTkRXH0.mjs → ROOT_DO_SIZE_WARN_BYTES-DDp_NomS.mjs}

@@ -196,7 +196,22 @@ const parseRelayName = (name) => {
 };
 
 const shapeRoutingKey = (name, args) => stableStringify({ args: args ?? {}, name });
-const DEFAULT_PROMOTION_THRESHOLDS = { tUp: 8e3 };
+const DEFAULT_PROMOTION_THRESHOLDS = { tDown: 4e3, tUp: 8e3 };
+const nextPromotionState = (current, subscribers, thresholds = DEFAULT_PROMOTION_THRESHOLDS) => {
+  if (thresholds.tDown >= thresholds.tUp) {
+    throw new Error(`invalid promotion thresholds: tDown (${String(thresholds.tDown)}) must be < tUp (${String(thresholds.tUp)})`);
+  }
+  if (current === "owned") {
+    return subscribers >= thresholds.tUp ? "promoted" : "owned";
+  }
+  return subscribers < thresholds.tDown ? "owned" : "promoted";
+};
+const clampPromotionThresholds = (tUp, tDownRaw) => {
+  if (tDownRaw < tUp) {
+    return { tDown: tDownRaw, tUp };
+  }
+  return { tDown: Math.min(Math.max(1, Math.floor(tUp / 2)), tUp - 1), tUp };
+};
 
 const projectColumns = (document_, columns) => {
   if (!columns) {
@@ -232,11 +247,12 @@ const diffGlobalMembership = (rows, previous, options) => {
   }
   return { next, rowsPatch };
 };
-const buildPokeFrames = (parts, meta) => {
+const encodeRowsPatch = (rowsPatch) => rowsPatch.map((op) => op.value === void 0 ? op : { ...op, value: encodeWire(op.value) });
+const buildPokeFrames = (parts, meta, options = {}) => {
   const { baseCheckpoint, checkpoint, epoch, lastMutationId, pokeId } = meta;
   const frames = [JSON.stringify({ baseCheckpoint, epoch, pokeId, type: "pokeStart" })];
   for (const part of parts) {
-    const rowsPatch = part.rowsPatch.map((op) => op.value === void 0 ? op : { ...op, value: encodeWire(op.value) });
+    const rowsPatch = options.preEncoded ? part.rowsPatch : encodeRowsPatch(part.rowsPatch);
     frames.push(
       JSON.stringify({
         pokeId,
@@ -376,6 +392,8 @@ class OwnerRelay extends RelayLink {
   relayShapeRegistry = /* @__PURE__ */ new Map();
   /** NON-uniform (identity-scoped) relay shapes, one entry per relay socket, keyed `relayIndex:connectionId:subId`. Each is served live by a per-socket proxy poke. */
   relayShapeProxies = /* @__PURE__ */ new Map();
+  /** The owner's current promotion state (plan 075 Phase 4), carried across `relayCount()` calls so hysteresis has memory — a shard hovering near the threshold can't flap. */
+  promotionState = "owned";
   constructor(host, ownerKey) {
     super(host, { ownerKey });
   }
@@ -406,13 +424,22 @@ class OwnerRelay extends RelayLink {
   }
   /**
    * How many relays the runtime should spread new connections across for this shard
-   * (plan 075 Phase 2). `0` keeps every connection on the owner. The owner promotes
-   * once its live socket count crosses `LUNORA_RELAY_THRESHOLD`, fanning to a fixed
-   * `LUNORA_RELAY_FAN` (capped by `LUNORA_MAX_RELAYS`, the cost ceiling).
+   * (plan 075 Phase 2, hysteresis added in Phase 4). `0` keeps every connection on
+   * the owner. The owner promotes once its live socket count reaches
+   * `LUNORA_RELAY_THRESHOLD` (`tUp`), fanning to a fixed `LUNORA_RELAY_FAN` (capped
+   * by `LUNORA_MAX_RELAYS`, the cost ceiling), and only collapses back to
+   * owner-served once subscribers drain below `LUNORA_RELAY_COLLAPSE_THRESHOLD`
+   * (`tDown`) — the band between the two holds the current state so a shard
+   * hovering near the threshold can't flap. {@link clampPromotionThresholds}
+   * guarantees a valid `tDown < tUp` band even under a misconfigured collapse
+   * threshold. Advances the promotion latch, so it is not a pure read.
    */
   relayCount() {
-    const threshold = envPositiveInt(this.host.env(), "LUNORA_RELAY_THRESHOLD", DEFAULT_PROMOTION_THRESHOLDS.tUp);
-    if (this.host.getWebSockets().length < threshold) {
+    const subscribers = this.host.getWebSockets().length;
+    const tUp = envPositiveInt(this.host.env(), "LUNORA_RELAY_THRESHOLD", DEFAULT_PROMOTION_THRESHOLDS.tUp);
+    const tDownRaw = envPositiveInt(this.host.env(), "LUNORA_RELAY_COLLAPSE_THRESHOLD", DEFAULT_PROMOTION_THRESHOLDS.tDown);
+    this.promotionState = nextPromotionState(this.promotionState, subscribers, clampPromotionThresholds(tUp, tDownRaw));
+    if (this.promotionState === "owned") {
       return 0;
     }
     const maxRelays = envPositiveInt(this.host.env(), "LUNORA_MAX_RELAYS", DEFAULT_MAX_RELAYS);
@@ -497,7 +524,10 @@ class OwnerRelay extends RelayLink {
         epoch,
         fromCursor,
         name: entry.name,
-        rowsPatch,
+        // Wire-encode before the poke crosses the owner→relay `JSON.stringify`
+        // hop (`requestRelayMessage`); the relay re-frames it with
+        // `preEncoded` so a `bytes`/`bigint` shape column isn't dropped/truncated.
+        rowsPatch: encodeRowsPatch(rowsPatch),
         type: "relay_shape_poke"
       };
       for (const index of relays) {
@@ -541,7 +571,9 @@ class OwnerRelay extends RelayLink {
         epoch,
         fromCursor,
         name: entry.name,
-        rowsPatch,
+        // Wire-encode before the owner→relay `JSON.stringify` hop (see the
+        // cohort-multicast path); the relay re-frames it with `preEncoded`.
+        rowsPatch: encodeRowsPatch(rowsPatch),
         targetConnectionId: entry.connectionId,
         type: "relay_shape_poke"
       };
@@ -861,13 +893,19 @@ class RelayMember extends RelayLink {
         if (memo?.cursor !== poke.fromCursor || memo.epoch !== poke.epoch || shapeRoutingKey(sub.name, sub.args) !== routingKey) {
           continue;
         }
-        const frames = buildPokeFrames([{ rowsPatch: poke.rowsPatch, shapeId: subId }], {
-          baseCheckpoint: void 0,
-          checkpoint: poke.checkpoint,
-          epoch: poke.epoch,
-          lastMutationId: void 0,
-          pokeId: this.host.nextPokeId()
-        });
+        const frames = buildPokeFrames(
+          [{ rowsPatch: poke.rowsPatch, shapeId: subId }],
+          {
+            baseCheckpoint: void 0,
+            checkpoint: poke.checkpoint,
+            epoch: poke.epoch,
+            lastMutationId: void 0,
+            pokeId: this.host.nextPokeId()
+          },
+          // `poke.rowsPatch` was wire-encoded by the owner before it crossed
+          // the hub — don't double-encode it here.
+          { preEncoded: true }
+        );
         for (const frame of frames) {
           trySendFrame(ws, frame);
         }
@@ -4651,8 +4689,12 @@ class ShardDO {
    * subscriber counts are folded live from each socket's attachment via
    * {@link summarizeFanoutTopics}; the running per-path cost counters are the
    * in-memory {@link ShardDO.fanout} tallies, sharing `metrics.sinceMs` as the
-   * "since this instance woke" epoch. Read-only: touches no SQLite and mutates
-   * no socket state.
+   * "since this instance woke" epoch. Touches no SQLite and mutates no socket
+   * state; it does call `relay.relayCount()`, which advances the promotion
+   * latch — safe here because that transition is a pure, monotonic function of
+   * the live socket count (DOs are single-threaded), so a metrics poll only ever
+   * drives the latch to the same state the routing path would compute for the
+   * same count, never a divergent one.
    */
   collectFanoutMetrics() {
     const summary = summarizeFanoutTopics(this.state.getWebSockets().map((ws) => this.readAttachment(ws)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/do",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-alpha.17",
   "description": "Lunora Durable Objects: ShardDO (SQLite, OCC, hibernated WebSocket subscriptions) and SessionDO",
   "keywords": [
     "cloudflare",