@rivalis/fleet 8.0.0

package/lib/FleetState.js

@@ -0,0 +1,865 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/orchestrator/FleetState.ts
+var FleetState_exports = {};
+__export(FleetState_exports, {
+  FleetError: () => FleetError,
+  FleetState: () => FleetState
+});
+module.exports = __toCommonJS(FleetState_exports);
+var import_node_crypto2 = require("crypto");
+
+// src/util/canonical.ts
+var import_node_crypto = require("crypto");
+function canonicalize(value) {
+  return encode(value);
+}
+function encode(value) {
+  if (value === null) {
+    return "null";
+  }
+  const type = typeof value;
+  if (type === "string") {
+    return JSON.stringify(value);
+  }
+  if (type === "number") {
+    return Number.isFinite(value) ? String(value) : "null";
+  }
+  if (type === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (type === "bigint") {
+    return value.toString();
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item) => encodeArrayItem(item));
+    return "[" + items.join(",") + "]";
+  }
+  if (type === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const key of keys) {
+      const child = obj[key];
+      if (isSkippable(child)) {
+        continue;
+      }
+      parts.push(JSON.stringify(key) + ":" + encode(child));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return "null";
+}
+function encodeArrayItem(item) {
+  return isSkippable(item) ? "null" : encode(item);
+}
+function isSkippable(value) {
+  const type = typeof value;
+  return value === void 0 || type === "function" || type === "symbol";
+}
+function hash64(value) {
+  const digest = (0, import_node_crypto.createHash)("sha256").update(canonicalize(value)).digest();
+  return digest.subarray(0, 8).toString("hex");
+}
+
+// src/util/logger.ts
+var NOOP_LOGGER = {
+  error() {
+  },
+  warning() {
+  },
+  info() {
+  },
+  debug() {
+  },
+  verbose() {
+  },
+  log() {
+  }
+};
+
+// src/domain/roomId.ts
+var ROOM_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+var NAMESPACE_SEPARATOR = "~";
+var ROOM_ID_CHAR = /[A-Za-z0-9_-]/;
+function isValidRoomId(id) {
+  return ROOM_ID_PATTERN.test(id);
+}
+function encodeRoomId(id) {
+  if (isValidRoomId(id)) {
+    return id;
+  }
+  let out = "";
+  for (const byte of Buffer.from(id, "utf8")) {
+    const ch = String.fromCharCode(byte);
+    out += ROOM_ID_CHAR.test(ch) ? ch : "%" + byte.toString(16).toUpperCase().padStart(2, "0");
+  }
+  return out;
+}
+function namespaceRoomId(processUid, encodedRoomId) {
+  return processUid + NAMESPACE_SEPARATOR + encodedRoomId;
+}
+
+// src/domain/roomCreate.ts
+var roomCreateSchema = {
+  type: { type: "string", required: true, min: 1 },
+  roomId: { type: "string", pattern: ROOM_ID_PATTERN.source },
+  placement: { type: "object" }
+};
+
+// src/domain/errors.ts
+var import_node = require("@toolcase/node");
+var CODE_TO_STATUS = {
+  VALIDATION: 400,
+  UNAUTHORIZED: 401,
+  INSTANCE_NOT_FOUND: 404,
+  ROOM_NOT_FOUND: 404,
+  NO_CANDIDATE: 409,
+  ROOM_EXISTS: 409,
+  INSTANCE_DRAINING: 409,
+  PAYLOAD_TOO_LARGE: 413,
+  INSTANCE_BUSY: 429,
+  AUTH_THROTTLED: 429,
+  SSE_LIMIT: 429,
+  COMMAND_FAILED: 502,
+  INSTANCE_DISCONNECTED: 502,
+  COMMAND_TIMEOUT: 504
+};
+var FleetError = class extends import_node.EndpointError {
+  constructor(code, message) {
+    super(CODE_TO_STATUS[code], code, message);
+    this.name = "FleetError";
+  }
+};
+
+// src/orchestrator/FleetState.ts
+var FleetState = class {
+  logger;
+  random;
+  /** Read model, keyed by connection-scoped `instanceId` (a reconnect is a new key). */
+  records = /* @__PURE__ */ new Map();
+  /** Live capacity reservations: token → instanceId. */
+  reservations = /* @__PURE__ */ new Map();
+  /** Reserved room slots per instance, derived from `reservations` for O(1) headroom checks. */
+  reservedByInstance = /* @__PURE__ */ new Map();
+  reservationSeq = 0;
+  /** Room ids reserved by in-flight creates (§11) — held until ack/timeout/rejection. */
+  reservedRoomIds = /* @__PURE__ */ new Set();
+  /**
+   * Room ids whose create has settled (acked OK or timed out) but whose room has
+   * not yet appeared in an applied snapshot from the owning instance (task 003).
+   * The id reservation is held *past* the command settle: releasing it on ack/timeout
+   * would free the id for up to one `heartbeatMs` before the room reconciles into the
+   * read model — the window in which the §10 retry-after-504 (or an immediate
+   * re-create) re-reserves the id and double-creates on a *different* instance, the
+   * exact cross-instance duplicate §11 exists to prevent. Keyed `roomId → owning
+   * instanceId`; cleared when the owning instance's next snapshot/poll reconciles
+   * (the read model takes over) or it is evicted. Held entries count toward both
+   * id-uniqueness ({@link isRoomIdTaken}) and `maxRooms` headroom ({@link hasHeadroom}).
+   */
+  pendingRoomIds = /* @__PURE__ */ new Map();
+  /** Pending-visibility room count per instance, for O(1) `maxRooms` headroom (task 003). */
+  pendingByInstance = /* @__PURE__ */ new Map();
+  /** Monotonic join counter — assigns each instance its tie-break order (§11). */
+  joinCounter = 0;
+  /**
+   * Instances the orchestrator has marked stale (wedged: connected but silent
+   * past 2×heartbeat — §7). Liveness bookkeeping, not snapshot-derived semantic
+   * state: it is **excluded from `stateHash`** (like `lastSyncAt`) but **excludes
+   * the instance from auto-placement**, so a wedged-yet-least-loaded node cannot
+   * keep winning placement until it is evicted at 3×heartbeat.
+   */
+  staleInstances = /* @__PURE__ */ new Set();
+  /**
+   * Agent-acked-but-not-yet-snapshotted status, kept for PLACEMENT candidacy only
+   * (task 004). On a `drain`/`undrain` ack the agent has already flipped its
+   * agent-owned status (§7), but the read-model `status` only catches up at the
+   * instance's next poll reply — up to one `heartbeatMs` later. Until then
+   * `place()` would still see the stale value and keep selecting a just-drained
+   * node (or keep excluding a just-undrained one). Like {@link staleInstances},
+   * this is a placement-only override: it is **excluded from `stateHash`** and the
+   * read model, and it **never writes the agent-owned `status`** (§7 status
+   * ownership stays intact) — it only shifts what {@link place} treats as the
+   * instance's effective status. Keyed `instanceId → effective status`; cleared the
+   * moment a snapshot/poll reconciles the matching status into the read model (the
+   * override has done its job) or the instance is removed.
+   */
+  pendingStatus = /* @__PURE__ */ new Map();
+  /**
+   * Memoized id-resolution pass ({@link resolve}) and {@link computeStateHash}
+   * result. The resolution is O(rooms) — flatten every room, group by base id,
+   * sort the collision buckets, build the public-id index, clone every instance —
+   * and was previously rebuilt on **every** read-model query (`stats`/`instances`/
+   * `rooms`/`getRoom`/…); one `GET /v1/stats` alone resolves ≥2×. Both are now
+   * computed lazily and held until the next SEMANTIC mutation.
+   *
+   * Invalidated by exactly the two mutations that change semantic state:
+   * {@link applySnapshot} (when it actually applies) and {@link removeInstance}.
+   * {@link touch} (advances `lastSyncAt`) and {@link setStale} are non-semantic —
+   * both are excluded from `stateHash` (§6) and from the resolution — so neither
+   * invalidates; `touch` instead keeps the cached `InstanceInfo.lastSyncAt` in step
+   * in place (see below). `null` ⇒ dirty, rebuild on next read.
+   *
+   * Read-only contract: the cached `InstanceInfo` / `RoomInfo` objects are now
+   * SHARED across callers and across queries (a query no longer clones afresh).
+   * They must be treated as immutable by consumers; the only sanctioned in-place
+   * write is `touch`'s `lastSyncAt` refresh, which is liveness bookkeeping outside
+   * both the resolution and the hash. The `instances`/`rooms`/`findRooms` getters
+   * still hand back a fresh array container so a caller's `sort()`/`push()` cannot
+   * corrupt the memo — only the element objects are shared.
+   */
+  resolvedView = null;
+  cachedStateHash = null;
+  constructor(options = {}) {
+    this.logger = options.logger ?? NOOP_LOGGER;
+    this.random = options.random ?? Math.random;
+  }
+  // -----------------------------------------------------------------------
+  // Read model mutation (driven by the fleet room — task 009)
+  // -----------------------------------------------------------------------
+  /**
+   * Apply a validated full `fleet/state` snapshot to the read model. Returns `true`
+   * when applied, `false` when dropped as an out-of-order/duplicate frame.
+   *
+   * `seq` is per-connection monotonic (§7); a frame whose `seq` does not
+   * strictly exceed the last applied one is **dropped, never applied** — this
+   * turns a hypothetical agent-side send-queue bug into a lost frame instead of
+   * read-model corruption (§7, §14). Field validation (§13) happens upstream;
+   * this method trusts the payload's shape.
+   */
+  applySnapshot(instanceId, payload, lastSyncAt) {
+    const existing = this.records.get(instanceId);
+    if (existing !== void 0 && payload.seq <= existing.lastSeq) {
+      this.logger.warning(
+        `fleet: dropped out-of-order snapshot from instance=${instanceId} (seq=${payload.seq} <= last=${existing.lastSeq})`
+      );
+      return false;
+    }
+    const info = buildInstanceInfo(instanceId, payload, lastSyncAt);
+    const joinSeq = existing?.joinSeq ?? ++this.joinCounter;
+    this.records.set(instanceId, { info, lastSeq: payload.seq, lastHash: payload.hash, joinSeq });
+    this.invalidate();
+    this.clearPendingVisibility(instanceId);
+    this.reconcilePendingStatus(instanceId);
+    return true;
+  }
+  /**
+   * Bump an instance's `lastSyncAt` without touching semantic state (used on
+   * a hash-only `fleet/state` reply). Deliberately does **not** affect `stateHash` — liveness
+   * bookkeeping is excluded so a quiet fleet still produces ETag 304s (§6, §10).
+   */
+  touch(instanceId, lastSyncAt) {
+    const record = this.records.get(instanceId);
+    if (record === void 0) {
+      return;
+    }
+    record.info.lastSyncAt = lastSyncAt;
+    this.clearPendingVisibility(instanceId);
+    this.reconcilePendingStatus(instanceId);
+    const cached = this.resolvedView?.byId.get(instanceId);
+    if (cached !== void 0) {
+      cached.lastSyncAt = lastSyncAt;
+    }
+  }
+  /** Remove an instance from the read model (socket close or eviction, §7). */
+  removeInstance(instanceId) {
+    const record = this.records.get(instanceId);
+    if (record === void 0) {
+      return null;
+    }
+    this.records.delete(instanceId);
+    this.staleInstances.delete(instanceId);
+    this.pendingStatus.delete(instanceId);
+    this.clearPendingVisibility(instanceId);
+    this.invalidate();
+    return record.info;
+  }
+  /**
+   * Mark/unmark an instance stale (orchestrator liveness — §7). A stale instance
+   * stays in the read model and the `stateHash` (so dashboards keep seeing it
+   * until eviction) but is dropped from auto-placement candidacy. Cleared
+   * automatically on {@link removeInstance}.
+   */
+  setStale(instanceId, stale) {
+    if (stale) {
+      this.staleInstances.add(instanceId);
+    } else {
+      this.staleInstances.delete(instanceId);
+    }
+  }
+  /**
+   * Record an agent-acked-but-not-yet-snapshotted status for PLACEMENT only
+   * (task 004) — called on a `drain`/`undrain` ack, where the agent has already
+   * flipped its status (§7) but the read model lags by up to one poll. `place()`
+   * reads this through {@link effectiveStatus} so candidacy converges at ack time
+   * (`drain` excludes the node, `undrain` re-includes it) instead of one poll
+   * interval later. Never writes the agent-owned read-model `status` and is absent
+   * from `stateHash`, so §7 status ownership and the §10 ETag are untouched. The
+   * override clears itself once a snapshot reconciles the matching status (see
+   * {@link reconcilePendingStatus}). No-op on an unknown instance — there is nothing
+   * to place onto, and a later join starts clean.
+   */
+  setPendingStatus(instanceId, status) {
+    if (!this.records.has(instanceId)) {
+      return;
+    }
+    this.pendingStatus.set(instanceId, status);
+  }
+  /** Hash of the last applied snapshot for an instance (sent as the poll `knownHash` for dedup, §7). */
+  lastHashOf(instanceId) {
+    return this.records.get(instanceId)?.lastHash ?? null;
+  }
+  // -----------------------------------------------------------------------
+  // Read model queries (§9)
+  // -----------------------------------------------------------------------
+  get instances() {
+    return [...this.resolve().instances];
+  }
+  get rooms() {
+    const rooms = [];
+    for (const instance of this.resolve().instances) {
+      rooms.push(...instance.rooms);
+    }
+    return rooms;
+  }
+  get stats() {
+    const instances = this.resolve().instances;
+    let connections = 0;
+    let rooms = 0;
+    const roomTypes = /* @__PURE__ */ new Set();
+    for (const instance of instances) {
+      connections += instance.connections;
+      rooms += instance.rooms.length;
+      for (const type of instance.roomTypes) {
+        roomTypes.add(type);
+      }
+    }
+    if (this.cachedStateHash === null) {
+      this.cachedStateHash = this.computeStateHash(instances);
+      this.logger.debug("fleet: computed semantic state hash");
+    }
+    return {
+      instances: instances.length,
+      rooms,
+      connections,
+      roomTypes: [...roomTypes].sort(),
+      stateHash: this.cachedStateHash
+    };
+  }
+  getInstance(id) {
+    return this.resolve().byId.get(id) ?? null;
+  }
+  /**
+   * Resolve an instance by its stable `processUid` (§6 pinning) to the **most
+   * recent connection** — the record with the highest `joinSeq` (task 011). During
+   * a reconnect overlap two records share a `processUid` (the live new connection
+   * plus the old wedged one not yet evicted, up to 3 poll intervals); `processUid`
+   * is the documented *stable* handle across reconnects, so it must resolve to the
+   * live connection. First-match (map insertion order) would pick the OLDEST — the
+   * dead connection in exactly the scenario `processUid` pinning exists for.
+   */
+  getInstanceByProcessUid(processUid) {
+    const record = this.latestRecordByProcessUid(processUid);
+    return record === null ? null : this.resolve().byId.get(record.info.id) ?? null;
+  }
+  /** Look up a room by its PUBLIC id (canonical, namespaced, or percent-encoded — §11). */
+  getRoom(roomId) {
+    return this.resolve().byPublicId.get(roomId)?.room ?? null;
+  }
+  /**
+   * Map a public room id (possibly namespaced or percent-encoded) back to its
+   * owning instance and the RAW id the agent knows it by — what a `fleet/cmd`
+   * `destroy` must carry, since the agent never sees the public id (§11). Returns
+   * null when no room has that public id.
+   */
+  resolveRoom(roomId) {
+    const locator = this.resolve().byPublicId.get(roomId);
+    if (locator === void 0) {
+      return null;
+    }
+    return { instanceId: locator.instanceId, rawRoomId: locator.rawRoomId };
+  }
+  /** Rooms cluster-wide, filtered by type / owning instance / owning-instance labels (§9). */
+  findRooms(filter = {}) {
+    const result = [];
+    for (const instance of this.resolve().instances) {
+      if (filter.instanceId !== void 0 && instance.id !== filter.instanceId) {
+        continue;
+      }
+      if (filter.labels !== void 0 && !matchesLabels(instance.labels, filter.labels)) {
+        continue;
+      }
+      for (const room of instance.rooms) {
+        if (filter.type !== void 0 && room.type !== filter.type) {
+          continue;
+        }
+        result.push(room);
+      }
+    }
+    return result;
+  }
+  // -----------------------------------------------------------------------
+  // Placement (§9)
+  // -----------------------------------------------------------------------
+  /**
+   * Select an instance for a new room and reserve a capacity slot on it,
+   * atomically (§9). Throws a coded {@link FleetError} on validation /
+   * no-candidate / draining-pin. The reservation must be released by the
+   * caller on ack, timeout, or rejection.
+   */
+  place(request) {
+    if (request.instanceId !== void 0 && request.processUid !== void 0) {
+      throw new FleetError("VALIDATION", "specify at most one of placement.instanceId or placement.processUid");
+    }
+    if (request.instanceId !== void 0 || request.processUid !== void 0) {
+      const instance2 = request.instanceId !== void 0 ? this.rawInstanceById(request.instanceId) : this.rawInstanceByProcessUid(request.processUid);
+      if (instance2 === null) {
+        const which = request.instanceId !== void 0 ? `instanceId=${request.instanceId}` : `processUid=${request.processUid}`;
+        throw new FleetError("INSTANCE_NOT_FOUND", `no instance matches ${which}`);
+      }
+      if (this.effectiveStatus(instance2) === "draining" && request.force !== true) {
+        throw new FleetError(
+          "INSTANCE_DRAINING",
+          `instance ${instance2.id} is draining; pin requires force: true`
+        );
+      }
+      if (this.staleInstances.has(instance2.id) && request.force !== true) {
+        throw new FleetError(
+          "INSTANCE_DISCONNECTED",
+          `instance ${instance2.id} is stale (missed poll replies); pin requires force: true`
+        );
+      }
+      if (!instance2.autoCreate) {
+        throw new FleetError("NO_CANDIDATE", `instance ${instance2.id} has autoCreate disabled`);
+      }
+      return { instance: instance2, reservation: this.reserve(instance2.id) };
+    }
+    const candidates = this.rawInstances().filter(
+      (instance2) => this.effectiveStatus(instance2) === "active" && !this.staleInstances.has(instance2.id) && instance2.autoCreate === true && instance2.roomTypes.includes(request.type) && (request.labels === void 0 || matchesLabels(instance2.labels, request.labels)) && this.hasHeadroom(instance2)
+    );
+    if (candidates.length === 0) {
+      throw new FleetError("NO_CANDIDATE", `no active instance can host room type "${request.type}"`);
+    }
+    const instance = this.pick(candidates, request.strategy ?? "least-loaded");
+    return { instance, reservation: this.reserve(instance.id) };
+  }
+  /** Release a capacity reservation (on ack, timeout, or rejection — §9). Idempotent. */
+  release(reservation) {
+    if (!this.reservations.delete(reservation.id)) {
+      return;
+    }
+    const count = this.reservedByInstance.get(reservation.instanceId) ?? 0;
+    if (count <= 1) {
+      this.reservedByInstance.delete(reservation.instanceId);
+    } else {
+      this.reservedByInstance.set(reservation.instanceId, count - 1);
+    }
+  }
+  /** Reserved (in-flight) room slots currently held against an instance. */
+  reservedRooms(instanceId) {
+    return this.reservedByInstance.get(instanceId) ?? 0;
+  }
+  // -----------------------------------------------------------------------
+  // Room-id uniqueness & reservation (§11)
+  // -----------------------------------------------------------------------
+  /**
+   * Validate, uniqueness-check, and reserve a room id for an in-flight create
+   * (§11). When `roomId` is omitted a collision-free `r_<id>` within the charset
+   * is generated. Throws {@link FleetError} `VALIDATION` (explicit id outside the
+   * charset) or `ROOM_EXISTS` (id already in the fleet or already reserved). The
+   * reservation closes the race window: two concurrent creates with the same
+   * explicit id cannot both pass — exactly one reserves, the rest fail fast. The
+   * caller must `releaseRoomId` on ack, timeout, or rejection.
+   */
+  reserveRoomId(roomId) {
+    if (roomId === void 0) {
+      const generated = this.generateFreeRoomId();
+      this.reservedRoomIds.add(generated);
+      return { roomId: generated };
+    }
+    if (!isValidRoomId(roomId)) {
+      throw new FleetError("VALIDATION", `roomId "${roomId}" must match ${ROOM_ID_PATTERN.source}`);
+    }
+    if (this.isRoomIdTaken(roomId)) {
+      throw new FleetError("ROOM_EXISTS", `room id "${roomId}" already exists or is reserved`);
+    }
+    this.reservedRoomIds.add(roomId);
+    return { roomId };
+  }
+  /** Release a room-id reservation (on ack, timeout, or rejection — §11). Idempotent. */
+  releaseRoomId(reservation) {
+    this.reservedRoomIds.delete(reservation.roomId);
+  }
+  /**
+   * Transition a create's reservations from *in-flight* to *pending-visibility*
+   * (task 003) — called by the command engine when a create **acks OK or times
+   * out**, instead of releasing. The room id stays reserved and one `maxRooms` slot
+   * stays counted until the owning instance's next snapshot/poll reconciles the room
+   * into the read model (or it is evicted). This closes the §11 window where a
+   * `504`-then-retry (§10) or an ack-then-immediate re-create would re-reserve the id
+   * after the command settled but before the room was visible, and double-create it on
+   * another instance. The original capacity reservation token is released and both
+   * holds collapse into one pending-visibility entry (still one id, one room slot).
+   */
+  holdUntilVisible(roomIdReservation, reservation) {
+    this.release(reservation);
+    this.reservedRoomIds.delete(roomIdReservation.roomId);
+    if (this.pendingRoomIds.has(roomIdReservation.roomId)) {
+      return;
+    }
+    this.pendingRoomIds.set(roomIdReservation.roomId, reservation.instanceId);
+    this.pendingByInstance.set(
+      reservation.instanceId,
+      (this.pendingByInstance.get(reservation.instanceId) ?? 0) + 1
+    );
+  }
+  /** Acked-but-not-yet-visible room slots held against an instance (task 003). */
+  pendingRooms(instanceId) {
+    return this.pendingByInstance.get(instanceId) ?? 0;
+  }
+  // -----------------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------------
+  /**
+   * A public id is taken when an in-flight reservation holds it, a settled-but-not-
+   * yet-visible create holds it (task 003), or a live room already uses it.
+   */
+  isRoomIdTaken(roomId) {
+    return this.reservedRoomIds.has(roomId) || this.pendingRoomIds.has(roomId) || this.getRoom(roomId) !== null;
+  }
+  /**
+   * Clear every pending-visibility hold for an instance (task 003) — called when the
+   * instance's snapshot/poll reconciles its room set (the read model now holds
+   * whatever rooms truly exist) or when it is evicted (its rooms vanish). Either way
+   * the in-flight hold has done its job: a present room is taken via the read model,
+   * an absent one is genuinely free. Idempotent.
+   */
+  clearPendingVisibility(instanceId) {
+    if (this.pendingByInstance.get(instanceId) === void 0) {
+      return;
+    }
+    for (const [roomId, owner] of [...this.pendingRoomIds]) {
+      if (owner === instanceId) {
+        this.pendingRoomIds.delete(roomId);
+      }
+    }
+    this.pendingByInstance.delete(instanceId);
+  }
+  /**
+   * The status `place()` should treat the instance as having (task 004): the
+   * pending placement override when one is held, else the snapshot-derived
+   * read-model `status`. The override exists only between a `drain`/`undrain` ack
+   * and the snapshot that confirms it.
+   */
+  effectiveStatus(instance) {
+    return this.pendingStatus.get(instance.id) ?? instance.status;
+  }
+  /**
+   * Drop the placement override once the read model has caught up (task 004) — i.e.
+   * the last-applied snapshot's status now equals the pending value. Called on every
+   * snapshot apply and hash-only poll reply. Idempotent; no-op when no override is held.
+   */
+  reconcilePendingStatus(instanceId) {
+    const pending = this.pendingStatus.get(instanceId);
+    if (pending !== void 0 && this.records.get(instanceId)?.info.status === pending) {
+      this.pendingStatus.delete(instanceId);
+    }
+  }
+  /** Generate a `r_<id>` not currently reserved or in use; near-certain on the first try. */
+  generateFreeRoomId() {
+    for (let attempt = 0; attempt < 1e3; attempt++) {
+      const candidate = generateRoomId();
+      if (!this.isRoomIdTaken(candidate)) {
+        return candidate;
+      }
+    }
+    throw new FleetError("ROOM_EXISTS", "could not generate a unique room id after 1000 attempts");
+  }
+  /** Raw read-model rows (raw room ids) — the placement candidate source. */
+  rawInstances() {
+    return [...this.records.values()].map((record) => record.info);
+  }
+  rawInstanceById(id) {
+    return this.records.get(id)?.info ?? null;
+  }
+  rawInstanceByProcessUid(processUid) {
+    return this.latestRecordByProcessUid(processUid)?.info ?? null;
+  }
+  /**
+   * The record for `processUid` with the highest `joinSeq` — the most recent
+   * connection (task 011). Shared by {@link getInstanceByProcessUid} (read API)
+   * and the pinned {@link place} path so both resolve a reconnect-overlapped
+   * `processUid` to the live connection, never the wedged old one.
+   */
+  latestRecordByProcessUid(processUid) {
+    let latest = null;
+    for (const record of this.records.values()) {
+      if (record.info.processUid === processUid && (latest === null || record.joinSeq > latest.joinSeq)) {
+        latest = record;
+      }
+    }
+    return latest;
+  }
+  /**
+   * Resolve raw agent-reported room ids into the fleet-unique PUBLIC id space
+   * (§11). Pure function of the current read model — derivable from snapshots
+   * alone (§3), so it survives an orchestrator restart. Rules:
+   *  - Local ids outside the charset are percent-encoded ({@link encodeRoomId}).
+   *  - When several rooms map to the same base id, exactly one keeps it: a
+   *    `fleet` room beats a `local` one, then the earliest joiner wins, then the
+   *    lower instance id (deterministic — never map-iteration order). The losers
+   *    surface namespaced as `<processUid>~<base>`, flagged `local` per their own
+   *    origin. Two `fleet` rooms colliding can only happen across a restart, so
+   *    that case is logged naming both instances (post-restart tie-break, §11).
+   */
+  resolve() {
+    if (this.resolvedView !== null) {
+      return this.resolvedView;
+    }
+    const entries = [];
+    for (const record of this.records.values()) {
+      for (const room of record.info.rooms) {
+        entries.push({
+          instanceId: record.info.id,
+          processUid: record.info.processUid,
+          joinSeq: record.joinSeq,
+          rawId: room.id,
+          base: encodeRoomId(room.id),
+          origin: room.local ? "local" : "fleet",
+          room,
+          publicId: ""
+        });
+      }
+    }
+    const groups = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      const bucket = groups.get(entry.base);
+      if (bucket === void 0) {
+        groups.set(entry.base, [entry]);
+      } else {
+        bucket.push(entry);
+      }
+    }
+    for (const [base, bucket] of groups) {
+      if (bucket.length === 1) {
+        bucket[0].publicId = base;
+        continue;
+      }
+      const ordered = [...bucket].sort(compareForCanonical);
+      const keeper = ordered[0];
+      keeper.publicId = base;
+      for (const entry of ordered) {
+        if (entry !== keeper) {
+          entry.publicId = namespaceRoomId(entry.processUid, base);
+        }
+      }
+      const fleetDuplicates = ordered.filter((entry) => entry.origin === "fleet");
+      if (fleetDuplicates.length > 1) {
+        for (const loser of fleetDuplicates) {
+          if (loser !== keeper) {
+            this.logger.warning(
+              `fleet: duplicate room id "${base}" reported by instance ${keeper.instanceId} (joined earliest, keeps the canonical id) and instance ${loser.instanceId} (surfaced as "${loser.publicId}") \u2014 \xA711 post-restart tie-break, no room hidden or destroyed`
+            );
+          }
+        }
+      }
+    }
+    const roomsByInstance = /* @__PURE__ */ new Map();
+    const byPublicId = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      const room = { ...entry.room, id: entry.publicId };
+      const list = roomsByInstance.get(entry.instanceId);
+      if (list === void 0) {
+        roomsByInstance.set(entry.instanceId, [room]);
+      } else {
+        list.push(room);
+      }
+      byPublicId.set(entry.publicId, { room, instanceId: entry.instanceId, rawRoomId: entry.rawId });
+    }
+    const instances = [];
+    const byId = /* @__PURE__ */ new Map();
+    for (const record of this.records.values()) {
+      const instance = { ...record.info, rooms: roomsByInstance.get(record.info.id) ?? [] };
+      instances.push(instance);
+      byId.set(instance.id, instance);
+    }
+    this.logger.debug("fleet: rebuilt id-resolution view");
+    this.resolvedView = { instances, byId, byPublicId };
+    return this.resolvedView;
+  }
+  /**
+   * Drop the memoized resolution + state hash. Called by the two SEMANTIC
+   * mutations only ({@link applySnapshot}, {@link removeInstance}); the next read
+   * rebuilds. Non-semantic mutations ({@link touch}, {@link setStale}) never call
+   * this — see {@link resolvedView}.
+   */
+  invalidate() {
+    this.resolvedView = null;
+    this.cachedStateHash = null;
+  }
+  reserve(instanceId) {
+    const id = `res_${++this.reservationSeq}`;
+    this.reservations.set(id, instanceId);
+    this.reservedByInstance.set(instanceId, (this.reservedByInstance.get(instanceId) ?? 0) + 1);
+    return { id, instanceId };
+  }
+  /**
+   * Headroom against capacity, counting in-flight reservations as rooms (§9).
+   * A pending create occupies a room slot but contributes no connections (the
+   * room is empty until clients join), so reservations gate `maxRooms` only;
+   * `maxConnections` is gated by the real connection count.
+   */
+  hasHeadroom(instance) {
+    const capacity = instance.capacity;
+    if (capacity.maxRooms !== null) {
+      const projected = instance.rooms.length + this.reservedRooms(instance.id) + this.pendingRooms(instance.id);
+      if (projected >= capacity.maxRooms) {
+        return false;
+      }
+    }
+    if (capacity.maxConnections !== null && instance.connections >= capacity.maxConnections) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Pick among filtered candidates (§9 steps 2–3). `least-loaded`/`most-loaded`
+   * score by `connections / maxConnections` only when *every* candidate
+   * declares `maxConnections`; if any leaves it undeclared, all are scored by
+   * raw `connections` (a normalized 0.93 and a raw 1500 are not comparable).
+   * Ties are broken randomly; `random` ignores load entirely.
+   */
+  pick(candidates, strategy) {
+    if (strategy === "random") {
+      return this.choose(candidates);
+    }
+    const allDeclare = candidates.every((instance) => instance.capacity.maxConnections !== null);
+    const scoreOf = (instance) => allDeclare ? instance.connections / instance.capacity.maxConnections : instance.connections;
+    let best = scoreOf(candidates[0]);
+    for (const instance of candidates) {
+      const score = scoreOf(instance);
+      best = strategy === "most-loaded" ? Math.max(best, score) : Math.min(best, score);
+    }
+    const tied = candidates.filter((instance) => scoreOf(instance) === best);
+    return this.choose(tied);
+  }
+  /** Uniform random choice from a non-empty list (placement tie-break / `random` strategy). */
+  choose(list) {
+    const index = Math.floor(this.random() * list.length);
+    return list[Math.min(index, list.length - 1)];
+  }
+  /**
+   * Hash of SEMANTIC fleet state only (§6): instances, rooms, counts, statuses,
+   * capacities, versions — explicitly EXCLUDING `lastSyncAt` and all liveness
+   * bookkeeping, so the §10 ETag does not churn on every heartbeat. Order-
+   * independent: instances are sorted by id before encoding.
+   */
+  computeStateHash(instances) {
+    const projection = instances.map((instance) => ({
+      id: instance.id,
+      name: instance.name,
+      processUid: instance.processUid,
+      endpointUrl: instance.endpointUrl,
+      labels: instance.labels,
+      roomTypes: instance.roomTypes,
+      connections: instance.connections,
+      capacity: instance.capacity,
+      autoCreate: instance.autoCreate,
+      status: instance.status,
+      agentVersion: instance.agentVersion,
+      protocolVersion: instance.protocolVersion,
+      rooms: instance.rooms.map((room) => ({
+        id: room.id,
+        type: room.type,
+        connections: room.connections,
+        instanceId: room.instanceId,
+        endpointUrl: room.endpointUrl,
+        local: room.local
+      }))
+    })).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    return hash64(projection);
+  }
+};
+function buildInstanceInfo(instanceId, payload, lastSyncAt) {
+  const rooms = payload.rooms.map((room) => ({
+    id: room.id,
+    type: room.type,
+    connections: room.connections,
+    instanceId,
+    // Denormalized from the owning instance so room lookups carry the URL (§6).
+    endpointUrl: payload.endpointUrl,
+    // Provenance is the agent's call, never inferred here (§6).
+    local: room.origin === "local"
+  }));
+  let connections = 0;
+  for (const room of rooms) {
+    connections += room.connections;
+  }
+  return {
+    id: instanceId,
+    name: payload.name,
+    processUid: payload.processUid,
+    endpointUrl: payload.endpointUrl,
+    labels: payload.labels,
+    roomTypes: payload.roomTypes,
+    rooms,
+    connections,
+    capacity: payload.capacity,
+    autoCreate: payload.autoCreate,
+    status: payload.status,
+    lastSyncAt,
+    agentVersion: payload.agentVersion,
+    protocolVersion: payload.protocolVersion
+  };
+}
+function matchesLabels(instanceLabels, required) {
+  for (const key of Object.keys(required)) {
+    if (instanceLabels[key] !== required[key]) {
+      return false;
+    }
+  }
+  return true;
+}
+function compareForCanonical(a, b) {
+  const rankA = a.origin === "fleet" ? 0 : 1;
+  const rankB = b.origin === "fleet" ? 0 : 1;
+  if (rankA !== rankB) {
+    return rankA - rankB;
+  }
+  if (a.joinSeq !== b.joinSeq) {
+    return a.joinSeq - b.joinSeq;
+  }
+  return a.instanceId < b.instanceId ? -1 : a.instanceId > b.instanceId ? 1 : 0;
+}
+var ROOM_ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+var ROOM_ID_RANDOM_LENGTH = 21;
+function generateRoomId() {
+  const bytes = (0, import_node_crypto2.randomBytes)(ROOM_ID_RANDOM_LENGTH);
+  let id = "r_";
+  for (let i = 0; i < ROOM_ID_RANDOM_LENGTH; i++) {
+    id += ROOM_ID_ALPHABET[bytes[i] & 63];
+  }
+  return id;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FleetError,
+  FleetState
+});