@fibril/can-core 0.1.1 → 0.3.0

package/dist/index.js

@@ -67,7 +67,7 @@ var AckTracker = class {
 * Standard ID (11 bit, §3.1) is dynamically allocated by the master and
 * has no fixed bitfield meaning — kept here only as the wire mask.
 */
-const PROTOCOL_VERSION = 1;
+const PROTOCOL_VERSION = 2;
 const MAX_FRAME_PAYLOAD = 64;
 const CHAN_CONFIG = 0;
 const CHAN_SVC_REQUEST = 1;
@@ -102,6 +102,18 @@ const STATE_UNPROVISIONED = 0;
 const STATE_PROVISIONED = 1;
 const STATE_RUNNING = 2;
 const STATE_FAULT = 3;
+const STATE_SUSPENDED = 4;
+/** Human-readable name for a node_state byte. Unknown values → `unknown(N)`. */
+function stateName(state) {
+	switch (state) {
+		case 0: return "UNPROVISIONED";
+		case 1: return "PROVISIONED";
+		case 2: return "RUNNING";
+		case 3: return "FAULT";
+		case 4: return "SUSPENDED";
+		default: return `unknown(${state})`;
+	}
+}
 const FAULT_NONE = 0;
 const FAULT_NOMEM = 1;
 const FAULT_INDEX_OVERFLOW = 2;
@@ -148,11 +160,7 @@ function extSeg(id) {
 }
 //#endregion
 //#region src/dlc.ts
-/**
-* CAN FD valid payload sizes in ascending order (§4.3).
-* Mirrors `fibril_can_core/include/fibril_can_core/packing.hpp::kCanFdDlcSteps`
-* and `fibril_can_runtime/src/fcan_wire.c::fcan_quantize_dlc`.
-*/
+/** Valid CAN FD payload sizes, ascending. */
 const FD_DLC_STEPS = Object.freeze([
 	0,
 	1,
@@ -171,21 +179,15 @@ const FD_DLC_STEPS = Object.freeze([
 	48,
 	64
 ]);
-/**
-* Round `bytes` up to the next valid CAN FD payload step. Returns 64 for any
-* input ≥ 64.
-*/
+/** Round `bytes` up to the next valid CAN FD payload step (caps at 64). */
 function quantizeDlc(bytes) {
 	if (bytes >= 64) return 64;
 	for (const step of FD_DLC_STEPS) if (step >= bytes) return step;
 	return 64;
 }
 /**
-* Grow `data` to the next DLC step by appending zero bytes. Returns a new
-* Uint8Array. Never shrinks: if `data` already exceeds 64 bytes (which is
-* a self-inconsistent frame the slave would misparse), the original is
-* returned unchanged so the backend rejects it loudly (parity with
-* `pad_to_dlc` in `fibril_can_bridge/src/config_plane_codec.cpp`).
+* Pad `data` to the next DLC step with zeros. Over-length input (>64 B, which
+* the slave would misparse) is returned unchanged so the backend rejects it.
 */
 function padToDlc(data) {
 	if (data.length >= 64) return data;
@@ -288,13 +290,9 @@ function encodeStop(nodeId, seq) {
 	return configFrame(nodeId, 33, seq, /* @__PURE__ */ new Uint8Array(0));
 }
 /**
-* Accumulator for SCHEMA_DATA chunks. The slave DLC-pads each response (§4.3)
-* so `chunk.bytes.length` is typically larger than what the master requested;
-* the accumulator clips against `expectedChunkLen` and the remaining blob
-* length to drop those padding bytes (parity with
-* `append_schema_chunk` in `fibril_can_bridge/src/config_plane_codec.cpp`).
-*
-* Out-of-order chunks are rejected (returns 0 from {@link append}).
+* SCHEMA_DATA reassembly. Clips each chunk against `expectedChunkLen` and
+* the remaining blob length so DLC padding is discarded. Out-of-order
+* chunks are rejected ({@link append} returns 0).
 */
 var SchemaAccumulator = class {
 	#buf = [];
@@ -330,12 +328,8 @@ var SchemaAccumulator = class {
 //#endregion
 //#region src/scalar-codec.ts
 /**
-* Scalar type enumeration and little-endian wire codecs. Mirrors
-* `fibril_can_core/include/fibril_can_core/scalar_type.hpp` and
-* `fibril_can_core/src/scalar_type.cpp`.
-*
-* Type ordinal values are part of the protobuf schema blob's enum, so they
-* must not be renumbered.
+* Scalar type enum and little-endian wire codecs. The ordinal values are
+* part of the protobuf schema blob and must not be renumbered.
 */
 let ScalarType = /* @__PURE__ */ function(ScalarType) {
 	ScalarType[ScalarType["Bool"] = 0] = "Bool";
@@ -388,14 +382,9 @@ function scalarFromName(name) {
 	return idx >= 0 ? idx : void 0;
 }
 /**
-* Pack an integer / bool value as little-endian bytes into `out` at `offset`.
-* Writes scalarSize(type) bytes — pass a wide-enough `out`.
-*
-* Pass `bigint` for 64-bit types (U64/I64). `number` is accepted for
-* everything (it is internally widened to bigint so signed callers get the
-* same sign-extension semantics as the C++ `pack_scalar_int_le(uint64_t)`).
-* Signed callers pass the negative number directly; the function performs the
-* 64-bit two's-complement cast.
+* Pack an int/bool as little-endian into `out[offset..offset+scalarSize(type))`.
+* `number` is widened to bigint so signed negatives sign-extend to 64-bit
+* two's complement before truncation, matching C++ `pack_scalar_int_le`.
 */
 function packScalarIntLe(type, value, out, offset = 0) {
 	const bytes = scalarSize(type);
@@ -451,7 +440,7 @@ var ProtoReader = class ProtoReader {
 	get position() {
 		return this.pos;
 	}
-	/** Read a base-128 varint as a JS number (overflows ≥ 2^53 wrap silently). */
+	/** Read a base-128 varint as a JS number (schema uses uint32 only). */
 	readVarint() {
 		let result = 0;
 		let shift = 0;
@@ -489,11 +478,7 @@ var ProtoReader = class ProtoReader {
 	readMessage() {
 		return new ProtoReader(this.readBytes());
 	}
-	/**
-	* Read the next tag and return both the field number and wire type. The
-	* caller is expected to dispatch on field number; unknown fields can be
-	* passed to {@link skipValue}.
-	*/
+	/** Read a tag as `{field, wire}`. Unknown fields dispatch to {@link skipValue}. */
 	readTag() {
 		const tag = this.readVarint();
 		return {
@@ -531,23 +516,13 @@ var ProtoError = class extends Error {
 //#endregion
 //#region src/schema.ts
 /**
-* NodeSchema IR + protobuf decoder for the schema blob (§9).
-*
-* Mirrors `fibril_can_core/include/fibril_can_core/ir.hpp` and
-* `fibril_can_core/src/schema_blob.cpp::parse_schema`. Field IDs come from
-* `fibril_can_core/proto/fibril_can.proto`.
-*
-* Master-side notes:
-*   - The proto carries `topic_id` / `service_id` / `param_id` / BlockType
-*     `type_id` for codegen stability; the master derives equivalent indices
-*     from {@link computeNumbering} instead, so these are accepted but
-*     discarded on parse.
-*   - The proto wire field is `tx_disabled` while the IR holds `tx_enabled`
-*     (inverted, matches the C++ side).
+* NodeSchema IR + protobuf decoder for the schema blob. Master-side notes:
+*   - Proto `topic_id` / `service_id` / `param_id` / BlockType `type_id`
+*     are accepted but discarded — the master derives indices from
+*     {@link computeNumbering}.
+*   - Proto wire `tx_disabled` inverts to IR `tx_enabled`.
 *   - `BlockArray.type_id` (proto) → `BlockArray.blockTypeIndex` (IR).
-*
-* The reader skips unknown fields silently so future schema additions do
-* not break old masters.
+* Unknown fields are skipped so future schema additions don't break masters.
 */
 const FIELD = {
 	Field: {
@@ -832,13 +807,11 @@ function decodeLimits(r) {
 	return l;
 }
 /**
-* Parse a schema blob (proto3 binary) into the master-side IR.
-*
-* Throws {@link ProtoError} on malformed input or on
-* `protocolVersion !== 1` (the only version this codec understands —
-* mirrors C++ side's UnsupportedProtocolVersion behaviour).
+* Parse a schema blob into the master-side IR. Throws {@link ProtoError}
+* on malformed input or `protocolVersion === 0` (proto3 leaves an unset
+* uint32 at 0, so zero means it was never populated).
 */
-function decodeSchema(blob) {
+function decodeSchemaWithMeta(blob) {
 	const schema = {
 		protocolVersion: 0,
 		nodeName: "",
@@ -868,9 +841,16 @@ function decodeSchema(blob) {
 			default: r.skipValue(wire);
 		}
 	}
-	if (schema.protocolVersion !== 1) throw new ProtoError(`unsupported schema protocol_version: ${schema.protocolVersion}`);
+	if (schema.protocolVersion === 0) throw new ProtoError(`schema protocol_version is 0 (unset)`);
 	for (const arr of schema.instances) if (arr.blockTypeIndex >= schema.types.length) throw new ProtoError(`BlockArray.type_id ${arr.blockTypeIndex} out of range (#types=${schema.types.length})`);
-	return schema;
+	return {
+		schema,
+		versionAheadOfMaster: schema.protocolVersion > 2
+	};
+}
+/** Shim for callers that don't need the metadata — prefer {@link decodeSchemaWithMeta}. */
+function decodeSchema(blob) {
+	return decodeSchemaWithMeta(blob).schema;
 }
 /** Wire size in bytes for a single field (scalar or fixed array). */
 function fieldWireSize(field) {
@@ -879,20 +859,8 @@ function fieldWireSize(field) {
 //#endregion
 //#region src/dynamic-codec.ts
 /**
-* Field-driven dict ⇄ Uint8Array codec. The runtime equivalent of what
-* codegen would otherwise emit per message — encode/decode is a pure
-* function of the field list ({@link SchemaField}[]) and the JS dict.
-*
-* Conventions (matches CLAUDE.md "値の表現規約"):
-* - dict keys are the schema field name verbatim
-* - scalar ↔ JS `number`, except U64/I64 ↔ `bigint`
-* - bool ↔ JS `boolean`
-* - fixed-length array (`arrayLen > 0`) ↔ regular JS array
-*   (`number[]` / `bigint[]` / `boolean[]`) of exactly `arrayLen` elements
-*
-* Throws on missing / wrong-shape inputs. Decode tolerates extra trailing
-* bytes (mirrors C++ side: the master ignores trailing slop so that future
-* schema additions don't break older decoders).
+* Field-driven dict ⇄ Uint8Array codec. Throws on shape mismatch; decode
+* tolerates trailing bytes so future schema additions don't break decoders.
 */
 var DynamicCodecError = class extends Error {
 	constructor(message) {
@@ -952,11 +920,7 @@ function fieldsWireSize(fields) {
 	for (const f of fields) n += fieldWireSize(f);
 	return n;
 }
-/**
-* Encode a dict into the canonical little-endian wire bytes for `fields`.
-* Returns a fresh `Uint8Array`. Throws {@link DynamicCodecError} on a
-* missing or wrong-shape field.
-*/
+/** Encode a dict into little-endian wire bytes. Throws on missing / wrong-shape fields. */
 function encodeFields(fields, value) {
 	const totalSize = fieldsWireSize(fields);
 	const out = new Uint8Array(totalSize);
@@ -983,11 +947,7 @@ function encodeFields(fields, value) {
 	}
 	return out;
 }
-/**
-* Decode wire bytes into a dict keyed by field name. Extra trailing bytes
-* are ignored. Throws {@link DynamicCodecError} only if the payload is
-* shorter than the field list demands.
-*/
+/** Decode wire bytes into a dict. Trailing bytes are ignored; throws only if too short. */
 function decodeFields(fields, bytes) {
 	const expected = fieldsWireSize(fields);
 	if (bytes.length < expected) throw new DynamicCodecError(`decodeFields: payload too short — need ${expected} bytes, got ${bytes.length}`);
@@ -1080,10 +1040,7 @@ var DataPlaneReceiver = class {
 		this.#now = opts.now ?? (() => Date.now());
 		this.#unsubFrame = opts.transport.onFrame((f) => this.#onFrame(f));
 	}
-	/**
-	* Claim a slave's S→M std_ids. Re-attaching the same nodeId atomically
-	* detaches the prior plan first (re-provisioning case).
-	*/
+	/** Claim a slave's S→M std_ids. Re-attach atomically detaches the prior plan. */
 	attachSlave(nodeId, framePlan, index) {
 		this.detachSlave(nodeId);
 		const owned = /* @__PURE__ */ new Set();
@@ -1218,9 +1175,8 @@ var DataPlaneReceiver = class {
 //#endregion
 //#region src/frame-planner.ts
 /**
-* 11-bit Standard ID allocator with a free pool for IDs released after a
-* grace window (§11.4.1). `next()` returns `null` on exhaustion rather
-* than wrapping — wrapping past 0x7FF would alias on the wire.
+* 11-bit std_id allocator with a delayed free pool. `next()` returns `null`
+* on exhaustion — wrapping past 0x7FF would alias on the wire.
 */
 var StdIdAllocator = class {
 	#next = 256;
@@ -1312,9 +1268,8 @@ function emitOversizedTopic(fields, dir, periodUs, alloc, out) {
 	return flush();
 }
 /**
-* Plan a slave's frame layout. Returns `null` if the StdIdAllocator runs
-* out of 11-bit IDs mid-plan — the caller MUST surface that; a partial
-* plan would silently drop fields.
+* Plan a slave's frame layout. Returns `null` on std_id exhaustion — a
+* partial plan would silently drop fields.
 */
 function planFrames(requests, alloc) {
 	const buckets = /* @__PURE__ */ new Map();
@@ -1402,19 +1357,10 @@ function joinPath$1(ns, name) {
 	return `${ns}/${name}`;
 }
 /**
-* Synthesize the default {@link FieldRequest} list from a decoded schema +
-* numbering table — every S2M topic field at its declared period
-* (`field.periodUsOverride` if present, else the owning topic's
-* `defaultPeriodUs`), skipping `txEnabled === false` fields.
-*
-* Pass `filter` to layer a runtime per-field mask on top (UI toggles,
-* per-slave overrides). Schema-disabled fields are unconditionally
-* dropped before `filter` is consulted, so callers don't have to repeat
-* the `txEnabled` check.
-*
-* This is the natural input to {@link planFrames} when the master just
-* wants to "observe everything the slave publishes" — i.e. the
-* sniffer-style auto-provision path.
+* Every schema-enabled S→M field at its declared period
+* (`field.periodUsOverride` ?? topic's `defaultPeriodUs`), optionally masked
+* further by `filter`. Feeds {@link planFrames} for the observe-everything
+* auto-provision path.
 */
 function buildDefaultS2MRequests(schema, numbering, filter) {
 	const out = [];
@@ -1451,17 +1397,10 @@ function buildDefaultS2MRequests(schema, numbering, filter) {
 	return out;
 }
 /**
-* One-line FramePlanFactory that subscribes to every S2M field at its
-* declared period using a freshly-allocated {@link StdIdAllocator}.
-*
-* Pass `filter` to apply a runtime per-field mask (e.g. a UI-controlled
-* field-tx-enable map). With no filter, every schema-enabled S→M field is
-* subscribed.
-*
-* Returns `[]` when planning fails (e.g. std_id exhaustion); the caller's
-* NodeAgent will then leave the slave in `provisioning` → `awaiting-announce`
-* with no frames defined, which is the right outcome — partial plans would
-* silently drop fields.
+* FramePlanFactory subscribing to every schema-enabled S→M field (optionally
+* masked by `filter`) with a fresh {@link StdIdAllocator}. Returns `[]` on
+* planning failure so NodeAgent stalls in `awaiting-announce` — a partial
+* plan would silently drop fields.
 */
 function defaultS2MFramePlan(schema, numbering, filter) {
 	const planned = planFrames(buildDefaultS2MRequests(schema, numbering, filter), new StdIdAllocator());
@@ -1512,19 +1451,13 @@ var MasterHeartbeatBroadcaster = class {
 //#endregion
 //#region src/numbering.ts
 /**
-* Flat-numbering tables for topics, services, and parameters (§4.2).
-*
-* Port of `fibril_can_core/src/numbering.cpp`. Numbering is a pure function
-* of (schema, instance-count-vector). The same tables are derived
-* independently by codegen (with max_count for static checks), the slave
-* runtime (with actual counts at boot) and the master (with counts from the
-* ANNOUNCE frame) — keeping this in one place is what guarantees they agree.
+* Flat-numbering tables for topics, services, and parameters — a pure
+* function of (schema, instance-count-vector). Codegen, slave runtime, and
+* master all derive these tables through the same function.
 */
 const SERVICE_INDEX_CANCEL = 255;
 const SERVICE_INDEX_PARAM_SET = 253;
-/** Maximum first-class service_index produced by numbering (inclusive). */
 const SERVICE_INDEX_MAX = 252;
-/** Number of available first-class service slots. */
 const SERVICE_INDEX_CAPACITY = 253;
 let NumberingError = /* @__PURE__ */ function(NumberingError) {
 	NumberingError["Ok"] = "ok";
@@ -1564,12 +1497,8 @@ function buildTable(schema, counts, pick) {
 	};
 }
 /**
-* Compute the three numbering tables. `actualCounts` must have the same
-* length as `schema.instances`. The result has `status !== Ok` if input is
-* malformed or service_index would overflow into the reserved range
-* (§4.2 §9.4).
-*
-* On error the returned tables are empty but still safe to inspect.
+* `actualCounts.length` must equal `schema.instances.length`. On any error
+* the returned tables are empty and `status !== Ok`.
 */
 function computeNumbering(schema, actualCounts) {
 	const empty = {
@@ -1614,29 +1543,13 @@ function computeNumbering(schema, actualCounts) {
 }
 //#endregion
 //#region src/schema-hash.ts
-/**
-* SHA-256 helpers for the schema blob (§5.4, §9.3).
-*
-* Both codegen (C++) and the bridge (C++) hash the entire schema blob with
-* SHA-256 and pack the first 8 bytes as little-endian u64 into the ANNOUNCE
-* frame. This module is the master-side equivalent: hash the blob we
-* received over SCHEMA_DATA and compare with the schema_hash the slave
-* advertised in ANNOUNCE.
-*
-* Uses Web Crypto (`crypto.subtle`) — available in modern browsers and Node
-* ≥ 19 / Deno / Bun, no polyfill needed for our target environments.
-*/
 async function sha256(bytes) {
 	if (typeof crypto === "undefined" || !crypto.subtle) throw new Error("crypto.subtle is not available in this environment");
 	const owned = new Uint8Array(bytes);
 	const digest = await crypto.subtle.digest("SHA-256", owned);
 	return new Uint8Array(digest);
 }
-/**
-* Compute the ANNOUNCE-shape schema hash: the first 8 bytes of SHA-256(blob),
-* interpreted as a little-endian u64. Mirrors
-* `fibril_can_core/sha256::hash_prefix_u64`.
-*/
+/** First 8 bytes of SHA-256(blob) as little-endian u64 — the ANNOUNCE shape. */
 async function schemaHashPrefix(blob) {
 	const digest = await sha256(blob);
 	let result = 0n;
@@ -1646,18 +1559,9 @@ async function schemaHashPrefix(blob) {
 //#endregion
 //#region src/schema-index.ts
 /**
-* Schema-driven path lookup. Resolves `'<expanded_ns>/<endpoint_name>'`
-* style paths to the flat (topic|service|param) index plus the field IR
-* needed to drive {@link ./dynamic-codec.ts}.
-*
-* Paths are local to a single slave (one {@link NodeAgent}). The block-array
-* `ros_namespace` is expanded by substituting `{i}` with the instance index
-* (mirrors `expand_i_token` in `fibril_can_bridge::node_agent_internal.hpp`).
-*
-* Two endpoints of the same kind sharing a path is a schema error — the
-* index throws on construction. Same path across different kinds (e.g. a
-* topic and a service named `motor0/foo`) is allowed because the caller
-* selects the kind explicitly via `topic()` / `service()` / `param()`.
+* Path (`<expanded_ns>/<endpoint_name>`) → descriptor lookup for one slave.
+* Duplicate path within the same kind throws; the same path across kinds
+* is allowed (caller selects via `topic()` / `service()` / `param()`).
 */
 const I_TOKEN = "{i}";
 function expandIToken(s, value) {
@@ -1674,10 +1578,6 @@ function sumFieldsWireSize(fields) {
 	for (const f of fields) n += fieldWireSize(f);
 	return n;
 }
-/**
-* Path → descriptor index for one slave. Built once from
-* (schema, numbering) and reused for the lifetime of a snapshot.
-*/
 var SchemaIndex = class {
 	#topicsByPath = /* @__PURE__ */ new Map();
 	#servicesByPath = /* @__PURE__ */ new Map();
@@ -1795,13 +1695,7 @@ var SchemaIndex = class {
 };
 //#endregion
 //#region src/seq-allocator.ts
-/**
-* Sequential u8 allocator used for the config-plane `seq` field shared by
-* every command this master has issued to a given slave. Wraps at 256,
-* matching `BridgeNode::alloc_seq` in
-* `fibril_can_bridge/src/bridge_node.cpp` (the bridge wraps on the same
-* boundary; the AckTracker indexes by the wrapped value).
-*/
+/** Wrapping u8 counter for the config-plane `seq` byte. */
 var SeqAllocator = class {
 	#next = 0;
 	next() {
@@ -1816,13 +1710,9 @@ var SeqAllocator = class {
 //#endregion
 //#region src/segmented-transfer.ts
 /**
-* Build the §7.4 SVC_REQUEST frame stream for a master→slave call. Mirrors
-* `make_svc_request_frames` in
-* `fibril_can_bridge/include/fibril_can_bridge/svc_request.hpp`.
-*
-* - ≤64 byte payload → one SINGLE frame (seg=0).
-* - Larger → seq=0 carries `[0]=0 [1..2]=total_len + ≤61B data`, subsequent
-*   seqs carry `[0]=seq + ≤63B data`. Throws on payloads >1024B.
+* SVC_REQUEST frames for a master→slave call. ≤64 B → one SINGLE frame;
+* larger → seq 0 carries `[0]=0 [1..2]=total + ≤61 B data`, later seqs
+* carry `[0]=seq + ≤63 B data`. Throws on payloads >1024 B.
 */
 function makeSvcRequestFrames(nodeId, svcIdx, callId, payload) {
 	if (payload.length > 1024) throw new RangeError(`service request payload ${payload.length} exceeds SEG_MAX_TOTAL (${SEG_MAX_TOTAL})`);
@@ -1863,9 +1753,8 @@ function makeSvcRequestFrames(nodeId, svcIdx, callId, payload) {
 	return out;
 }
 /**
-* Build §7.4 response segments. Used by mock slaves and any TS slave runtime.
-* `channel` is the channel field (typically `CHAN_SVC_RESPONSE`); the payload
-* is `[status, ...response]` so the caller bakes status into the buffer.
+* Response segments (for mock slaves / TS slave runtime). `payload` must
+* already carry `[status, ...body]`; `channel` is typically CHAN_SVC_RESPONSE.
 */
 function makeSvcSegmentedFrames(channel, nodeId, svcIdx, callId, payload) {
 	if (payload.length > 1024) throw new RangeError(`service response payload ${payload.length} exceeds SEG_MAX_TOTAL (${SEG_MAX_TOTAL})`);
@@ -1905,11 +1794,7 @@ function makeSvcSegmentedFrames(channel, nodeId, svcIdx, callId, payload) {
 	}
 	return out;
 }
-/**
-* Bitmask of segment seqs required to reassemble a `totalLen`-byte payload.
-* Identical formula to `expected_mask` in
-* `fibril_can_bridge/src/node_agent.cpp` and the slave's `seg_expected_mask`.
-*/
+/** Bitmask of seg-seqs required to reassemble a `totalLen`-byte payload. */
 function segExpectedMask(totalLen) {
 	if (totalLen <= 0) return 0;
 	if (totalLen <= 61) return 1;
@@ -1918,20 +1803,16 @@ function segExpectedMask(totalLen) {
 	if (nSegs >= 32) return 4294967295;
 	return (1 << nSegs) - 1;
 }
-/**
-* Per-(svc, call_id) reassembly slot. The caller drives one of these per
-* outstanding incoming segmented transfer.
-*/
+/** Per-(svc, call_id) reassembly slot for one segmented transfer. */
 var SegmentReassembler = class {
 	totalLen = 0;
 	rxBitmap = 0;
 	lastRxMs = 0;
 	#buffer = /* @__PURE__ */ new Uint8Array(0);
 	/**
-	* Ingest one seg=1 frame. `data` is the frame payload (with the seq /
-	* total_len header still attached). Returns the fully-assembled payload
-	* once every required segment has arrived; otherwise null. Returns null
-	* on protocol violations and resets the slot.
+	* Ingest one seg=1 frame (payload with seq / total_len header attached).
+	* Returns the assembled payload once complete, else null. Resets the slot
+	* on protocol violation.
 	*/
 	ingest(data, nowMs) {
 		if (data.length === 0) return this.#reset();
@@ -2018,13 +1899,8 @@ const REASM_MAX_CONCURRENT = 16;
 /** §7.4 reassembly TTL. */
 const SEG_TIMEOUT_MS = 100;
 /**
-* Single-slave master service-call client. Port of NodeAgent's
-* begin_service_call / on_service_response / on_service_segment flow but
-* Promise-based and AbortSignal-aware.
-*
-* One {@link ServiceClient} attaches to the transport and demuxes incoming
-* SVC_RESPONSE frames for a single `nodeId`. NodeAgent owns one per slave
-* and exposes it on the running snapshot.
+* Promise-based, AbortSignal-aware service-call client for one slave.
+* NodeAgent owns one per slave and exposes it on the running snapshot.
 */
 var ServiceClient = class {
 	nodeId;
@@ -2189,24 +2065,8 @@ var ServiceClient = class {
 //#endregion
 //#region src/typed-param.ts
 /**
-* Schema-driven typed wrapper around PARAM_SET (SPEC §8.2, reserved
-* service_index 0xFD).
-*
-* Per SPEC §8.1 PARAM is M→S one-way: the master holds the source of truth
-* and re-injects defaults at provisioning time, so this wrapper exposes
-* `.set()` only — there's no `.get()` that queries the slave. The
-* descriptor's decoded default is available via `defaultValue()` for
-* reference / hydration of master-side state.
-*
-* The wire shape for one PARAM_SET request is:
-*   [0] count = 1
-*   [1..2] u16 param_index (LE)
-*   [3..]  value (scalar little-endian or fixed-array contiguous)
-*
-* Response is `[0] status [1..2] failed_param_index (when status != OK)`.
-* `set()` resolves with the status code; non-OK includes `failedIndex` so
-* the caller can correlate with a multi-param batch (single-param sets
-* always blame this param).
+* Typed wrapper around PARAM_SET (service_index 0xFD). PARAM is M→S
+* one-way, so this exposes `.set()` and `.defaultValue()` only.
 */
 var ParamCodecError = class extends Error {
 	constructor(message) {
@@ -2289,11 +2149,7 @@ var TypedParam = class {
 		this.descriptor = descriptor;
 		this.path = descriptor.path;
 	}
-	/**
-	* Decode the schema-embedded default value (SPEC §9.1 `default`). Useful
-	* to seed the master-side persistence store. Returns `null` if the
-	* descriptor carries no default payload.
-	*/
+	/** Decoded schema default; `null` if the descriptor carries no default. */
 	defaultValue() {
 		if (this.descriptor.defaultValue.length === 0) return null;
 		return unpackValue(this.descriptor, this.descriptor.defaultValue);
@@ -2351,15 +2207,10 @@ const DEFAULT_OPTS = {
 	heartbeatTimeoutMs: 350
 };
 /**
-* Per-slave provisioning state machine. Mirrors
-* `fibril_can_bridge::NodeAgent` lifecycle entry points but trimmed for the
-* single-threaded TS master — no ROS entity creation, no PARAM_SET
-* re-injection (P5), no plan computation (P6).
-*
-* Lifecycle: `idle` → `awaiting-announce` → `schema-reading` (skipped if
-* blob already cached on this agent instance) → `numbering` →
-* `provisioning` → `running`. HEARTBEAT loss drops to `lost`; the next
-* ANNOUNCE restarts the flow.
+* Per-slave provisioning state machine.
+* `idle` → `awaiting-announce` → `schema-reading` (skipped on cache hit) →
+* `numbering` → `provisioning` → `running`. HEARTBEAT loss drops to `lost`;
+* the next ANNOUNCE restarts the flow.
 */
 var NodeAgent = class {
 	nodeId;
@@ -2420,9 +2271,8 @@ var NodeAgent = class {
 		return this.#snapshot;
 	}
 	/**
-	* Attach to the transport and wait for ANNOUNCE. Resolves immediately —
-	* progress flows via {@link state} / {@link snapshot} / `onState`. Call
-	* `stop()` to detach.
+	* Attach and wait for ANNOUNCE. Resolves immediately; progress flows via
+	* {@link state} / {@link snapshot} / `onState`.
 	*/
 	async start() {
 		if (this.#stopped) throw new Error("NodeAgent.start() after stop() is not supported — construct a new agent");
@@ -2433,17 +2283,11 @@ var NodeAgent = class {
 		this.#setState({ kind: "awaiting-announce" });
 	}
 	/**
-	* Re-run the FRAME_DEFINE / START handshake against the live slave using
-	* the most recent ANNOUNCE + cached schema. The {@link FramePlanFactory}
-	* is invoked again — callers that key off an external mutable state
-	* (e.g. per-field TX-enable overrides) will see the latest values.
-	*
-	* The agent must have observed an ANNOUNCE already; `reprovision()`
-	* before that throws. RUNNING is required so that the slave is known to
-	* be reachable — calling during `lost` would race the heartbeat
-	* watchdog. Pending service calls are failed and the current snapshot is
-	* torn down before the new bring-up begins, mirroring what happens on a
-	* boot_id change.
+	* Re-run FRAME_DEFINE / START against the live slave with the most recent
+	* ANNOUNCE + cached schema. Invokes {@link FramePlanFactory} again so
+	* per-slave overrides pick up their latest values. Requires a prior
+	* ANNOUNCE. Tears down the current snapshot and fails pending service
+	* calls, mirroring a boot_id change.
 	*/
 	async reprovision() {
 		if (this.#stopped) throw new Error("NodeAgent.reprovision() after stop()");
@@ -2567,6 +2411,11 @@ var NodeAgent = class {
 			if (this.#snapshot !== null) this.#setState({ kind: "running" });
 			else if (this.#pendingStart !== null) this.#setState({ kind: "awaiting-start" });
 		}
+		if (this.#snapshot !== null) {
+			const isSuspended = h.state === 4;
+			if (isSuspended && this.#state.kind === "running") this.#setState({ kind: "suspended" });
+			else if (!isSuspended && this.#state.kind === "suspended") this.#setState({ kind: "running" });
+		}
 	}
 	#startSchemaRead(a) {
 		const progress = {
@@ -2648,13 +2497,15 @@ var NodeAgent = class {
 			return;
 		}
 		let schema;
+		let versionAheadOfMaster;
 		try {
-			schema = decodeSchema(blob);
+			({schema, versionAheadOfMaster} = decodeSchemaWithMeta(blob));
 		} catch (e) {
 			this.#error(e);
 			this.#setState({ kind: "awaiting-announce" });
 			return;
 		}
+		if (versionAheadOfMaster) this.#error(/* @__PURE__ */ new Error(`node ${this.nodeId}: schema protocol_version=${schema.protocolVersion} exceeds master-known — proceeding with best-effort`));
 		this.#blobCache.set(a.schemaHash, {
 			blob,
 			schema
@@ -2738,10 +2589,8 @@ var NodeAgent = class {
 		this.#maybeIssueStart(a, schema, blob, numbering, gen, p);
 	}
 	/**
-	* FRAME_DEFINE has succeeded (or been skipped). Consult the autoStart
-	* gate and either fire START immediately or park in `awaiting-start`,
-	* remembering enough context that `startNow()` can resume without
-	* re-running FRAME_DEFINE.
+	* Fire START if autoStart allows, else park in `awaiting-start` with
+	* enough context that `startNow()` can resume without re-running FRAME_DEFINE.
 	*/
 	#maybeIssueStart(a, schema, blob, numbering, gen, progress) {
 		if (this.#autoStart()) {
@@ -2759,10 +2608,8 @@ var NodeAgent = class {
 		this.#setState({ kind: "awaiting-start" });
 	}
 	/**
-	* Commit the deferred START when {@link NodeAgentOptions.autoStart}
-	* gated the previous bring-up. Only legal in `awaiting-start`; any
-	* other state throws so callers spot logic bugs instead of racing
-	* with a fresh ANNOUNCE.
+	* Commit the deferred START. Only legal in `awaiting-start`; throws
+	* elsewhere so callers spot logic bugs instead of racing a fresh ANNOUNCE.
 	*/
 	async startNow() {
 		if (this.#stopped) throw new Error("NodeAgent.startNow() after stop()");
@@ -2886,19 +2733,12 @@ var MasterController = class {
 		this.#onError = opts.onError;
 	}
 	/**
-	* Master-side decoder for S→M topic frames. Auto-attached / detached as
-	* each slave transitions in and out of `running`. Subscribe with
-	* `dataPlane.onTopic(nodeId, path, listener)`; read latest values with
-	* `dataPlane.latest(nodeId, path)`.
+	* S→M topic decoder. Auto-attaches / detaches on each slave's `running`
+	* transition; subscribe via `dataPlane.onTopic` / read via `dataPlane.latest`.
 	*/
 	get dataPlane() {
 		return this.#dataPlane;
 	}
-	/**
-	* Attach to the transport, start MASTER_HEARTBEAT, fire one initial
-	* broadcast DISCOVER to flush stale slave state from a previous master
-	* session. New slaves auto-spawn a NodeAgent on first sight.
-	*/
 	start() {
 		if (this.#started) return;
 		this.#started = true;
@@ -2939,7 +2779,7 @@ var MasterController = class {
 			schemaHash: r.schemaHash
 		})).sort((a, b) => a.nodeId - b.nodeId);
 	}
-	/** Subscribe to slave-set / state-change updates. Fires on every change. */
+	/** Subscribe to slave-set / state-change updates. Fires immediately with the current snapshot, then on every change. */
 	onChange(cb) {
 		this.#listeners.add(cb);
 		cb(this.snapshots());
@@ -2947,24 +2787,18 @@ var MasterController = class {
 			this.#listeners.delete(cb);
 		};
 	}
-	/**
-	* Access the NodeAgent for one slave, if it exists. Returns null until
-	* the slave has been observed. Useful for service / param calls from
-	* code that already knows the nodeId.
-	*/
+	/** NodeAgent for one slave, or null if not yet observed. */
 	agent(nodeId) {
 		return this.#slaves.get(nodeId)?.agent ?? null;
 	}
-	/** Issue an ad-hoc broadcast DISCOVER (between periodic firings). */
+	/** Ad-hoc broadcast DISCOVER. */
 	async discoverNow() {
 		await this.#transport.send(encodeDiscover());
 	}
 	/**
-	* Commit the deferred START on one slave that is parked in
-	* `awaiting-start` because the autoStart gate blocked its bring-up.
-	* Returns `false` if the slave is unknown or not currently waiting
-	* for a manual start; otherwise resolves once START has been queued
-	* on the wire (the RUNNING transition arrives later via `onChange`).
+	* Commit the deferred START on a slave parked in `awaiting-start`.
+	* Returns `false` if the slave is unknown or not waiting; the RUNNING
+	* transition arrives later via `onChange`.
 	*/
 	async startNode(nodeId) {
 		const rec = this.#slaves.get(nodeId);
@@ -2979,13 +2813,10 @@ var MasterController = class {
 		}
 	}
 	/**
-	* Re-run the FRAME_DEFINE / START handshake for one slave so the
-	* {@link FramePlanFactory} is consulted again. Use when external state
-	* the factory closes over has changed (e.g. per-field TX-enable
-	* toggles). Returns `false` when the slave is unknown or has never
-	* ANNOUNCEd; otherwise resolves once the new bring-up has been kicked
-	* off (it does not await the next RUNNING transition — listen via
-	* {@link onChange} instead).
+	* Re-run FRAME_DEFINE / START so the {@link FramePlanFactory} is consulted
+	* again (e.g. after a UI-driven field-tx-enable change). Returns `false`
+	* if unknown / never ANNOUNCEd; resolves once bring-up is kicked off, not
+	* when RUNNING is reached — listen via {@link onChange}.
 	*/
 	async reprovision(nodeId) {
 		const rec = this.#slaves.get(nodeId);
@@ -3072,6 +2903,6 @@ var MasterController = class {
 	}
 };
 //#endregion
-export { AckTracker, CHAN_CONFIG, CHAN_SVC_REQUEST, CHAN_SVC_RESPONSE, CMD_ACK, CMD_ANNOUNCE, CMD_DISCOVER, CMD_FRAME_DEFINE, CMD_HB_PERIOD, CMD_HEARTBEAT, CMD_MASTER_HEARTBEAT, CMD_NAK, CMD_SCHEMA_DATA, CMD_SCHEMA_READ, CMD_START, CMD_STOP, DIR_RX_M2S, DIR_TX_S2M, DataPlaneReceiver, Direction, DynamicCodecError, FAULT_ID_CONFLICT, FAULT_INDEX_OVERFLOW, FAULT_NOMEM, FAULT_NONE, FD_DLC_STEPS, MAX_FRAME_PAYLOAD, MasterController, MasterHeartbeatBroadcaster, NAK_BAD_LENGTH, NAK_BAD_PARAM, NAK_BAD_STATE, NAK_DIR_MISMATCH, NAK_ID_CONFLICT, NAK_INDEX_RANGE, NAK_NO_RESOURCE, NAK_SIZE_OVERFLOW, NAK_UNKNOWN_CMD, NODE_ID_BROADCAST, NoCallSlotError, NodeAgent, NumberingError, PROTOCOL_VERSION, ParamCodecError, ProtoError, ProtoReader, SCALAR_NAMES, SEG_FIRST_DATA, SEG_MAX_SEQ, SEG_MAX_TOTAL, SEG_REST_DATA, SERVICE_INDEX_CANCEL, SERVICE_INDEX_CAPACITY, SERVICE_INDEX_MAX, SERVICE_INDEX_PARAM_SET, STATE_FAULT, STATE_PROVISIONED, STATE_RUNNING, STATE_UNPROVISIONED, STD_ID_MASK, SVC_ACCEPTED, SVC_APP_ERROR, SVC_BAD_INDEX, SVC_BAD_LENGTH, SVC_BAD_VALUE, SVC_BUSY, SVC_CANCEL, SVC_MAX_FIRST_CLASS, SVC_OK, SVC_PARAM_SET, SVC_UNAVAIL, ScalarType, SchemaAccumulator, SchemaIndex, SegmentReassembler, SeqAllocator, ServiceCallError, ServiceCancelledError, ServiceClient, ServiceTimeoutError, ServiceUnavailableError, StdIdAllocator, TypedParam, TypedService, buildDefaultS2MRequests, computeNumbering, decodeAnnounce, decodeFields, decodeHeartbeat, decodeNak, decodeSchema, decodeSchemaData, defaultS2MFramePlan, encodeDiscover, encodeDiscoverTo, encodeFields, encodeFrameDefine, encodeMasterHeartbeat, encodeParamSetSingle, encodeSchemaRead, encodeStart, encodeStop, extChannel, extIndex, extNodeId, extSeg, extSeq, fieldWireSize, fieldsWireSize, makeExtId, makeSvcRequestFrames, makeSvcSegmentedFrames, packScalarF32Le, packScalarF64Le, packScalarIntLe, padToDlc, planFrames, quantizeDlc, scalarFromName, scalarName, scalarSize, schemaHashPrefix, segExpectedMask, segOffset, sha256, signExtend, unpackScalarF32Le, unpackScalarF64Le, unpackScalarIntLe };
+export { AckTracker, CHAN_CONFIG, CHAN_SVC_REQUEST, CHAN_SVC_RESPONSE, CMD_ACK, CMD_ANNOUNCE, CMD_DISCOVER, CMD_FRAME_DEFINE, CMD_HB_PERIOD, CMD_HEARTBEAT, CMD_MASTER_HEARTBEAT, CMD_NAK, CMD_SCHEMA_DATA, CMD_SCHEMA_READ, CMD_START, CMD_STOP, DIR_RX_M2S, DIR_TX_S2M, DataPlaneReceiver, Direction, DynamicCodecError, FAULT_ID_CONFLICT, FAULT_INDEX_OVERFLOW, FAULT_NOMEM, FAULT_NONE, FD_DLC_STEPS, MAX_FRAME_PAYLOAD, MasterController, MasterHeartbeatBroadcaster, NAK_BAD_LENGTH, NAK_BAD_PARAM, NAK_BAD_STATE, NAK_DIR_MISMATCH, NAK_ID_CONFLICT, NAK_INDEX_RANGE, NAK_NO_RESOURCE, NAK_SIZE_OVERFLOW, NAK_UNKNOWN_CMD, NODE_ID_BROADCAST, NoCallSlotError, NodeAgent, NumberingError, PROTOCOL_VERSION, ParamCodecError, ProtoError, ProtoReader, SCALAR_NAMES, SEG_FIRST_DATA, SEG_MAX_SEQ, SEG_MAX_TOTAL, SEG_REST_DATA, SERVICE_INDEX_CANCEL, SERVICE_INDEX_CAPACITY, SERVICE_INDEX_MAX, SERVICE_INDEX_PARAM_SET, STATE_FAULT, STATE_PROVISIONED, STATE_RUNNING, STATE_SUSPENDED, STATE_UNPROVISIONED, STD_ID_MASK, SVC_ACCEPTED, SVC_APP_ERROR, SVC_BAD_INDEX, SVC_BAD_LENGTH, SVC_BAD_VALUE, SVC_BUSY, SVC_CANCEL, SVC_MAX_FIRST_CLASS, SVC_OK, SVC_PARAM_SET, SVC_UNAVAIL, ScalarType, SchemaAccumulator, SchemaIndex, SegmentReassembler, SeqAllocator, ServiceCallError, ServiceCancelledError, ServiceClient, ServiceTimeoutError, ServiceUnavailableError, StdIdAllocator, TypedParam, TypedService, buildDefaultS2MRequests, computeNumbering, decodeAnnounce, decodeFields, decodeHeartbeat, decodeNak, decodeSchema, decodeSchemaData, decodeSchemaWithMeta, defaultS2MFramePlan, encodeDiscover, encodeDiscoverTo, encodeFields, encodeFrameDefine, encodeMasterHeartbeat, encodeParamSetSingle, encodeSchemaRead, encodeStart, encodeStop, extChannel, extIndex, extNodeId, extSeg, extSeq, fieldWireSize, fieldsWireSize, makeExtId, makeSvcRequestFrames, makeSvcSegmentedFrames, packScalarF32Le, packScalarF64Le, packScalarIntLe, padToDlc, planFrames, quantizeDlc, scalarFromName, scalarName, scalarSize, schemaHashPrefix, segExpectedMask, segOffset, sha256, signExtend, stateName, unpackScalarF32Le, unpackScalarF64Le, unpackScalarIntLe };
 
 //# sourceMappingURL=index.js.map