mixdog 0.9.150 → 0.9.152

package/src/standalone/session-runtime-shard-router.mjs

@@ -0,0 +1,149 @@
+'use strict';
+
+// Deterministic routing for the session runtime SHARD host.
+//
+// One child process owning every session runtime, every agent dispatch, every
+// provider parse and every tool result is a single event-loop failure domain:
+// one slow parse or one runaway tool stalls unrelated sessions and their
+// control/abort path. The host therefore runs a BOUNDED set of identical
+// runtime children ("shards") and routes work to them deterministically.
+//
+// Routing rules (all pure, all testable here):
+//   * Ownership is keyed by session identity (sessionId), not by arrival
+//     order, so every view/recovery/resume of one session lands on the SAME
+//     shard and its in-process session store stays authoritative.
+//   * A key's home shard is a stable hash; probing continues in a stable
+//     rotation only while the home shard is not placeable (lagging/quarantined).
+//   * Once a key is claimed it keeps its shard until the last holder releases
+//     it — health changes never migrate live work, which would strand accepted
+//     input in the abandoned child.
+
+export const SESSION_RUNTIME_SHARD_ENV = 'MIXDOG_SESSION_RUNTIME_SHARDS';
+export const MAX_SESSION_RUNTIME_SHARDS = 16;
+
+/**
+ * The external-host compatibility seam defaults to one shared runtime process.
+ * Production sessions now use the daemon's in-process actor host instead.
+ *
+ * The legacy env is intentionally ignored. Explicit multi-process counts stay
+ * available only through createSessionRuntimeHost({ shardCount }) as a test
+ * seam for recovery and routing contracts.
+ */
+export function resolveShardCount() {
+  return 1;
+}
+
+/** FNV-1a (32-bit): stable across processes and daemon restarts. */
+export function hashRoutingKey(key) {
+  const text = String(key ?? '');
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index) & 0xff;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+export function normalizeShardCount(shardCount) {
+  const count = Math.floor(Number(shardCount) || 1);
+  return Math.max(1, Math.min(MAX_SESSION_RUNTIME_SHARDS, count));
+}
+
+/** Home shard for a routing key. */
+export function shardIndexForKey(key, shardCount) {
+  const count = normalizeShardCount(shardCount);
+  return hashRoutingKey(key) % count;
+}
+
+/** Home shard first, then a stable rotation over the remaining shards. */
+export function shardProbeOrder(key, shardCount) {
+  const count = normalizeShardCount(shardCount);
+  const home = shardIndexForKey(key, count);
+  const order = [];
+  for (let step = 0; step < count; step += 1) order.push((home + step) % count);
+  return order;
+}
+
+/**
+ * Placement for a NEW key. Falls back through the probe order while shards are
+ * not placeable; when every shard is unplaceable the home shard still owns the
+ * work (queued, never dropped).
+ */
+export function selectShardIndex(key, shardCount, isPlaceable = () => true) {
+  const order = shardProbeOrder(key, shardCount);
+  for (const index of order) {
+    let ok = true;
+    try { ok = isPlaceable(index) !== false; } catch { ok = true; }
+    if (ok) return index;
+  }
+  return order[0];
+}
+
+/** Routing key for a session runtime: session identity when known. */
+export function runtimeRoutingKey(options, fallbackKey = '') {
+  const sessionId = String(options?.sessionId || '').trim();
+  return sessionId || String(fallbackKey || '');
+}
+
+/**
+ * Refcounted key -> shard ownership. Ownership is sticky for as long as any
+ * holder exists so recovery/resume of the same session never changes shard.
+ */
+export function createShardOwnership() {
+  const owners = new Map(); // key -> { index, refs }
+  return {
+    claim(key, resolve) {
+      const id = String(key || '');
+      const existing = owners.get(id);
+      if (existing) {
+        existing.refs += 1;
+        return existing.index;
+      }
+      const index = Math.max(0, Math.floor(Number(resolve(id)) || 0));
+      owners.set(id, { index, refs: 1 });
+      return index;
+    },
+    peek(key) {
+      const existing = owners.get(String(key || ''));
+      return existing ? existing.index : null;
+    },
+    release(key) {
+      const id = String(key || '');
+      const existing = owners.get(id);
+      if (!existing) return null;
+      existing.refs -= 1;
+      if (existing.refs <= 0) owners.delete(id);
+      return existing.index;
+    },
+    get size() { return owners.size; },
+    entries() { return [...owners].map(([key, value]) => ({ key, ...value })); },
+  };
+}
+
+/**
+ * Provider capacity cooldown is an ACCOUNT-wide fact, but each shard discovers
+ * it in its own process. The host merges the strongest known cooldown and
+ * replays it to the other shards; merging must be monotonic so a replay can
+ * never shorten or clear a live cooldown (that would re-open the hammering
+ * window this state exists to close).
+ */
+export function mergeProviderCooldown(current, incoming) {
+  const base = {
+    untilMs: Number(current?.untilMs) || 0,
+    disabledReason: current?.disabledReason ? String(current.disabledReason) : null,
+    updatedAt: Number(current?.updatedAt) || 0,
+  };
+  const untilMs = Number(incoming?.untilMs) || 0;
+  const disabledReason = incoming?.disabledReason ? String(incoming.disabledReason) : null;
+  const grew = untilMs > base.untilMs + 1_000;
+  const newlyDisabled = Boolean(disabledReason) && disabledReason !== base.disabledReason;
+  if (!grew && !newlyDisabled) return { changed: false, cooldown: base };
+  return {
+    changed: true,
+    cooldown: {
+      untilMs: Math.max(base.untilMs, untilMs),
+      disabledReason: disabledReason || base.disabledReason,
+      updatedAt: Number(incoming?.observedAt) || Date.now(),
+    },
+  };
+}

