paseo-plugin-zcode-provider 0.0.0-stage → 0.2.0

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-codec.ts

@@ -0,0 +1,240 @@
+// V4 physical wire encoder：按调用方真实 JSON/RPC envelope 计量，logical frame
+// 超过物理上限时只在 UTF-8 bytes 层分片，不改变 seq/apply 语义。
+import { PROTOCOL_V4_LIMITS, V4_WIRE_PROTOCOL_VERSION } from "./core.js";
+import { crc32WireBytes, encodeWireBytesBase64 } from "./wire-binary.js";
+import type {
+  TopicFrameDeliveryKind,
+  TopicWireChecksum,
+  TopicWireFrame,
+  TopicWireFrameCandidate,
+} from "./wire.js";
+
+const CHANNEL_EVENT_RESPONSE_TYPE = 204;
+const SOCKET_PROTOCOL_HEADER_BYTES = 13;
+
+function vqlByteLength(value: number): number {
+  let bytes = 1;
+  for (let remaining = value >>> 7; remaining > 0; remaining >>>= 7) bytes += 1;
+  return bytes;
+}
+
+/**
+ * 按当前生产三层真实承载计量 topic notification。mobile relay
+ * 会把 Channel binary 再 base64，不能只测 CLI 的 logical JSON。
+ */
+export function measureTopicNotificationEnvelopeBytes(wire: TopicWireFrameCandidate): {
+  cliNdjsonBytes: number;
+  channelSocketBytes: number;
+  mobileRelayBytes: number;
+  maxBytes: number;
+} {
+  const cliNdjsonBytes =
+    utf8JsonByteLength({
+      method: "v4/conversation/frame",
+      params: wire,
+    }) + 1;
+
+  const wireJsonBytes = utf8JsonByteLength(wire);
+  // @zcode/rpc serialization：Array tag+length+[EventFire,id]，再加 Object tag+length+JSON。
+  // ChannelClient 的 id 无 31-bit wrap；超过 signed int 后 serialize 会走 Object JSON
+  // fallback。因此按 Number.MAX_SAFE_INTEGER 的 16-byte JSON 形态计算最坏 header。
+  const maxEventIdJsonBytes = String(Number.MAX_SAFE_INTEGER).length;
+  const maxEventIdSerializedBytes = 1 + vqlByteLength(maxEventIdJsonBytes) + maxEventIdJsonBytes;
+  const channelHeaderBytes =
+    1 +
+    vqlByteLength(2) +
+    1 +
+    vqlByteLength(CHANNEL_EVENT_RESPONSE_TYPE) +
+    maxEventIdSerializedBytes;
+  const channelPayloadBytes = channelHeaderBytes + 1 + vqlByteLength(wireJsonBytes) + wireJsonBytes;
+  // SocketProtocol/PersistentProtocol 在 Channel payload 外再加固定 13-byte frame header。
+  const channelSocketBytes = channelPayloadBytes + SOCKET_PROTOCOL_HEADER_BYTES;
+  // topic encoder 继续用 legacy 单片 outer 作为保守 logical budget；production 已不发送该形态，
+  // Channel payload 会再经 acknowledged raw adapter 独立分片并按最终 JSON 精确计量。
+  // 两层预算分别约束 topic logical frame 与 relay physical frame，不能互相替代。
+  const dataBase64Bytes = 4 * Math.ceil(channelPayloadBytes / 3);
+  const transportId = "x".repeat(PROTOCOL_V4_LIMITS.transportEnvelopeIdMaxChars);
+  const mobileRelayFixedBytes = utf8JsonByteLength({
+    type: "data",
+    payload: {
+      zcode_type: "rpc-frame",
+      bridgeSessionId: transportId,
+      bridgeGeneration: Number.MAX_SAFE_INTEGER,
+      recoveryId: transportId,
+      seq: Number.MAX_SAFE_INTEGER,
+      dataBase64: "",
+    },
+    client_ts: Number.MAX_SAFE_INTEGER,
+    server_ts: Number.MAX_SAFE_INTEGER,
+  });
+  const mobileRelayBytes = mobileRelayFixedBytes + dataBase64Bytes;
+  return {
+    cliNdjsonBytes,
+    channelSocketBytes,
+    mobileRelayBytes,
+    maxBytes: Math.max(cliNdjsonBytes, channelSocketBytes, mobileRelayBytes),
+  };
+}
+
+export function utf8JsonByteLength(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+
+function encodeJson(value: unknown): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(value));
+}
+
+export class TopicWireFrameEncodingError extends Error {
+  constructor(readonly reasonCode: string) {
+    super(reasonCode);
+    this.name = "TopicWireFrameEncodingError";
+  }
+}
+
+function hardBound(value: number | undefined, maximum: number, name: string): number {
+  const resolved = value ?? maximum;
+  if (!Number.isFinite(resolved) || resolved <= 0) {
+    throw new TopicWireFrameEncodingError(`proto.invalidLimit.${name}`);
+  }
+  return Math.min(Math.floor(resolved), maximum);
+}
+
+export interface EncodeTopicWireFramesOptions<F> {
+  deliveryKind: TopicFrameDeliveryKind;
+  topic: string;
+  subscriptionId: string;
+  logicalFrameId: string;
+  logicalFrameOrdinal: number;
+  maxPhysicalFrameBytes?: number;
+  maxAssemblyBytes?: number;
+  measurePhysicalFrameBytes(wire: TopicWireFrame<F>): number;
+}
+
+function makeFragment<F>(params: {
+  options: EncodeTopicWireFramesOptions<F>;
+  fragmentIndex: number;
+  fragmentCount: number;
+  logicalBytes: number;
+  checksum: TopicWireChecksum;
+  dataBase64: string;
+}): TopicWireFrame<F> {
+  return {
+    wireVersion: V4_WIRE_PROTOCOL_VERSION,
+    kind: "fragment",
+    deliveryKind: params.options.deliveryKind,
+    logicalFrameId: params.options.logicalFrameId,
+    logicalFrameOrdinal: params.options.logicalFrameOrdinal,
+    topic: params.options.topic,
+    subscriptionId: params.options.subscriptionId,
+    fragmentIndex: params.fragmentIndex,
+    fragmentCount: params.fragmentCount,
+    logicalBytes: params.logicalBytes,
+    checksum: params.checksum,
+    dataBase64: params.dataBase64,
+  };
+}
+
+function findFragmentByteBudget<F>(params: {
+  options: EncodeTopicWireFramesOptions<F>;
+  logicalBytes: number;
+  checksum: TopicWireChecksum;
+  maxPhysicalFrameBytes: number;
+}): number {
+  let low = 1;
+  let high = Math.min(params.logicalBytes, params.maxPhysicalFrameBytes);
+  let best = 0;
+  // 使用最坏索引位数测量，实际 fragment 的 envelope 只会更小。
+  const worstCount = params.logicalBytes;
+  while (low <= high) {
+    const candidate = Math.floor((low + high) / 2);
+    const dataBase64 = "A".repeat(4 * Math.ceil(candidate / 3));
+    const wire = makeFragment({
+      options: params.options,
+      fragmentIndex: Math.max(0, worstCount - 1),
+      fragmentCount: worstCount,
+      logicalBytes: params.logicalBytes,
+      checksum: params.checksum,
+      dataBase64,
+    });
+    if (params.options.measurePhysicalFrameBytes(wire) <= params.maxPhysicalFrameBytes) {
+      best = candidate;
+      low = candidate + 1;
+    } else {
+      high = candidate - 1;
+    }
+  }
+  return best;
+}
+
+export function encodeTopicWireFrames<F>(
+  frame: F,
+  options: EncodeTopicWireFramesOptions<F>,
+): TopicWireFrame<F>[] {
+  const maxPhysicalFrameBytes = hardBound(
+    options.maxPhysicalFrameBytes,
+    PROTOCOL_V4_LIMITS.maxFrameBytes,
+    "maxPhysicalFrameBytes",
+  );
+  const maxAssemblyBytes = hardBound(
+    options.maxAssemblyBytes,
+    PROTOCOL_V4_LIMITS.logicalFrameAssemblyMaxBytes,
+    "maxAssemblyBytes",
+  );
+  const logical = encodeJson(frame);
+  if (logical.byteLength > maxAssemblyBytes) {
+    throw new TopicWireFrameEncodingError("proto.frameAssemblyTooLarge");
+  }
+
+  const complete: TopicWireFrame<F> = {
+    wireVersion: V4_WIRE_PROTOCOL_VERSION,
+    kind: "complete",
+    deliveryKind: options.deliveryKind,
+    logicalFrameId: options.logicalFrameId,
+    logicalFrameOrdinal: options.logicalFrameOrdinal,
+    topic: options.topic,
+    subscriptionId: options.subscriptionId,
+    frame,
+  };
+  if (options.measurePhysicalFrameBytes(complete) <= maxPhysicalFrameBytes) {
+    return [complete];
+  }
+
+  const checksum: TopicWireChecksum = {
+    algorithm: "crc32",
+    value: crc32WireBytes(logical),
+  };
+  const chunkBytes = findFragmentByteBudget({
+    options,
+    logicalBytes: logical.byteLength,
+    checksum,
+    maxPhysicalFrameBytes,
+  });
+  if (chunkBytes < 1) {
+    throw new TopicWireFrameEncodingError("proto.frameEnvelopeTooLarge");
+  }
+  const fragmentCount = Math.ceil(logical.byteLength / chunkBytes);
+  if (fragmentCount > PROTOCOL_V4_LIMITS.logicalFrameAssemblyMaxFragments) {
+    throw new TopicWireFrameEncodingError("proto.frameFragmentCountExceeded");
+  }
+
+  const frames: TopicWireFrame<F>[] = [];
+  for (let fragmentIndex = 0; fragmentIndex < fragmentCount; fragmentIndex += 1) {
+    const start = fragmentIndex * chunkBytes;
+    const end = Math.min(start + chunkBytes, logical.byteLength);
+    const wire = makeFragment({
+      options,
+      fragmentIndex,
+      fragmentCount,
+      logicalBytes: logical.byteLength,
+      checksum,
+      dataBase64: encodeWireBytesBase64(logical.subarray(start, end)),
+    });
+    if (options.measurePhysicalFrameBytes(wire) > maxPhysicalFrameBytes) {
+      // physical 上限包含调用方真实 envelope；任何估算漂移都必须
+      // fail closed，不能把超限 frame 交给下游再静默截断。
+      throw new TopicWireFrameEncodingError("proto.frameEnvelopeTooLarge");
+    }
+    frames.push(wire);
+  }
+  return frames;
+}

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-fault.ts

