@fibril/can-core 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -1,12 +1,7 @@
 import { CanFrameTx, ITransport, Unsubscribe } from "@fibril/can-transport";
 
 //#region src/ack-tracker.d.ts
-/**
- * In-flight ACK/NAK ledger keyed by `seq`. Mirrors the per-node `AckEntry`
- * map in `fibril_can_bridge/include/fibril_can_bridge/node_agent.hpp` but
- * pared down for the single-threaded TS master — no deadlines list, the
- * caller polls via {@link sweep}.
- */
+/** In-flight ACK/NAK ledger keyed by `seq`. Caller polls via {@link sweep}. */
 type AckOutcome = {
   kind: 'acked';
 } | {
@@ -120,13 +115,8 @@ declare function extSeg(id: number): number;
 //#endregion
 //#region src/config-plane.d.ts
 /**
- * Config-plane wire codec. Mirrors
- * `fibril_can_bridge/include/fibril_can_bridge/config_plane_codec.hpp`
- * and `fibril_can_bridge/src/config_plane_codec.cpp`.
- *
- * All integers are little-endian. Decoders return `null` on malformed input
- * (wrong length etc.); encoders produce CAN frames padded to the next DLC
- * step, matching what the slave sees on the bus.
+ * Config-plane wire codec. All integers little-endian; decoders return `null`
+ * on malformed input; encoders produce CAN-FD frames padded to the next DLC step.
  */
 /** ANNOUNCE payload (S→M, §5.4). */
 interface AnnounceMsg {
@@ -173,13 +163,9 @@ declare function encodeFrameDefine(nodeId: number, seq: number, stdId: number, p
 declare function encodeStart(nodeId: number, seq: number): CanFrameTx;
 declare function encodeStop(nodeId: number, seq: number): CanFrameTx;
 /**
- * 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).
  */
 declare class SchemaAccumulator {
   #private;
@@ -197,12 +183,8 @@ declare class SchemaAccumulator {
 //#endregion
 //#region src/scalar-codec.d.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.
  */
 declare enum ScalarType {
   Bool = 0,
@@ -223,14 +205,9 @@ declare function scalarSize(type: ScalarType): number;
 declare function scalarName(type: ScalarType): string | undefined;
 declare function scalarFromName(name: string): ScalarType | undefined;
 /**
- * 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`.
  */
 declare function packScalarIntLe(type: ScalarType, value: number | bigint, out: Uint8Array, offset?: number): void;
 /** Bit-cast a float32 to its IEEE-754 little-endian representation. */
@@ -332,61 +309,33 @@ declare function fieldWireSize(field: SchemaField): number;
 //#endregion
 //#region src/dynamic-codec.d.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.
  */
 declare class DynamicCodecError extends Error {
   constructor(message: string);
 }
-/** Tag union of accepted JS value shapes for one field. */
 type FieldValue = number | bigint | boolean | number[] | bigint[] | boolean[];
-/** Dict shape — string-keyed values, one entry per field. */
 type Dict = Record<string, FieldValue>;
 /**
  * Sum the wire size of a field list. The result is the byte count that
  * {@link encodeFields} will produce.
  */
 declare function fieldsWireSize(fields: readonly SchemaField[]): number;
-/**
- * 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. */
 declare function encodeFields(fields: readonly SchemaField[], value: Dict): Uint8Array;
-/**
- * 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. */
 declare function decodeFields(fields: readonly SchemaField[], bytes: Uint8Array): Dict;
 //#endregion
 //#region src/numbering.d.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.
  */
 declare const SERVICE_INDEX_CANCEL = 255;
 declare const SERVICE_INDEX_PARAM_SET = 253;
-/** Maximum first-class service_index produced by numbering (inclusive). */
 declare const SERVICE_INDEX_MAX = 252;
-/** Number of available first-class service slots. */
 declare const SERVICE_INDEX_CAPACITY: number;
 declare enum NumberingError {
   Ok = "ok",
@@ -396,23 +345,15 @@ declare enum NumberingError {
   InstanceCountMismatch = "actual_counts length != #instances",
   BlockTypeOutOfRange = "BlockArray::blockTypeIndex out of range"
 }
-/** Concrete location of one (instance, endpoint) within a NodeSchema. */
 interface EndpointKey {
-  /** Index into NodeSchema.instances. */
   blockArray: number;
-  /** 0..count-1 */
   instance: number;
-  /** 0..nEndpoints(type)-1 */
   endpoint: number;
 }
-/** Forward + inverse maps for a single endpoint kind. */
 interface NumberingTable {
-  /**
-   * size = Σ_b(actualCounts[b] × nEndpoints(types[instances[b].blockTypeIndex]));
-   * the array index IS the flat numbering.
-   */
+  /** Array index is the flat numbering. */
   byIndex: EndpointKey[];
-  /** Per-block-array base offsets (size = #blockArrays + 1; last is total). */
+  /** Per-block-array base offsets. Length = #blockArrays + 1; last is total. */
   bases: number[];
 }
 interface NumberingResult {
@@ -422,12 +363,8 @@ interface NumberingResult {
   status: NumberingError;
 }
 /**
- * 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`.
  */
 declare function computeNumbering(schema: NodeSchema, actualCounts: readonly number[]): NumberingResult;
 //#endregion
@@ -466,10 +403,6 @@ interface ParamDescriptor {
   readonly maxValue: Uint8Array;
 }
 type EndpointDescriptor = TopicDescriptor | ServiceDescriptor | ParamDescriptor;
-/**
- * Path → descriptor index for one slave. Built once from
- * (schema, numbering) and reused for the lifetime of a snapshot.
- */
 declare class SchemaIndex {
   #private;
   constructor(schema: NodeSchema, numbering: NumberingResult, instanceCounts: readonly number[]);
@@ -517,13 +450,8 @@ declare class NoCallSlotError extends ServiceCallError {
   constructor(serviceIndex: number);
 }
 /**
- * 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.
  */
 declare class ServiceClient {
   #private;
@@ -550,24 +478,8 @@ declare class ServiceClient {
 //#endregion
 //#region src/typed-param.d.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.
  */
 declare class ParamCodecError extends Error {
   constructor(message: string);
@@ -577,13 +489,9 @@ interface TypedParamSetOptions {
   signal?: AbortSignal;
 }
 interface TypedParamSetResult {
-  /** SPEC §7.2 status (0 = SVC_OK). */
+  /** SVC_OK = 0; non-zero = slave error code. */
   readonly status: number;
-  /**
-   * On `status != SVC_OK`, the slave-reported param_index that failed.
-   * For a single-param call this is always `descriptor.paramIndex` if the
-   * slave fills the field, else `null` (slave omitted the field).
-   */
+  /** Slave-reported failing param_index (non-OK only); null if omitted. */
   readonly failedIndex: number | null;
 }
 /** Build a PARAM_SET request payload for a single (descriptor, value) pair. */
@@ -593,11 +501,7 @@ declare class TypedParam<T> {
   readonly path: string;
   readonly descriptor: ParamDescriptor;
   constructor(client: ServiceClient, descriptor: ParamDescriptor);
-  /**
-   * 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(): T | null;
   /** Send a PARAM_SET with a single entry for this param. */
   set(value: T, opts?: TypedParamSetOptions): Promise<TypedParamSetResult>;
@@ -605,20 +509,9 @@ declare class TypedParam<T> {
 //#endregion
 //#region src/typed-service.d.ts
 /**
- * Schema-driven typed wrapper around {@link ServiceClient.call}.
- *
- * The generic parameters are compile-time only: at runtime, encoding is
- * driven entirely by the {@link ServiceDescriptor}'s field list. Callers
- * supply `Req` / `Resp` interfaces matching the schema fields by name —
- * the runtime trusts the dict layout and packs by field iteration order.
- *
- * Returned on success: `{ status, data }` where `status` is the SPEC §7.2
- * service status (0 = OK) and `data` is the decoded response dict typed as
- * `Resp`. Non-OK responses still return a `data` object — the slave is
- * required to fill the response payload even on failure (§7.2), and the
- * decoder will best-effort attempt it; if the body is shorter than the
- * schema demands, `data` is `null` instead of throwing (so callers can
- * surface the status to the user without losing the whole response).
+ * Result of a {@link TypedService.call}. `status` follows SPEC §7.2 (0 = OK);
+ * `data` is best-effort even on non-OK, and `null` if the response body is
+ * shorter than the schema demands.
  */
 interface TypedServiceResult<Resp extends Dict> {
   readonly status: number;
@@ -638,35 +531,20 @@ declare class TypedService<Req extends Dict, Resp extends Dict> {
 }
 //#endregion
 //#region src/node-agent.d.ts
-/**
- * One planned data-plane CAN frame, supplied by the caller (typically a
- * frame planner — P6) and consumed by {@link NodeAgent} when it issues
- * FRAME_DEFINE during bring-up. Mirrors `FrameSpec` in
- * `fibril_can_bridge/include/fibril_can_bridge/frame_planner.hpp`.
- */
+/** One planned data-plane CAN frame consumed by FRAME_DEFINE during bring-up. */
 interface FramePlan {
   stdId: number;
   periodUs: number;
   dir: Direction;
   entries: readonly FrameDefineEntry[];
 }
-/**
- * Per-bring-up context handed to a {@link FramePlanFactory} callback so the
- * caller can branch on the specific slave being provisioned (e.g. read an
- * external per-nodeId field-enable override map). The same factory is
- * shared across every {@link NodeAgent} the controller spawns, so this is
- * the only way for the factory to discriminate slaves.
- */
+/** Context handed to {@link FramePlanFactory} so it can branch on the slave. */
 interface FramePlanContext {
-  /** The slave being provisioned (1..0x7E). */
   readonly nodeId: number;
 }
 /**
- * Builds the FRAME_DEFINE plan for a slave once its schema is decoded and
- * numbered. The optional `ctx` argument carries the nodeId so callers that
- * keep per-slave overrides (e.g. UI-controlled S→M field toggles) can fork
- * on it without threading state through {@link NodeAgentOptions}. The
- * 2-arg form is still accepted — extra parameters are simply ignored.
+ * Builds the FRAME_DEFINE plan once schema and numbering are known.
+ * `ctx.nodeId` lets a shared factory fork on the specific slave.
  */
 type FramePlanFactory = ((schema: NodeSchema, numbering: NumberingResult, ctx: FramePlanContext) => readonly FramePlan[]) | readonly FramePlan[];
 /** Phase machine — public for observers. */
@@ -683,18 +561,11 @@ type NodeProvisionState = {
 } | {
   kind: 'provisioning';
   pendingDefines: number;
-}
-/**
- * FRAME_DEFINE completed successfully but START has been withheld by
- * the {@link NodeAgentOptions.autoStart} gate. `startNow()` moves the
- * agent forward. `reprovision()` / a fresh ANNOUNCE re-enter the flow
- * from bring-up.
- */
-| {
+} /** FRAME_DEFINE done, autoStart blocked START. `startNow()` moves forward. */ | {
   kind: 'awaiting-start';
 } | {
   kind: 'running';
-} /** Slave reported node_state = SUSPENDED. Reverts to running on the next non-SUSPENDED HEARTBEAT. */ | {
+} /** Slave reported SUSPENDED. Reverts to running on the next non-SUSPENDED HEARTBEAT. */ | {
   kind: 'suspended';
 } | {
   kind: 'lost';
@@ -717,22 +588,11 @@ interface NodeRunningSnapshot {
   stdIdToTopicIndex: Map<number, number>;
   /** §7 master-side RPC client. Stays valid for the lifetime of the snapshot. */
   services: ServiceClient;
-  /**
-   * Path → IR descriptor lookup. Drives the typed accessors below.
-   * Exposed for sniffer-style introspection (`index.topicPaths()` etc.).
-   */
+  /** Path → IR descriptor lookup; drives `service()` / `param()` below. */
   index: SchemaIndex;
-  /**
-   * Schema-driven typed RPC wrapper. Throws if `path` is unknown. Generic
-   * `Req` / `Resp` are compile-time only — runtime encoding is driven by
-   * the schema's field list.
-   */
+  /** Typed RPC wrapper. Throws if `path` is unknown. */
   service<Req extends Dict, Resp extends Dict>(path: string): TypedService<Req, Resp>;
-  /**
-   * Schema-driven PARAM_SET wrapper. Throws if `path` is unknown.
-   * `T` is `number` for scalar params (except U64/I64 → `bigint`),
-   * `boolean` for bool, or the array form for fixed-length array params.
-   */
+  /** Typed PARAM_SET wrapper. Throws if `path` is unknown. */
   param<T = number | bigint | boolean | number[] | bigint[] | boolean[]>(path: string): TypedParam<T>;
 }
 interface NodeAgentOptions {
@@ -742,59 +602,34 @@ interface NodeAgentOptions {
   transport: ITransport;
   /** Strategy for building the FRAME_DEFINE plan. */
   framePlan: FramePlanFactory;
-  /**
-   * Per-config-command ACK timeout in ms. Slaves must ACK within this
-   * window or the agent abandons the bring-up attempt and waits for the
-   * next ANNOUNCE. Default 250 ms (matches bridge's
-   * `bring_up_ack_timeout_`).
-   */
+  /** Per-config-command ACK timeout in ms. Default 250. */
   ackTimeoutMs?: number;
-  /**
-   * SCHEMA_READ chunk byte limit. SPEC §4.3 caps a single response at the
-   * SINGLE-frame payload (≤59 data bytes after the 4-byte offset header).
-   * Default 59.
-   */
+  /** SCHEMA_READ chunk byte limit — caps at the SINGLE-frame payload. Default 59. */
   schemaChunkSize?: number;
-  /**
-   * Multiplier on `ackTimeoutMs` used as the schema-read retry budget.
-   * Default 3 (one initial + two retries).
-   */
+  /** SCHEMA_READ retry budget. Default 3. */
   schemaReadRetries?: number;
-  /**
-   * Heartbeat-loss budget. The agent expects a HEARTBEAT every 100 ms
-   * (§14); after this much silence it transitions to `lost`. Default 350.
-   */
+  /** HEARTBEAT-loss budget in ms. Default 350. */
   heartbeatTimeoutMs?: number;
   /** Per-call default timeout for `services.call()`. Default `ackTimeoutMs`. */
   serviceTimeoutMs?: number;
   /**
-   * Gate consulted right before START is issued. When it returns `false`,
-   * the agent stops in {@link NodeProvisionState} `awaiting-start` after
-   * FRAME_DEFINE ACKs come back; the caller commits with `startNow()`.
-   * Read fresh at each decision point so callers can flip the setting at
-   * runtime without reconstructing the agent. Default `() => true`.
+   * Gate consulted before each START. Returning `false` parks in
+   * `awaiting-start`; caller commits with `startNow()`. Read fresh each
+   * time so the flag can flip at runtime. Default `() => true`.
    */
   autoStart?: () => boolean;
   /** Optional state-change observer. */
   onState?: (state: NodeProvisionState) => void;
-  /** Optional non-fatal error observer (decode warnings, hash mismatch). */
+  /** Optional non-fatal error observer. */
   onError?: (err: Error) => void;
-  /**
-   * Override for the wall clock. Tests pass a deterministic counter.
-   * Default `() => Date.now()`.
-   */
+  /** Wall-clock override for tests. Default `() => Date.now()`. */
   now?: () => number;
 }
 /**
- * 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.
  */
 declare class NodeAgent {
   #private;
@@ -805,59 +640,32 @@ declare class NodeAgent {
   get state(): NodeProvisionState;
   get snapshot(): NodeRunningSnapshot | null;
   /**
-   * 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`.
    */
   start(): Promise<void>;
   /**
-   * 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.
    */
   reprovision(): Promise<void>;
   /** Detach, send STOP if currently RUNNING, clear all in-flight state. */
   stop(): Promise<void>;
   /**
-   * 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.
    */
   startNow(): Promise<void>;
 }
 //#endregion
 //#region src/data-plane.d.ts
 /**
- * Master-side decoder for S→M data-plane frames.
- *
- * Listens on the transport for standard-ID frames whose IDs match one of
- * the std_ids configured in any attached slave's {@link FramePlan}. For
- * each match, unpacks the topic entries packed into the frame's payload
- * (in FRAME_DEFINE order) using the schema field bitmask and publishes
- * a decoded {@link Dict} per topic to subscribers.
- *
- * Lifecycle:
- *   - `new DataPlaneReceiver({ transport })` registers an `onFrame` tap.
- *   - `attachSlave(nodeId, framePlan, schemaIndex)` claims a slave's std_ids.
- *   - `detachSlave(nodeId)` releases them (call on RUNNING → not-RUNNING).
- *   - `dispose()` unsubscribes and clears all state.
- *
- * Two slaves cannot publish on the same std_id — attaching the second
- * throws. This mirrors the bus-level reality: identical std_ids would
- * collide on the wire.
- *
- * M→S frames (master output, dir `Direction.M2S`) are skipped during
- * attach so the receiver doesn't try to decode echo or self-loopback
- * frames as if they were slave-published.
+ * Master-side decoder for S→M data-plane frames. `attachSlave` claims a
+ * slave's std_ids; two slaves cannot share a std_id (throws). M→S frames
+ * are skipped so echo / self-loopback isn't decoded as slave-published.
  */
 interface DataPlaneReceiverOptions {
   transport: ITransport;
@@ -872,23 +680,16 @@ interface TopicSample {
   readonly tsMs: number;
 }
 interface TopicStats {
-  /** Frames ever decoded into this topic since the slave attached. */
   readonly count: number;
   /** `now()` of the most recent frame. */
   readonly lastRxMs: number;
-  /**
-   * Rolling rate over the last few samples (Hz). 0 until at least
-   * two frames have been seen.
-   */
+  /** Rolling rate in Hz over the last {@link RATE_WINDOW} samples; 0 with <2 samples. */
   readonly ratePerSec: number;
 }
 declare class DataPlaneReceiver {
   #private;
   constructor(opts: DataPlaneReceiverOptions);
-  /**
-   * 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: number, framePlan: readonly FramePlan[], index: SchemaIndex): void;
   /** Release a slave's std_ids and drop its cached topic samples. */
   detachSlave(nodeId: number): void;
@@ -904,19 +705,10 @@ declare class DataPlaneReceiver {
 //#endregion
 //#region src/frame-planner.d.ts
 /**
- * Frame planner — turns a list of "I want field X at period Y" requests into
- * the concrete FRAME_DEFINE bodies the master ships to the slave (§6.3).
- *
- * Port of `fibril_can_core/src/frame_planner.cpp` — same bucketing rules:
- *   - Group requests by (direction, period_us); never combine across either.
- *   - Inside a bucket, bin-pack whole topics into ≤64-byte frames.
- *   - A single topic whose declared fields exceed 64 bytes is the sole
- *     field-split exception (`emitOversizedTopic`).
- *
- * Determinism is load-bearing: codegen, bridge, and this TS master must
- * produce identical std_id assignments for the same input. Both the
- * bucket map and the per-bucket topic map iterate in ascending key order
- * (matching `std::map` in the C++ reference).
+ * Field-requests → FRAME_DEFINE bodies. Groups by (dir, period_us) and
+ * bin-packs whole topics into ≤64-byte frames; a topic that exceeds 64 B
+ * is the sole field-split exception. Iteration order is ascending on
+ * every level so codegen / bridge / master produce identical std_ids.
  */
 interface FieldRequest {
   topicIndex: number;
@@ -936,9 +728,8 @@ interface FrameSpec {
   entries: FrameDefineEntry[];
 }
 /**
- * 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.
  */
 declare class StdIdAllocator {
   #private;
@@ -947,26 +738,16 @@ declare class StdIdAllocator {
   reset(start?: number): void;
 }
 /**
- * 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.
  */
 declare function planFrames(requests: readonly FieldRequest[], alloc: StdIdAllocator): FrameSpec[] | null;
 //#endregion
 //#region src/default-plan.d.ts
 /**
- * Per-field predicate handed to {@link buildDefaultS2MRequests} (and via
- * it, {@link defaultS2MFramePlan}) so callers can apply a runtime mask on
- * top of the schema-declared `txEnabled`.
- *
- * Contract:
- *   - Returning `false` skips the field entirely; the slave will not pack
- *     it into any S→M frame. Returning `true` keeps it.
- *   - Called only for S→M fields whose schema declares `txEnabled !==
- *     false` (schema-disabled fields are filtered out unconditionally).
- *   - `topicPath` is the same `'<expanded_ns>/<topic_name>'` string the
- *     master uses elsewhere (mirrors {@link SchemaIndex.topicPaths}), so
- *     UI override maps can key on the same identifier.
+ * Predicate for masking S→M fields on top of the schema-declared `txEnabled`.
+ * Only called for fields with `txEnabled !== false`. Return `false` to drop
+ * the field. `topicPath` mirrors {@link SchemaIndex.topicPaths}.
  */
 type S2MFieldFilter = (info: {
   topicPath: string;
@@ -976,84 +757,37 @@ type S2MFieldFilter = (info: {
   field: SchemaField;
 }) => boolean;
 /**
- * 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.
  */
 declare function buildDefaultS2MRequests(schema: NodeSchema, numbering: NumberingResult, filter?: S2MFieldFilter): FieldRequest[];
 /**
- * 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.
  */
 declare function defaultS2MFramePlan(schema: NodeSchema, numbering: NumberingResult, filter?: S2MFieldFilter): FramePlan[];
 //#endregion
 //#region src/dlc.d.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. */
 declare const FD_DLC_STEPS: readonly number[];
-/**
- * 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). */
 declare function quantizeDlc(bytes: number): number;
 /**
- * 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.
  */
 declare function padToDlc(data: Uint8Array): Uint8Array;
 //#endregion
 //#region src/master-controller.d.ts
 /**
- * Multi-slave coordinator.
- *
- * One {@link MasterController} owns:
- *   - a single transport (the bus)
- *   - one {@link MasterHeartbeatBroadcaster} (shared across slaves)
- *   - a single broadcast DISCOVER at start() to flush every slave's frame
- *     table and pull fresh ANNOUNCEs onto the bus
- *   - a `Map<nodeId, NodeAgent>` of provisioned slaves — auto-spawned on
- *     the first ANNOUNCE / HEARTBEAT from a previously-unseen nodeId
- *
- * Periodic broadcast DISCOVER is intentionally NOT done. Broadcast
- * DISCOVER is destructive (§5.11): every receiving slave clears its frame
- * table and drops to UNPROVISIONED. Late-joining slaves are covered by
- * their own spontaneous ANNOUNCE × 3 at boot (§5.4); the user-initiated
- * "Discover" button (`discoverNow()`) is the escape hatch for the rare
- * case where the master came up first and missed the burst.
- *
- * Provisioning per slave still goes through {@link NodeAgent}. The
- * controller is the right place to add cross-slave concerns later (PARAM
- * persistence, name ownership, lab-mode multiplexers) without bloating
- * `NodeAgent`.
- *
- * The controller does NOT replace `NodeAgent` for single-slave embedded
- * use cases (e.g. tests, a fixed-topology setup); it sits one layer above
- * and is the natural entrypoint for the Web UI.
+ * Multi-slave coordinator. Owns the transport, one MASTER_HEARTBEAT
+ * broadcaster, and a `Map<nodeId, NodeAgent>` populated on first sight of
+ * ANNOUNCE / HEARTBEAT. Broadcast DISCOVER is destructive so it is fired
+ * only once at start(); use `discoverNow()` on demand.
  */
 /** Default policy hooks applied to every spawned NodeAgent. */
 interface MasterControllerOptions {
@@ -1064,20 +798,11 @@ interface MasterControllerOptions {
   /** MASTER_HEARTBEAT broadcast period in ms. Default 100 (§5.11). */
   heartbeatPeriodMs?: number;
   /**
-   * Broadcast DISCOVER period in ms. Default 0 (disabled). Setting >0 is
-   * destructive — every periodic broadcast DISCOVER wipes every slave's
-   * frame table and forces re-provisioning, breaking S→M topic flow until
-   * each NodeAgent re-pushes its FRAME_DEFINEs. Useful only for very
-   * niche reconnect-storm scenarios; prefer `discoverNow()` for on-demand
-   * rediscovery and rely on slave spontaneous ANNOUNCE × 3 (§5.4) for
-   * normal late-join.
+   * Periodic broadcast DISCOVER period in ms. Default 0 (disabled). Each
+   * firing wipes every slave's frame table — prefer `discoverNow()`.
    */
   discoverPeriodMs?: number;
-  /**
-   * Send a single broadcast DISCOVER inside `start()` to flush stale
-   * slave state from a previous master session. Default true. Set false
-   * in tests that drive ANNOUNCE manually and need a quiet bus.
-   */
+  /** One broadcast DISCOVER inside `start()` to flush stale slaves. Default true. */
   initialDiscover?: boolean;
   /** Per-NodeAgent ACK timeout in ms. Default 250 (matches NodeAgent). */
   ackTimeoutMs?: number;
@@ -1085,12 +810,7 @@ interface MasterControllerOptions {
   heartbeatTimeoutMs?: number;
   /** Per-service-call default timeout in ms. Default `ackTimeoutMs`. */
   serviceTimeoutMs?: number;
-  /**
-   * Read-through gate applied to every spawned NodeAgent right before it
-   * issues START. Callers pass a getter (not a boolean) so the flag can
-   * be flipped at runtime — see `NodeAgentOptions.autoStart`. Default
-   * `() => true`.
-   */
+  /** Getter (not a boolean) gating START on every spawned NodeAgent. Default `() => true`. */
   autoStart?: () => boolean;
   /** Optional clock override (tests). Default `() => Date.now()`. */
   now?: () => number;
@@ -1115,48 +835,32 @@ declare class MasterController {
   #private;
   constructor(opts: MasterControllerOptions);
   /**
-   * 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(): DataPlaneReceiver;
-  /**
-   * 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(): void;
   /** Stop all internals, stop every NodeAgent, detach from the transport. */
   stop(): Promise<void>;
   /** Snapshot of all known slaves. Stable identity per call. */
   snapshots(): ControllerSlaveSnapshot[];
-  /** 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: ControllerListener): Unsubscribe;
-  /**
-   * 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: number): NodeAgent | null;
-  /** Issue an ad-hoc broadcast DISCOVER (between periodic firings). */
+  /** Ad-hoc broadcast DISCOVER. */
   discoverNow(): Promise<void>;
   /**
-   * 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`.
    */
   startNode(nodeId: number): Promise<boolean>;
   /**
-   * 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}.
    */
   reprovision(nodeId: number): Promise<boolean>;
 }
@@ -1188,7 +892,7 @@ declare class ProtoReader {
   constructor(buf: Uint8Array, end?: number);
   get done(): boolean;
   get position(): number;
-  /** 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(): number;
   /** Read a length-delimited byte slice (no copy). */
   readBytes(): Uint8Array;
@@ -1196,11 +900,7 @@ declare class ProtoReader {
   readString(): string;
   /** Read a length-delimited sub-message and return a new reader scoped to it. */
   readMessage(): ProtoReader;
-  /**
-   * 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(): {
     field: number;
     wire: number;
@@ -1213,75 +913,40 @@ declare class ProtoError extends Error {
 }
 //#endregion
 //#region src/schema-hash.d.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.
- */
 declare function sha256(bytes: Uint8Array): Promise<Uint8Array>;
-/**
- * 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. */
 declare function schemaHashPrefix(blob: Uint8Array): Promise<bigint>;
 //#endregion
 //#region src/segmented-transfer.d.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.
  */
 declare function makeSvcRequestFrames(nodeId: number, svcIdx: number, callId: number, payload: Uint8Array): CanFrameTx[];
 /**
- * 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.
  */
 declare function makeSvcSegmentedFrames(channel: number, nodeId: number, svcIdx: number, callId: number, payload: Uint8Array): CanFrameTx[];
-/**
- * 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. */
 declare function segExpectedMask(totalLen: number): number;
-/**
- * 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. */
 declare class SegmentReassembler {
   #private;
   totalLen: number;
   rxBitmap: number;
   lastRxMs: number;
   /**
-   * 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: Uint8Array, nowMs: number): Uint8Array | null;
 }
 //#endregion
 //#region src/seq-allocator.d.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. */
 declare class SeqAllocator {
   #private;
   next(): number;