package/src/standalone/session-runtime-shard-router.test.mjs

@@ -0,0 +1,101 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  createShardOwnership,
+  hashRoutingKey,
+  normalizeShardCount,
+  mergeProviderCooldown,
+  resolveShardCount,
+  runtimeRoutingKey,
+  selectShardIndex,
+  shardIndexForKey,
+  shardProbeOrder,
+} from './session-runtime-shard-router.mjs';
+
+test('production always uses one shared actor runtime process', () => {
+  assert.equal(resolveShardCount({}, 1), 1);
+  assert.equal(resolveShardCount({}, 2), 1);
+  assert.equal(resolveShardCount({}, 128), 1);
+  assert.equal(resolveShardCount({ MIXDOG_SESSION_RUNTIME_SHARDS: '6' }, 128), 1);
+  // Explicit constructor counts remain a bounded recovery/routing test seam.
+  assert.equal(normalizeShardCount(999), 16);
+  assert.equal(normalizeShardCount(0), 1);
+  assert.equal(normalizeShardCount(-3), 1);
+  assert.equal(normalizeShardCount(Number.NaN), 1);
+  assert.equal(normalizeShardCount(3), 3);
+});
+
+test('routing is deterministic, in range, and spreads keys across shards', () => {
+  assert.equal(hashRoutingKey('sess-1'), hashRoutingKey('sess-1'));
+  const used = new Set();
+  for (let index = 0; index < 200; index += 1) {
+    const key = `sess-${index}`;
+    const shard = shardIndexForKey(key, 4);
+    assert.equal(shard, shardIndexForKey(key, 4));
+    assert.ok(shard >= 0 && shard < 4);
+    used.add(shard);
+  }
+  // Fan-out is the point: a batch of independent sessions must not collapse
+  // onto one event loop.
+  assert.equal(used.size, 4);
+});
+
+test('probe order starts at the home shard and covers every shard once', () => {
+  const order = shardProbeOrder('sess-probe', 4);
+  assert.equal(order.length, 4);
+  assert.equal(order[0], shardIndexForKey('sess-probe', 4));
+  assert.equal(new Set(order).size, 4);
+});
+
+test('placement skips unplaceable shards but never drops the work', () => {
+  const key = 'sess-degraded';
+  const home = shardIndexForKey(key, 3);
+  const next = shardProbeOrder(key, 3)[1];
+  assert.equal(selectShardIndex(key, 3, () => true), home);
+  assert.equal(selectShardIndex(key, 3, (index) => index !== home), next);
+  // Every shard degraded: the home shard still owns it (queued, not lost).
+  assert.equal(selectShardIndex(key, 3, () => false), home);
+});
+
+test('session identity owns the shard and ownership is sticky until released', () => {
+  assert.equal(runtimeRoutingKey({ sessionId: 'sess-a' }, 'runtime-1'), 'sess-a');
+  assert.equal(runtimeRoutingKey({}, 'runtime-1'), 'runtime-1');
+
+  const ownership = createShardOwnership();
+  const first = ownership.claim('sess-a', () => 1);
+  // A second holder of the same session never re-resolves: same shard, even if
+  // the placement policy would now choose differently.
+  const second = ownership.claim('sess-a', () => 2);
+  assert.equal(first, 1);
+  assert.equal(second, 1);
+  assert.equal(ownership.size, 1);
+  ownership.release('sess-a');
+  assert.equal(ownership.peek('sess-a'), 1);
+  ownership.release('sess-a');
+  assert.equal(ownership.peek('sess-a'), null);
+  assert.equal(ownership.size, 0);
+  assert.equal(ownership.claim('sess-a', () => 2), 2);
+});
+
+test('provider cooldown merges monotonically across shards', () => {
+  const start = { untilMs: 0, disabledReason: null, updatedAt: 0 };
+  const first = mergeProviderCooldown(start, { untilMs: 10_000, observedAt: 5 });
+  assert.equal(first.changed, true);
+  assert.equal(first.cooldown.untilMs, 10_000);
+
+  // A shorter/echoed cooldown must never shorten or re-broadcast.
+  const echo = mergeProviderCooldown(first.cooldown, { untilMs: 9_500 });
+  assert.equal(echo.changed, false);
+  assert.equal(echo.cooldown.untilMs, 10_000);
+
+  const longer = mergeProviderCooldown(first.cooldown, { untilMs: 30_000 });
+  assert.equal(longer.changed, true);
+  assert.equal(longer.cooldown.untilMs, 30_000);
+
+  const disabled = mergeProviderCooldown(longer.cooldown, { untilMs: 0, disabledReason: 'overage off' });
+  assert.equal(disabled.changed, true);
+  assert.equal(disabled.cooldown.disabledReason, 'overage off');
+  assert.equal(disabled.cooldown.untilMs, 30_000);
+  assert.equal(mergeProviderCooldown(disabled.cooldown, { disabledReason: 'overage off' }).changed, false);
+});