@@ -0,0 +1,39 @@
+// V4 physical assembly fault 的分类：**内容确定性失败** vs 瞬态失败。
+//
+// 恢复阶梯默认把 fault 当瞬态处理：先 same-sub resync（服务端可能回 resume），再断档则升级
+// forceSnapshot，仍不成则 fail closed。这套升级对丢片、超时、校验和不符是对的——重投一次很可能
+// 就好了。对 **schema 拒收** 却是错的：字节已经过了 length/checksum/UTF-8/JSON 四道关，被拒说明
+// 本端读不懂对端发来的**内容**，而 resume 档只会把同一批 delta 再投一遍，必然同样被拒。
+//
+// 工具卡载荷出现不兼容字段时，重投相同内容无法恢复；应尝试快照后明确报告内容不兼容。
+//
+// 本模块只回答「这个 reason code 是不是确定性内容失败」，不决定怎么处置——处置在两个 store 里
+// （conversationProjectionStore / sessionsIndexStore）。
+
+/**
+ * 帧内容通过了 checksum/JSON，却没过 zod schema 的 reason code。
+ *
+ * 常量化而不是各处写字面量：判定这一侧与产出这一侧（wire-assembler、wire-reassembly）必须永远
+ * 是同一个词——两处分叉的症状正是本模块要修的那类静默失配。
+ */
+export const WIRE_FAULT_INVALID_PAYLOAD = "proto.frameAssemblyInvalidPayload";
+
+/**
+ * 这个 fault 是不是「同一份内容再投一次必然再被拒」的确定性失败。
+ *
+ * 目前只有 schema 拒收一个。刻意**不**把 `proto.frameAssemblyInvalidJson` 也算进来：JSON 不合法
+ * 也可能来自组装路径本身（分片拼接、编码边界），重投确实可能不同；把瞬态误判成确定性会让本该
+ * 自愈的 gap 停在原地，那是比多一次无用重试更坏的失败。按证据逐个加，不按猜测扩大。
+ */
+export function isDeterministicContentFault(reasonCode: string | undefined): boolean {
+  return reasonCode === WIRE_FAULT_INVALID_PAYLOAD;
+}
+
+/**
+ * 内容确定性失败走到底的客户端终态 code（`fault.subscription.*` 是 04-sync 的词表）。
+ *
+ * 与 `fault.subscription.recoveryFailed` 分开是有用的区分，不是命名洁癖：后者是「链路没恢复
+ * 过来」，重连有意义；本 code 是「本端读不懂对端发来的内容」，重连必然得到同样结果。遥测按
+ * code 聚合，两者混在一起会把一次版本失配读成一片网络抖动。
+ */
+export const SUBSCRIPTION_CONTENT_REJECTED = "fault.subscription.contentRejected";

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire.ts

