wire

@kyneta/wire

Frame envelopes, CBOR/JSON wire codecs, generic fragmentation, stream parsing, wire-message validation. Bytes-and-format primitives — the orchestrator lives in @kyneta/transport.

What this package provides

Primitive	Description	Key exports
Frame envelopes	6-byte binary header, 2-char text prefix	encodeBinaryFrame, decodeBinaryFrame, encodeTextFrame, decodeTextFrame
Wire codecs	CBOR (binary) and JSON (text) wire-message encoding	BINARY_CODEC, TEXT_CODEC, encodeWireMessage, decodeWireMessage
Generic fragmentation	Substrate-agnostic chunk loop + reassembler	fragmentGeneric<T>, Reassembler<T>, SubstrateOps<T>
Wire-message validation	Runtime shape checks at the decoder seam	validateWireMessage, WireValidationFailure
Identifier validation	UTF-8 byte-length caps for doc IDs and schema hashes	validateDocId, validateSchemaHash
Result type	Typed success/failure union for fallible operations	Result<T, E>, ok, err
Wire error	Discriminated union of all wire-pipeline errors	WireError

Dependencies

{
  "dependencies": { "@kyneta/schema": "workspace:^" }
}

No transport peer-dependency. @kyneta/wire is a pure leaf.

Quick start

Binary frame encode/decode

import {
  encodeBinaryFrame, decodeBinaryFrame,
  complete, WIRE_VERSION,
} from "@kyneta/wire"

// Build a complete frame with a raw payload
const payload = new Uint8Array([0x01, 0x02, 0x03])
const frame = complete(WIRE_VERSION, payload)

// Encode → 6-byte header + payload bytes
const wire = encodeBinaryFrame(frame)

// Decode back
const decoded = decodeBinaryFrame(wire) // Frame<Uint8Array>

Generic reassembly

import { Reassembler, BINARY_CODEC } from "@kyneta/wire"

const reassembler = new Reassembler(BINARY_CODEC, {
  timeoutMs: 10_000,
  maxConcurrentFrames: 32,
  maxTotalSize: 50 * 1024 * 1024,
})

// Feed wire pieces (complete frames or fragments)
const result = reassembler.receive(wirePiece)

if (result.status === "complete") {
  // result.frame is a Frame<Uint8Array> with kind: "complete"
}

reassembler.dispose()

Fragmentation

import {
  fragmentGeneric, createFrameIdCounter, BINARY_CODEC,
} from "@kyneta/wire"

const nextFrameId = createFrameIdCounter()

const result = fragmentGeneric(
  encodedPayload,
  100 * 1024,          // 100 KB threshold
  nextFrameId(),
  BINARY_CODEC,
)

if (result.kind === "fragments") {
  // result.pieces: readonly Uint8Array[] — each is a fully encoded fragment frame
}

Wire-message validation

import { validateWireMessage } from "@kyneta/wire"

const result = validateWireMessage(decodedObject)

if (result.ok) {
  // result.value: WireMessage — structurally valid
} else {
  // result.error: WireValidationError — { reason, path? }
}

Frame format

Each message is wrapped in a 6-byte binary frame before transmission:

┌──────────┬──────────┬──────────────────────────────────────────┐
│ Version  │  Type    │         Payload Length                   │
│ (1 byte) │ (1 byte) │         (4 bytes, big-endian)            │
├──────────┴──────────┴──────────────────────────────────────────┤
│                 Payload (codec-encoded)                        │
└────────────────────────────────────────────────────────────────┘

• Version — WIRE_VERSION = 2
• Type — 0x00 complete, 0x01 fragment
• Payload length — Uint32 big-endian byte count

Text frames use a 2-character "Vx" prefix (c = complete, f = fragment) followed by a JSON string.

CBOR compact wire format

The CBOR codec uses integer type discriminators and short field names to minimize payload size. See PROTOCOL.md for the full wire protocol specification.

License

MIT