@adhdev/mesh-shared 1.0.56-rc.9 → 1.0.56

package/dist/index.d.ts

@@ -24,3 +24,4 @@ export * from './slot-proposal';
 export * from './interpolation';
 export * from './mesh-tool-names';
 export * from './mesh-status-probe';
+export * from './rpc-chunking';

package/dist/index.js

@@ -25,7 +25,14 @@ __export(index_exports, {
   CLI_SLOT_RECIPES: () => CLI_SLOT_RECIPES,
   DEFAULT_DIFFICULTY_BRAINS: () => DEFAULT_DIFFICULTY_BRAINS,
   MAGI_RAW_ANSWER_CAP: () => MAGI_RAW_ANSWER_CAP,
+  MESH_CHUNK_KIND: () => MESH_CHUNK_KIND,
+  MESH_CHUNK_PAYLOAD_CHARS: () => MESH_CHUNK_PAYLOAD_CHARS,
+  MESH_CHUNK_TTL_MS: () => MESH_CHUNK_TTL_MS,
+  MESH_MAX_CHUNKS: () => MESH_MAX_CHUNKS,
+  MESH_MAX_INLINE_FRAME_BYTES: () => MESH_MAX_INLINE_FRAME_BYTES,
+  MESH_MAX_REASSEMBLED_BYTES: () => MESH_MAX_REASSEMBLED_BYTES,
   MESH_TASK_DIFFICULTIES: () => MESH_TASK_DIFFICULTIES,
+  MeshChunkAssembler: () => MeshChunkAssembler,
   QUOTA_SUPPORTED_PROVIDERS: () => QUOTA_SUPPORTED_PROVIDERS,
   STATUS_PROBE_ARG_KEY: () => STATUS_PROBE_ARG_KEY,
   UNKNOWN_CLI_SLOT_RECIPE: () => UNKNOWN_CLI_SLOT_RECIPE,
@@ -46,7 +53,10 @@ __export(index_exports, {
   isRawDaemonDoId: () => isRawDaemonDoId,
   joinRepoPath: () => joinRepoPath,
   machineCoreFromDaemonId: () => machineCoreFromDaemonId,
+  measureWorstCaseChunkEnvelopeBytes: () => measureWorstCaseChunkEnvelopeBytes,
+  meshFrameNeedsChunking: () => meshFrameNeedsChunking,
   meshNodeIdMatches: () => meshNodeIdMatches,
+  meshUtf8ByteLength: () => meshUtf8ByteLength,
   meshWorkspacesEquivalent: () => meshWorkspacesEquivalent,
   normalizeBrainSlot: () => normalizeBrainSlot,
   normalizeDifficultyBrainMap: () => normalizeDifficultyBrainMap,
@@ -69,6 +79,7 @@ __export(index_exports, {
   scoreGitStatusCandidate: () => scoreGitStatusCandidate,
   scoreGitUpstreamFreshness: () => scoreGitUpstreamFreshness,
   sessionIdsEquivalent: () => sessionIdsEquivalent,
+  splitMeshFrame: () => splitMeshFrame,
   stripStatusProbeMarker: () => stripStatusProbeMarker,
   summarizeGitShape: () => summarizeGitShape,
   supportsQuota: () => supportsQuota,
@@ -807,6 +818,183 @@ function stripStatusProbeMarker(args) {
   const { [STATUS_PROBE_ARG_KEY]: _drop, ...rest } = args;
   return rest;
 }
+
+// src/rpc-chunking.ts
+var MESH_MAX_INLINE_FRAME_BYTES = 6e4;
+var MESH_CHUNK_PAYLOAD_CHARS = 16e3;
+var MESH_MAX_CHUNKS = 1024;
+var MESH_MAX_REASSEMBLED_BYTES = 16e6;
+var MESH_CHUNK_TTL_MS = 6e4;
+var MESH_CHUNK_KIND = "rpc_chunk";
+function meshUtf8ByteLength(value) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(value).byteLength;
+  let bytes = 0;
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 55296 && code <= 56319) {
+      bytes += 4;
+      i += 1;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+function measureWorstCaseChunkEnvelopeBytes() {
+  const densest = "\uD55C".repeat(MESH_CHUNK_PAYLOAD_CHARS);
+  return meshUtf8ByteLength(JSON.stringify(
+    buildChunkEnvelope(Number.MAX_SAFE_INTEGER, "x".repeat(64), MESH_MAX_CHUNKS, MESH_MAX_CHUNKS, densest)
+  ));
+}
+function meshFrameNeedsChunking(json) {
+  return meshUtf8ByteLength(json) > MESH_MAX_INLINE_FRAME_BYTES;
+}
+function buildChunkEnvelope(version, chunkId, index, total, data) {
+  return { v: version, kind: MESH_CHUNK_KIND, chunkId, index, total, data };
+}
+function splitMeshFrame(json, chunkId, version) {
+  const slices = [];
+  let offset = 0;
+  while (offset < json.length) {
+    let end = Math.min(json.length, offset + MESH_CHUNK_PAYLOAD_CHARS);
+    while (end > offset) {
+      const candidate = json.slice(offset, end);
+      const probe = JSON.stringify(buildChunkEnvelope(version, chunkId, slices.length, MESH_MAX_CHUNKS, candidate));
+      if (meshUtf8ByteLength(probe) <= MESH_MAX_INLINE_FRAME_BYTES) break;
+      const shrunk = Math.max(1, Math.floor((end - offset) * 0.8));
+      if (offset + shrunk >= end) {
+        end -= 1;
+        continue;
+      }
+      end = offset + shrunk;
+    }
+    if (end <= offset) {
+      return { ok: false, reason: "chunk_too_large", detail: "a single character did not fit the chunk envelope budget" };
+    }
+    slices.push(json.slice(offset, end));
+    if (slices.length > MESH_MAX_CHUNKS) {
+      return {
+        ok: false,
+        reason: "too_many_chunks",
+        detail: `frame needs more than ${MESH_MAX_CHUNKS} chunks (${meshUtf8ByteLength(json)} bytes)`
+      };
+    }
+    offset = end;
+  }
+  if (slices.length === 0) {
+    return { ok: false, reason: "chunk_too_large", detail: "refusing to chunk an empty frame" };
+  }
+  const total = slices.length;
+  return { ok: true, chunks: slices.map((data, index) => buildChunkEnvelope(version, chunkId, index, total, data)) };
+}
+var MeshChunkAssembler = class {
+  constructor(now = () => Date.now()) {
+    this.now = now;
+  }
+  buffers = /* @__PURE__ */ new Map();
+  /** True when the frame is a chunk envelope this assembler should handle. */
+  static isChunkFrame(frame) {
+    return !!frame && typeof frame === "object" && frame.kind === MESH_CHUNK_KIND;
+  }
+  /** Drop partials older than the TTL so a dead sender cannot pin memory. */
+  sweep() {
+    const now = this.now();
+    for (const [key, entry] of Array.from(this.buffers.entries())) {
+      if (now - entry.createdAt > MESH_CHUNK_TTL_MS) this.buffers.delete(key);
+    }
+  }
+  /** Discard any partial state for a peer (call on disconnect). */
+  reset() {
+    this.buffers.clear();
+  }
+  /** Number of frames currently mid-reassembly — for tests and diagnostics. */
+  get pendingCount() {
+    return this.buffers.size;
+  }
+  /**
+   * Accept one chunk envelope.
+   *
+   * Never throws and never returns a partially-applied frame: the result is exactly one
+   * of partial / complete / failed, and `failed` carries a typed reason the transport
+   * turns into an explicit RPC error.
+   */
+  accept(frame) {
+    this.sweep();
+    const raw = frame;
+    const chunkId = typeof raw?.chunkId === "string" ? raw.chunkId : "";
+    const index = Number(raw?.index);
+    const total = Number(raw?.total);
+    const data = typeof raw?.data === "string" ? raw.data : "";
+    if (!chunkId || !Number.isInteger(index) || !Number.isInteger(total) || index < 0 || total <= 0 || index >= total || !data) {
+      return {
+        status: "failed",
+        reason: "malformed_chunk",
+        detail: `malformed chunk envelope (chunkId=${chunkId || "-"} index=${raw?.index} total=${raw?.total})`,
+        chunkId
+      };
+    }
+    if (total > MESH_MAX_CHUNKS) {
+      this.buffers.delete(chunkId);
+      return {
+        status: "failed",
+        reason: "too_many_chunks",
+        detail: `chunk total ${total} exceeds the ${MESH_MAX_CHUNKS} cap`,
+        chunkId
+      };
+    }
+    let entry = this.buffers.get(chunkId);
+    if (!entry) {
+      entry = { total, chunks: new Array(total).fill(""), received: 0, bytesReceived: 0, createdAt: this.now() };
+      this.buffers.set(chunkId, entry);
+    } else if (entry.total !== total) {
+      this.buffers.delete(chunkId);
+      return {
+        status: "failed",
+        reason: "inconsistent_total",
+        detail: `chunk ${index} declares total ${total} but the group was opened with ${entry.total}`,
+        chunkId
+      };
+    }
+    const existing = entry.chunks[index];
+    if (existing) {
+      if (existing === data) return { status: "partial", received: entry.received, total: entry.total };
+      this.buffers.delete(chunkId);
+      return {
+        status: "failed",
+        reason: "duplicate_chunk_mismatch",
+        detail: `chunk ${index} arrived twice with different content`,
+        chunkId
+      };
+    }
+    const chunkBytes = meshUtf8ByteLength(data);
+    if (entry.bytesReceived + chunkBytes > MESH_MAX_REASSEMBLED_BYTES) {
+      this.buffers.delete(chunkId);
+      return {
+        status: "failed",
+        reason: "budget_exceeded",
+        detail: `reassembled frame would exceed ${MESH_MAX_REASSEMBLED_BYTES} bytes`,
+        chunkId
+      };
+    }
+    entry.chunks[index] = data;
+    entry.received += 1;
+    entry.bytesReceived += chunkBytes;
+    if (entry.received < entry.total) {
+      return { status: "partial", received: entry.received, total: entry.total };
+    }
+    this.buffers.delete(chunkId);
+    try {
+      return { status: "complete", frame: JSON.parse(entry.chunks.join("")) };
+    } catch (error) {
+      return {
+        status: "failed",
+        reason: "reassembled_parse_failed",
+        detail: `reassembled frame is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        chunkId
+      };
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CANONICAL_MESH_TOOL_COUNT,
@@ -814,7 +1002,14 @@ function stripStatusProbeMarker(args) {
   CLI_SLOT_RECIPES,
   DEFAULT_DIFFICULTY_BRAINS,
   MAGI_RAW_ANSWER_CAP,
+  MESH_CHUNK_KIND,
+  MESH_CHUNK_PAYLOAD_CHARS,
+  MESH_CHUNK_TTL_MS,
+  MESH_MAX_CHUNKS,
+  MESH_MAX_INLINE_FRAME_BYTES,
+  MESH_MAX_REASSEMBLED_BYTES,
   MESH_TASK_DIFFICULTIES,
+  MeshChunkAssembler,
   QUOTA_SUPPORTED_PROVIDERS,
   STATUS_PROBE_ARG_KEY,
   UNKNOWN_CLI_SLOT_RECIPE,
@@ -835,7 +1030,10 @@ function stripStatusProbeMarker(args) {
   isRawDaemonDoId,
   joinRepoPath,
   machineCoreFromDaemonId,
+  measureWorstCaseChunkEnvelopeBytes,
+  meshFrameNeedsChunking,
   meshNodeIdMatches,
+  meshUtf8ByteLength,
   meshWorkspacesEquivalent,
   normalizeBrainSlot,
   normalizeDifficultyBrainMap,
@@ -858,6 +1056,7 @@ function stripStatusProbeMarker(args) {
   scoreGitStatusCandidate,
   scoreGitUpstreamFreshness,
   sessionIdsEquivalent,
+  splitMeshFrame,
   stripStatusProbeMarker,
   summarizeGitShape,
   supportsQuota,