@@ -0,0 +1,159 @@
+// V4 physical wire schema：logical topic frame 保持原子 seq 语义，超大帧只在
+// UTF-8 byte 层分片。codec/reassembly 纯函数见 wire-codec.ts。
+import { z } from "zod";
+import { PROTOCOL_V4_LIMITS, V4_WIRE_PROTOCOL_VERSION } from "./core.js";
+import { topicWireBase64Schema } from "./wire-binary.js";
+
+export const topicWireChecksumSchema = z
+  .object({
+    algorithm: z.literal("crc32"),
+    value: z.string().regex(/^[0-9a-f]{8}$/u),
+  })
+  .strict();
+export type TopicWireChecksum = z.infer<typeof topicWireChecksumSchema>;
+
+/** publisher reservation 对物理帧用途的权威标记；consumer 禁止按 RPC 时序猜测。 */
+export const topicFrameDeliveryKindSchema = z.enum(["initial", "online", "recovery"]);
+export type TopicFrameDeliveryKind = z.infer<typeof topicFrameDeliveryKindSchema>;
+
+export type TopicWireFrame<F> =
+  | {
+      wireVersion: typeof V4_WIRE_PROTOCOL_VERSION;
+      kind: "complete";
+      deliveryKind: TopicFrameDeliveryKind;
+      logicalFrameId: string;
+      logicalFrameOrdinal: number;
+      topic: string;
+      subscriptionId: string;
+      frame: F;
+    }
+  | {
+      wireVersion: typeof V4_WIRE_PROTOCOL_VERSION;
+      kind: "fragment";
+      deliveryKind: TopicFrameDeliveryKind;
+      logicalFrameId: string;
+      logicalFrameOrdinal: number;
+      topic: string;
+      subscriptionId: string;
+      fragmentIndex: number;
+      fragmentCount: number;
+      logicalBytes: number;
+      checksum: TopicWireChecksum;
+      dataBase64: string;
+    };
+
+/**
+ * service 边界只验证可安全路由/计量的 outer 形状；range/base64/checksum/logical
+ * payload 的完整校验必须在 ownership 过滤后的 assembler 中产生 typed fault。
+ */
+export const topicWireFrameCandidateSchema = z.discriminatedUnion("kind", [
+  z
+    .object({
+      wireVersion: z.literal(V4_WIRE_PROTOCOL_VERSION),
+      kind: z.literal("complete"),
+      // ownership 路由只读 topic/subId；坏 deliveryKind 必须进入 owned assembler
+      // 产生 typed fault，不能在 service 边界 warn/drop 后让 store 永久等待。
+      deliveryKind: z.unknown().optional(),
+      logicalFrameId: z.string().min(1),
+      logicalFrameOrdinal: z.number(),
+      topic: z.string().min(1),
+      subscriptionId: z.string().min(1),
+      // inner payload 故意不在 service route boundary 校验；缺失/类型/extra 由
+      // ownership 后 assembler 统一转 typed fault，避免早期 warn/drop 永久 loading。
+      frame: z.unknown().optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      wireVersion: z.literal(V4_WIRE_PROTOCOL_VERSION),
+      kind: z.literal("fragment"),
+      deliveryKind: z.unknown().optional(),
+      logicalFrameId: z.string().min(1),
+      logicalFrameOrdinal: z.number(),
+      topic: z.string().min(1),
+      subscriptionId: z.string().min(1),
+      fragmentIndex: z.unknown().optional(),
+      fragmentCount: z.unknown().optional(),
+      logicalBytes: z.unknown().optional(),
+      checksum: z.unknown().optional(),
+      dataBase64: z.unknown().optional(),
+    })
+    .passthrough(),
+]);
+export type TopicWireFrameCandidate = z.infer<typeof topicWireFrameCandidateSchema>;
+
+export function createTopicWireFrameSchema<F extends z.ZodTypeAny>(frameSchema: F) {
+  return z
+    .discriminatedUnion("kind", [
+      z
+        .object({
+          wireVersion: z.literal(V4_WIRE_PROTOCOL_VERSION),
+          kind: z.literal("complete"),
+          deliveryKind: topicFrameDeliveryKindSchema,
+          logicalFrameId: z.string().min(1),
+          logicalFrameOrdinal: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+          topic: z.string().min(1),
+          subscriptionId: z.string().min(1),
+          frame: frameSchema,
+        })
+        .strict(),
+      z
+        .object({
+          wireVersion: z.literal(V4_WIRE_PROTOCOL_VERSION),
+          kind: z.literal("fragment"),
+          deliveryKind: topicFrameDeliveryKindSchema,
+          logicalFrameId: z.string().min(1),
+          logicalFrameOrdinal: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+          topic: z.string().min(1),
+          subscriptionId: z.string().min(1),
+          fragmentIndex: z.number().int().nonnegative(),
+          fragmentCount: z
+            .number()
+            .int()
+            .positive()
+            .max(PROTOCOL_V4_LIMITS.logicalFrameAssemblyMaxFragments),
+          logicalBytes: z.number().int().positive(),
+          checksum: topicWireChecksumSchema,
+          dataBase64: topicWireBase64Schema,
+        })
+        .strict(),
+    ])
+    .superRefine((wire, context) => {
+      const value = wire as unknown as TopicWireFrame<z.output<F>>;
+      if (value.kind === "fragment") {
+        if (value.fragmentIndex >= value.fragmentCount) {
+          context.addIssue({
+            code: "custom",
+            message: "fragmentIndex must be smaller than fragmentCount",
+            path: ["fragmentIndex"],
+          });
+        }
+        if (value.fragmentCount > value.logicalBytes) {
+          context.addIssue({
+            code: "custom",
+            message: "fragmentCount cannot exceed logicalBytes",
+            path: ["fragmentCount"],
+          });
+        }
+        return;
+      }
+      const frame = value.frame as {
+        topic?: unknown;
+        subscriptionId?: unknown;
+      };
+      if (frame.topic !== value.topic) {
+        context.addIssue({
+          code: "custom",
+          message: "complete wire topic must match logical frame topic",
+          path: ["topic"],
+        });
+      }
+      if (frame.subscriptionId !== value.subscriptionId) {
+        context.addIssue({
+          code: "custom",
+          message: "complete wire subscriptionId must match logical frame subscriptionId",
+          path: ["subscriptionId"],
+        });
+      }
+    });
+}