LCOV - code coverage report
Current view: top level - src/workbench/extensions/agent/crdt - opEnvelope.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 1.7 % 60 1
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : /**
       2              :  * The transport boundary of the human write leg (plan 3.3): mints wire
       3              :  * identity onto semantic {@link GraphOperation}s and chunks batches to the
       4              :  * wire caps clients respect (contract layer, verified against comfy-cli's
       5              :  * vocabulary): 256 ops and 4 MiB per batch, under the package's own library
       6              :  * budgets. `clear` is catastrophic-by-nature and never rides inside a batch
       7              :  * (plan D4): it always ships as a batch of exactly one.
       8              :  */
       9              : import { BATCHABLE_OPS } from '@comfyorg/comfy-multi-player'
      10              : import type { Actor, Op, Stamp } from '@comfyorg/comfy-multi-player'
      11              : 
      12              : import { createUuidv4 } from '@/utils/uuid'
      13              : 
      14              : import type { DocOp } from './docFrameClient'
      15              : import type { GraphOperation } from './graphOperations'
      16              : 
      17              : export const WIRE_MAX_OPS_PER_BATCH = 256
      18              : export const WIRE_MAX_BATCH_BYTES = 4 * 1024 * 1024
      19              : const STAMP_LIFT_HEADROOM = WIRE_MAX_OPS_PER_BATCH * 2 * 16
      20              : 
      21              : export interface MintContext {
      22              :   actor: Actor
      23              :   /** Doc version the ops are minted against (`base_version` on every op). */
      24              :   baseVersion: number
      25              : }
      26              : 
      27              : /** uuid4 hex: 32 lowercase `[0-9a-f]` chars (vocabulary §8.2). */
      28            0 : export function mintOpId(): string {
      29            0 :   return createUuidv4().replaceAll('-', '')
      30              : }
      31              : 
      32            0 : function withEnvelope<T extends GraphOperation>(
      33              :   operation: T,
      34              :   { actor, baseVersion }: MintContext
      35              : ): T & { op_id: string; actor: Actor; base_version: number; stamp: Stamp } {
      36            0 :   return {
      37              :     ...operation,
      38              :     op_id: mintOpId(),
      39              :     actor,
      40              :     base_version: baseVersion,
      41              :     stamp: [baseVersion, actor]
      42              :   }
      43              : }
      44              : 
      45              : /**
      46              :  * Attach wire identity to every operation. `op_id` is minted exactly once
      47              :  * here — a retry re-sends the SAME minted ops (the sender never re-mints;
      48              :  * changed-payload reuse rejects host-side).
      49              :  */
      50            0 : export function mintWireOps(
      51              :   operations: GraphOperation[],
      52              :   context: MintContext
      53              : ): Op[] {
      54            0 :   return operations.map((operation) => withEnvelope(operation, context))
      55              : }
      56              : 
      57            0 : function isBatchable(op: Op): boolean {
      58            0 :   return (BATCHABLE_OPS as readonly string[]).includes(op.op)
      59              : }
      60              : 
      61              : /**
      62              :  * A minted op as admitted: the semantic `op` callers get back at settlement,
      63              :  * the `wire` object the transport sends, and its UTF-8 size. `wire` is the
      64              :  * parsed result of the one serialization performed at admission: plain JSON
      65              :  * data with no `toJSON` and no cycles, so encoding the frame later yields
      66              :  * exactly the measured bytes however the original op's values behave.
      67              :  */
      68              : export interface SizedOp {
      69              :   readonly op: Op
      70              :   readonly wire: DocOp
      71              :   readonly bytes: number
      72              : }
      73              : 
      74              : /**
      75              :  * The sequencing envelope: the fields the chunker classifies by (`op`), the
      76              :  * sender settles by (`op_id`), and the applier orders by (`base_version`,
      77              :  * `stamp`, `actor`). The wire must carry exactly the values minted onto the
      78              :  * semantic op.
      79              :  */
      80              : interface Envelope {
      81              :   readonly op: string
      82              :   readonly op_id: string
      83              :   readonly actor: Actor
      84              :   readonly base_version: number
      85              :   readonly stamp: Stamp
      86              : }
      87              : 
      88              : type WireOp = DocOp & Envelope
      89              : 
      90            1 : const WIRE_SCALAR_FIELDS = {
      91              :   op: 'string',
      92              :   op_id: 'string',
      93              :   actor: 'string',
      94              :   base_version: 'number'
      95              : } as const
      96              : 
      97            0 : function isStamp(value: unknown): value is Stamp {
      98            0 :   return (
      99              :     Array.isArray(value) &&
     100              :     value.length === 2 &&
     101              :     typeof value[0] === 'number' &&
     102              :     typeof value[1] === 'string'
     103              :   )
     104              : }
     105              : 
     106            0 : function isRecord(value: unknown): value is Record<string, unknown> {
     107            0 :   return typeof value === 'object' && value !== null && !Array.isArray(value)
     108              : }
     109              : 
     110            0 : function isWireOp(value: unknown): value is WireOp {
     111            0 :   if (!isRecord(value)) return false
     112              :   const scalarsTyped = Object.entries(WIRE_SCALAR_FIELDS).every(
     113              :     ([field, type]) => typeof value[field] === type
     114              :   )
     115            0 :   return scalarsTyped && isStamp(value.stamp)
     116              : }
     117              : 
     118            0 : function envelopeOf({
     119              :   op,
     120              :   op_id,
     121              :   actor,
     122              :   base_version,
     123              :   stamp
     124              : }: Envelope): Envelope {
     125            0 :   return { op, op_id, actor, base_version, stamp: [stamp[0], stamp[1]] }
     126              : }
     127              : 
     128            0 : function sameEnvelope(a: Envelope, b: Envelope): boolean {
     129            0 :   return (
     130              :     a.op === b.op &&
     131              :     a.op_id === b.op_id &&
     132              :     a.actor === b.actor &&
     133              :     a.base_version === b.base_version &&
     134              :     a.stamp[0] === b.stamp[0] &&
     135              :     a.stamp[1] === b.stamp[1]
     136              :   )
     137              : }
     138              : 
     139              : export type WireMeasurement =
     140              :   | { readonly admitted: true; readonly sized: SizedOp }
     141              :   | { readonly admitted: false; readonly op: Op; readonly cause: unknown }
     142              : 
     143            0 : function stringifyOp(op: Op): { json: string } | { cause: unknown } {
     144            0 :   try {
     145            0 :     const json: unknown = JSON.stringify(op)
     146            0 :     return typeof json === 'string'
     147              :       ? { json }
     148              :       : { cause: new TypeError('Operation did not serialize to JSON') }
     149              :   } catch (cause) {
     150            0 :     return { cause }
     151              :   }
     152              : }
     153              : 
     154            0 : function rejected(op: Op, message: string): WireMeasurement {
     155            0 :   return { admitted: false, op, cause: new TypeError(message) }
     156              : }
     157              : 
     158              : /**
     159              :  * Serialize an op once to prove it can ride a `doc_ops` frame and learn its
     160              :  * wire form and size. Never throws: anything `JSON.stringify` cannot turn
     161              :  * into a wire object (a cycle in a custom-node value, a `toJSON` that throws
     162              :  * or yields a non-object) comes back as a rejection carrying the cause, and
     163              :  * so does any serializer that leaves the wire's {@link Envelope} different
     164              :  * from the one minted before serialization, or rewrites the semantic op's
     165              :  * own envelope while running. The envelope is captured before `toJSON` runs
     166              :  * and compared against both results afterwards, so a stateful serializer
     167              :  * cannot settle one sequence position while transmitting another. Callers
     168              :  * settle a rejected op at admission; the original op is never serialized
     169              :  * again.
     170              :  */
     171            0 : export function measureWireOp(op: Op): WireMeasurement {
     172            0 :   const minted = envelopeOf(op)
     173            0 :   const serialized = stringifyOp(op)
     174            0 :   if ('cause' in serialized)
     175            0 :     return { admitted: false, op, cause: serialized.cause }
     176            0 :   const wire: unknown = JSON.parse(serialized.json)
     177            0 :   if (!isWireOp(wire))
     178            0 :     return rejected(op, 'Operation did not serialize to a wire object')
     179            0 :   if (!sameEnvelope(wire, minted))
     180            0 :     return rejected(op, 'Operation serialized with a different envelope')
     181            0 :   if (!sameEnvelope(op, minted))
     182            0 :     return rejected(op, 'Operation changed its envelope while serializing')
     183            0 :   return {
     184              :     admitted: true,
     185              :     sized: { op, wire, bytes: new TextEncoder().encode(serialized.json).length }
     186              :   }
     187              : }
     188              : 
     189              : /**
     190              :  * Split measured ops into wire batches: order-preserving, at most
     191              :  * {@link WIRE_MAX_OPS_PER_BATCH} ops and {@link WIRE_MAX_BATCH_BYTES} bytes
     192              :  * per batch; every non-batchable op (`clear`) is a batch of one. A single op
     193              :  * larger than the byte cap still ships alone — the host, not the chunker,
     194              :  * owns rejecting it. Pure arithmetic over sizes measured at admission: it
     195              :  * cannot throw.
     196              :  */
     197            0 : export function chunkWireOps(ops: readonly SizedOp[]): SizedOp[][] {
     198            0 :   const batches: SizedOp[][] = []
     199            0 :   let current: SizedOp[] = []
     200            0 :   let currentBytes = 0
     201              : 
     202            0 :   const flush = (): void => {
     203            0 :     if (current.length > 0) batches.push(current)
     204            0 :     current = []
     205            0 :     currentBytes = 0
     206              :   }
     207              : 
     208            0 :   for (const sized of ops) {
     209            0 :     if (!isBatchable(sized.op)) {
     210            0 :       flush()
     211            0 :       batches.push([sized])
     212            0 :       continue
     213              :     }
     214            0 :     const overOps = current.length + 1 > WIRE_MAX_OPS_PER_BATCH
     215            0 :     const overBytes =
     216              :       current.length > 0 &&
     217              :       currentBytes + sized.bytes > WIRE_MAX_BATCH_BYTES - STAMP_LIFT_HEADROOM
     218            0 :     if (overOps || overBytes) flush()
     219            0 :     current.push(sized)
     220            0 :     currentBytes += sized.bytes
     221              :   }
     222            0 :   flush()
     223            0 :   return batches
     224              : }
        

Generated by: LCOV version 2.0-1